The Tor Browser / file revision

 /* -*- 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 = [

   "Promise"

 ];

 /**

  * This module implements the "promise" construct, according to the

  * "Promises/A+" proposal as known in April 2013, documented here:

  *

  * <http://promises-aplus.github.com/promises-spec/>

  *

  * A promise is an object representing a value that may not be available yet.

  * Internally, a promise can be in one of three states:

  *

  * - Pending, when the final value is not available yet.  This is the only state

  *   that may transition to one of the other two states.

  *

  * - Resolved, when and if the final value becomes available.  A resolution

  *   value becomes permanently associated with the promise.  This may be any

  *   value, including "undefined".

  *

  * - Rejected, if an error prevented the final value from being determined.  A

  *   rejection reason becomes permanently associated with the promise.  This may

  *   be any value, including "undefined", though it is generally an Error

  *   object, like in exception handling.

  *

  * A reference to an existing promise may be received by different means, for

  * example as the return value of a call into an asynchronous API.  In this

  * case, the state of the promise can be observed but not directly controlled.

  *

  * To observe the state of a promise, its "then" method must be used.  This

  * method registers callback functions that are called as soon as the promise is

  * either resolved or rejected.  The method returns a new promise, that in turn

  * is resolved or rejected depending on the state of the original promise and on

  * the behavior of the callbacks.  For example, unhandled exceptions in the

  * callbacks cause the new promise to be rejected, even if the original promise

  * is resolved.  See the documentation of the "then" method for details.

  *

  * Promises may also be created using the "Promise.defer" function, the main

  * entry point of this module.  The function, along with the new promise,

  * returns separate methods to change its state to be resolved or rejected.

  * See the documentation of the "Deferred" prototype for details.

  *

  * -----------------------------------------------------------------------------

  *

  * Cu.import("resource://gre/modules/Promise.jsm");

  *

  * // This function creates and returns a new promise.

  * function promiseValueAfterTimeout(aValue, aTimeout)

  * {

  *   let deferred = Promise.defer();

  *

  *   try {

  *     // An asynchronous operation will trigger the resolution of the promise.

  *     // In this example, we don't have a callback that triggers a rejection.

  *     do_timeout(aTimeout, function () {

  *       deferred.resolve(aValue);

  *     });

  *   } catch (ex) {

  *     // Generally, functions returning promises propagate exceptions through

  *     // the returned promise, though they may also choose to fail early.

  *     deferred.reject(ex);

  *   }

  *

  *   // We don't return the deferred to the caller, but only the contained

  *   // promise, so that the caller cannot accidentally change its state.

  *   return deferred.promise;

  * }

  *

  * // This code uses the promise returned be the function above.

  * let promise = promiseValueAfterTimeout("Value", 1000);

  *

  * let newPromise = promise.then(function onResolve(aValue) {

  *   do_print("Resolved with this value: " + aValue);

  * }, function onReject(aReason) {

  *   do_print("Rejected with this reason: " + aReason);

  * });

  *

  * // Unexpected errors should always be reported at the end of a promise chain.

  * newPromise.then(null, Components.utils.reportError);

  *

  * -----------------------------------------------------------------------------

  */

 // These constants must be defined on the "this" object for them to be visible

 // by subscripts in B2G, since "this" does not match the global scope.

 this.Cc = Components.classes;

 this.Ci = Components.interfaces;

 this.Cu = Components.utils;

 this.Cr = Components.results;

 this.Cc["@mozilla.org/moz/jssubscript-loader;1"]

     .getService(this.Ci.mozIJSSubScriptLoader)

     .loadSubScript("resource://gre/modules/Promise-backend.js", this);