dcp-client 4.2.31 → 4.2.32

package/generated/sandbox-definitions.json

@@ -1 +1 @@
-{"browser":["deny-node","kvin/kvin.js","script-load-wrapper","wrap-event-listeners","event-loop-virtualization","gpu-timers","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"node":["kvin/kvin.js","sa-ww-simulation","script-load-wrapper","wrap-event-listeners","event-loop-virtualization","gpu-timers","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"native":["deny-node","kvin/kvin.js","sa-ww-simulation","script-load-wrapper","native-event-loop","wrap-event-listeners","event-loop-virtualization","gpu-timers","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"webGpuNative":["deny-node","kvin/kvin.js","sa-ww-simulation","script-load-wrapper","native-event-loop","wrap-event-listeners","event-loop-virtualization","webgpu-worker-environment","gpu-timers","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"nodeTesting":["kvin/kvin.js","sa-ww-simulation","script-load-wrapper","wrap-event-listeners","event-loop-virtualization","gpu-timers","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap","testing.js"],"testing":["deny-node","kvin/kvin.js","sa-ww-simulation","script-load-wrapper","native-event-loop","wrap-event-listeners","event-loop-virtualization","gpu-timers","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap","testing.js"]}
+{"browser":["deny-node","kvin/kvin.js","script-load-wrapper","wrap-event-listeners","timer-classes","event-loop-virtualization","unique-timing","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"node":["kvin/kvin.js","sa-ww-simulation","script-load-wrapper","wrap-event-listeners","timer-classes","event-loop-virtualization","unique-timing","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"native":["deny-node","kvin/kvin.js","sa-ww-simulation","script-load-wrapper","native-event-loop","wrap-event-listeners","timer-classes","event-loop-virtualization","unique-timing","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"webGpuNative":["deny-node","kvin/kvin.js","sa-ww-simulation","script-load-wrapper","native-event-loop","wrap-event-listeners","timer-classes","webgpu-worker-environment","event-loop-virtualization","unique-timing","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap"],"nodeTesting":["kvin/kvin.js","sa-ww-simulation","script-load-wrapper","wrap-event-listeners","timer-classes","event-loop-virtualization","unique-timing","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap","testing.js"],"testing":["deny-node","kvin/kvin.js","sa-ww-simulation","script-load-wrapper","native-event-loop","wrap-event-listeners","timer-classes","event-loop-virtualization","unique-timing","access-lists","bravojs-init","bravojs/bravo.js","bravojs-env","calculate-capabilities","bootstrap","testing.js"]}

package/libexec/sandbox/access-lists.js

@@ -649,11 +649,10 @@ self.wrapScriptLoading({ scriptName: 'access-lists', ringTransition: true }, fun
   // Set values to true to disallow access to symbols
   const blockList = {
     OffscreenCanvas: false,
+    WebGPUWindow: false,
+    GPU: false,
   };
 
-  const blockListRequirements = {
-    OffscreenCanvas: "environment.offscreenCanvas"
-  };
   /**
    * Applies a allow list and a block list of properties to an object. After this function, if someone tries
    * to access non-allowed or blocked properties, a warning is logged and it will return undefined. The allow
@@ -663,10 +662,9 @@ self.wrapScriptLoading({ scriptName: 'access-lists', ringTransition: true }, fun
    * @param {object} obj - The object, which will have the allow list applied to its properties.
    * @param {Set} allowList - A set of properties to allow people to access.
    * @param {Set} blockList - An object of property names mapping to booleans to indicate whether access is allowed or not.
-   * @param {Set} blockListRequirements - An object of property names mapping requirement path strings, used to print useful warnings.
    * @param {Set} polyfills - An object of property names that have been polyfilled.
    */
-  function applyAccessLists(obj, allowList, blockList = {}, blockListRequirements = {}, polyfills = {}) {
+  function applyAccessLists(obj, allowList, blockList = {}, polyfills = {}) {
     if (!obj) { return; }
     Object.getOwnPropertyNames(obj).forEach(function (prop) {
       if (Object.getOwnPropertyDescriptor(obj, prop).configurable) {
@@ -693,7 +691,6 @@ self.wrapScriptLoading({ scriptName: 'access-lists', ringTransition: true }, fun
         } else if (prop in blockList) {
           let isSet = false;
           let blocked = blockList[prop];
-          let requirement = blockListRequirements[prop];
           let propValue = obj[prop];
           Object.defineProperty(obj, prop, {
             get: function () {
@@ -761,38 +758,32 @@ self.wrapScriptLoading({ scriptName: 'access-lists', ringTransition: true }, fun
     // before we allow Object's properties
 
     var global = typeof globalThis === 'undefined' ? self : globalThis;
-    // Save them in scope because they'll get hidden by the allowList
-    let _allowList = allowList;
-    let _blockList = blockList;
-    let _polyfills = polyfills;
 
     // Ternary expression to avoid a ReferenceError on navigator
-    let _navigator = typeof navigator !== 'undefined' ? navigator : undefined;
     let _GPU       = ((typeof navigator !== 'undefined') && (typeof navigator.gpu !== 'undefined')) ? navigator.gpu : 
       (typeof GPU !== 'undefined'? GPU : undefined);
-    let _blockListRequirements = blockListRequirements;
-    let _applyAccessLists = applyAccessLists;
-    let _applyPolyfills = applyPolyfills;
 
     for (let g = global; g.__proto__ && (g.__proto__ !== Object); g = g.__proto__) {
-      applyAccessLists(g, allowList, blockList, blockListRequirements, polyfills);
+      applyAccessLists(g, allowList, blockList, polyfills);
     }
 
-    if (typeof _navigator === 'undefined') {
-      _navigator = navigator = {
+    if (typeof navigator === 'undefined')
+    {
+      navigator = {
         userAgent: 'not a browser',
-        gpu: _GPU, 
+        gpu: _GPU,
       };
-    } else {
+    }
+    else if (!protectedStorage.createdNewNavigator)
+    {
       // We also want to allowList certain parts of navigator, but not others.
-      
-      navAllowlist = new Set([
+      const navAllowlist = new Set([
         'userAgent',
         'gpu',
       ]);
       let navPolyfill = {
         userAgent: typeof navigator.userAgent !== 'undefined'? navigator.userAgent : 'not a browser',
-        gpu: _GPU 
+        gpu: _GPU,
       };
       applyAccessLists(navigator.__proto__, navAllowlist, {}, {}, navPolyfill);
       applyPolyfills(navigator.__proto__, navPolyfill);
@@ -810,7 +801,21 @@ self.wrapScriptLoading({ scriptName: 'access-lists', ringTransition: true }, fun
     global.requestAnimationFrame = callback => setTimeout(callback, 0);
   }
 
-  if (protectedStorage.hasWebglSupport()) {
+  function hasWebGLSupport()
+  {
+    try
+    {
+      const canvas = new OffscreenCanvas(1,1);
+      return Boolean(canvas.getContext('webgl') || canvas.getContext('webgl2'));
+    }
+    catch
+    {
+      return false;
+    }
+
+  }
+
+  if (hasWebGLSupport()) {
 
     // This deals with Firefox bug 1529995, which causes the tab to crash if fenceSync is called.
     if (navigator.userAgent.indexOf('Firefox') >= 0) {
@@ -840,6 +845,8 @@ self.wrapScriptLoading({ scriptName: 'access-lists', ringTransition: true }, fun
         // Assume the scheduler gave us a nicely-shaped req object.
         const requirements = event.requirements;
         blockList.OffscreenCanvas = !requirements.environment.offscreenCanvas;
+        blockList.WebGPUWindow = !requirements.environment.webgpu;
+        blockList.GPU = !requirements.environment.webgpu;
         applyAllAccessLists();
 
         ring1PostMessage({ request: 'applyRequirementsDone' });

package/libexec/sandbox/bravojs-env.js

@@ -13,19 +13,13 @@ self.wrapScriptLoading({ scriptName: 'bravojs-env', ringTransition: true }, func
 {
   // This file starts at ring 2, but transitions to ring 3 partway through it.
   const ring2PostMessage = self.postMessage; 
-  let ring3PostMessage
+  let ring3PostMessage;
+  let totalTime;
 
   bravojs.ww = {}
   bravojs.ww.allDeps = []
   bravojs.ww.provideCallbacks = {}
 
-  async function tryFlushMicroTaskQueue()
-  {
-    await Promise.resolve();
-    await Promise.resolve();
-    await Promise.resolve();
-  }
-  
   //Listens for postMessage from the sandbox
   addEventListener('message', async (event) => {
     let message = event
@@ -180,27 +174,34 @@ self.wrapScriptLoading({ scriptName: 'bravojs-env', ringTransition: true }, func
     });
   };
 
-  /* Report the GPU and total metrics for a slice that was rejected */
-  function reportRejectedGPUandTotal (t0) {
-    try
-    {
-      const total = performance.now() - t0;
-      const webGL = protectedStorage.getAndResetWebGLTimer();
-      protectedStorage.subtractWebGLTimeFromCPUTime(webGL);
-      ring3PostMessage({ request: 'measurement', total, webGL });
-    }
-    catch (error)
-    {
-      ring3PostMessage({ request: 'sandboxError', error });
-    }
+  /* Report metrics to sandbox/supervisor */
+  async function reportTimes ()
+  {
+    const timers = protectedStorage.timers;
+    const webGL = timers.webGL.duration();
+    const webGPU = await timers.webGPU.duration();
+
+    timers.cpu.mostRecentInterval.stop();
+    let CPU = timers.cpu.duration();
+    CPU -= webGL; // webGL is synchronous gpu usage, subtract that from cpu time.
+
+    totalTime.stop();
+    const total = totalTime.length;
+
+    timers.cpu.reset();
+    timers.webGL.reset();
+    timers.webGPU.reset();
+    protectedStorage.clearAllTimers();
+
+    ring3PostMessage({ request: 'measurement', total, webGL, webGPU, CPU });
   }
 
   /* Report an error from the work function to the supervisor */
-  function reportError (t0, error)
+  function reportError (error)
   {
     let err = { message: 'initial state', name: 'initial state' };
 
-    for (prop of [ 'message', 'name', 'code', 'stack', 'lineNumber', 'columnNumber' ])
+    for (const prop of [ 'message', 'name', 'code', 'stack', 'lineNumber', 'columnNumber' ])
     {
       try
       {
@@ -214,31 +215,25 @@ self.wrapScriptLoading({ scriptName: 'bravojs-env', ringTransition: true }, func
       err['message'] = protectedStorage.workRejectReason;
       err['name'] = 'EWORKREJECT';
       err['stack'] = 'Slice was rejected in the sandbox by work.reject'
-      reportRejectedGPUandTotal(t0);
+      reportTimes().then(() => ring3PostMessage({ request: 'workError', error: err }));
+    }
+    else
+    {
+      ring3PostMessage({request: 'workError', error: err});
     }
-
-    ring3PostMessage({request: 'workError', error: err});
   }
 
   /**
    * Report a result from work function and metrics to the supervisor.
-   * @param     t0      timestamp when work began
    * @param     result  the value that the work function returned promise resolved to
    */
-  function reportResult (t0, result)
+  function reportResult (result)
   {
-    try
-    {
-      const total = performance.now() - t0 + 1; /* +1 to ensure we never have "0 second slices" */
-      const webGL = protectedStorage.getAndResetWebGLTimer();
-      protectedStorage.subtractWebGLTimeFromCPUTime(webGL); /* Because webGL is sync but doesn't use CPU */
-      ring3PostMessage({ request: 'measurement', total, webGL });
+    reportTimes().then(() => {
       ring3PostMessage({ request: 'complete', result });
-    }
-    catch(error)
-    {
+    }).catch((error) => {
       ring3PostMessage({ request: 'sandboxError', error });
-    }
+    });
   }
   
   /**
@@ -266,12 +261,14 @@ self.wrapScriptLoading({ scriptName: 'bravojs-env', ringTransition: true }, func
       rejection = error;
     }
 
-    /* try to flush any pending tasks on the microtask queue, then flush any pending console events, 
-     * especially in the case of a repeating message that hasn't been emitted yet
-     */
-    try { await tryFlushMicroTaskQueue(); } catch(e) {};
+    // flush any pending console events, especially in the case of a repeating message that hasn't been emitted yet 
     try { flushLastLog(); } catch(e) {};
-    try { protectedStorage.markCPUTimeAsDone(); } catch(e) {};
+    try
+    {
+      protectedStorage.lockTimers(); // lock timers so no new timeouts will be run.
+      await new Promise(r => protectedStorage.realSetTimeout(r)); // flush microtask queue
+    }
+    catch(e) {}
 
     if (rejection)
       errorCallback(rejection);
@@ -290,12 +287,21 @@ self.wrapScriptLoading({ scriptName: 'bravojs-env', ringTransition: true }, func
   function runWorkFunction(datum)
   {
     // Measure performance directly before and after the job to get as accurate total time as
-    const t0 = performance.now();
-
+    totalTime = new protectedStorage.TimeInterval();
+
+    // Guarantee CPU timers are cleared before the main work function runs.
+    // This is necessary because the GPU object has been wrapped to make setTimeout calls to
+    // allow for measurement. However, when these timeouts are invoked during capability
+    // calculations, they are erroneously measured as CPU time. This can cause CPU time > total time
+    // and CPUDensity > 1
+    protectedStorage.timers.cpu.reset();
+    protectedStorage.timers.webGPU.reset(); // also reset other timers for saftey
+    protectedStorage.timers.webGL.reset();
+    protectedStorage.unlockTimers();
     /* Use setTimeout trampoline to
      * 1. shorten stack
      * 2. initialize the event loop measurement code
      */
-    protectedStorage.setTimeout(() => runWorkFunction_inner(datum, (result) => reportResult(t0, result), (rejection) => reportError(t0, rejection)));
+    protectedStorage.setTimeout(() => runWorkFunction_inner(datum, (result) => reportResult(result), (rejection) => reportError(rejection)));
   }
 }); /* end of fn */

package/libexec/sandbox/calculate-capabilities.js

@@ -64,8 +64,8 @@ self.wrapScriptLoading({ scriptName: 'calculate-capabilities' }, function calcul
               title: 'DCP-evaluator',
               visible: false,
             });
-
-            const adapter = await GPU.requestAdapter({ gpuWindow });
+            
+            const adapter = await GPU.requestAdapter({ window: gpuWindow });
             await adapter.requestDevice(adapter.extensions);
           } else {
             const adapter = await navigator.gpu.requestAdapter();
@@ -102,6 +102,7 @@ self.wrapScriptLoading({ scriptName: 'calculate-capabilities' }, function calcul
           //Any error in this using an extensions should likely result in specifications for that capability being set to false.
           offscreenCanvas = false;
         }
+        protectedStorage.timers.webGL.reset() // Testing for webGL != using webGL.
       }
 
       try {

package/libexec/sandbox/event-loop-virtualization.js

@@ -19,15 +19,24 @@
 self.wrapScriptLoading({ scriptName: 'event-loop-virtualization' }, function eventLoopVirtualization$$fn(protectedStorage, ring0PostMessage)
 {
   (function privateScope(realSetTimeout, realSetInterval, realSetImmediate, realClearTimeout, realClearInterval, realClearImmediate) {
-    let totalCPUTime = 0;
-    let startTime;
+    const cpuTimer = protectedStorage.timers.cpu;
     const events = [];
     events.serial = 0;
+    let timersLocked = false;
+
+    protectedStorage.lockTimers =   function lockTimers()   { timersLocked = true;  }
+    protectedStorage.unlockTimers = function unlockTimers() { timersLocked = false; }
+
 
     function sortEvents() {
       events.sort(function (a, b) { return a.when - b.when; });
     }
 
+    /*
+     * Assumption: serviceEvents must only be triggered if there is an event waiting to
+     * be run. If there are no pending events (or the last one is removed), the trigger 
+     * to call serviceEvents next should be removed.
+    */
     function serviceEvents()
     {
       serviceEvents.timeout = null;
@@ -35,56 +44,37 @@ self.wrapScriptLoading({ scriptName: 'event-loop-virtualization' }, function eve
       serviceEvents.servicing = true;
       serviceEvents.sliceIsFinished = false;
 
-      startTime = performance.now();
-      let now = Date.now();
+      serviceEvents.interval = new protectedStorage.TimeInterval();
+      cpuTimer.push(serviceEvents.interval);
 
       sortEvents();
-      if (events[0].when <= now)
+      const event = events.shift();
+      if (event.eventType === 'timer')
       {
-        const event = events.shift();
-        if (event.eventType === 'timer')
+        serviceEvents.executingTimeout = realSetTimeout(event.fn, 0, event.args);
+        if (event.recur)
         {
-          serviceEvents.executingTimeout = realSetTimeout(event.fn, 0, event.args);
-          if (event.recur)
-          {
-            event.when = Date.now() + event.recur;
-            events.push(event);
-            sortEvents();
-          }
+          event.when = Date.now() + event.recur;
+          events.push(event);
+          sortEvents();
         }
-        // Can add handles for events to the event loop as needed (ie messages)
       }
+      // Can add handles for events to the event loop as needed (ie messages)
 
       // Measure the time on the event loop after everything has executed
       serviceEvents.measurerTimeout = realSetTimeout(endOfRealEventCycle,1);
       function endOfRealEventCycle()
       {
         serviceEvents.servicing = false;
-        if (!serviceEvents.sliceIsFinished)
+        serviceEvents.interval.stop();
+
+        if (!serviceEvents.sliceIsFinished && events.length)
         {
-          const endTime = performance.now();
-          totalCPUTime += endTime - startTime;
-  
-          // Set timeout to rerun this function if there are events remaining that just can't be used yet
-          if (events.length > 0)
-          {
-            serviceEvents.nextTimeout = events[0].when
-            serviceEvents.timeout = realSetTimeout(serviceEvents, events[0].when - Date.now());
-          }
+          serviceEvents.nextTimeout = events[0].when
+          serviceEvents.timeout = realSetTimeout(serviceEvents, events[0].when - Date.now());
         }
       }
     }
-    protectedStorage.markCPUTimeAsDone = function markCPUTimeAsDone()
-    {
-      const endTime = performance.now();
-      totalCPUTime += endTime - startTime;
-      serviceEvents.sliceIsFinished = true;
-    }
-
-    protectedStorage.subtractWebGLTimeFromCPUTime = function subtractCPUTime(time)
-    {
-      totalCPUTime -= time;
-    }
 
     /** Execute callback after at least timeout ms. 
      * 
@@ -94,6 +84,10 @@ self.wrapScriptLoading({ scriptName: 'event-loop-virtualization' }, function eve
      *  @returns                    {object} A value which may be used as the timeoutId parameter of clearTimeout()
      */
     setTimeout = function eventLoop$$Worker$setTimeout(callback, timeout, arg) {
+      // Work function has resolved, Don't let client init any new timeouts.
+      if (timersLocked)
+        return {};
+
       timeout = timeout || 0;
       let timer, args;
       if (typeof callback === 'string') {
@@ -237,34 +231,8 @@ self.wrapScriptLoading({ scriptName: 'event-loop-virtualization' }, function eve
       serviceEvents.sliceIsFinished = false;
     }
 
-    addEventListener('message', async (event) => {
-      try {
-        if (event.request === 'clearTimers') {
-          clearAllTimers();
-          ring0PostMessage({
-            request: 'clearTimersDone',
-          });
-        }
-        else if (event.request === 'resetAndGetCPUTime')
-        {
-          const cpuTime = totalCPUTime;
-          totalCPUTime = 0;
-          ring0PostMessage({
-            request: 'totalCPUTime',
-            CPU: cpuTime
-          })
-        }
-      } catch (error) {
-        ring0PostMessage({
-          request: 'error',
-          error: {
-            name: error.name,
-            message: error.message,
-            stack: error.stack,
-          },
-        });
-      }
-    });
+    protectedStorage.clearAllTimers = clearAllTimers;
+
   })(self.setTimeout, self.setInterval, self.setImmediate, self.clearTimeout, self.clearInterval, self.clearImmediate);
 
   self.setTimeout = setTimeout;

package/libexec/sandbox/timer-classes.js

@@ -0,0 +1,226 @@
+/**
+ *  @file       timer-classes.js
+ *              This file creates classes that will be required for timing.
+ * 
+ * The 4 classes defined are:
+ *  - TimeInterval: measure an interval of time.
+ *  - TimeThing:    generic collection of TimeIntervals
+ *  - TimeCPU:      collection of TimeIntervals, with a reference to the most recent interval.
+ *  - TimeWebGPU:   collection of TimeIntervals, with duration not counting overlap, and awaiting for GPU completion event.
+ * 
+ * TimeInterval is an object shaped like {start: X, stop: Y} with a few additional functions to stop the interval.
+ * Start is set to the current time immediately when the interval is created, and stop is set when the `stop` function
+ * is called. If the length of an interval is accessed before the interval is stopped, it will throw an error.
+ * A TimeThing contains a possibly-overlapping list of TimeIntervals. It adds a duration function to calculate the total
+ * time of all intervals (double-counting any overlaps). If the Thing may need to have it's final interval stopped in an
+ * area that won't otherwise have a reference to that interval, TimeCPU can be used. TimeCPU only adds a reference to the
+ * most recent interval to be added to the list.
+ * TimeWebGPU is special due to the challenges of timing a GPU from Javascript. It's duration function is async, since
+ * the moment the GPU is finished is unknowable until it reports it's finished. If a work function adds a task to the GPU,
+ * but resolves before the GPU is finished, we need to carefully to wait for the GPU to be finished before the duration
+ * can be calculated. TimeWebGPU has this built-in to the duration function.
+
+ * @author  Ryan Saweczko <ryansaweczko@kingsds.network>
+ * @date    Aug 2022
+ */
+
+// @ts-nocheck
+
+self.wrapScriptLoading({ scriptName: 'timer-classes' }, function timerClasses$$fn(protectedStorage)
+{
+  /**
+   * Time interval class.
+   * 
+   * Contains a start time and end time. The start time is set immediately when the interval is created,
+   * and the end time is set when `stop` is called. Once the interval has been stopped, the length
+   * can be accessed (getting interval.length before it's stopped is an error).
+   */
+  function TimeInterval()
+  {
+    this.start = performance.now();
+    this.end = null;
+  }
+
+  Object.defineProperty(TimeInterval.prototype, 'length', {
+    get: function length()
+    {
+      if (!this.end)
+        throw new Error("Invalid length: interval hasn't been stopped");
+      return this.end - this.start;
+    }
+  });
+
+  /**
+   * Stop a timer. The `end` time is set.
+   */
+  TimeInterval.prototype.stop = function stop()
+  {
+    if (this.end)
+      return false
+    this.end = performance.now();
+    return true;
+  }
+
+  /**
+   * Check if the interval has been stopped (end time has been set)
+   */
+  TimeInterval.prototype.hasEnded = function hasEnded()
+  {
+    return typeof this.end === 'number';
+  };
+
+  protectedStorage.TimeInterval = TimeInterval;
+
+  /**
+   * Time Thing class
+   * 
+   * Generic collection of time intervals. Contains a list
+   * of intervals, and provides a way to get the total time
+   * of all intervals.
+   */
+  function TimeThing()
+  {
+    this.intervals = [];
+  }
+
+  /**
+   * Get the total length of all intervals. If the intervals are overlapping,
+   * the overlapping time will be counted twice.  
+   */
+  TimeThing.prototype.duration = function totalDuration()
+  {
+    let sum = 0;
+    for (let interval of this.intervals)
+      sum += interval.length;
+    return sum;
+  }
+
+  /**
+   * Add a new interval.
+   * 
+   * @Param {TimeInterval} interval - new interval to add to the collection
+   */
+  TimeThing.prototype.push = function push(interval)
+  {
+    this.intervals.push(interval);
+  }
+
+  /**
+   * Reset the interval. Resets the interval list to an empty list.
+   */
+  TimeThing.prototype.reset = function reset()
+  {
+    this.intervals = [];
+  }
+
+  /**
+   * Time CPU class
+   * 
+   * Inherits from TimeThing, but adds a reference to the most recent interval
+   * to be added.
+   */
+  function TimeCPU()
+  {
+    TimeThing.call(this);
+    this.mostRecentInterval = null;
+  }
+  TimeCPU.prototype = new TimeThing();
+
+  /**
+   * Add a new interval. `this.mostRecentInterval` is set to this interval.
+   * 
+   * @Param {TimeInterval} interval - new interval to add to the collection
+   */
+  TimeCPU.prototype.push = function push(ele)
+  {
+    this.intervals.push(ele);
+    this.mostRecentInterval = ele;
+  }
+
+  /**
+   * Time WebGPU class
+   * 
+   * Inherits from TimeThing, but adds a reference to the most recent interval,
+   * as well as large changes to the duration function to handle overlapping time intervals.
+   */
+  function TimeWebGPU()
+  {
+    TimeThing.call(this);
+    this.latestWebGPUCall = null;
+  }
+  TimeWebGPU.prototype = new TimeThing();
+
+  /**
+   * Add a new interval. `this.mostRecentInterval` is set to this interval.
+   * 
+   * @Param {object} interval - {interval: TimeInterval, queueP: Promise}
+   *                            new interval to add to the collection, as well as a corresponding promise
+   *                            for when the most recently submitted webGPU queue is finished.
+   */
+  TimeWebGPU.prototype.push = function push(obj)
+  {
+    this.intervals.push(obj.interval);
+    this.latestWebGPUCall = obj.queueP;
+  }
+
+  /**
+   * Measure time (in ms) spent in the gpu. Timing is done ignoring overlaps - 
+   * so if interval 1 was from 0-5 seconds and interval 2 was from 3-8 seconds,
+   * the returned duration will be 8.
+   * 
+   * Furthermore, since it's impossible to know when webGPU code execution is finished until
+   * the GPU reports it's finished, awaiting the last `onSubmittedWorkDone` promise is required.
+   * A loop is used here in case the webGPU finishing triggers anything else on the microtask queue
+   * 
+   * @returns - promise that will resolve with the total duration once all webGPU code has run to completion.
+   */
+  TimeWebGPU.prototype.duration = async function duration()
+  {
+    var totalTime = 0;
+    var previousEnd = 0;
+
+    while (this.latestWebGPUCall)
+    {
+      const latestCall = this.latestWebGPUCall;
+      await this.latestWebGPUCall;
+      if (latestCall === this.latestWebGPUCall)
+        this.latestWebGPUCall = null;
+    }
+
+    for (let interval of this.intervals)
+    {
+      if (previousEnd <= interval.start)
+        totalTime += interval.length
+      else
+      {
+        if (!interval.hasEnded())
+          throw new Error("Invalid length: interval hasn't been stopped");
+        totalTime += interval.end - previousEnd;
+      }
+      previousEnd = interval.end;
+    }
+    return totalTime;
+  }
+
+  /**
+   * Instantiate a timer for each type of execution we need to measure.
+   * 
+   * cpu: measure total CPU usage of a slice. This measurement is based on
+   *      the state of the event loop, and when any specific JavaScript code
+   *      block is executing
+   * webGPU: measure the amount of time between `submitting` a command queue, and
+   *         an onSubmittedWorkDone promise resolving to signal all work sent to the GPU
+   *         is finished. These measurements are as close as we can get in JavaScript to
+   *         the exact duration of the execution of code on the GPU using webGPU.
+   * webGL: measure the amount of time spent in a webGL function. Since webGL is synchronously
+   *        executed, this time is indistinguishable from CPU time measured (unless all webGL
+   *        functions also stop/start new CPU timing), so we have to subtract this measured
+   *        time from CPU time to get the actual CPU time.
+   */
+  protectedStorage.timers = {
+    cpu:    new TimeCPU(),
+    webGPU: new TimeWebGPU(),
+    webGL:  new TimeThing(),
+  }
+
+})