summaryrefslogtreecommitdiffstats
path: root/toolkit/modules/Promise.jsm
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.jsm
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.jsm')
-rw-r--r--toolkit/modules/Promise.jsm101
1 files changed, 101 insertions, 0 deletions
diff --git a/toolkit/modules/Promise.jsm b/toolkit/modules/Promise.jsm
new file mode 100644
index 000000000..0df4977af
--- /dev/null
+++ b/toolkit/modules/Promise.jsm
@@ -0,0 +1,101 @@
+/* -*- 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.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);