The Promise.jsm
JavaScript code module implements the Promises/A+ proposal as known in April 2013.
This module was used before DOM Promises were made globally available in Gecko 29. Its usage is not suggested for new code.
If you just need a Promise, consider using a DOM Promise instead.
If you need a Deferred, because you want to create a Promise and manually resolve or reject it, consider using PromiseUtils.jsm instead.
To use it, you first need to import the code module into your JavaScript scope:
Components.utils.import("resource://gre/modules/Promise.jsm");
Note: A preliminary promise module is also available starting from Gecko 17, though it didn't conform to the Promises/A+ proposal until Gecko 25:
Components.utils.import("resource://gre/modules/commonjs/promise/core.js"); // Gecko 17 to 20 Components.utils.import("resource://gre/modules/commonjs/sdk/core/promise.js"); // Gecko 21 to 24
This implementation also includes helper functions that are specific to the Add-on SDK. While you may still import this module from the above paths, the recommended way for loading it is through the Add-on SDK loader.
For an introduction to promises, you may start from the Add-on SDK documentation, keeping in mind that only the core subset is implemented in this module.
A promise is an object representing a value that may not be available yet. Internally, a promise can be in one of three states:
undefined
.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 fulfilled or rejected. The method returns a new promise that, in turn, is fulfilled 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 fulfilled. See the documentation of the then
method for details.
Promises may also be created using the new Promise()
constructor.
Deferred defer(); Obsolete since Gecko 30 |
Promise resolve([optional] aValue); |
Promise reject([optional] aReason); |
Creates a new pending promise and provides methods to resolve or reject it.
Deferred defer(); Obsolete since Gecko 30
None.
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.
Creates a new promise fulfilled with the specified value, or propagates the state of an existing promise.
Promise resolve( aValue );
aValue
Optionalundefined
, it becomes the fulfillment value of the returned promise. If this value is a promise, then the returned promise will be resolved with the value, i.e. it will eventually assume the same state as the provided promise.A promise that can be pending, fulfilled, or rejected.
Creates a new promise rejected with the specified reason.
Promise reject( aReason );
aReason
OptionalThe rejection reason for the returned promise. Although the reason can be undefined
, it is generally an Error
object, like in exception handling.
A rejected promise.
See the examples page.