The Tor Browser: toolkit/modules/DeferredTask.jsm@b8a032363ba2 (annotated)

toolkit/modules/DeferredTask.jsm@b8a032363ba2 (annotated)

toolkit/modules/DeferredTask.jsm

Thu, 22 Jan 2015 13:21:57 +0100

author: Michael Schloh von Bennewitz <michael@schloh.com>
date: Thu, 22 Jan 2015 13:21:57 +0100
branch: TOR_BUG_9701
changeset 15: b8a032363ba2
permissions: -rw-r--r--

Incorporate requested changes from Mozilla in review:
https://bugzilla.mozilla.org/show_bug.cgi?id=1123480#c6

 /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
 /* vim: set ts=2 et sw=2 tw=80 filetype=javascript: */
 /* This Source Code Form is subject to the terms of the Mozilla Public
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
 "use strict";
 this.EXPORTED_SYMBOLS = [
   "DeferredTask",
 ];
 /**
  * Sets up a function or an asynchronous task whose execution can be triggered
  * after a defined delay.  Multiple attempts to run the task before the delay
  * has passed are coalesced.  The task cannot be re-entered while running, but
  * can be executed again after a previous run finished.
  *
  * A common use case occurs when a data structure should be saved into a file
  * every time the data changes, using asynchronous calls, and multiple changes
  * to the data may happen within a short time:
  *
  *   let saveDeferredTask = new DeferredTask(function* () {
  *     yield OS.File.writeAtomic(...);
  *     // Any uncaught exception will be reported.
  *   }, 2000);
  *
  *   // The task is ready, but will not be executed until requested.
  *
  * The "arm" method can be used to start the internal timer that will result in
  * the eventual execution of the task.  Multiple attempts to arm the timer don't
  * introduce further delays:
  *
  *   saveDeferredTask.arm();
  *
  *   // The task will be executed in 2 seconds from now.
  *
  *   yield waitOneSecond();
  *   saveDeferredTask.arm();
  *
  *   // The task will be executed in 1 second from now.
  *
  * The timer can be disarmed to reset the delay, or just to cancel execution:
  *
  *   saveDeferredTask.disarm();
  *   saveDeferredTask.arm();
  *
  *   // The task will be executed in 2 seconds from now.
  *
  * When the internal timer fires and the execution of the task starts, the task
  * cannot be canceled anymore.  It is however possible to arm the timer again
  * during the execution of the task, in which case the task will need to finish
  * before the timer is started again, thus guaranteeing a time of inactivity
  * between executions that is at least equal to the provided delay.
  *
  * The "finalize" method can be used to ensure that the task terminates
  * properly.  The promise it returns is resolved only after the last execution
  * of the task is finished.  To guarantee that the task is executed for the
  * last time, the method prevents any attempt to arm the timer again.
  *
  * If the timer is already armed when the "finalize" method is called, then the
  * task is executed immediately.  If the task was already running at this point,
  * then one last execution from start to finish will happen again, immediately
  * after the current execution terminates.  If the timer is not armed, the
  * "finalize" method only ensures that any running task terminates.
  *
  * For example, during shutdown, you may want to ensure that any pending write
  * is processed, using the latest version of the data if the timer is armed:
  *
  *   AsyncShutdown.profileBeforeChange.addBlocker(
  *     "Example service: shutting down",
  *     () => saveDeferredTask.finalize()
  *   );
  *
  * Instead, if you are going to delete the saved data from disk anyways, you
  * might as well prevent any pending write from starting, while still ensuring
  * that any write that is currently in progress terminates, so that the file is
  * not in use anymore:
  *
  *   saveDeferredTask.disarm();
  *   saveDeferredTask.finalize().then(() => OS.File.remove(...))
  *                              .then(null, Components.utils.reportError);
  */
 ////////////////////////////////////////////////////////////////////////////////
 //// Globals
 const { classes: Cc, interfaces: Ci, utils: Cu, results: Cr } = Components;
 Cu.import("resource://gre/modules/XPCOMUtils.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Promise",
                                   "resource://gre/modules/Promise.jsm");
 XPCOMUtils.defineLazyModuleGetter(this, "Task",
                                   "resource://gre/modules/Task.jsm");
 const Timer = Components.Constructor("@mozilla.org/timer;1", "nsITimer",
                                      "initWithCallback");
 ////////////////////////////////////////////////////////////////////////////////
 //// DeferredTask
 /**
  * Sets up a task whose execution can be triggered after a delay.
  *
  * @param aTaskFn
  *        Function or generator function to execute.  This argument is passed to
  *        the "Task.spawn" method every time the task should be executed.  This
  *        task is never re-entered while running.
  * @param aDelayMs
  *        Time between executions, in milliseconds.  Multiple attempts to run
  *        the task before the delay has passed are coalesced.  This time of
  *        inactivity is guaranteed to pass between multiple executions of the
  *        task, except on finalization, when the task may restart immediately
  *        after the previous execution finished.
  */
 this.DeferredTask = function (aTaskFn, aDelayMs) {
   this._taskFn = aTaskFn;
   this._delayMs = aDelayMs;
 }
 this.DeferredTask.prototype = {
   /**
    * Function or generator function to execute.
    */
   _taskFn: null,
   /**
    * Time between executions, in milliseconds.
    */
   _delayMs: null,
   /**
    * Indicates whether the task is currently requested to start again later,
    * regardless of whether it is currently running.
    */
   get isArmed() this._armed,
   _armed: false,
   /**
    * Indicates whether the task is currently running.  This is always true when
    * read from code inside the task function, but can also be true when read
    * from external code, in case the task is an asynchronous generator function.
    */
   get isRunning() !!this._runningPromise,
   /**
    * Promise resolved when the current execution of the task terminates, or null
    * if the task is not currently running.
    */
   _runningPromise: null,
   /**
    * nsITimer used for triggering the task after a delay, or null in case the
    * task is running or there is no task scheduled for execution.
    */
   _timer: null,
   /**
    * Actually starts the timer with the delay specified on construction.
    */
   _startTimer: function ()
   {
     this._timer = new Timer(this._timerCallback.bind(this), this._delayMs,
                             Ci.nsITimer.TYPE_ONE_SHOT);
   },
   /**
    * Requests the execution of the task after the delay specified on
    * construction.  Multiple calls don't introduce further delays.  If the task
    * is running, the delay will start when the current execution finishes.
    *
    * The task will always be executed on a different tick of the event loop,
    * even if the delay specified on construction is zero.  Multiple "arm" calls
    * within the same tick of the event loop are guaranteed to result in a single
    * execution of the task.
    *
    * @note By design, this method doesn't provide a way for the caller to detect
    *       when the next execution terminates, or collect a result.  In fact,
    *       doing that would often result in duplicate processing or logging.  If
    *       a special operation or error logging is needed on completion, it can
    *       be better handled from within the task itself, for example using a
    *       try/catch/finally clause in the task.  The "finalize" method can be
    *       used in the common case of waiting for completion on shutdown.
    */
   arm: function ()
   {
     if (this._finalized) {
       throw new Error("Unable to arm timer, the object has been finalized.");
     }
     this._armed = true;
     // In case the timer callback is running, do not create the timer now,
     // because this will be handled by the timer callback itself.  Also, the
     // timer is not restarted in case it is already running.
     if (!this._runningPromise && !this._timer) {
       this._startTimer();
     }
   },
   /**
    * Cancels any request for a delayed the execution of the task, though the
    * task itself cannot be canceled in case it is already running.
    *
    * This method stops any currently running timer, thus the delay will restart
    * from its original value in case the "arm" method is called again.
    */
   disarm: function () {
     this._armed = false;
     if (this._timer) {
       // Calling the "cancel" method and discarding the timer reference makes
       // sure that the timer callback will not be called later, even if the
       // timer thread has already posted the timer event on the main thread.
       this._timer.cancel();
       this._timer = null;
     }
   },
   /**
    * Ensures that any pending task is executed from start to finish, while
    * preventing any attempt to arm the timer again.
    *
    * - If the task is running and the timer is armed, then one last execution
    *   from start to finish will happen again, immediately after the current
    *   execution terminates, then the returned promise will be resolved.
    * - If the task is running and the timer is not armed, the returned promise
    *   will be resolved when the current execution terminates.
    * - If the task is not running and the timer is armed, then the task is
    *   started immediately, and the returned promise resolves when the new
    *   execution terminates.
    * - If the task is not running and the timer is not armed, the method returns
    *   a resolved promise.
    *
    * @return {Promise}
    * @resolves After the last execution of the task is finished.
    * @rejects Never.
    */
   finalize: function () {
     if (this._finalized) {
       throw new Error("The object has been already finalized.");
     }
     this._finalized = true;
     // If the timer is armed, it means that the task is not running but it is
     // scheduled for execution.  Cancel the timer and run the task immediately.
     if (this._timer) {
       this.disarm();
       this._timerCallback();
     }
     // Wait for the operation to be completed, or resolve immediately.
     if (this._runningPromise) {
       return this._runningPromise;
     }
     return Promise.resolve();
   },
   _finalized: false,
   /**
    * Timer callback used to run the delayed task.
    */
   _timerCallback: function ()
   {
     let runningDeferred = Promise.defer();
     // All these state changes must occur at the same time directly inside the
     // timer callback, to prevent race conditions and to ensure that all the
     // methods behave consistently even if called from inside the task.  This
     // means that the assignment of "this._runningPromise" must complete before
     // the task gets a chance to start.
     this._timer = null;
     this._armed = false;
     this._runningPromise = runningDeferred.promise;
     runningDeferred.resolve(Task.spawn(function () {
       // Execute the provided function asynchronously.
       yield Task.spawn(this._taskFn).then(null, Cu.reportError);
       // Now that the task has finished, we check the state of the object to
       // determine if we should restart the task again.
       if (this._armed) {
         if (!this._finalized) {
           this._startTimer();
         } else {
           // Execute the task again immediately, for the last time.  The isArmed
           // property should return false while the task is running, and should
           // remain false after the last execution terminates.
           this._armed = false;
           yield Task.spawn(this._taskFn).then(null, Cu.reportError);
         }
       }
       // Indicate that the execution of the task has finished.  This happens
       // synchronously with the previous state changes in the function.
       this._runningPromise = null;
     }.bind(this)).then(null, Cu.reportError));
   },
 };

The Tor Browser / annotate

toolkit/modules/DeferredTask.jsm@b8a032363ba2 (annotated)

toolkit/modules/DeferredTask.jsm