summaryrefslogtreecommitdiffstats
path: root/toolkit/modules/Promise-backend.js
diff options
context:
space:
mode:
authorMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
committerMatt A. Tobin <mattatobin@localhost.localdomain>2018-02-02 04:16:08 -0500
commit5f8de423f190bbb79a62f804151bc24824fa32d8 (patch)
tree10027f336435511475e392454359edea8e25895d /toolkit/modules/Promise-backend.js
parent49ee0794b5d912db1f95dce6eb52d781dc210db5 (diff)
downloadUXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.gz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.lz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.tar.xz
UXP-5f8de423f190bbb79a62f804151bc24824fa32d8.zip
Add m-esr52 at 52.6.0
Diffstat (limited to 'toolkit/modules/Promise-backend.js')
-rw-r--r--toolkit/modules/Promise-backend.js970
1 files changed, 970 insertions, 0 deletions
diff --git a/toolkit/modules/Promise-backend.js b/toolkit/modules/Promise-backend.js
new file mode 100644
index 000000000..712a8b4f5
--- /dev/null
+++ b/toolkit/modules/Promise-backend.js
@@ -0,0 +1,970 @@
+/* -*- indent-tabs-mode: nil; js-indent-level: 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 implementation file is imported by the Promise.jsm module, and as a
+ * special case by the debugger server. To support chrome debugging, the
+ * debugger server needs to have all its code in one global, so it must use
+ * loadSubScript directly.
+ *
+ * In the general case, this script should be used by importing Promise.jsm:
+ *
+ * Components.utils.import("resource://gre/modules/Promise.jsm");
+ *
+ * More documentation can be found in the Promise.jsm module.
+ */
+
+// Globals
+
+// Obtain an instance of Cu. How this instance is obtained depends on how this
+// file is loaded.
+//
+// This file can be loaded in three different ways:
+// 1. As a CommonJS module, by Loader.jsm, on the main thread.
+// 2. As a CommonJS module, by worker-loader.js, on a worker thread.
+// 3. As a subscript, by Promise.jsm, on the main thread.
+//
+// If require is defined, the file is loaded as a CommonJS module. Components
+// will not be defined in that case, but we can obtain an instance of Cu from
+// the chrome module. Otherwise, this file is loaded as a subscript, and we can
+// obtain an instance of Cu from Components directly.
+//
+// If the file is loaded as a CommonJS module on a worker thread, the instance
+// of Cu obtained from the chrome module will be null. The reason for this is
+// that Components is not defined in worker threads, so no instance of Cu can
+// be obtained.
+
+var Cu = this.require ? require("chrome").Cu : Components.utils;
+var Cc = this.require ? require("chrome").Cc : Components.classes;
+var Ci = this.require ? require("chrome").Ci : Components.interfaces;
+// If we can access Components, then we use it to capture an async
+// parent stack trace; see scheduleWalkerLoop. However, as it might
+// not be available (see above), users of this must check it first.
+var Components_ = this.require ? require("chrome").components : Components;
+
+// If Cu is defined, use it to lazily define the FinalizationWitnessService.
+if (Cu) {
+ Cu.import("resource://gre/modules/Services.jsm");
+ Cu.import("resource://gre/modules/XPCOMUtils.jsm");
+
+ XPCOMUtils.defineLazyServiceGetter(this, "FinalizationWitnessService",
+ "@mozilla.org/toolkit/finalizationwitness;1",
+ "nsIFinalizationWitnessService");
+
+ // For now, we're worried about add-ons using Promises with CPOWs, so we'll
+ // permit them in this scope, but this support will go away soon.
+ Cu.permitCPOWsInScope(this);
+}
+
+const STATUS_PENDING = 0;
+const STATUS_RESOLVED = 1;
+const STATUS_REJECTED = 2;
+
+// This N_INTERNALS name allow internal properties of the Promise to be
+// accessed only by this module, while still being visible on the object
+// manually when using a debugger. This doesn'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 N_INTERNALS = "{private:internals:" + salt + "}";
+
+// We use DOM Promise for scheduling the walker loop.
+const DOMPromise = Cu ? Promise : null;
+
+// Warn-upon-finalization mechanism
+//
+// One of the difficult problems with promises is locating uncaught
+// rejections. We adopt the following strategy: if a promise is rejected
+// at the time of its garbage-collection *and* if the promise is at the
+// end of a promise chain (i.e. |thatPromise.then| has never been
+// called), then we print a warning.
+//
+// let deferred = Promise.defer();
+// let p = deferred.promise.then();
+// deferred.reject(new Error("I am un uncaught error"));
+// deferred = null;
+// p = null;
+//
+// In this snippet, since |deferred.promise| is not the last in the
+// chain, no error will be reported for that promise. However, since
+// |p| is the last promise in the chain, the error will be reported
+// for |p|.
+//
+// Note that this may, in some cases, cause an error to be reported more
+// than once. For instance, consider:
+//
+// let deferred = Promise.defer();
+// let p1 = deferred.promise.then();
+// let p2 = deferred.promise.then();
+// deferred.reject(new Error("I am an uncaught error"));
+// p1 = p2 = deferred = null;
+//
+// In this snippet, the error is reported both by p1 and by p2.
+//
+
+var PendingErrors = {
+ // An internal counter, used to generate unique id.
+ _counter: 0,
+ // Functions registered to be notified when a pending error
+ // is reported as uncaught.
+ _observers: new Set(),
+ _map: new Map(),
+
+ /**
+ * Initialize PendingErrors
+ */
+ init: function() {
+ Services.obs.addObserver(function observe(aSubject, aTopic, aValue) {
+ PendingErrors.report(aValue);
+ }, "promise-finalization-witness", false);
+ },
+
+ /**
+ * Register an error as tracked.
+ *
+ * @return The unique identifier of the error.
+ */
+ register: function(error) {
+ let id = "pending-error-" + (this._counter++);
+ //
+ // At this stage, ideally, we would like to store the error itself
+ // and delay any treatment until we are certain that we will need
+ // to report that error. However, in the (unlikely but possible)
+ // case the error holds a reference to the promise itself, doing so
+ // would prevent the promise from being garbabe-collected, which
+ // would both cause a memory leak and ensure that we cannot report
+ // the uncaught error.
+ //
+ // To avoid this situation, we rather extract relevant data from
+ // the error and further normalize it to strings.
+ //
+ let value = {
+ date: new Date(),
+ message: "" + error,
+ fileName: null,
+ stack: null,
+ lineNumber: null
+ };
+ try { // Defend against non-enumerable values
+ if (error && error instanceof Ci.nsIException) {
+ // nsIException does things a little differently.
+ try {
+ // For starters |.toString()| does not only contain the message, but
+ // also the top stack frame, and we don't really want that.
+ value.message = error.message;
+ } catch (ex) {
+ // Ignore field
+ }
+ try {
+ // All lowercase filename. ;)
+ value.fileName = error.filename;
+ } catch (ex) {
+ // Ignore field
+ }
+ try {
+ value.lineNumber = error.lineNumber;
+ } catch (ex) {
+ // Ignore field
+ }
+ } else if (typeof error == "object" && error) {
+ for (let k of ["fileName", "stack", "lineNumber"]) {
+ try { // Defend against fallible getters and string conversions
+ let v = error[k];
+ value[k] = v ? ("" + v) : null;
+ } catch (ex) {
+ // Ignore field
+ }
+ }
+ }
+
+ if (!value.stack) {
+ // |error| is not an Error (or Error-alike). Try to figure out the stack.
+ let stack = null;
+ if (error && error.location &&
+ error.location instanceof Ci.nsIStackFrame) {
+ // nsIException has full stack frames in the |.location| member.
+ stack = error.location;
+ } else {
+ // Components.stack to the rescue!
+ stack = Components_.stack;
+ // Remove those top frames that refer to Promise.jsm.
+ while (stack) {
+ if (!stack.filename.endsWith("/Promise.jsm")) {
+ break;
+ }
+ stack = stack.caller;
+ }
+ }
+ if (stack) {
+ let frames = [];
+ while (stack) {
+ frames.push(stack);
+ stack = stack.caller;
+ }
+ value.stack = frames.join("\n");
+ }
+ }
+ } catch (ex) {
+ // Ignore value
+ }
+ this._map.set(id, value);
+ return id;
+ },
+
+ /**
+ * Notify all observers that a pending error is now uncaught.
+ *
+ * @param id The identifier of the pending error, as returned by
+ * |register|.
+ */
+ report: function(id) {
+ let value = this._map.get(id);
+ if (!value) {
+ return; // The error has already been reported
+ }
+ this._map.delete(id);
+ for (let obs of this._observers.values()) {
+ obs(value);
+ }
+ },
+
+ /**
+ * Mark all pending errors are uncaught, notify the observers.
+ */
+ flush: function() {
+ // Since we are going to modify the map while walking it,
+ // let's copying the keys first.
+ for (let key of Array.from(this._map.keys())) {
+ this.report(key);
+ }
+ },
+
+ /**
+ * Stop tracking an error, as this error has been caught,
+ * eventually.
+ */
+ unregister: function(id) {
+ this._map.delete(id);
+ },
+
+ /**
+ * Add an observer notified when an error is reported as uncaught.
+ *
+ * @param {function} observer A function notified when an error is
+ * reported as uncaught. Its arguments are
+ * {message, date, fileName, stack, lineNumber}
+ * All arguments are optional.
+ */
+ addObserver: function(observer) {
+ this._observers.add(observer);
+ },
+
+ /**
+ * Remove an observer added with addObserver
+ */
+ removeObserver: function(observer) {
+ this._observers.delete(observer);
+ },
+
+ /**
+ * Remove all the observers added with addObserver
+ */
+ removeAllObservers: function() {
+ this._observers.clear();
+ }
+};
+
+// Initialize the warn-upon-finalization mechanism if and only if Cu is defined.
+// Otherwise, FinalizationWitnessService won't be defined (see above).
+if (Cu) {
+ PendingErrors.init();
+}
+
+// Default mechanism for displaying errors
+PendingErrors.addObserver(function(details) {
+ const generalDescription = "A promise chain failed to handle a rejection." +
+ " Did you forget to '.catch', or did you forget to 'return'?\nSee" +
+ " https://developer.mozilla.org/Mozilla/JavaScript_code_modules/Promise.jsm/Promise\n\n";
+
+ let error = Cc['@mozilla.org/scripterror;1'].createInstance(Ci.nsIScriptError);
+ if (!error || !Services.console) {
+ // Too late during shutdown to use the nsIConsole
+ dump("*************************\n");
+ dump(generalDescription);
+ dump("On: " + details.date + "\n");
+ dump("Full message: " + details.message + "\n");
+ dump("Full stack: " + (details.stack||"not available") + "\n");
+ dump("*************************\n");
+ return;
+ }
+ let message = details.message;
+ if (details.stack) {
+ message += "\nFull Stack: " + details.stack;
+ }
+ error.init(
+ /* message*/ generalDescription +
+ "Date: " + details.date + "\nFull Message: " + message,
+ /* sourceName*/ details.fileName,
+ /* sourceLine*/ details.lineNumber?("" + details.lineNumber):0,
+ /* lineNumber*/ details.lineNumber || 0,
+ /* columnNumber*/ 0,
+ /* flags*/ Ci.nsIScriptError.errorFlag,
+ /* category*/ "chrome javascript");
+ Services.console.logMessage(error);
+});
+
+
+// Additional warnings for developers
+//
+// 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"];
+
+// Promise
+
+/**
+ * The Promise constructor. Creates a new promise given an executor callback.
+ * The executor callback is called with the resolve and reject handlers.
+ *
+ * @param aExecutor
+ * The callback that will be called with resolve and reject.
+ */
+this.Promise = function Promise(aExecutor)
+{
+ if (typeof(aExecutor) != "function") {
+ throw new TypeError("Promise constructor must be called with an executor.");
+ }
+
+ /*
+ * Object holding all of our internal values we associate with the promise.
+ */
+ Object.defineProperty(this, N_INTERNALS, { value: {
+ /*
+ * Internal status of the promise. This can be equal to STATUS_PENDING,
+ * STATUS_RESOLVED, or STATUS_REJECTED.
+ */
+ status: STATUS_PENDING,
+
+ /*
+ * When the 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
+ * status property is STATUS_REJECTED, this contains the final rejection
+ * reason, that could be a promise, even if this is uncommon.
+ */
+ value: undefined,
+
+ /*
+ * Array of Handler objects registered by the "then" method, and not processed
+ * yet. Handlers are removed when the promise is resolved or rejected.
+ */
+ handlers: [],
+
+ /**
+ * When the status property is STATUS_REJECTED and until there is
+ * a rejection callback, this contains an array
+ * - {string} id An id for use with |PendingErrors|;
+ * - {FinalizationWitness} witness A witness broadcasting |id| on
+ * notification "promise-finalization-witness".
+ */
+ witness: undefined
+ }});
+
+ Object.seal(this);
+
+ let resolve = PromiseWalker.completePromise
+ .bind(PromiseWalker, this, STATUS_RESOLVED);
+ let reject = PromiseWalker.completePromise
+ .bind(PromiseWalker, this, STATUS_REJECTED);
+
+ try {
+ aExecutor.call(undefined, resolve, reject);
+ } catch (ex) {
+ reject(ex);
+ }
+}
+
+/**
+ * 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.
+ */
+Promise.prototype.then = function (aOnResolve, aOnReject)
+{
+ let handler = new Handler(this, aOnResolve, aOnReject);
+ this[N_INTERNALS].handlers.push(handler);
+
+ // Ensure the handler is scheduled for processing if this promise is already
+ // resolved or rejected.
+ if (this[N_INTERNALS].status != STATUS_PENDING) {
+
+ // This promise is not the last in the chain anymore. Remove any watchdog.
+ if (this[N_INTERNALS].witness != null) {
+ let [id, witness] = this[N_INTERNALS].witness;
+ this[N_INTERNALS].witness = null;
+ witness.forget();
+ PendingErrors.unregister(id);
+ }
+
+ PromiseWalker.schedulePromise(this);
+ }
+
+ return handler.nextPromise;
+};
+
+/**
+ * Invokes `promise.then` with undefined for the resolve handler and a given
+ * reject handler.
+ *
+ * @param aOnReject
+ * The rejection handler.
+ *
+ * @return A new pending promise returned.
+ *
+ * @see Promise.prototype.then
+ */
+Promise.prototype.catch = function (aOnReject)
+{
+ return this.then(undefined, aOnReject);
+};
+
+/**
+ * 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.
+ */
+Promise.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.
+ */
+Promise.resolve = function (aValue)
+{
+ if (aValue && typeof(aValue) == "function" && aValue.isAsyncFunction) {
+ throw new TypeError(
+ "Cannot resolve a promise with an async function. " +
+ "You should either invoke the async function first " +
+ "or use 'Task.spawn' instead of 'Task.async' to start " +
+ "the Task and return its promise.");
+ }
+
+ if (aValue instanceof Promise) {
+ return aValue;
+ }
+
+ return new Promise((aResolve) => aResolve(aValue));
+};
+
+/**
+ * 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.
+ */
+Promise.reject = function (aReason)
+{
+ return new Promise((_, aReject) => aReject(aReason));
+};
+
+/**
+ * Returns a promise that is resolved or rejected when all values are
+ * resolved or any is rejected.
+ *
+ * @param aValues
+ * Iterable of promises that may be pending, resolved, or rejected. When
+ * all are resolved or any is rejected, the returned promise will be
+ * resolved or rejected as well.
+ *
+ * @return A new promise that is fulfilled when all values are resolved or
+ * that is rejected when any of the values are rejected. Its
+ * resolution value will be an array of all resolved values in the
+ * given order, or undefined if aValues is an empty array. The reject
+ * reason will be forwarded from the first promise in the list of
+ * given promises to be rejected.
+ */
+Promise.all = function (aValues)
+{
+ if (aValues == null || typeof(aValues[Symbol.iterator]) != "function") {
+ throw new Error("Promise.all() expects an iterable.");
+ }
+
+ return new Promise((resolve, reject) => {
+ let values = Array.isArray(aValues) ? aValues : [...aValues];
+ let countdown = values.length;
+ let resolutionValues = new Array(countdown);
+
+ if (!countdown) {
+ resolve(resolutionValues);
+ return;
+ }
+
+ function checkForCompletion(aValue, aIndex) {
+ resolutionValues[aIndex] = aValue;
+ if (--countdown === 0) {
+ resolve(resolutionValues);
+ }
+ }
+
+ for (let i = 0; i < values.length; i++) {
+ let index = i;
+ let value = values[i];
+ let resolver = val => checkForCompletion(val, index);
+
+ if (value && typeof(value.then) == "function") {
+ value.then(resolver, reject);
+ } else {
+ // Given value is not a promise, forward it as a resolution value.
+ resolver(value);
+ }
+ }
+ });
+};
+
+/**
+ * Returns a promise that is resolved or rejected when the first value is
+ * resolved or rejected, taking on the value or reason of that promise.
+ *
+ * @param aValues
+ * Iterable of values or promises that may be pending, resolved, or
+ * rejected. When any is resolved or rejected, the returned promise will
+ * be resolved or rejected as to the given value or reason.
+ *
+ * @return A new promise that is fulfilled when any values are resolved or
+ * rejected. Its resolution value will be forwarded from the resolution
+ * value or rejection reason.
+ */
+Promise.race = function (aValues)
+{
+ if (aValues == null || typeof(aValues[Symbol.iterator]) != "function") {
+ throw new Error("Promise.race() expects an iterable.");
+ }
+
+ return new Promise((resolve, reject) => {
+ for (let value of aValues) {
+ Promise.resolve(value).then(resolve, reject);
+ }
+ });
+};
+
+Promise.Debugging = {
+ /**
+ * Add an observer notified when an error is reported as uncaught.
+ *
+ * @param {function} observer A function notified when an error is
+ * reported as uncaught. Its arguments are
+ * {message, date, fileName, stack, lineNumber}
+ * All arguments are optional.
+ */
+ addUncaughtErrorObserver: function(observer) {
+ PendingErrors.addObserver(observer);
+ },
+
+ /**
+ * Remove an observer added with addUncaughtErrorObserver
+ *
+ * @param {function} An observer registered with
+ * addUncaughtErrorObserver.
+ */
+ removeUncaughtErrorObserver: function(observer) {
+ PendingErrors.removeObserver(observer);
+ },
+
+ /**
+ * Remove all the observers added with addUncaughtErrorObserver
+ */
+ clearUncaughtErrorObservers: function() {
+ PendingErrors.removeAllObservers();
+ },
+
+ /**
+ * Force all pending errors to be reported immediately as uncaught.
+ * Note that this may cause some false positives.
+ */
+ flushUncaughtErrors: function() {
+ PendingErrors.flush();
+ },
+};
+Object.freeze(Promise.Debugging);
+
+Object.freeze(Promise);
+
+// If module is defined, this file is loaded as a CommonJS module. Make sure
+// Promise is exported in that case.
+if (this.module) {
+ module.exports = 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_INTERNALS].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_INTERNALS].status = aStatus;
+ aPromise[N_INTERNALS].value = aValue;
+ if (aPromise[N_INTERNALS].handlers.length > 0) {
+ this.schedulePromise(aPromise);
+ } else if (Cu && aStatus == STATUS_REJECTED) {
+ // This is a rejection and the promise is the last in the chain.
+ // For the time being we therefore have an uncaught error.
+ let id = PendingErrors.register(aValue);
+ let witness =
+ FinalizationWitnessService.make("promise-finalization-witness", id);
+ aPromise[N_INTERNALS].witness = [id, witness];
+ }
+ },
+
+ /**
+ * Sets up the PromiseWalker loop to start on the next tick of the event loop
+ */
+ scheduleWalkerLoop: function()
+ {
+ this.walkerLoopScheduled = true;
+
+ // If this file is loaded on a worker thread, DOMPromise will not behave as
+ // expected: because native promises are not aware of nested event loops
+ // created by the debugger, their respective handlers will not be called
+ // until after leaving the nested event loop. The debugger server relies
+ // heavily on the use promises, so this could cause the debugger to hang.
+ //
+ // To work around this problem, any use of native promises in the debugger
+ // server should be avoided when it is running on a worker thread. Because
+ // it is still necessary to be able to schedule runnables on the event
+ // queue, the worker loader defines the function setImmediate as a
+ // per-module global for this purpose.
+ //
+ // If Cu is defined, this file is loaded on the main thread. Otherwise, it
+ // is loaded on the worker thread.
+ if (Cu) {
+ let stack = Components_ ? Components_.stack : null;
+ if (stack) {
+ DOMPromise.resolve().then(() => {
+ Cu.callFunctionWithAsyncStack(this.walkerLoop.bind(this), stack,
+ "Promise")
+ });
+ } else {
+ DOMPromise.resolve().then(() => this.walkerLoop());
+ }
+ } else {
+ setImmediate(this.walkerLoop);
+ }
+ },
+
+ /**
+ * 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_INTERNALS].handlers) {
+ this.handlers.push(handler);
+ }
+ aPromise[N_INTERNALS].handlers.length = 0;
+
+ // Schedule the walker loop on the next tick of the event loop.
+ if (!this.walkerLoopScheduled) {
+ this.scheduleWalkerLoop();
+ }
+ },
+
+ /**
+ * 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 ()
+ {
+ // If there is more than one handler waiting, reschedule the walker loop
+ // immediately. Otherwise, use walkerLoopScheduled to tell schedulePromise()
+ // to reschedule the loop if it adds more handlers to the queue. 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.
+ if (this.handlers.length > 1) {
+ this.scheduleWalkerLoop();
+ } else {
+ 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 Promise((aResolve, aReject) => {
+ this.resolve = aResolve;
+ this.reject = aReject;
+ });
+ 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: null,
+
+ /**
+ * 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: null,
+};
+
+// 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 Promise(() => {});
+}
+
+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_INTERNALS].status;
+ let nextValue = this.thisPromise[N_INTERNALS].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.call(undefined, nextValue);
+ }
+ } else if (typeof(this.onReject) == "function") {
+ nextValue = this.onReject.call(undefined, nextValue);
+ nextStatus = STATUS_RESOLVED;
+ }
+ } catch (ex) {
+
+ // An exception has occurred in the handler.
+
+ if (ex && typeof ex == "object" && "name" in ex &&
+ ERRORS_TO_REPORT.indexOf(ex.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.
+
+ dump("*************************\n");
+ dump("A coding exception was thrown in a Promise " +
+ ((nextStatus == STATUS_RESOLVED) ? "resolution":"rejection") +
+ " callback.\n");
+ dump("See https://developer.mozilla.org/Mozilla/JavaScript_code_modules/Promise.jsm/Promise\n\n");
+ dump("Full message: " + ex + "\n");
+ dump("Full stack: " + (("stack" in ex)?ex.stack:"not available") + "\n");
+ dump("*************************\n");
+
+ }
+
+ // Additionally, reject the next promise.
+ nextStatus = STATUS_REJECTED;
+ nextValue = ex;
+ }
+
+ // Propagate the newly determined state to the next promise.
+ PromiseWalker.completePromise(this.nextPromise, nextStatus, nextValue);
+ },
+};