1/* -*- indent-tabs-mode: nil; js-indent-level: 2 -*- */
2/* vim: set ts=2 et sw=2 tw=80 filetype=javascript: */
3/* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6
7"use strict";
8
9var EXPORTED_SYMBOLS = ["Promise"];
10
11/**
12 * This module implements the "promise" construct, according to the
13 * "Promises/A+" proposal as known in April 2013, documented here:
14 *
15 * <http://promises-aplus.github.com/promises-spec/>
16 *
17 * A promise is an object representing a value that may not be available yet.
18 * Internally, a promise can be in one of three states:
19 *
20 * - Pending, when the final value is not available yet.  This is the only state
21 *   that may transition to one of the other two states.
22 *
23 * - Resolved, when and if the final value becomes available.  A resolution
24 *   value becomes permanently associated with the promise.  This may be any
25 *   value, including "undefined".
26 *
27 * - Rejected, if an error prevented the final value from being determined.  A
28 *   rejection reason becomes permanently associated with the promise.  This may
29 *   be any value, including "undefined", though it is generally an Error
30 *   object, like in exception handling.
31 *
32 * A reference to an existing promise may be received by different means, for
33 * example as the return value of a call into an asynchronous API.  In this
34 * case, the state of the promise can be observed but not directly controlled.
35 *
36 * To observe the state of a promise, its "then" method must be used.  This
37 * method registers callback functions that are called as soon as the promise is
38 * either resolved or rejected.  The method returns a new promise, that in turn
39 * is resolved or rejected depending on the state of the original promise and on
40 * the behavior of the callbacks.  For example, unhandled exceptions in the
41 * callbacks cause the new promise to be rejected, even if the original promise
42 * is resolved.  See the documentation of the "then" method for details.
43 *
44 * Promises may also be created using the "Promise.defer" function, the main
45 * entry point of this module.  The function, along with the new promise,
46 * returns separate methods to change its state to be resolved or rejected.
47 * See the documentation of the "Deferred" prototype for details.
48 *
49 * -----------------------------------------------------------------------------
50 *
51 * Cu.import("resource://gre/modules/Promise.jsm");
52 *
53 * // This function creates and returns a new promise.
54 * function promiseValueAfterTimeout(aValue, aTimeout)
55 * {
56 *   let deferred = Promise.defer();
57 *
58 *   try {
59 *     // An asynchronous operation will trigger the resolution of the promise.
60 *     // In this example, we don't have a callback that triggers a rejection.
61 *     do_timeout(aTimeout, function () {
62 *       deferred.resolve(aValue);
63 *     });
64 *   } catch (ex) {
65 *     // Generally, functions returning promises propagate exceptions through
66 *     // the returned promise, though they may also choose to fail early.
67 *     deferred.reject(ex);
68 *   }
69 *
70 *   // We don't return the deferred to the caller, but only the contained
71 *   // promise, so that the caller cannot accidentally change its state.
72 *   return deferred.promise;
73 * }
74 *
75 * // This code uses the promise returned be the function above.
76 * let promise = promiseValueAfterTimeout("Value", 1000);
77 *
78 * let newPromise = promise.then(function onResolve(aValue) {
79 *   do_print("Resolved with this value: " + aValue);
80 * }, function onReject(aReason) {
81 *   do_print("Rejected with this reason: " + aReason);
82 * });
83 *
84 * // Unexpected errors should always be reported at the end of a promise chain.
85 * newPromise.then(null, Components.utils.reportError);
86 *
87 * -----------------------------------------------------------------------------
88 */
89
90// eslint-disable-next-line mozilla/use-services
91Cc["@mozilla.org/moz/jssubscript-loader;1"]
92  .getService(Ci.mozIJSSubScriptLoader)
93  .loadSubScript("resource://gre/modules/Promise-backend.js", this);
94