mozilla
Your Search Results

    Task.jsm

    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 yield operator 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 the yield operator works on the returned promise. This reduces the syntax overhead of calling Task.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 yield operator 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 yield operator returns exactly what you specified.

    Method overview

    Function async(aTask); Requires Gecko 30
    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");
    Note: If you want to exit early from a generator function, without returning a value for the task, you can just use the return statement without any arguments.

    Methods

    async()

    Create and return an "async function" that starts a new task.

    Function async(
      aTask
    );
    

    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 promise returned by the task either fulfills with the returned value if generator returns or rejects with the thrown error if the generator throws.
    • 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 promise returned by the task either fulfills with the returned value if generator returns or rejects with the thrown error if the generator throws.
    • If you specify a function that is not a generator, it is called with no arguments, and its return value is used to fulfill the returned promise.
    • If you specify anything else, you get a promise that is already fulfilled with the specified value.
    Return value

    A promise that is fulfills when the task returns or rejects when the task throws an exception.

    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, "!");
      }
    
     return "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.

    See also

    Document Tags and Contributors

    Contributors to this page: P.A., bbenvie, mnoorenberghe, arai
    Last updated by: arai,