[schedule] Support multiple callbacks in scheduler (#12746)

* Support using id to cancel scheduled callback

**what is the change?:**
see title

**why make this change?:**
Once we support multiple callbacks you will need to use the id to
specify which callback you mean.

**test plan:**
Added a test, ran all tests, lint, etc.

* ran prettier

* fix lint

* Use object for storing callback info in scheduler

* Wrap initial test in a describe block

* Support multiple callbacks in `ReactScheduler`

**what is the change?:**
We keep a queue of callbacks instead of just one at a time, and call
them in order first by their timeoutTime and then by the order which
they were scheduled in.

**why make this change?:**
We plan on using this module to coordinate JS outside of React, so we
will need to schedule more than one callback at a time.

**test plan:**
Added a boatload of shiny new tests. :)

Plus ran all the old ones.

NOTE: The tests do not yet cover the vital logic of callbacks timing
out, and later commits will add the missing test coverage.

* Heuristic to avoid looking for timed out callbacks when none timed out

**what is the change?:**
Tracks the current soonest timeOut time for all scheduled callbacks.

**why make this change?:**
We were checking every scheduled callback to see if it timed out on
every tick. It's more efficient to skip that O(n) check if we know that
none have timed out.

**test plan:**
Ran existing tests.

Will write new tests to cover timeout behavior in more detail soon.

* Put multiple callback support under a disabled feature flag

**what is the change?:**
See title

**why make this change?:**
We don't have error handling in place yet, so should maintain the old
behavior until that is in place.

But want to get this far to continue making incremental changes.

**test plan:**
Updated and ran tests.

* Hide support for multiple callbacks under a feature flag

**what is the change?:**
see title

**why make this change?:**
We haven't added error handling yet, so should not expose this feature.

**test plan:**
Ran all tests, temporarily split out the tests for multiple callbacks
into separate file. Will recombine once we remove the flag.

* Fix nits from code review

See comments on #12743

* update checklist in comments

* Remove nested loop which calls additional timed out callbacks

**what is the change?:**
We used to re-run any callbacks which time out whilst other callbacks
are running, but now we will only check once for timed out callbacks
then then run them.

**why make this change?:**
To simplify the code and the behavior of this module.

**test plan:**
Ran all existing tests.

* Remove feature flag

**what is the change?:**
see title

**why make this change?:**
Because only React is using this, and it sounds like async. rendering
won't hit any different behavior due to these changes.

**test plan:**
Existing tests pass, and this allowed us to recombine all tests to run
in both 'test' and 'test-build' modes.

* remove outdated file

* fix typo

Author: flarnie

packages/react-scheduler/src/ReactScheduler.js

@@ -14,8 +14,8 @@
  * control than requestAnimationFrame and requestIdleCallback.
  * Current TODO items:
  * X- Pull out the rIC polyfill built into React
- * - Initial test coverage
- * - Support for multiple callbacks
+ * X- Initial test coverage
+ * X- Support for multiple callbacks
  * - Support for two priorities; serial and deferred
  * - Better test coverage
  * - Better docblock
@@ -31,6 +31,11 @@
 // The frame rate is dynamically adjusted.
 
 import type {Deadline} from 'react-reconciler';
+type CallbackConfigType = {|
+  scheduledCallback: Deadline => void,
+  timeoutTime: number,
+  callbackId: number, // used for cancelling
+|};
 
 import ExecutionEnvironment from 'fbjs/lib/ExecutionEnvironment';
 import warning from 'fbjs/lib/warning';
@@ -85,12 +90,31 @@ if (!ExecutionEnvironment.canUseDOM) {
     clearTimeout(timeoutID);
   };
 } else {
-  // Always polyfill requestIdleCallback and cancelIdleCallback
+  // We keep callbacks in a queue.
+  // Calling rIC will push in a new callback at the end of the queue.
+  // When we get idle time, callbacks are removed from the front of the queue
+  // and called.
+  const pendingCallbacks: Array<CallbackConfigType> = [];
 
-  let scheduledRICCallback = null;
-  let isIdleScheduled = false;
-  let timeoutTime = -1;
+  let callbackIdCounter = 0;
+  const getCallbackId = function(): number {
+    callbackIdCounter++;
+    return callbackIdCounter;
+  };
+
+  // When a callback is scheduled, we register it by adding it's id to this
+  // object.
+  // If the user calls 'cIC' with the id of that callback, it will be
+  // unregistered by removing the id from this object.
+  // Then we skip calling any callback which is not registered.
+  // This means cancelling is an O(1) time complexity instead of O(n).
+  const registeredCallbackIds: {[number]: boolean} = {};
 
+  // We track what the next soonest timeoutTime is, to be able to quickly tell
+  // if none of the scheduled callbacks have timed out.
+  let nextSoonestTimeoutTime = -1;
+
+  let isIdleScheduled = false;
   let isAnimationFrameScheduled = false;
 
   let frameDeadline = 0;
@@ -100,14 +124,75 @@ if (!ExecutionEnvironment.canUseDOM) {
   let previousFrameTime = 33;
   let activeFrameTime = 33;
 
-  const frameDeadlineObject = {
+  const frameDeadlineObject: Deadline = {
     didTimeout: false,
     timeRemaining() {
       const remaining = frameDeadline - now();
       return remaining > 0 ? remaining : 0;
     },
   };
 
+  const safelyCallScheduledCallback = function(callback, callbackId) {
+    if (!registeredCallbackIds[callbackId]) {
+      // ignore cancelled callbacks
+      return;
+    }
+    try {
+      callback(frameDeadlineObject);
+      // Avoid using 'catch' to keep errors easy to debug
+    } finally {
+      // always clean up the callbackId, even if the callback throws
+      delete registeredCallbackIds[callbackId];
+    }
+  };
+
+  /**
+   * Checks for timed out callbacks, runs them, and then checks again to see if
+   * any more have timed out.
+   * Keeps doing this until there are none which have currently timed out.
+   */
+  const callTimedOutCallbacks = function() {
+    if (pendingCallbacks.length === 0) {
+      return;
+    }
+
+    const currentTime = now();
+    // TODO: this would be more efficient if deferred callbacks are stored in
+    // min heap.
+    // Or in a linked list with links for both timeoutTime order and insertion
+    // order.
+    // For now an easy compromise is the current approach:
+    // Keep a pointer to the soonest timeoutTime, and check that first.
+    // If it has not expired, we can skip traversing the whole list.
+    // If it has expired, then we step through all the callbacks.
+    if (nextSoonestTimeoutTime === -1 || nextSoonestTimeoutTime > currentTime) {
+      // We know that none of them have timed out yet.
+      return;
+    }
+    nextSoonestTimeoutTime = -1; // we will reset it below
+
+    // keep checking until we don't find any more timed out callbacks
+    frameDeadlineObject.didTimeout = true;
+    for (let i = 0, len = pendingCallbacks.length; i < len; i++) {
+      const currentCallbackConfig = pendingCallbacks[i];
+      const timeoutTime = currentCallbackConfig.timeoutTime;
+      if (timeoutTime !== -1 && timeoutTime <= currentTime) {
+        // it has timed out!
+        // call it
+        const callback = currentCallbackConfig.scheduledCallback;
+        safelyCallScheduledCallback(callback, timeoutTime);
+      } else {
+        if (
+          timeoutTime !== -1 &&
+          (nextSoonestTimeoutTime === -1 ||
+            timeoutTime < nextSoonestTimeoutTime)
+        ) {
+          nextSoonestTimeoutTime = timeoutTime;
+        }
+      }
+    }
+  };
+
   // We use the postMessage trick to defer idle work until after the repaint.
   const messageKey =
     '__reactIdleCallback$' +
@@ -119,36 +204,30 @@ if (!ExecutionEnvironment.canUseDOM) {
       return;
     }
 
+    if (pendingCallbacks.length === 0) {
+      return;
+    }
     isIdleScheduled = false;
 
-    const currentTime = now();
-    if (frameDeadline - currentTime <= 0) {
-      // There's no time left in this idle period. Check if the callback has
-      // a timeout and whether it's been exceeded.
-      if (timeoutTime !== -1 && timeoutTime <= currentTime) {
-        // Exceeded the timeout. Invoke the callback even though there's no
-        // time left.
-        frameDeadlineObject.didTimeout = true;
-      } else {
-        // No timeout.
-        if (!isAnimationFrameScheduled) {
-          // Schedule another animation callback so we retry later.
-          isAnimationFrameScheduled = true;
-          requestAnimationFrame(animationTick);
-        }
-        // Exit without invoking the callback.
-        return;
-      }
-    } else {
-      // There's still time left in this idle period.
+    // First call anything which has timed out, until we have caught up.
+    callTimedOutCallbacks();
+
+    let currentTime = now();
+    // Next, as long as we have idle time, try calling more callbacks.
+    while (frameDeadline - currentTime > 0 && pendingCallbacks.length > 0) {
+      const latestCallbackConfig = pendingCallbacks.shift();
       frameDeadlineObject.didTimeout = false;
+      const latestCallback = latestCallbackConfig.scheduledCallback;
+      const newCallbackId = latestCallbackConfig.callbackId;
+      safelyCallScheduledCallback(latestCallback, newCallbackId);
+      currentTime = now();
     }
-
-    timeoutTime = -1;
-    const callback = scheduledRICCallback;
-    scheduledRICCallback = null;
-    if (callback !== null) {
-      callback(frameDeadlineObject);
+    if (pendingCallbacks.length > 0) {
+      if (!isAnimationFrameScheduled) {
+        // Schedule another animation callback so we retry later.
+        isAnimationFrameScheduled = true;
+        requestAnimationFrame(animationTick);
+      }
     }
   };
   // Assumes that we have addEventListener in this environment. Might need
@@ -190,12 +269,23 @@ if (!ExecutionEnvironment.canUseDOM) {
     callback: (deadline: Deadline) => void,
     options?: {timeout: number},
   ): number {
-    // This assumes that we only schedule one callback at a time because that's
-    // how Fiber uses it.
-    scheduledRICCallback = callback;
+    let timeoutTime = -1;
     if (options != null && typeof options.timeout === 'number') {
       timeoutTime = now() + options.timeout;
     }
+    if (timeoutTime > nextSoonestTimeoutTime) {
+      nextSoonestTimeoutTime = timeoutTime;
+    }
+
+    const newCallbackId = getCallbackId();
+    const scheduledCallbackConfig = {
+      scheduledCallback: callback,
+      callbackId: newCallbackId,
+      timeoutTime,
+    };
+    pendingCallbacks.push(scheduledCallbackConfig);
+
+    registeredCallbackIds[newCallbackId] = true;
     if (!isAnimationFrameScheduled) {
       // If rAF didn't already schedule one, we need to schedule a frame.
       // TODO: If this rAF doesn't materialize because the browser throttles, we
@@ -204,13 +294,11 @@ if (!ExecutionEnvironment.canUseDOM) {
       isAnimationFrameScheduled = true;
       requestAnimationFrame(animationTick);
     }
-    return 0;
+    return newCallbackId;
   };
 
-  cIC = function() {
-    scheduledRICCallback = null;
-    isIdleScheduled = false;
-    timeoutTime = -1;
+  cIC = function(callbackId: number) {
+    delete registeredCallbackIds[callbackId];
   };
 }