Handle deferred processing when document is hidden

packages/messaging/src/index.ts

@@ -195,6 +195,29 @@ export type MessageHook =
  * The namespace for the global singleton message loop.
  */
 export namespace MessageLoop {
+  /**
+   * A function that cancels the pending loop task; `null` if unavailable.
+   */
+  let pending: (() => void) | null = null;
+
+  /**
+   * Schedules a function for invocation as soon as possible asynchronously.
+   *
+   * @param fn The function to invoke when called back.
+   *
+   * @returns An anonymous function that will unschedule invocation if possible.
+   */
+  const schedule = (
+    resolved =>
+    (fn: () => unknown): (() => void) => {
+      let rejected = false;
+      resolved.then(() => !rejected && fn());
+      return () => {
+        rejected = true;
+      };
+    }
+  )(Promise.resolve());
+
   /**
    * Send a message to a message handler to process immediately.
    *
@@ -296,7 +319,7 @@ export namespace MessageLoop {
     handler: IMessageHandler,
     hook: MessageHook
   ): void {
-    // Lookup the hooks for the handler.
+    // Look up the hooks for the handler.
     let hooks = messageHooks.get(handler);
 
     // Bail early if the hook is already installed.
@@ -378,8 +401,7 @@ export namespace MessageLoop {
    * Process the pending posted messages in the queue immediately.
    *
    * #### Notes
-   * This function is useful when posted messages must be processed
-   * immediately, instead of on the next animation frame.
+   * This function is useful when posted messages must be processed immediately.
    *
    * This function should normally not be needed, but it may be
    * required to work around certain browser idiosyncrasies.
@@ -388,12 +410,13 @@ export namespace MessageLoop {
    */
   export function flush(): void {
     // Bail if recursion is detected or if there is no pending task.
-    if (flushGuard || loopTaskID === 0) {
+    if (flushGuard || pending === null) {
       return;
     }
 
     // Unschedule the pending loop task.
-    unschedule(loopTaskID);
+    pending();
+    pending = null;
 
     // Run the message loop within the recursion guard.
     flushGuard = true;
@@ -467,34 +490,11 @@ export namespace MessageLoop {
     console.error(err);
   };
 
-  type ScheduleHandle = number | any; //  requestAnimationFrame (number) and setImmediate (any)
-
-  /**
-   * The id of the pending loop task animation frame.
-   */
-  let loopTaskID: ScheduleHandle = 0;
-
   /**
    * A guard flag to prevent flush recursion.
    */
   let flushGuard = false;
 
-  /**
-   * A function to schedule an event loop callback.
-   */
-  const schedule = ((): ScheduleHandle => {
-    let ok = typeof requestAnimationFrame === 'function';
-    return ok ? requestAnimationFrame : setImmediate;
-  })();
-
-  /**
-   * A function to unschedule an event loop callback.
-   */
-  const unschedule = (() => {
-    let ok = typeof cancelAnimationFrame === 'function';
-    return ok ? cancelAnimationFrame : clearImmediate;
-  })();
-
   /**
    * Invoke a message hook with the specified handler and message.
    *
@@ -543,12 +543,12 @@ export namespace MessageLoop {
     messageQueue.addLast({ handler, msg });
 
     // Bail if a loop task is already pending.
-    if (loopTaskID !== 0) {
+    if (pending !== null) {
       return;
     }
 
     // Schedule a run of the message loop.
-    loopTaskID = schedule(runMessageLoop);
+    pending = schedule(runMessageLoop);
   }
 
   /**
@@ -559,8 +559,8 @@ export namespace MessageLoop {
    * be processed on the next cycle of the loop.
    */
   function runMessageLoop(): void {
-    // Clear the task ID so the next loop can be scheduled.
-    loopTaskID = 0;
+    // Clear the task so the next loop can be scheduled.
+    pending = null;
 
     // If the message queue is empty, there is nothing else to do.
     if (messageQueue.isEmpty) {

packages/messaging/tests/src/index.spec.ts

@@ -472,6 +472,7 @@ describe('@lumino/messaging', () => {
 
     describe('flush()', () => {
       it('should immediately process all posted messages', () => {
+        const expected = ['one', 'two', 'three', 'six', 'four', 'five'];
         let h1 = new Handler();
         let h2 = new Handler();
         MessageLoop.postMessage(h1, new Message('one'));
@@ -480,9 +481,21 @@ describe('@lumino/messaging', () => {
         MessageLoop.postMessage(h2, new Message('two'));
         MessageLoop.postMessage(h1, new Message('three'));
         MessageLoop.postMessage(h2, new Message('three'));
+
         MessageLoop.flush();
-        expect(h1.messages).to.deep.equal(['one', 'two', 'three']);
-        expect(h2.messages).to.deep.equal(['one', 'two', 'three']);
+
+        MessageLoop.postMessage(h1, new Message('four'));
+        MessageLoop.postMessage(h2, new Message('four'));
+        MessageLoop.postMessage(h1, new Message('five'));
+        MessageLoop.postMessage(h2, new Message('five'));
+
+        MessageLoop.sendMessage(h1, new Message('six'));
+        MessageLoop.sendMessage(h2, new Message('six'));
+
+        MessageLoop.flush();
+
+        expect(h1.messages).to.deep.equal(expected);
+        expect(h2.messages).to.deep.equal(expected);
       });
 
       it('should ignore recursive calls', () => {

packages/polling/src/poll.ts

@@ -32,6 +32,7 @@ export class Poll<T = any, U = any, V extends string = 'standby'>
    */
   constructor(options: Poll.IOptions<T, U, V>) {
     this._factory = options.factory;
+    this._linger = options.linger ?? Private.DEFAULT_LINGER;
     this._standby = options.standby || Private.DEFAULT_STANDBY;
     this._state = { ...Private.DEFAULT_STATE, timestamp: new Date().getTime() };
 
@@ -244,6 +245,8 @@ export class Poll<T = any, U = any, V extends string = 'standby'>
 
       this._execute();
     };
+
+    // Cache the handle in case it needs to be unscheduled.
     this._timeout = setTimeout(execute, state.interval);
   }
 
@@ -274,18 +277,34 @@ export class Poll<T = any, U = any, V extends string = 'standby'>
     });
   }
 
+  /**
+   * Whether the poll is hidden.
+   *
+   * #### Notes
+   * This property is only relevant in a browser context.
+   */
+  protected get hidden(): boolean {
+    return Private.hidden;
+  }
+
   /**
    * Execute a new poll factory promise or stand by if necessary.
    */
   private _execute(): void {
     let standby =
       typeof this.standby === 'function' ? this.standby() : this.standby;
-    standby =
-      standby === 'never'
-        ? false
-        : standby === 'when-hidden'
-        ? !!(typeof document !== 'undefined' && document && document.hidden)
-        : standby;
+
+    // Check if execution should proceed, linger, or stand by.
+    if (standby === 'never') {
+      standby = false;
+    } else if (standby === 'when-hidden') {
+      if (this.hidden) {
+        standby = ++this._lingered > this._linger;
+      } else {
+        this._lingered = 0;
+        standby = false;
+      }
+    }
 
     // If in standby mode schedule next tick without calling the factory.
     if (standby) {
@@ -322,11 +341,13 @@ export class Poll<T = any, U = any, V extends string = 'standby'>
   private _disposed = new Signal<this, void>(this);
   private _factory: Poll.Factory<T, U, V>;
   private _frequency: IPoll.Frequency;
+  private _linger: number;
+  private _lingered = 0;
   private _standby: Poll.Standby | (() => boolean | Poll.Standby);
   private _state: IPoll.State<T, U, V>;
   private _tick = new PromiseDelegate<this>();
   private _ticked = new Signal<this, IPoll.State<T, U, V>>(this);
-  private _timeout?: ReturnType<typeof setTimeout>; // Support node and browser.
+  private _timeout: ReturnType<typeof setTimeout> | undefined;
 }
 
 /**
@@ -371,6 +392,12 @@ export namespace Poll {
      */
     factory: Factory<T, U, V>;
 
+    /**
+     * The number of ticks to linger if poll switches to standby `when-hidden`.
+     * Defaults to `1`.
+     */
+    linger?: number;
+
     /**
      * The polling frequency parameters.
      */
@@ -395,7 +422,7 @@ export namespace Poll {
     standby?: Standby | (() => boolean | Standby);
   }
   /**
-   * An interval value (0ms) that indicates the poll should tick immediately.
+   * An interval value in ms that indicates the poll should tick immediately.
    */
   export const IMMEDIATE = 0;
 
@@ -431,6 +458,11 @@ namespace Private {
     max: 30 * 1000
   };
 
+  /**
+   * The default number of times to `linger` when a poll is hidden.
+   */
+  export const DEFAULT_LINGER = 1;
+
   /**
    * The default poll name.
    */
@@ -461,23 +493,6 @@ namespace Private {
     timestamp: new Date(0).getTime()
   };
 
-  /**
-   * Get a random integer between min and max, inclusive of both.
-   *
-   * #### Notes
-   * From
-   * https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/random#Getting_a_random_integer_between_two_values_inclusive
-   *
-   * From the MDN page: It might be tempting to use Math.round() to accomplish
-   * that, but doing so would cause your random numbers to follow a non-uniform
-   * distribution, which may not be acceptable for your needs.
-   */
-  function getRandomIntInclusive(min: number, max: number) {
-    min = Math.ceil(min);
-    max = Math.floor(max);
-    return Math.floor(Math.random() * (max - min + 1)) + min;
-  }
-
   /**
    * Returns the number of milliseconds to sleep before the next tick.
    *
@@ -500,4 +515,44 @@ namespace Private {
 
     return Math.min(max, random);
   }
+
+  /**
+   * Keep track of whether the document is hidden. This flag is only relevant in
+   * a browser context.
+   *
+   * Listen to `visibilitychange` event to set the `hidden` flag.
+   *
+   * Listening to `pagehide` is also necessary because Safari support for
+   * `visibilitychange` events is partial, cf.
+   * https://developer.mozilla.org/docs/Web/API/Document/visibilitychange_event
+   */
+  export let hidden = (() => {
+    if (typeof document === 'undefined') {
+      return false;
+    }
+    document.addEventListener('visibilitychange', () => {
+      hidden = document.visibilityState === 'hidden';
+    });
+    document.addEventListener('pagehide', () => {
+      hidden = document.visibilityState === 'hidden';
+    });
+    return document.visibilityState === 'hidden';
+  })();
+
+  /**
+   * Get a random integer between min and max, inclusive of both.
+   *
+   * #### Notes
+   * From
+   * https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Math/random#Getting_a_random_integer_between_two_values_inclusive
+   *
+   * From the MDN page: It might be tempting to use Math.round() to accomplish
+   * that, but doing so would cause your random numbers to follow a non-uniform
+   * distribution, which may not be acceptable for your needs.
+   */
+  function getRandomIntInclusive(min: number, max: number) {
+    min = Math.ceil(min);
+    max = Math.floor(max);
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+  }
 }