About thread safety

The Worker interface spawns real OS-level threads, and concurrency can cause interesting effects in your code if you aren't careful. However, in the case of web workers, the carefully controlled communication points with other threads means that it's actually very hard to cause concurrency problems.  There's no access to non-thread safe components or the DOM and you have to pass specific data in and out of a thread through serialized objects.  So you have to work really hard to cause problems in your code.

Spawning a worker

Creating a new worker is simple.  All you need to do is call the Worker() constructor, specifying the URI of a script to execute in the worker thread, and, if you wish to be able to receive notifications from the worker, set the worker's onmessage property to an appropriate event handler function.

var worker = new Worker('my_task.js');
worker.onmessage = function(event) {
 console.log("Called back by the worker!\n");
};

Alternatively, you could use addEventListener:

var worker = new Worker('my_task.js');
worker.addEventListener('message', function(event) {
 console.log("Called back by the worker!\n");
}, false);

worker.postMessage(); // start the worker.

Line 1 in this example creates a new worker thread,.  Line 2 sets up a listener to handle message events from the worker. This event handler will be called when the worker calls its own postMessage() function. Finally, Line 6 starts the worker thread.

var worker = new Worker('my_task.js');
worker.onmessage = function(event) {
  console.log("Worker said:" + event.data);
};

self.onmessage = function(event) {
  self.postMessage('Hi there!');
};

postMessage({'cmd': 'init', 'timestamp': Date.now()});

// Create a 32MB "file" and fill it.
var uInt8View = new Uint8Array(1024*1024*32); // 32MB
for (var i = 0; i < uInt8View.length; ++i) {
  uInt8View[i] = i;
}

worker.webkitPostMessage(uInt8Array.buffer, [uInt8Array.buffer]);

Spawning subworkers

Workers may spawn more workers if they wish.  So-called subworkers must be hosted within the same origin as the parent page.  Also, the URIs for subworkers are resolved relative to the parent worker's location rather than that of the owning page.  This makes it easier for workers to keep track of where their dependencies are.

Subworkers are currently not supported in Chrome. See crbug.com/31666.

Timeouts and intervals

Workers can use timeouts and intervals just like the main thread can.  This can be useful, for example, if you want to have your worker thread run code periodically instead of nonstop.

See setTimeout(), clearTimeout(), setInterval(), and clearInterval() for details.

Terminating a worker

If you need to immediately terminate a running worker, you can do so by calling the worker's terminate() method:

myWorker.terminate();

The worker thread is killed immediately without an opportunity to complete its operations or clean up after itself.

Workers may close themselves by calling their own nsIWorkerScope.close() method.

Handling errors

When a runtime error occurs in worker, its onerror event handler is called.  It receives an event named error which implements the ErrorEvent interface.  The event doesn't bubble and is cancelable; to prevent the default action from taking place, the worker can call the error event's preventDefault() method.

The error event has the following three fields that are of interest:

message

A human-readable error message.

filename

The name of the script file in which the error occurred.

lineno

The line number of the script file on which the error occurred.

Accessing the navigator object

Workers may access the navigator object, which is available within their scope.  It contains the following strings which can be used to identify the browser, just as can be done from normal scripts:

• appName
• appVersion
• platform
• userAgent

Importing scripts and libraries

Worker threads have access to a global function, importScripts(), which lets them import scripts or libraries into their scope.  It accepts as parameters zero or more URIs to resources to import; all of the following examples are valid:

importScripts();                        /* imports nothing */
importScripts('foo.js');                /* imports just "foo.js" */
importScripts('foo.js', 'bar.js');      /* imports two scripts */

The browser loads each listed script and executes it. Any global objects from each script may then be used by the worker.
When the script cannot be loaded, NETWORK_ERROR will be thrown, and subsequent code will not be executed. Previously executed code (including code deferred using window.setTimeout) will still be functional though. Function declarations after the importScript() method are also kept, since these are always evaluated before the rest of the code.

Examples

This section provides several examples of how to use DOM workers.

var results = [];

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

function errorReceiver(event) {
  throw event.data;
}

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.onerror = errorReceiver;
    worker.postMessage(n - i);
  }
 };

<!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;
      dump("Got: " + event.data + "\n");
    };

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

    worker.postMessage("5");

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

Browser compatibility

See also

• File API Specification: Web WorkersED
• Worker interface

• SharedWorker interface
• Functions available to workers
• HTML5Rocks - The Basics of Web Workers