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

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

toolkit/modules/Task.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 = [
   "Task"
 ];
 /**
  * This module implements a subset of "Task.js" <http://taskjs.org/>.
  *
  * Paraphrasing from the Task.js site, tasks make sequential, asynchronous
  * operations simple, using the power of JavaScript's "yield" operator.
  *
  * Tasks are built upon generator functions and promises, documented here:
  *
  * <https://developer.mozilla.org/en/JavaScript/Guide/Iterators_and_Generators>
  * <http://wiki.commonjs.org/wiki/Promises/A>
  *
  * The "Task.spawn" function takes a generator function and starts running it as
  * a task.  Every time the task yields a promise, it waits until the promise is
  * fulfilled.  "Task.spawn" returns a promise that is resolved when the task
  * completes successfully, or is rejected if an exception occurs.
  *
  * -----------------------------------------------------------------------------
  *
  * Cu.import("resource://gre/modules/Task.jsm");
  *
  * Task.spawn(function* () {
  *
  *   // This is our task. Let's create a promise object, wait on it and capture
  *   // its resolution value.
  *   let myPromise = getPromiseResolvedOnTimeoutWithValue(1000, "Value");
  *   let result = yield myPromise;
  *
  *   // This part is executed only after the promise above is fulfilled (after
  *   // one second, in this imaginary example).  We can easily loop while
  *   // calling asynchronous functions, and wait multiple times.
  *   for (let i = 0; i < 3; i++) {
  *     result += yield getPromiseResolvedOnTimeoutWithValue(50, "!");
  *   }
  *
  *   return "Resolution result for the task: " + result;
  * }).then(function (result) {
  *
  *   // result == "Resolution result for the task: Value!!!"
  *
  *   // The result is undefined if no value was returned.
  *
  * }, function (exception) {
  *
  *   // Failure!  We can inspect or report the exception.
  *
  * });
  *
  * -----------------------------------------------------------------------------
  *
  * This module implements only the "Task.js" interfaces described above, with no
  * additional features to control the task externally, or do custom scheduling.
  * It also provides the following extensions that simplify task usage in the
  * most common cases:
  *
  * - The "Task.spawn" function also accepts an iterator returned by a generator
  *   function, in addition to a generator function.  This way, you can call into
  *   the generator function with the parameters you want, and with "this" bound
  *   to the correct value.  Also, "this" is never bound to the task object when
  *   "Task.spawn" calls the generator function.
  *
  * - In addition to a promise object, a task can yield the iterator returned by
  *   a generator function.  The iterator is turned into a task automatically.
  *   This reduces the syntax overhead of calling "Task.spawn" explicitly when
  *   you want to recurse into other task functions.
  *
  * - The "Task.spawn" function also accepts a primitive value, or a function
  *   returning a primitive value, and treats the value as the result of the
  *   task.  This makes it possible to call an externally provided function and
  *   spawn a task from it, regardless of whether it is an asynchronous generator
  *   or a synchronous function.  This comes in handy when iterating over
  *   function lists where some items have been converted to tasks and some not.
  */
 ////////////////////////////////////////////////////////////////////////////////
 //// Globals
 const Cc = Components.classes;
 const Ci = Components.interfaces;
 const Cu = Components.utils;
 const Cr = Components.results;
 Cu.import("resource://gre/modules/Promise.jsm");
 // The following error types are considered programmer errors, which should be
 // reported (possibly redundantly) so as to let programmers fix their code.
 const ERRORS_TO_REPORT = ["EvalError", "RangeError", "ReferenceError", "TypeError"];
 /**
  * Detect whether a value is a generator.
  *
  * @param aValue
  *        The value to identify.
  * @return A boolean indicating whether the value is a generator.
  */
 function isGenerator(aValue) {
   return Object.prototype.toString.call(aValue) == "[object Generator]";
 }
 ////////////////////////////////////////////////////////////////////////////////
 //// Task
 /**
  * This object provides the public module functions.
  */
 this.Task = {
   /**
    * Creates and starts a new task.
    *
    * @param aTask
    *        - If you specify a generator function, it is called with no
    *          arguments to retrieve the associated iterator.  The generator
    *          function is a task, that is can yield promise objects to wait
    *          upon.
    *        - If you specify the iterator returned by a generator function you
    *          called, the generator function is also executed as a task.  This
    *          allows you to call the function with arguments.
    *        - If you specify a function that is not a generator, it is called
    *          with no arguments, and its return value is used to resolve the
    *          returned promise.
    *        - If you specify anything else, you get a promise that is already
    *          resolved with the specified value.
    *
    * @return A promise object where you can register completion callbacks to be
    *         called when the task terminates.
    */
   spawn: function Task_spawn(aTask) {
     return createAsyncFunction(aTask).call(undefined);
   },
   /**
    * Create and return an 'async function' that starts a new task.
    *
    * This is similar to 'spawn' except that it doesn't immediately start
    * the task, it binds the task to the async function's 'this' object and
    * arguments, and it requires the task to be a function.
    *
    * It simplifies the common pattern of implementing a method via a task,
    * like this simple object with a 'greet' method that has a 'name' parameter
    * and spawns a task to send a greeting and return its reply:
    *
    * let greeter = {
    *   message: "Hello, NAME!",
    *   greet: function(name) {
    *     return Task.spawn((function* () {
    *       return yield sendGreeting(this.message.replace(/NAME/, name));
    *     }).bind(this);
    *   })
    * };
    *
    * With Task.async, the method can be declared succinctly:
    *
    * let greeter = {
    *   message: "Hello, NAME!",
    *   greet: Task.async(function* (name) {
    *     return yield sendGreeting(this.message.replace(/NAME/, name));
    *   })
    * };
    *
    * While maintaining identical semantics:
    *
    * greeter.greet("Mitchell").then((reply) => { ... }); // behaves the same
    *
    * @param aTask
    *        The task function to start.
    *
    * @return A function that starts the task function and returns its promise.
    */
   async: function Task_async(aTask) {
     if (typeof(aTask) != "function") {
       throw new TypeError("aTask argument must be a function");
     }
     return createAsyncFunction(aTask);
   },
   /**
    * Constructs a special exception that, when thrown inside a legacy generator
    * function (non-star generator), allows the associated task to be resolved
    * with a specific value.
    *
    * Example: throw new Task.Result("Value");
    */
   Result: function Task_Result(aValue) {
     this.value = aValue;
   }
 };
 function createAsyncFunction(aTask) {
   let asyncFunction = function () {
     let result = aTask;
     if (aTask && typeof(aTask) == "function") {
       if (aTask.isAsyncFunction) {
         throw new TypeError(
           "Cannot use an async function in place of a promise. " +
           "You should either invoke the async function first " +
           "or use 'Task.spawn' instead of 'Task.async' to start " +
           "the Task and return its promise.");
       }
       try {
         // Let's call into the function ourselves.
         result = aTask.apply(this, arguments);
       } catch (ex if ex instanceof Task.Result) {
         return Promise.resolve(ex.value);
       } catch (ex) {
         return Promise.reject(ex);
       }
     }
     if (isGenerator(result)) {
       // This is an iterator resulting from calling a generator function.
       return new TaskImpl(result).deferred.promise;
     }
     // Just propagate the given value to the caller as a resolved promise.
     return Promise.resolve(result);
   };
   asyncFunction.isAsyncFunction = true;
   return asyncFunction;
 }
 ////////////////////////////////////////////////////////////////////////////////
 //// TaskImpl
 /**
  * Executes the specified iterator as a task, and gives access to the promise
  * that is fulfilled when the task terminates.
  */
 function TaskImpl(iterator) {
   this.deferred = Promise.defer();
   this._iterator = iterator;
   this._isStarGenerator = !("send" in iterator);
   this._run(true);
 }
 TaskImpl.prototype = {
   /**
    * Includes the promise object where task completion callbacks are registered,
    * and methods to resolve or reject the promise at task completion.
    */
   deferred: null,
   /**
    * The iterator returned by the generator function associated with this task.
    */
   _iterator: null,
   /**
    * Whether this Task is using a star generator.
    */
   _isStarGenerator: false,
   /**
    * Main execution routine, that calls into the generator function.
    *
    * @param aSendResolved
    *        If true, indicates that we should continue into the generator
    *        function regularly (if we were waiting on a promise, it was
    *        resolved). If true, indicates that we should cause an exception to
    *        be thrown into the generator function (if we were waiting on a
    *        promise, it was rejected).
    * @param aSendValue
    *        Resolution result or rejection exception, if any.
    */
   _run: function TaskImpl_run(aSendResolved, aSendValue) {
     if (this._isStarGenerator) {
       try {
         let result = aSendResolved ? this._iterator.next(aSendValue)
                                    : this._iterator.throw(aSendValue);
         if (result.done) {
           // The generator function returned.
           this.deferred.resolve(result.value);
         } else {
           // The generator function yielded.
           this._handleResultValue(result.value);
         }
       } catch (ex) {
         // The generator function failed with an uncaught exception.
         this._handleException(ex);
       }
     } else {
       try {
         let yielded = aSendResolved ? this._iterator.send(aSendValue)
                                     : this._iterator.throw(aSendValue);
         this._handleResultValue(yielded);
       } catch (ex if ex instanceof Task.Result) {
         // The generator function threw the special exception that allows it to
         // return a specific value on resolution.
         this.deferred.resolve(ex.value);
       } catch (ex if ex instanceof StopIteration) {
         // The generator function terminated with no specific result.
         this.deferred.resolve();
       } catch (ex) {
         // The generator function failed with an uncaught exception.
         this._handleException(ex);
       }
     }
   },
   /**
    * Handle a value yielded by a generator.
    *
    * @param aValue
    *        The yielded value to handle.
    */
   _handleResultValue: function TaskImpl_handleResultValue(aValue) {
     // If our task yielded an iterator resulting from calling another
     // generator function, automatically spawn a task from it, effectively
     // turning it into a promise that is fulfilled on task completion.
     if (isGenerator(aValue)) {
       aValue = Task.spawn(aValue);
     }
     if (aValue && typeof(aValue.then) == "function") {
       // We have a promise object now. When fulfilled, call again into this
       // function to continue the task, with either a resolution or rejection
       // condition.
       aValue.then(this._run.bind(this, true),
                   this._run.bind(this, false));
     } else {
       // If our task yielded a value that is not a promise, just continue and
       // pass it directly as the result of the yield statement.
       this._run(true, aValue);
     }
   },
   /**
    * Handle an uncaught exception thrown from a generator.
    *
    * @param aException
    *        The uncaught exception to handle.
    */
   _handleException: function TaskImpl_handleException(aException) {
     if (aException && typeof aException == "object" && "name" in aException &&
         ERRORS_TO_REPORT.indexOf(aException.name) != -1) {
       // We suspect that the exception is a programmer error, so we now
       // display it using dump().  Note that we do not use Cu.reportError as
       // we assume that this is a programming error, so we do not want end
       // users to see it. Also, if the programmer handles errors correctly,
       // they will either treat the error or log them somewhere.
       let stack = ("stack" in aException) ? aException.stack : "not available";
       dump("*************************\n");
       dump("A coding exception was thrown and uncaught in a Task.\n\n");
       dump("Full message: " + aException + "\n");
       dump("Full stack: " + stack + "\n");
       dump("*************************\n");
     }
     this.deferred.reject(aException);
   }
 };

The Tor Browser / annotate

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

toolkit/modules/Task.jsm