101 lines
4.2 KiB
JavaScript
101 lines
4.2 KiB
JavaScript
/* -*- indent-tabs-mode: nil; js-indent-level: 2 -*- */
|
|
/* 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);
|