[scheduler] Priority levels, continuations, and wrapped callbacks

All of these features are based on features of React's internal
scheduler. The eventual goal is to lift as much as possible out of the
React internals into the Scheduler package.

Includes some renaming of existing methods.

- `scheduleWork` is now `scheduleCallback`
- `cancelScheduledWork` is now `cancelCallback`


Priority levels
---------------

Adds the ability to schedule callbacks at different priority levels.
The current levels are (final names TBD):

- Immediate priority. Fires at the end of the outermost currently
executing (similar to a microtask).
- Interactive priority. Fires within a few hundred milliseconds. This
should only be used to provide quick feedback to the user as a result
of an interaction.
- Normal priority. This is the default. Fires within several seconds.
- "Maybe" priority. Only fires if there's nothing else to do. Used for
prerendering or warming a cache.

The priority is changed using `runWithPriority`:

```js
runWithPriority(InteractivePriority, () => {
  scheduleCallback(callback);
});
```


Continuations
-------------

Adds the ability for a callback to yield without losing its place
in the queue, by returning a continuation. The continuation will have
the same expiration as the callback that yielded.


Wrapped callbacks
-----------------

Adds the ability to wrap a callback so that, when it is called, it
receives the priority of the current execution context.

Author: acdlite

packages/scheduler/src/Scheduler.js

@@ -8,14 +8,34 @@
 
 /* eslint-disable no-var */
 
-// TODO: Currently there's only a single priority level, Deferred. Will add
-// additional priorities.
-var DEFERRED_TIMEOUT = 5000;
+// TODO: Use symbols?
+var ImmediatePriority = 1;
+var InteractivePriority = 2;
+var DefaultPriority = 3;
+var MaybePriority = 4;
+
+// Max 31 bit integer. The max integer size in V8 for 32-bit systems.
+// Math.pow(2, 30) - 1
+// 0b111111111111111111111111111111
+var maxSigned31BitInt = 1073741823;
+
+// Times out immediately
+var IMMEDIATE_PRIORITY_TIMEOUT = -1;
+// Eventually times out
+var INTERACTIVE_PRIORITY_TIMEOUT = 250;
+var DEFAULT_PRIORITY_TIMEOUT = 5000;
+// Never times out
+var MAYBE_PRIORITY_TIMEOUT = maxSigned31BitInt;
 
 // Callbacks are stored as a circular, doubly linked list.
 var firstCallbackNode = null;
 
-var isPerformingWork = false;
+var currentPriorityLevel = DefaultPriority;
+var currentEventStartTime = -1;
+var currentExpirationTime = -1;
+
+// This is set when a callback is being executed, to prevent re-entrancy.
+var isExecutingCallback = false;
 
 var isHostCallbackScheduled = false;
 
@@ -25,6 +45,14 @@ var hasNativePerformanceNow =
 var timeRemaining;
 if (hasNativePerformanceNow) {
   timeRemaining = function() {
+    if (
+      firstCallbackNode !== null &&
+      firstCallbackNode.expirationTime < currentExpirationTime
+    ) {
+      // A higher priority callback was scheduled. Yield so we can switch to
+      // working on that.
+      return 0;
+    }
     // We assume that if we have a performance timer that the rAF callback
     // gets a performance timer value. Not sure if this is always true.
     var remaining = getFrameDeadline() - performance.now();
@@ -33,6 +61,12 @@ if (hasNativePerformanceNow) {
 } else {
   timeRemaining = function() {
     // Fallback to Date.now()
+    if (
+      firstCallbackNode !== null &&
+      firstCallbackNode.expirationTime < currentExpirationTime
+    ) {
+      return 0;
+    }
     var remaining = getFrameDeadline() - Date.now();
     return remaining > 0 ? remaining : 0;
   };
@@ -44,22 +78,22 @@ var deadlineObject = {
 };
 
 function ensureHostCallbackIsScheduled() {
-  if (isPerformingWork) {
+  if (isExecutingCallback) {
     // Don't schedule work yet; wait until the next time we yield.
     return;
   }
-  // Schedule the host callback using the earliest timeout in the list.
-  var timesOutAt = firstCallbackNode.timesOutAt;
+  // Schedule the host callback using the earliest expiration in the list.
+  var expirationTime = firstCallbackNode.expirationTime;
   if (!isHostCallbackScheduled) {
     isHostCallbackScheduled = true;
   } else {
     // Cancel the existing host callback.
     cancelCallback();
   }
-  requestCallback(flushWork, timesOutAt);
+  requestCallback(flushWork, expirationTime);
 }
 
-function flushFirstCallback(node) {
+function flushFirstCallback() {
   var flushedNode = firstCallbackNode;
 
   // Remove the node from the list before calling the callback. That way the
@@ -70,20 +104,101 @@ function flushFirstCallback(node) {
     firstCallbackNode = null;
     next = null;
   } else {
-    var previous = firstCallbackNode.previous;
-    firstCallbackNode = previous.next = next;
-    next.previous = previous;
+    var lastCallbackNode = firstCallbackNode.previous;
+    firstCallbackNode = lastCallbackNode.next = next;
+    next.previous = lastCallbackNode;
   }
 
   flushedNode.next = flushedNode.previous = null;
 
   // Now it's safe to call the callback.
   var callback = flushedNode.callback;
-  callback(deadlineObject);
+  var expirationTime = flushedNode.expirationTime;
+  var priorityLevel = flushedNode.priorityLevel;
+  var previousPriorityLevel = currentPriorityLevel;
+  var previousExpirationTime = currentExpirationTime;
+  currentPriorityLevel = priorityLevel;
+  currentExpirationTime = expirationTime;
+  var continuationCallback;
+  try {
+    continuationCallback = callback(deadlineObject);
+  } finally {
+    currentPriorityLevel = previousPriorityLevel;
+    currentExpirationTime = previousExpirationTime;
+  }
+
+  if (typeof continuationCallback === 'function') {
+    var continuationNode: CallbackNode = {
+      callback: continuationCallback,
+      priorityLevel,
+      expirationTime,
+      next: null,
+      previous: null,
+    };
+
+    // Insert the new callback into the list, sorted by its timeout.
+    if (firstCallbackNode === null) {
+      // This is the first callback in the list.
+      firstCallbackNode = continuationNode.next = continuationNode.previous = continuationNode;
+    } else {
+      var nextAfterContinuation = null;
+      var node = firstCallbackNode;
+      do {
+        if (node.expirationTime >= expirationTime) {
+          // This callback is equal or lower priority than the new one.
+          nextAfterContinuation = node;
+          break;
+        }
+        node = node.next;
+      } while (node !== firstCallbackNode);
+
+      if (nextAfterContinuation === null) {
+        // No equal or lower priority callback was found, which means the new
+        // callback is the lowest priority callback in the list.
+        nextAfterContinuation = firstCallbackNode;
+      } else if (nextAfterContinuation === firstCallbackNode) {
+        // The new callback is the highest priority callback in the list.
+        firstCallbackNode = continuationNode;
+        ensureHostCallbackIsScheduled(firstCallbackNode);
+      }
+
+      var previous = nextAfterContinuation.previous;
+      previous.next = nextAfterContinuation.previous = continuationNode;
+      continuationNode.next = nextAfterContinuation;
+      continuationNode.previous = previous;
+    }
+  }
+}
+
+function flushImmediateWork() {
+  if (
+    currentEventStartTime === -1 &&
+    firstCallbackNode !== null &&
+    firstCallbackNode.priorityLevel === ImmediatePriority
+  ) {
+    isExecutingCallback = true;
+    deadlineObject.didTimeout = true;
+    try {
+      do {
+        flushFirstCallback();
+      } while (
+        firstCallbackNode !== null &&
+        firstCallbackNode.priorityLevel === ImmediatePriority
+      );
+    } finally {
+      isExecutingCallback = false;
+      if (firstCallbackNode !== null) {
+        // There's still work remaining. Request another callback.
+        ensureHostCallbackIsScheduled(firstCallbackNode);
+      } else {
+        isHostCallbackScheduled = false;
+      }
+    }
+  }
 }
 
 function flushWork(didTimeout) {
-  isPerformingWork = true;
+  isExecutingCallback = true;
   deadlineObject.didTimeout = didTimeout;
   try {
     if (didTimeout) {
@@ -93,12 +208,12 @@ function flushWork(didTimeout) {
         // earlier than that time. Then read the current time again and repeat.
         // This optimizes for as few performance.now calls as possible.
         var currentTime = getCurrentTime();
-        if (firstCallbackNode.timesOutAt <= currentTime) {
+        if (firstCallbackNode.expirationTime <= currentTime) {
           do {
             flushFirstCallback();
           } while (
             firstCallbackNode !== null &&
-            firstCallbackNode.timesOutAt <= currentTime
+            firstCallbackNode.expirationTime <= currentTime
           );
           continue;
         }
@@ -116,36 +231,93 @@ function flushWork(didTimeout) {
       }
     }
   } finally {
-    isPerformingWork = false;
+    isExecutingCallback = false;
     if (firstCallbackNode !== null) {
       // There's still work remaining. Request another callback.
       ensureHostCallbackIsScheduled(firstCallbackNode);
     } else {
       isHostCallbackScheduled = false;
     }
+    flushImmediateWork();
+  }
+}
+
+function unstable_runWithPriority(eventHandler, priorityLevel) {
+  switch (priorityLevel) {
+    case ImmediatePriority:
+    case InteractivePriority:
+    case DefaultPriority:
+    case MaybePriority:
+      break;
+    default:
+      priorityLevel = DefaultPriority;
+  }
+
+  var previousPriorityLevel = currentPriorityLevel;
+  var previousEventStartTime = currentEventStartTime;
+  currentPriorityLevel = priorityLevel;
+  currentEventStartTime = getCurrentTime();
+
+  try {
+    return eventHandler();
+  } finally {
+    currentPriorityLevel = previousPriorityLevel;
+    currentEventStartTime = previousEventStartTime;
+    flushImmediateWork();
   }
 }
 
-function unstable_scheduleWork(callback, options) {
-  var currentTime = getCurrentTime();
+function unstable_wrap(callback) {
+  var parentPriorityLevel = currentPriorityLevel;
+  return function() {
+    var previousPriorityLevel = currentPriorityLevel;
+    var previousEventStartTime = currentEventStartTime;
+    currentPriorityLevel = parentPriorityLevel;
+    currentEventStartTime = getCurrentTime();
+
+    try {
+      return callback.apply(this, arguments);
+    } finally {
+      currentPriorityLevel = previousPriorityLevel;
+      currentEventStartTime = previousEventStartTime;
+      flushImmediateWork();
+    }
+  };
+}
 
-  var timesOutAt;
+function unstable_scheduleWork(callback, deprecated_options) {
+  var startTime =
+    currentEventStartTime !== -1 ? currentEventStartTime : getCurrentTime();
+
+  var expirationTime;
   if (
-    options !== undefined &&
-    options !== null &&
-    options.timeout !== null &&
-    options.timeout !== undefined
+    typeof deprecated_options === 'object' &&
+    deprecated_options !== null &&
+    typeof deprecated_options.timeout === 'number'
   ) {
-    // Check for an explicit timeout
-    timesOutAt = currentTime + options.timeout;
+    // FIXME: Remove this branch once we lift expiration times out of React.
+    expirationTime = startTime + deprecated_options.timeout;
   } else {
-    // Compute an absolute timeout using the default constant.
-    timesOutAt = currentTime + DEFERRED_TIMEOUT;
+    switch (currentPriorityLevel) {
+      case ImmediatePriority:
+        expirationTime = startTime + IMMEDIATE_PRIORITY_TIMEOUT;
+        break;
+      case InteractivePriority:
+        expirationTime = startTime + INTERACTIVE_PRIORITY_TIMEOUT;
+        break;
+      case MaybePriority:
+        expirationTime = startTime + MAYBE_PRIORITY_TIMEOUT;
+        break;
+      case DefaultPriority:
+      default:
+        expirationTime = startTime + DEFAULT_PRIORITY_TIMEOUT;
+    }
   }
 
   var newNode = {
     callback,
-    timesOutAt,
+    priorityLevel: currentPriorityLevel,
+    expirationTime,
     next: null,
     previous: null,
   };
@@ -159,20 +331,20 @@ function unstable_scheduleWork(callback, options) {
     var next = null;
     var node = firstCallbackNode;
     do {
-      if (node.timesOutAt > timesOutAt) {
-        // The new callback times out before this one.
+      if (node.expirationTime > expirationTime) {
+        // The new callback expires before this one.
         next = node;
         break;
       }
       node = node.next;
     } while (node !== firstCallbackNode);
 
     if (next === null) {
-      // No callback with a later timeout was found, which means the new
-      // callback has the latest timeout in the list.
+      // No callback with a later expiration was found, which means the new
+      // callback has the latest expiration in the list.
       next = firstCallbackNode;
     } else if (next === firstCallbackNode) {
-      // The new callback has the earliest timeout in the entire list.
+      // The new callback has the earliest expiration in the entire list.
       firstCallbackNode = newNode;
       ensureHostCallbackIsScheduled(firstCallbackNode);
     }
@@ -299,6 +471,7 @@ if (typeof window === 'undefined') {
   getFrameDeadline = impl[2];
 } else {
   if (typeof console !== 'undefined') {
+    // TODO: Remove fb.me link
     if (typeof localRequestAnimationFrame !== 'function') {
       console.error(
         "This browser doesn't support requestAnimationFrame. " +
@@ -441,7 +614,12 @@ if (typeof window === 'undefined') {
 }
 
 export {
+  ImmediatePriority as unstable_ImmediatePriority,
+  InteractivePriority as unstable_InteractivePriority,
+  DefaultPriority as unstable_DefaultPriority,
+  unstable_runWithPriority,
   unstable_scheduleWork,
   unstable_cancelScheduledWork,
+  unstable_wrap,
   getCurrentTime as unstable_now,
 };