DOMWorkerThreads current

From MozillaWiki
Jump to: navigation, search

This page describes the API used in the Firefox 3.1 Beta 2 release. We expect few changes before final release, and nothing that would break compatibility with what we currently implement.

Please do file bugs if you find any!

Sample usage

fibonacci.html:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
  <title>Test threads fibonacci</title>
  <body>

  <div id="result"></div>

  <script language="javascript">

    var worker = new Worker("fibonacci.js");

    worker.onmessage = function(event) {
      document.getElementById("result").textContent = event.data;
    };

    worker.onerror = function(event) {
      dump("Worker error: " + event.data + "\n");
    };

    worker.postMessage(10);

  </script>
  </body>
</html>

fibonacci.js:

var results = [];

function resultReceiver(event) {
  results.push(parseInt(event.data));
  if (results.length == 2) {
    postMessage(results[0] + results[1]);
  }
}

onmessage = function(event) {
  var n = parseInt(event.data);

  if (n == 0 || n == 1) {
    postMessage(n);
    return;
  }

  for (var i = 1; i <= 2; i++) {
    var worker = new Worker("fibonacci.js");
    worker.onmessage = resultReceiver;
    worker.postMessage(n - i);
  }
}

Full API

This API shouldn't change between Beta 2 and final with the exception of adding a few properties, so code written to the following spec should continue to work.

The worker object

Workers are created as follows:

var worker = new Worker("workerScript.js");

Once created, the worker object has the following interface:

interface Worker : DOMEventTarget
{
  /**
   * Event listener that will be called whenever a MessageEvent bubbles through
   * the worker with type 'error'. The error message will be stored in the
   * 'data' member of the event.
   */
  attribute EventListener onerror;

  /**
   * Event listener that will be called whenever a MesageEvent bubbles through
   * the worker with type 'message'. The message will be stored in the 'data'
   * member of the event.
   */
  attribute EventListener onmessage;

  /**
   * Sends 'aMessage' as the 'data' member of a MessageEvent targeted at the
   * worker's inner scope.
   */
  void postMessage(in DOMString aMessage);
};

The worker scope

The global object for the scope in which a worker's script runs has the following interface:

interface WorkerScope : DOMEventTarget
{
  /**
   * Gets WorkerScope object itself.
   */
  readonly attribute WorkerScope self;

  /**
   * Event listener that will be called whenever a MesageEvent bubbles through
   * the worker's inner scope with type 'message'. The message will be stored
   * in the 'data' member of the event.
   */
  attribute EventListener onmessage;

  /**
   * Sends 'aMessage' as the 'data' member of a MessageEvent targeted at the
   * scope's parent worker object.
   */
  void postMessage(in DOMString aMessage);

  /**
   * Loads the scripts referenced by the given urls. Begins downloading all
   * scripts simultaneously but ensures that they are executed in the order
   * given.
   */
  void importScripts([Variadic] in DOMString aURLs);

  /**
   * The following constructors are available just as on the main thread:
   *
   * 1. Worker(in DOMString aURL);
   *      var worker = new Worker("scriptUrl.js");
   *
   * 2. XMLHttpRequest();
   *      var xhr = new XMLHttpRequest();
   *
   *    Note: The XHR objects created in a worker script behave identically to
   *          the XHR objects created on the main thread except that the
   *          'responseXML' and 'channel' attributes always return null (see
   *          nsIXMLHttpRequest.idl).
   */

  /**
   * See nsIDOMJSWindow.idl for info on the following methods.
   */
  void dump(in DOMString aMessage);
  long setTimeout();
  long setInterval();
  void clearTimeout();
  void clearInterval();
};