{{ gecko_minversion_header("17") }}
The Task.jsm JavaScript code module implements a subset of Task.js to make sequential, asynchronous operations simple, using the power of JavaScript's yield operator. To use it, you first need to import the code module into your JavaScript scope:
Components.utils.import("resource://gre/modules/Task.jsm");
Introduction
For an introduction to tasks, you may start from the Task.js documentation, keeping in mind that only the core subset is implemented in this module.
Tasks are built upon generator functions and promises. The Task.spawn() function takes a generator function and starts running it as a task. Every time the task yields a promise, it waits until the promise is resolved. Task.spawn() returns a promise that is resolved when the task completes successfully, or is rejected if an exception occurs.
You can use the yield operator inside the generator function to wait on a promise, spawn another task, or propagate a value:
let resolutionValue = yield (promise/generator/iterator/value);
- If you specify a promise, the
yieldoperator returns its resolution value as soon as the promise is resolved. If the promise is rejected, its rejection reason is thrown as an exception. - If you specify a generator function or the iterator returned by a generator function, then
Task.spawn()is implicitly called, and theyieldoperator works on the returned promise. This reduces the syntax overhead of callingTask.spawn()explicitly when you want to recurse into other task functions. - If you specify a function that is not a generator, it is called with no arguments, and the
yieldoperator returns the return value of the function. This comes in handy when iterating over function lists where some items have been converted to tasks and some not. - If you specify anything else, the
yieldoperator returns exactly what you specified.
Method overview
Promise spawn(aTask); |
Properties
| Attribute | Type | Description |
Result Read only |
Constructor |
Constructs a special exception that, when thrown inside a generator function, allows the associated task to be resolved with a specific value. Example:
throw new Task.Result("Value");
|
Methods
spawn()
Creates and starts a new task.
Promise spawn( aTask );
Parameters
- aTask
-
This parameter accepts different data types:
- If you specify a generator function, it is called with no arguments to retrieve the associated iterator. The generator function is a task, that is can yield promise objects to wait upon. The resolution value of the returned promise is
undefinedunless aTask.Resultexception is thrown from inside the generator function. - If you specify the iterator returned by a generator function you called, the generator function is also executed as a task. This allows you to call the function with arguments. The resolution value of the returned promise is
undefinedunless aTask.Resultexception is thrown from inside the generator function. - If you specify a function that is not a generator, it is called with no arguments, and its return value is used to resolve the returned promise.
- If you specify anything else, you get a promise that is already resolved with the specified value.
- If you specify a generator function, it is called with no arguments to retrieve the associated iterator. The generator function is a task, that is can yield promise objects to wait upon. The resolution value of the returned promise is
Return value
A promise that is resolved when the task terminates, or rejected if an exception occurs in the task.
Examples
General example
Cu.import("resource://gre/modules/Task.jsm");
Task.spawn(function () {
// This is our task. It is a generator function because it contains the
// "yield" operator at least once. Let's create a promise object, wait on
// it and capture its resolution value.
let myPromise = getPromiseResolvedOnTimeoutWithValue(1000, "Value");
let result = yield myPromise;
// This part is executed only after the promise above is resolved (after
// one second, in this imaginary example). We can easily loop while
// calling asynchronous functions, and wait multiple times.
for (let i = 0; i < 3; i++) {
result += yield getPromiseResolvedOnTimeoutWithValue(50, "!");
}
// Optionally, a value can be returned using this special exception
// (because "return" cannot communicate a result in generator functions).
throw new Task.Result("Resolution result for the task: " + result);
}).then(function (result) {
// result == "Resolution result for the task: Value!!!"
// The result is undefined if no special Task.Result exception was thrown.
}, function (exception) {
// Failure! We can inspect or report the exception.
});
Exception handling
Components.utils.import("resource://gre/modules/osfile.jsm")
Components.utils.import("resource://gre/modules/Task.jsm")
Task.spawn(function () {
let currentDir = yield OS.File.getCurrentDirectory();
let path = OS.Path.join(currentDir, ".mozconfig");
try {
let info = yield OS.File.stat(path);
console.log("The .mozconfig file is " + info.size + " bytes long.");
} catch (ex if ex instanceof OS.File.Error && ex.becauseNoSuchFile) {
console.log("You don't have .mozconfig in " + currentDir);
}
}).then(null, Components.utils.reportError);
In this example, if the promise returned by OS.File.stat is rejected, an exception is thrown inside the task. If the reason for the exception is that the file doesn't exist, this is treated as an expected condition, and the task will complete succesfully.
Any other unhandled exception that is thrown inside the task is reported by Components.utils.reportError.