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