/* -*- 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: * * * * 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); * * ----------------------------------------------------------------------------- */ //////////////////////////////////////////////////////////////////////////////// //// Globals const Cc = Components.classes; const Ci = Components.interfaces; const Cu = Components.utils; const Cr = Components.results; Cu.import("resource://gre/modules/Services.jsm"); const STATUS_PENDING = 0; const STATUS_RESOLVED = 1; const STATUS_REJECTED = 2; // These "private names" allow some properties of the Promise object to be // accessed only by this module, while still being visible on the object // manually when using a debugger. They don't strictly guarantee that the // properties are inaccessible by other code, but provide enough protection to // avoid using them by mistake. const salt = Math.floor(Math.random() * 100); const Name = (n) => "{private:" + n + ":" + salt + "}"; const N_STATUS = Name("status"); const N_VALUE = Name("value"); const N_HANDLERS = Name("handlers"); //////////////////////////////////////////////////////////////////////////////// //// Promise /** * This object provides the public module functions. */ this.Promise = Object.freeze({ /** * Creates a new pending promise and provides methods to resolve or reject it. * * @return A new object, containing the new promise in the "promise" property, * and the methods to change its state in the "resolve" and "reject" * properties. See the Deferred documentation for details. */ defer: function () { return new Deferred(); }, /** * Creates a new promise resolved with the specified value, or propagates the * state of an existing promise. * * @param aValue * If this value is not a promise, including "undefined", it becomes * the resolution value of the returned promise. If this value is a * promise, then the returned promise will eventually assume the same * state as the provided promise. * * @return A promise that can be pending, resolved, or rejected. */ resolve: function (aValue) { let promise = new PromiseImpl(); PromiseWalker.completePromise(promise, STATUS_RESOLVED, aValue); return promise; }, /** * Creates a new promise rejected with the specified reason. * * @param aReason * The rejection reason for the returned promise. Although the reason * can be "undefined", it is generally an Error object, like in * exception handling. * * @return A rejected promise. * * @note The aReason argument should not be a promise. Using a rejected * promise for the value of aReason would make the rejection reason * equal to the rejected promise itself, and not its rejection reason. */ reject: function (aReason) { let promise = new PromiseImpl(); PromiseWalker.completePromise(promise, STATUS_REJECTED, aReason); return promise; }, }); //////////////////////////////////////////////////////////////////////////////// //// PromiseWalker /** * This singleton object invokes the handlers registered on resolved and * rejected promises, ensuring that processing is not recursive and is done in * the same order as registration occurred on each promise. * * There is no guarantee on the order of execution of handlers registered on * different promises. */ this.PromiseWalker = { /** * Singleton array of all the unprocessed handlers currently registered on * resolved or rejected promises. Handlers are removed from the array as soon * as they are processed. */ handlers: [], /** * Called when a promise needs to change state to be resolved or rejected. * * @param aPromise * Promise that needs to change state. If this is already resolved or * rejected, this method has no effect. * @param aStatus * New desired status, either STATUS_RESOLVED or STATUS_REJECTED. * @param aValue * Associated resolution value or rejection reason. */ completePromise: function (aPromise, aStatus, aValue) { // Do nothing if the promise is already resolved or rejected. if (aPromise[N_STATUS] != STATUS_PENDING) { return; } // Resolving with another promise will cause this promise to eventually // assume the state of the provided promise. if (aStatus == STATUS_RESOLVED && aValue && typeof(aValue.then) == "function") { aValue.then(this.completePromise.bind(this, aPromise, STATUS_RESOLVED), this.completePromise.bind(this, aPromise, STATUS_REJECTED)); return; } // Change the promise status and schedule our handlers for processing. aPromise[N_STATUS] = aStatus; aPromise[N_VALUE] = aValue; if (aPromise[N_HANDLERS].length > 0) { this.schedulePromise(aPromise); } }, /** * Schedules the resolution or rejection handlers registered on the provided * promise for processing. * * @param aPromise * Resolved or rejected promise whose handlers should be processed. It * is expected that this promise has at least one handler to process. */ schedulePromise: function (aPromise) { // Migrate the handlers from the provided promise to the global list. for (let handler of aPromise[N_HANDLERS]) { this.handlers.push(handler); } aPromise[N_HANDLERS].length = 0; // Schedule the walker loop on the next tick of the event loop. if (!this.walkerLoopScheduled) { this.walkerLoopScheduled = true; Services.tm.currentThread.dispatch(this.walkerLoop, Ci.nsIThread.DISPATCH_NORMAL); } }, /** * Indicates whether the walker loop is currently scheduled for execution on * the next tick of the event loop. */ walkerLoopScheduled: false, /** * Processes all the known handlers during this tick of the event loop. This * eager processing is done to avoid unnecessarily exiting and re-entering the * JavaScript context for each handler on a resolved or rejected promise. * * This function is called with "this" bound to the PromiseWalker object. */ walkerLoop: function () { // Allow rescheduling the walker loop immediately. This makes this walker // resilient to the case where one handler does not return, but starts a // nested event loop. In that case, the newly scheduled walker will take // over. In the common case, the newly scheduled walker will be invoked // after this one has returned, with no actual handler to process. This // small overhead is required to make nested event loops work correctly, but // occurs at most once per resolution chain, thus having only a minor // impact on overall performance. this.walkerLoopScheduled = false; // Process all the known handlers eagerly. while (this.handlers.length > 0) { this.handlers.shift().process(); } }, }; // Bind the function to the singleton once. PromiseWalker.walkerLoop = PromiseWalker.walkerLoop.bind(PromiseWalker); //////////////////////////////////////////////////////////////////////////////// //// Deferred /** * Returned by "Promise.defer" to provide a new promise along with methods to * change its state. */ function Deferred() { this.promise = new PromiseImpl(); this.resolve = this.resolve.bind(this); this.reject = this.reject.bind(this); Object.freeze(this); } Deferred.prototype = { /** * A newly created promise, initially in the pending state. */ promise: null, /** * Resolves the associated promise with the specified value, or propagates the * state of an existing promise. If the associated promise has already been * resolved or rejected, this method does nothing. * * This function is bound to its associated promise when "Promise.defer" is * called, and can be called with any value of "this". * * @param aValue * If this value is not a promise, including "undefined", it becomes * the resolution value of the associated promise. If this value is a * promise, then the associated promise will eventually assume the same * state as the provided promise. * * @note Calling this method with a pending promise as the aValue argument, * and then calling it again with another value before the promise is * resolved or rejected, has unspecified behavior and should be avoided. */ resolve: function (aValue) { PromiseWalker.completePromise(this.promise, STATUS_RESOLVED, aValue); }, /** * Rejects the associated promise with the specified reason. If the promise * has already been resolved or rejected, this method does nothing. * * This function is bound to its associated promise when "Promise.defer" is * called, and can be called with any value of "this". * * @param aReason * The rejection reason for the associated promise. Although the * reason can be "undefined", it is generally an Error object, like in * exception handling. * * @note The aReason argument should not generally be a promise. In fact, * using a rejected promise for the value of aReason would make the * rejection reason equal to the rejected promise itself, not to the * rejection reason of the rejected promise. */ reject: function (aReason) { PromiseWalker.completePromise(this.promise, STATUS_REJECTED, aReason); }, }; //////////////////////////////////////////////////////////////////////////////// //// PromiseImpl /** * The promise object implementation. This includes the public "then" method, * as well as private state properties. */ function PromiseImpl() { /* * Internal status of the promise. This can be equal to STATUS_PENDING, * STATUS_RESOLVED, or STATUS_REJECTED. */ Object.defineProperty(this, N_STATUS, { value: STATUS_PENDING, writable: true }); /* * When the N_STATUS property is STATUS_RESOLVED, this contains the final * resolution value, that cannot be a promise, because resolving with a * promise will cause its state to be eventually propagated instead. When the * N_STATUS property is STATUS_REJECTED, this contains the final rejection * reason, that could be a promise, even if this is uncommon. */ Object.defineProperty(this, N_VALUE, { writable: true }); /* * Array of Handler objects registered by the "then" method, and not processed * yet. Handlers are removed when the promise is resolved or rejected. */ Object.defineProperty(this, N_HANDLERS, { value: [] }); Object.seal(this); } PromiseImpl.prototype = { /** * Calls one of the provided functions as soon as this promise is either * resolved or rejected. A new promise is returned, whose state evolves * depending on this promise and the provided callback functions. * * The appropriate callback is always invoked after this method returns, even * if this promise is already resolved or rejected. You can also call the * "then" method multiple times on the same promise, and the callbacks will be * invoked in the same order as they were registered. * * @param aOnResolve * If the promise is resolved, this function is invoked with the * resolution value of the promise as its only argument, and the * outcome of the function determines the state of the new promise * returned by the "then" method. In case this parameter is not a * function (usually "null"), the new promise returned by the "then" * method is resolved with the same value as the original promise. * * @param aOnReject * If the promise is rejected, this function is invoked with the * rejection reason of the promise as its only argument, and the * outcome of the function determines the state of the new promise * returned by the "then" method. In case this parameter is not a * function (usually left "undefined"), the new promise returned by the * "then" method is rejected with the same reason as the original * promise. * * @return A new promise that is initially pending, then assumes a state that * depends on the outcome of the invoked callback function: * - If the callback returns a value that is not a promise, including * "undefined", the new promise is resolved with this resolution * value, even if the original promise was rejected. * - If the callback throws an exception, the new promise is rejected * with the exception as the rejection reason, even if the original * promise was resolved. * - If the callback returns a promise, the new promise will * eventually assume the same state as the returned promise. * * @note If the aOnResolve callback throws an exception, the aOnReject * callback is not invoked. You can register a rejection callback on * the returned promise instead, to process any exception occurred in * either of the callbacks registered on this promise. */ then: function (aOnResolve, aOnReject) { let handler = new Handler(this, aOnResolve, aOnReject); this[N_HANDLERS].push(handler); // Ensure the handler is scheduled for processing if this promise is already // resolved or rejected. if (this[N_STATUS] != STATUS_PENDING) { PromiseWalker.schedulePromise(this); } return handler.nextPromise; }, }; //////////////////////////////////////////////////////////////////////////////// //// Handler /** * Handler registered on a promise by the "then" function. */ function Handler(aThisPromise, aOnResolve, aOnReject) { this.thisPromise = aThisPromise; this.onResolve = aOnResolve; this.onReject = aOnReject; this.nextPromise = new PromiseImpl(); } Handler.prototype = { /** * Promise on which the "then" method was called. */ thisPromise: null, /** * Unmodified resolution handler provided to the "then" method. */ onResolve: null, /** * Unmodified rejection handler provided to the "then" method. */ onReject: null, /** * New promise that will be returned by the "then" method. */ nextPromise: null, /** * Called after thisPromise is resolved or rejected, invokes the appropriate * callback and propagates the result to nextPromise. */ process: function() { // The state of this promise is propagated unless a handler is defined. let nextStatus = this.thisPromise[N_STATUS]; let nextValue = this.thisPromise[N_VALUE]; try { // If a handler is defined for either resolution or rejection, invoke it // to determine the state of the next promise, that will be resolved with // the returned value, that can also be another promise. if (nextStatus == STATUS_RESOLVED) { if (typeof(this.onResolve) == "function") { nextValue = this.onResolve(nextValue); } } else if (typeof(this.onReject) == "function") { nextValue = this.onReject(nextValue); nextStatus = STATUS_RESOLVED; } } catch (ex) { // If an exception occurred in the handler, reject the next promise. nextStatus = STATUS_REJECTED; nextValue = ex; } // Propagate the newly determined state to the next promise. PromiseWalker.completePromise(this.nextPromise, nextStatus, nextValue); }, };