Overhalled continuations to work with React's scheduler

Author: Brian Vaughn

packages/interaction-tracking/src/InteractionEmitter.js

@@ -7,9 +7,7 @@
  * @flow
  */
 
-import type {Interaction} from './InteractionTracking';
-
-type Interactions = Array<Interaction>;
+import type {Interactions} from './InteractionTracking';
 
 export type InteractionObserver = {
   onInteractionsScheduled: (

packages/interaction-tracking/src/InteractionTracking.js

@@ -7,7 +7,7 @@
  * @flow
  */
 
-import invariant from 'shared/invariant';
+import warning from 'shared/warning';
 import {
   __onInteractionsScheduled,
   __onInteractionsStarting,
@@ -16,20 +16,17 @@ import {
 
 export {registerInteractionObserver} from './InteractionEmitter';
 
-type Interactions = Array<Interaction>;
-
+// Maps execution ID to Interactions for all scheduled continuations.
+// We key off of ID because Interactions may be scheduled for multiple continuations.
+// For example, an Interaction may schedule work with React at multiple priorities.
+// Each priority would reserve a continuation (since they may be processed separately).
+export type Continuations = Map<number, Interaction>;
 export type Interaction = {|
   id: number,
   name: string,
   timestamp: number,
 |};
-
-export type Continuation = {
-  __hasBeenRun: boolean,
-  __id: number,
-  __interactions: Interactions,
-  __prevInteractions: Interactions | null,
-};
+export type Interactions = Set<Interaction>;
 
 // Normally we would use the current renderer HostConfig's "now" method,
 // But since interaction-tracking will be a separate package,
@@ -43,10 +40,33 @@ if (typeof performance === 'object' && typeof performance.now === 'function') {
   now = () => localDate.now();
 }
 
-let currentContinuation: Continuation | null = null;
-let globalExecutionID: number = 0;
-let globalInteractionID: number = 0;
-let interactions: Interactions | null = null;
+// Counters used to generate unique IDs for all interactions,
+// And InteractionObserver executions (including continuations).
+let executionIDCounter: number = 0;
+let interactionIDCounter: number = 0;
+
+// Set of currently tracked interactions.
+// Interactions "stack"–
+// Meaning that newly tracked interactions are appended to the previously active set.
+// When an interaction goes out of scope, the previous set (if any) is restored.
+let interactions: Interactions = new Set();
+
+// Temporarily holds the Set of interactions masked by an active "continuation".
+// This is necessary since continuations are started/stopped externally.
+// This value enables previous interactions to be restored when the continuation ends.
+// This implementation supports only one active continuation at any time.
+// We could change this to a stack structure in the future if this requirement changed.
+let interactionsMaskedByContinuation: Interactions = interactions;
+
+// Map continuation (execution) UIDs to interaction UIDs.
+// These Maps are only used for DEV mode validation.
+// Ideally we can replace these Maps with WeakMaps at some point.
+let scheduledContinuations: Continuations | null = null;
+let startedContinuations: Continuations | null = null;
+if (__DEV__) {
+  scheduledContinuations = new Map();
+  startedContinuations = new Map();
+}
 
 export function getCurrent(): Interactions | null {
   if (!__PROFILE__) {
@@ -56,77 +76,99 @@ export function getCurrent(): Interactions | null {
   }
 }
 
-export function reserveContinuation(): Continuation | null {
+// A "continuation" signifies that an interaction is not completed when its callback finish running.
+// This is useful for React, since scheduled work may be batched and processed asynchronously.
+// Continuations have a unique execution ID which must later be used to restore the interaction.
+// This is done by calling startContinuations() before processing the delayed work,
+// And stopContinuations() to indicate that the work has been completed.
+export function reserveContinuation(interaction: Interaction): number {
   if (!__PROFILE__) {
-    return null;
+    return 0;
   }
 
-  if (interactions !== null) {
-    const executionID = globalExecutionID++;
+  const executionID = executionIDCounter++;
 
-    __onInteractionsScheduled(interactions, executionID);
+  __onInteractionsScheduled(new Set([interaction]), executionID);
 
-    return {
-      __hasBeenRun: false,
-      __id: executionID,
-      __interactions: interactions,
-      __prevInteractions: null,
-    };
-  } else {
-    return null;
+  if (__DEV__) {
+    ((scheduledContinuations: any): Continuations).set(
+      executionID,
+      interaction,
+    );
   }
+
+  return executionID;
 }
 
-export function startContinuation(continuation: Continuation | null): void {
+export function startContinuations(continuations: Continuations): void {
   if (!__PROFILE__) {
     return;
   }
 
-  invariant(
-    currentContinuation === null,
-    'Cannot start a continuation when one is already active.',
-  );
-
-  if (continuation === null) {
-    return;
+  if (__DEV__) {
+    warning(
+      ((startedContinuations: any): Continuations).size === 0,
+      'Only one batch of continuations can be active at a time.',
+    );
   }
 
-  invariant(
-    !continuation.__hasBeenRun,
-    'A continuation can only be started once',
-  );
+  const continuationInteractions = new Set();
+
+  const entries = Array.from(continuations);
+  for (let index = 0; index < entries.length; index++) {
+    const [executionID: number, interaction: Interaction] = entries[index];
 
-  continuation.__hasBeenRun = true;
-  currentContinuation = continuation;
+    if (__DEV__) {
+      warning(
+        ((scheduledContinuations: any): Continuations).get(executionID) ===
+          interaction,
+        'Cannot run an unscheduled continuation.',
+      );
+
+      ((scheduledContinuations: any): Continuations).delete(executionID);
+      ((startedContinuations: any): Continuations).set(
+        executionID,
+        interaction,
+      );
+    }
+
+    __onInteractionsStarting(new Set([interaction]), executionID);
+
+    continuationInteractions.add(interaction);
+  }
 
   // Continuations should mask (rather than extend) any current interactions.
   // Upon completion of a continuation, previous interactions will be restored.
-  continuation.__prevInteractions = interactions;
-  interactions = continuation.__interactions;
-
-  __onInteractionsStarting(interactions, continuation.__id);
+  interactionsMaskedByContinuation = interactions;
+  interactions = continuationInteractions;
 }
 
-export function stopContinuation(continuation: Continuation): void {
+export function stopContinuations(continuations: Continuations): void {
   if (!__PROFILE__) {
     return;
   }
 
-  invariant(
-    currentContinuation === continuation,
-    'Cannot stop a continuation that is not active.',
-  );
+  // Stop interactions in the reverse order they were started.
+  const entries = Array.from(continuations);
+  for (let index = entries.length - 1; index >= 0; index--) {
+    const [executionID: number, interaction: Interaction] = entries[index];
 
-  if (continuation === null) {
-    return;
-  }
+    if (__DEV__) {
+      warning(
+        ((startedContinuations: any): Continuations).get(executionID) ===
+          interaction,
+        'Cannot stop an inactive continuation.',
+      );
 
-  __onInteractionsEnded(continuation.__interactions, continuation.__id);
+      ((startedContinuations: any): Continuations).delete(executionID);
+    }
 
-  currentContinuation = null;
+    __onInteractionsEnded(new Set([interaction]), executionID);
+  }
 
   // Restore previous interactions.
-  interactions = continuation.__prevInteractions;
+  interactions = interactionsMaskedByContinuation;
+  interactionsMaskedByContinuation = interactions;
 }
 
 export function track(name: string, callback: Function): void {
@@ -136,19 +178,19 @@ export function track(name: string, callback: Function): void {
   }
 
   const interaction: Interaction = {
-    id: globalInteractionID++,
+    id: interactionIDCounter++,
     name,
     timestamp: now(),
   };
 
-  const executionID = globalExecutionID++;
+  const executionID = executionIDCounter++;
   const prevInteractions = interactions;
 
   // Tracked interactions should stack/accumulate.
   // To do that, clone the current interactions array.
   // The previous interactions array will be restored upon completion.
-  interactions =
-    interactions === null ? [interaction] : interactions.concat(interaction);
+  interactions = new Set(interactions);
+  interactions.add(interaction);
 
   try {
     __onInteractionsScheduled(interactions, executionID);
@@ -171,7 +213,7 @@ export function wrap(callback: Function): Function {
     return callback;
   }
 
-  const executionID = globalExecutionID++;
+  const executionID = executionIDCounter++;
   const wrappedInteractions = interactions;
 
   __onInteractionsScheduled(wrappedInteractions, executionID);