html5/spec-ja/.workers-spec.en.html


<html lang=en-US-x-hixie>
 <head>
  <title>Web Workers</title>
  <link href="/style/specification" rel=stylesheet>
  <link href="/images/icon" rel=icon>

  <style>
   p > span:not([title=""]):not([class="big-issue"]), li > span:not([title=""]):not([class="big-issue"]) { border-bottom: solid #99CC99; }
  </style>

 <body class=draft>
  <div class=head>
   <p><a class=logo href="http://www.whatwg.org/" rel=home><img alt=WHATWG
    src="/images/logo"></a></p>

   <h1 id=web-workers>Web Workers</h1>

   <h2 class="no-num no-toc" id=draft>Draft Recommendation &mdash; 14 August
    2008</h2>

   <p>You can take part in this work. <a
    href="http://www.whatwg.org/mailing-list">Join the working group's
    discussion list.</a></p>

   <p><strong>Web designers!</strong> We have a <a
    href="http://blog.whatwg.org/faq/">FAQ</a>, a <a
    href="http://forums.whatwg.org/">forum</a>, and a <a
    href="http://www.whatwg.org/mailing-list#help">help mailing list</a> for
    you!</p>

   <dl>
    <dt>This version:

    <dd><a
     href="http://www.whatwg.org/specs/web-workers/current-work/">http://whatwg.org/ww</a>

    <dt>Version history:

    <dd>Twitter messages (non-editorial changes only): <a
     href="http://twitter.com/WHATWG">http://twitter.com/WHATWG</a>

    <dd>Commit-Watchers mailing list: <a
     href="http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org">http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a>

    <dd>Interactive Web interface: <a
     href="http://html5.org/tools/web-workers-tracker">http://html5.org/tools/web-workers-tracker</a>

    <dd>Subversion interface: <a
     href="http://svn.whatwg.org/webworkers/">http://svn.whatwg.org/webworkers/</a>

    <dt>Issues:

    <dd>To send feedback: <a
     href="http://www.whatwg.org/mailing-list">whatwg@whatwg.org</a>

    <dd>To view and vote on feedback: <a
     href="http://www.whatwg.org/issues/">http://www.whatwg.org/issues/</a>

    <dt>Editor:

    <dd>Ian Hickson, Google, ian@hixie.ch
   </dl>

   <p class=copyright>&copy; Copyright 2004-2008 Apple Computer, Inc.,
    Mozilla Foundation, and Opera Software ASA.</p>

   <p class=copyright>You are granted a license to use, reproduce and create
    derivative works of this document.</p>
  </div>

  <hr>

  <h2 class="no-num no-toc" id=abstract>Abstract</h2>

  <p>This specification defines an API that allows Web application authors to
   spawn background workers running scripts in parallel to their main page.
   This allows for thread-like operation with message-passing as the
   coordination mechanism.

  <h2 class="no-num no-toc" id=status>Status of this document</h2>

  <p><strong>This is a work in progress!</strong> This document is changing
   on a daily if not hourly basis in response to comments and as a general
   part of its development process. Comments are very welcome, please send
   them to <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a>. Thank
   you.

  <p>The current focus is in developing a first draft proposal.

  <p>Implementors should be aware that this specification is not stable.
   <strong>Implementors who are not taking part in the discussions are likely
   to find the specification changing out from under them in incompatible
   ways.</strong> Vendors interested in implementing this specification
   before it eventually reaches the call for implementations should join the
   <a href="/mailing-list">WHATWG mailing list</a> and take part in the
   discussions.

  <p>This specification is also being produced by the <a
   href="http://www.w3.org/html/wg">W3C HTML WG</a>. The two specifications
   are identical from the table of contents onwards.

  <h2 class="no-num no-toc" id=contents>Table of contents</h2>
  <!--begin-toc-->

  <ul class=toc>
   <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
    <ul class=toc>
     <li><a href="#tutorial"><span class=secno>1.1 </span>Tutorial</a>
      <ul class=toc>
       <li><a href="#a-background"><span class=secno>1.1.1 </span>A
        background number-crunching worker</a>

       <li><a href="#a-worker"><span class=secno>1.1.2 </span>A worker for
        updating a client-side database</a>

       <li><a href="#worker"><span class=secno>1.1.3 </span>Worker used for
        backgroud I/O</a>

       <li><a href="#shared"><span class=secno>1.1.4 </span>Shared
        workers</a>

       <li><a href="#delegation"><span class=secno>1.1.5
        </span>Delegation</a>

       <li><a href="#providing"><span class=secno>1.1.6 </span>Providing
        libraries</a>

       <li><a href="#granting"><span class=secno>1.1.7 </span>Granting
        capabilities</a>
      </ul>

     <li><a href="#conformance"><span class=secno>1.2 </span>Conformance
      requirements</a>
      <ul class=toc>
       <li><a href="#dependencies"><span class=secno>1.2.1
        </span>Dependencies</a>
      </ul>

     <li><a href="#terminology"><span class=secno>1.3 </span>Terminology</a>
    </ul>

   <li><a href="#infrastructure"><span class=secno>2.
    </span>Infrastructure</a>
    <ul class=toc>
     <li><a href="#the-workerglobalscope"><span class=secno>2.1 </span>The
      <code>WorkerGlobalScope</code> interface</a>

     <li><a href="#base-urls"><span class=secno>2.2 </span>Base URLs and
      origins of workers</a>

     <li><a href="#the-queue"><span class=secno>2.3 </span>The queue of
      events</a>

     <li><a href="#the-workers"><span class=secno>2.4 </span>The worker's
      ports</a>

     <li><a href="#processing"><span class=secno>2.5 </span>Processing
      model</a>

     <li><a href="#creating"><span class=secno>2.6 </span>Creating
      workers</a>
    </ul>

   <li><a href="#apis-available"><span class=secno>3. </span>APIs available
    to workers</a>
    <ul class=toc>
     <li><a href="#importing"><span class=secno>3.1 </span>Importing scripts
      and libraries</a>

     <li><a href="#apis-defined"><span class=secno>3.2 </span>APIs defined in
      other specifications</a>

     <li><a href="#interface"><span class=secno>3.3 </span>Interface objects
      and constructors</a>

     <li><a href="#worker0"><span class=secno>3.4 </span>Worker locations</a>
      
    </ul>

   <li class=no-num><a href="#references">References</a>

   <li class=no-num><a href="#acknowledgements">Acknowledgements</a>
  </ul>
  <!--end-toc-->

  <hr>

  <h2 id=introduction><span class=secno>1. </span>Introduction</h2>

  <h3 id=tutorial><span class=secno>1.1 </span>Tutorial</h3>

  <p><em>This section is non-normative.</em>

  <p>There are a variety of uses that workers can be put to. The following
   subsections show various examples of this use.

  <h4 id=a-background><span class=secno>1.1.1 </span>A background
   number-crunching worker</h4>

  <p><em>This section is non-normative.</em>

  <p>The simplest use of workers is for performing a computationally
   expensive task without interrupting the user interface.

  <p>In this example, the main document spawns a worker to (na&iuml;vely)
   compute prime numbers, and progressively displays the most recently found
   prime number.

  <p>The main page is as follows:

  <pre>&lt;!DOCTYPE HTML>
&lt;html>
 &lt;head>
  &lt;title>Worker example: One-core computation&lt;/title>
 &lt;/head>
 &lt;body>
  &lt;p>The highest prime number discovered so far is: &lt;output id="result">&lt;/output>&lt;/p>
  &lt;script>
   var worker = createWorker('worker.js');
   worker.port.onmessage = function (event) {
     document.getElementById('result').textContent = event.message;
   };
  &lt;/script>
 &lt;/body>
&lt;/html></pre>

  <p>The <code title=dom-WorkerFactory-createWorker><a
   href="#createworker">createWorker()</a></code> method call creates a
   worker and returns a <code><a href="#worker1">Worker</a></code> object
   representing that worker and containing a <code>MessagePort</code> object,
   which is used to communicate with the worker. That object's <code
   title=dom-MessagePort-onmessage>onmessage</code> event handler attribute
   allows the code to receive messages from the worker.

  <p>The worker itself is as follows:

  <pre>var n = 1;
search: while (true) {
  n += 1;
  for (var i = 2; i &lt;= Math.sqrt(n); i += 1)
    if (n % i == 0)
     continue search;
  // found a prime!
  port.postMessage(n);
}</pre>

  <p>The bulk of this code is simply an unoptimised search for a prime
   number. To send a message back to the page, the <code
   title=dom-WorkerGlobalScope-port><a href="#port">port</a></code> variable
   (defined automatically when the worker is created) is used to post a
   message when a prime is found.

  <p><a href="http://www.whatwg.org/demos/workers/primes/page.html">View this
   example online</a>.

  <h4 id=a-worker><span class=secno>1.1.2 </span>A worker for updating a
   client-side database</h4>

  <p><em>This section is non-normative.</em>

  <p>In this example, the main document spawns a worker whose only task is to
   listen for notifications from the server, and, when appropriate, either
   add or remove data from the client-side database.

  <p>Since no communication occurs between the worker and the main page, the
   main page can start the worker by just doing:

  <pre>&lt;script>
 createWorker('worker.js');
&lt;/script></pre>

  <p>The worker itself is as follows:

  <pre>var server = new WebSocket('ws://whatwg.org/database');
var database = openDatabase('demobase', '1.0', 'Demo Database', 10240);
server.onmessage = function (event) {
  // data is in the format "command key value"
  var data = event.message.split(' ');
  switch (data[0]) {
    case '+':
     database.transaction(function(tx) {
       tx.executeSql('INSERT INTO pairs (key, value) VALUES (?, ?)', data[1], data[2]);
     });
    case '-':
     database.transaction(function(tx) {
       tx.executeSql('DELETE FROM pairs WHERE key=? AND value=?', data[1], data[2]);
     });
  }
};</pre>

  <p>This connects to the server using the <code>WebSocket</code> mechanism
   and opens the local database (which, we presume, has been created
   earlier). The worker then just listens for messages from the worker and
   acts on them as appropriate, forever (or until the main page is closed).

  <p><a
   href="http://www.whatwg.org/demos/workers/database-updater/page.html">View
   this example online</a>. (This example will not actually function, since
   the server does not actually exist and the database is not created by this
   sample code.)

  <h4 id=worker><span class=secno>1.1.3 </span>Worker used for backgroud I/O</h4>

  <p><em>This section is non-normative.</em>

  <p>In this example, the main document uses two workers, one for fetching
   stock updates for at regular intervals, and one for fetching performing
   search queries that the user requests.

  <p>The main page is as follows:

  <pre>&lt;!DOCTYPE HTML>
&lt;html>
 &lt;head>
  &lt;title>Worker example: Stock ticker&lt;/title>
  &lt;script>
   // TICKER
   var symbol = 'GOOG'; // default symbol to watch
   var ticker = createWorker('ticker.js');
   ticker.port.postMessage(symbol);

   // SEARCHER
   var searcher = createWorker('searcher.js');
   function search(query) {
     searcher.port.postMessage(query);
   }

   // SYMBOL SELECTION UI
   function select(newSymbol) {
     symbol = newSymbol;
     ticker.port.postMessage(symbol);
   }
  &lt;/script>
 &lt;/head>
 &lt;body>
  &lt;p>&lt;output id="symbol">&lt;/output> &lt;output id="value">&lt;/output>&lt;/p>
  &lt;script>
   ticker.port.onmessage = function (event) {
     var data = event.message.split(' ');
     document.getElementById('symbol').textContent = data[0];
     document.getElementById('value').textContent = data[1];
   };
  &lt;/script>
  &lt;p>&lt;label>Search: &lt;input type="text" oninput="search(this.value)">&lt;/label>&lt;/p>
  &lt;ul id="results">&lt;/ul>
  &lt;script>
   searcher.port.onmessage = function (event) {
     var data = event.message.split(' ');
     var results = document.getElementById('results');
     while (results.hasChildNodes()) // clear previous results
       results.removeChild(results.firstChild);
     for (var i = 0; i &lt; data.length; i += 1) {
       // add a list item with a button for each result
       var li = document.createElement('li');
       var button = document.createElement('button');
       button.value = data[i];
       button.type = 'button';
       button.onclick = function () { select(this.value); };
       button.textContent = data[i];
       li.appendChild(button);
       results.appendChild(li);
     }
   };
  &lt;/script>
  &lt;p>(The data in this example is not real. Try searching for "Google" or "Apple".)&lt;/p>
 &lt;/body>
&lt;/html></pre>

  <p>Messages are queued until the <code
   title=handler-MessagePort-onmessage>onmessage</code> handler is set, so
   even if it takes a while for the message handler to be attached, no data
   is lost.

  <p>The two workers use a common library for performing the actual network
   calls. This library is as follows:

  <pre>function get(url) {
   try {
     var xhr = new XMLHttpRequest();
     xhr.open('GET', url, false);
     xhr.send();
     return xhr.responseText;
   } catch (e) {
     return ''; // turn all errors into empty results
   }
}</pre>

  <p>The stock updater worker is as follows:

  <pre>importScripts('io.js');
var timer;
var symbol;
function update() {
  port.postMessage(symbol + ' ' + get('stock.cgi?' + symbol));
  timer = setTimeout(update, 10000);
}
port.onmessage = function (event) {
  if (timer)
    clearTimeout(timer);
  symbol = event.message;
  update();
};</pre>

  <p>The search query worker is as follows:

  <pre>importScripts('io.js');
port.onmessage = function (event) {
  port.postMessage(get('search.cgi?' + event.message));
};</pre>

  <p><a href="http://www.whatwg.org/demos/workers/stocks/page.html">View this
   example online</a>.

  <h4 id=shared><span class=secno>1.1.4 </span>Shared workers</h4>

  <p><em>This section is non-normative.</em>

  <p>In this example, multiple windows (viewers) can be opened that are all
   viewing the same map. All the windows share the same map information, with
   a single worker coordinating all the viewers. Each viewer can move around
   idependently, but if they set any data on the map, all the viewers are
   updated.

  <p>The main page isn't interesting, it merely provides a way to open the
   viewers:

  <pre>&lt;!DOCTYPE HTML>
&lt;html>
 &lt;head>
  &lt;title>Workers example: Multiviewer&lt;/title>
  &lt;script>
   function openViewer() {
     window.open('viewer.html');
   }
  &lt;/script>
 &lt;/head>
 &lt;body>
  &lt;p>&lt;button type=button onclick="openViewer()">Open a new
  viewer&lt;/button>&lt;/p>
  &lt;p>Each viewer opens in a new window. You can have as many viewers
  as you like, they all view the same data.&lt;/p>
 &lt;/body>
&lt;/html></pre>

  <p>The viewer is more involved:

  <pre>&lt;!DOCTYPE HTML>
&lt;html>
 &lt;head>
  &lt;title>Workers example: Multiviewer viewer&lt;/title>
  &lt;script>
   var worker = createNamedWorker('worker.js', 'core');

   // CONFIGURATION
   function configure(event) {
     if (event.message.substr(0, 4) != 'cfg ') return;
     var name = event.message.substr(4).split(' ', 1);
     // update display to mention our name is name
     document.getElementsByTagName('h1')[0].textContent += ' ' + name;
     // no longer need this listener
     worker.port.removeEventListener('message', configure, false);
   }
   worker.port.addEventListener('message', configure, false);

   // MAP
   function paintMap(event) {
     if (event.message.substr(0, 4) != 'map ') return;
     var data = event.message.substr(4).split(',');
     // display tiles data[0] .. data[8]
     var canvas = document.getElementById('map');
     var context = canvas.getContext('2d');
     for (var y = 0; y &lt; 3; y += 1) {
       for (var x = 0; x &lt; 3; x += 1) {
         var tile = data[y * 3 + x];
         if (tile == '0')
           context.fillStyle = 'green';
         else 
           context.fillStyle = 'maroon';
         fillRect(x * 50, y * 50, 50, 50);
       }
     }
   }
   worker.port.addEventListener('message', paintMap, false);

   // PUBLIC CHAT
   function updatePublicChat(event) {
     if (event.message.substr(0, 4) != 'txt ') return;
     var name = event.message.substr(4).split(' ', 1);
     var message = event.message.substr(4 + length(name) + 1);
     // display "&lt;name> message" in public chat
     var dialog = document.getElementById('public');
     var dt = document.createElement('dt');
     dt.textContent = name;
     dialog.appendChild(dt);
     var dd = document.createElement('dd');
     dd.textContent = message;
     dialog.appendChild(dd);
   }
   worker.port.addEventListener('message', updatePublicChat, false);

   // PRIVATE CHAT
   function startPrivateChat(event) {
     if (event.message.substr(0, 4) != 'msg ') return;
     var name = event.message.substr(4).split(' ', 1);
     var port = event.port;
     // display a private chat UI
     var ul = document.getElementById('private');
     var li = document.createElement('li');
     var h3 = document.createElement('h3');
     h3.textContent = 'Private chat with ' + name;
     li.appendChild(h3);
     var dialog = document.createElement('dialog');
     var addMessage = function(name, message) {
       var dt = document.createElement('dt');
       dt.textContent = name;
       dialog.appendChild(dt);
       var dd = document.createElement('dd');
       dd.textContent = message;
       dialog.appendChild(dd);
     };
     port.onmessage = function (event) {
       addMessage(name, event.message);
     };
     li.appendChild(dialog);
     var form = document.createElement('form');
     var p = document.createElement('p');
     var input = document.createElement('input');
     input.size = 50;
     p.appendChild(input);
     p.appendChild(document.createTextNode(' '));
     var button = document.createElement('button');
     button.textContent = 'Post';
     p.appendChild(button);
     form.onsubmit = function () {
       port.postMessage(input.value);
       addMessage('me', input.value);
       input.value = '';
       return false;
     };
     form.appendChild(p);
     li.appendChild(form);
   }
   worker.port.addEventListener('message', startPrivateChat, false);

   function init() {
     // begin receiving messages (messages are queued until you either
     // set worker.port.onmessage or call worker.port.start())
     worker.port.start();
   }
  &lt;/script>
 &lt;/head>
 &lt;body onload="init()">
  &lt;h1>Viewer&lt;/h1>
  &lt;h2>Map&lt;/h2>
  &lt;p>&lt;canvas id="map" height=150 width=150>&lt;/canvas>&lt;/p>
  &lt;p>
   &lt;button type=button onclick="worker.port.postMessage('mov left')">Left&lt;/button>
   &lt;button type=button onclick="worker.port.postMessage('mov up')">Up&lt;/button>
   &lt;button type=button onclick="worker.port.postMessage('mov down')">Down&lt;/button>
   &lt;button type=button onclick="worker.port.postMessage('mov right')">Right&lt;/button>
   &lt;button type=button onclick="worker.port.postMessage('set 0')">Set 0&lt;/button>
   &lt;button type=button onclick="worker.port.postMessage('set 1')">Set 1&lt;/button>
  &lt;/p>
  &lt;h2>Public Chat&lt;/h2>
  &lt;dialog id="public">&lt;/dialog>
  &lt;form onsubmit="worker.port.postMessage('txt ' + message.value); message.value = ''; return false;">
   &lt;p>
    &lt;input type="text" name="message" size="50">
    &lt;button>Post&lt;/button>
   &lt;/p>
  &lt;/form>
  &lt;h2>Private Chat&lt;/h2>
  &lt;ul id="private">&lt;/ul>
 &lt;/body>
&lt;/html>
</pre>

  <p>There are several key things worth noting about the way the viewer is
   written.

  <p><strong>Multiple listeners</strong>. Instead of a single message
   processing function, the code here attaches multiple event listeners, each
   one performing a quick check to see if it is relevant for the message. In
   this example it doesn't make much difference, but if multiple authors
   wanted to collaborate using a single port to communicate with a worker, it
   would allow for independent code instead of changes having to all be made
   to a single event handling function.

  <p>Because event listeners are registered using <code
   title="">addEventListener()</code> instead of <code
   title=handler-MessagePort-onmessage>onmessge</code>, the events remain
   queued until the <code title=dom-MessagePort-start>start()</code> method
   is called on the message port, in the <code title="">init()</code>
   function called from the <code title=handler-onload>onload</code> handler.

  <p>Registering event listeners in this way also allows you to unregister
   specific listeners when you are done with them, as is done with the <code
   title="">configure()</code> method in this example.

  <p>Finally, the worker:

  <pre>
var nextName = 0;
function getNextName() {
  // this could use more friendly names
  // but for now just return a number
  return nextName++;
}

var map = [
 [0, 0, 0, 0, 0, 0, 0],
 [1, 1, 0, 1, 0, 1, 1],
 [0, 1, 0, 1, 0, 0, 0],
 [0, 1, 0, 1, 0, 1, 1],
 [0, 0, 0, 1, 0, 0, 0],
 [1, 0, 0, 1, 1, 1, 1],
 [1, 1, 0, 1, 1, 0, 1],
];

function wrapX(x) {
  if (x &lt; 0) return wrapX(x + map[0].length);
  if (x >= map[0].length) return wrapX(x - map[0].length);
  return x;
}

function wrapY(y) {
  if (y &lt; 0) return wrapY(y + map.length);
  if (y >= map[0].length) return wrapY(y - map.length);
  return y;
}

function sendMapData(viewer) {
  var data = '';
  for (var y = viewer.y-1; y &lt;= viewer.y+1; y += 1) {
    for (var x = viewer.x-1; x &lt;= viewer.x+1; x += 1) {
      if (data != '')
        data += ',';
      data += map[y][x];
    }
  }
  viewer.port.postMessage('map ' + data);
}

var viewers = {};
onconnect = function (event) {
  event.port._name = getNextName();
  event.port._data = { port: event.port, x: 0, y: 0, };
  viewers[event.port._name] = event.port._data;
  event.port.postMessage('cfg ' + name);
  event.port.onmessage = getMessage;
  sendMapData(event.port._data);
};

function getMessage(event) {
  switch (event.message.substr(0, 4)) {
    case 'mov ':
      var direction = event.message.substr(4);
      var dx = 0;
      var dy = 0;
      switch (direction) {
        case 'up': dy = -1; break;
        case 'down': dy = 1; break;
        case 'left': dx = -1; break;
        case 'right': dx = 1; break;
      }
      event.target._data.x = wrapX(event.target._data.x + dx);
      event.target._data.y = wrapY(event.target._data.y + dy);
      sendMapData(event.target._data);
      break;
    case 'set ':
      var value = event.message.substr(4);
      map[event.target._data.y][event.target._data.x] = value;
      for (var viewer in viewers)
        sendMapData(viewers[viewer]);
      break;
    case 'txt ':
      var name = event.target._name;
      var message = event.message.substr(4);
      for (var viewer in viewers)
        viewers[viewer].port.postMessage('txt ' + name + ' ' + message);
      break;
    case 'msg ':
      var party1 = event._data;
      var party2 = viewers[event.message.substr(4).split(' ', 1)];
      if (party2) {
        var channel = new MessageChannel();
        party1.port.postMessage('msg ' + party2.name, channel.port1);
        party2.port.postMessage('msg ' + party1.name, channel.port2);
      }
      break;
  }
}</pre>

  <p><strong>Connecting to multiple pages</strong>. Instead of using the
   <code title=dom-WorkerGlobalScope-port><a href="#port">port</a></code>
   global variable in the worker, the script uses the <code
   title=handler-WorkerGlobalScope-onconnect><a
   href="#onconnect">onconnect</a></code> event listener to listen for
   multiple connections.

  <p><strong>Direct channels</strong>. When the worker receives a "msg"
   message from one viewer naming another viewer, it sets up a direct
   connection between the two, so that the two viewers can communicate
   directly without the worker having to proxy all the messages.

  <p><a href="http://www.whatwg.org/demos/workers/multiviewer/page.html">View
   this example online</a>.

  <h4 id=delegation><span class=secno>1.1.5 </span>Delegation</h4>

  <p><em>This section is non-normative.</em>

  <p>With multicore CPUs becoming prevalent, one way to obtain better
   performance is to split computationally expensive tasks amongst multiple
   workers. In this example, a computationally expensive task that is to be
   performed for every number from 1 to 10,000,000 is farmed out to ten
   subworkers.

  <p>The main page is as follows, it just reports the result:

  <pre>&lt;!DOCTYPE HTML>
&lt;html>
 &lt;head>
  &lt;title>Worker example: One-core computation&lt;/title>
 &lt;/head>
 &lt;body>
  &lt;p>The highest prime number discovered so far is: &lt;output id="result">&lt;/output>&lt;/p>
  &lt;script>
   var worker = createWorker('worker.js');
   worker.port.onmessage = function (event) {
     document.getElementById('result').textContent = event.message;
   };
  &lt;/script>
 &lt;/body>
&lt;/html></pre>

  <p>The worker itself is as follows:

  <pre>// settings
var num_workers = 10;
var items_per_worker = 1000000;

// start the workers
var result = 0;
var pending_workers = num_workers;
for (var i = 0; i &lt; num_workers; i += 1) {
  var worker = createWorker('core.js');
  worker.port.postMessage(i * items_per_worker);
  worker.port.postMessage((i+1) * items_per_worker);
  worker.port.onmessage = storeResult;
}

// handle the results
function storeResult(event) {
  result += 1*event.message;
  pending_workers -= 1;
  if (pending_workers &lt;= 0)
    port.postMessage(result); // finished!
}</pre>

  <p>It consists of a loop to start the subworkers, and then a handler that
   waits for all the subworkers to respond.

  <p>The subworkers are implemented as follows:

  <pre>var start;
onmessage = getStart;
function getStart(event) {
  start = 1*event.message;
  onmessage = getEnd;
}

var end;
function getEnd(event) {
  end = 1*event.message;
  onmessage = null;
  do();
}

function do() {
  var result = 0;
  for (var i = start; i &lt; end; i += 1) {
    // perform some complex calculation here
    result += 1;
  }
  port.postMessage(result);
}</pre>

  <p>They receive two numbers in two events, perform the computation for the
   range of numbers thus specified, and then report the result back to the
   parent.

  <p><a href="http://www.whatwg.org/demos/workers/multicore/page.html">View
   this example online</a>.

  <h4 id=providing><span class=secno>1.1.6 </span>Providing libraries</h4>

  <p><em>This section is non-normative.</em>

  <p>Suppose that a cryptography library is made available that provides
   three tasks:

  <dl>
   <dt>Generate a public/private key pair

   <dd>Takes a port, on which it will send two messages, first the public key
    and then the private key.

   <dt>Given a plaintext and a public key, return the corresponding
    cyphertext

   <dd>Takes a port, to which any number of messages can be sent, the first
    giving the public key, and the remainder giving the plaintext, each of
    which is encrypted and then sent on that same channel as the cyphertext.
    The user can close the port when it is done encrypting content.

   <dt>Given a cyphertext and a private key, return the corresponding
    plaintext

   <dd>Takes a port, to which any number of messages can be sent, the first
    giving the private key, and the remainder giving the cyphertext, each of
    which is decrypted and then sent on that same channel as the plaintext.
    The user can close the port when it is done decrypting content.
  </dl>

  <p>The library itself is as follows:

  <pre>function handleMessage(e) {
  if (e.message == "genkeys")
    genkeys(e.port);
  else if (e.message == "encrypt")
    encrypt(e.port);
  else if (e.message == "decrypt")
    decrypt(e.port);
}

function genkeys(p) {
  var keys = _generateKeyPair();
  p.postMessage(keys[0]);
  p.postMessage(keys[1]);
}

function encrypt(p) {
  var key, state = 0;
  p.onmessage = function (e) {
    if (state == 0) {
      key = e.message;
      state = 1;
    } else {
      p.postMessage(_encrypt(key, e.message));
    }
  };
}

function decrypt(p) {
  var key, state = 0;
  p.onmessage = function (e) {
    if (state == 0) {
      key = e.message;
      state = 1;
    } else {
      p.postMessage(_decrypt(key, e.message));
    }
  };
}

onconnect = function (e) { e.port.onmessage = handleMessage; }


// the "crypto" functions:

function _generateKeyPair() {
  return [Math.random(), Math.random()];
}

function _encrypt(k, s) {
  return 'encrypted-' + k + ' ' + s;
}

function _decrypt(k, s) {
  return s.substr(s.indexOf(' ')+1);
}</pre>

  <p>Note that the crypto functions here are just stubs and don't do real
   cryptography.

  <p>This library could be used as follows:

  <pre>&lt;!DOCTYPE HTML>
&lt;html>
 &lt;head>
  &lt;title>Worker example: Crypto library&lt;/title>
  &lt;script>
   var crytoLib = createWorker('libcrypto-v1.js'); // or could use 'libcrypto-v2.js'
   function getKeys() {
     var state = 0;
     cryptoLib.port.startConversation("genkeys").onmessage = function (e) {
       if (state == 0)
         document.getElementById('public').value = e.message;
       else if (state == 1)
         document.getElementById('private').value = e.message;
       state += 1;
     };
   }
   function enc() {
     var channel = new MessageChannel();
     cryptoLib.port.postMessage("encrypt", channel.port2);
     channel.port1.postMessage(document.getElementById('public').value);
     channel.port1.postMessage(document.getElementById('input').value);
     port1.onmessage = function (e) {
       document.getElementById('input').value = e.message;
       port1.close();
     };
   }
   function dec() {
     var channel = new MessageChannel();
     cryptoLib.port.postMessage("decrypt", channel.port2);
     channel.port1.postMessage(document.getElementById('private').value);
     channel.port1.postMessage(document.getElementById('input').value);
     port1.onmessage = function (e) {
       document.getElementById('input').value = e.message;
       port1.close();
     };
   }
  &lt;/script>
  &lt;style>
   textarea { display: block; }
  &lt;/style>
 &lt;/head>
 &lt;body onload="getKeys()">
  &lt;fieldset>
   &lt;legend>Keys&lt;/legend>
   &lt;p>&lt;label>Public Key: &lt;textarea id="public">&lt;/label>&lt;/p>
   &lt;p>&lt;label>Private Key: &lt;textarea id="private">&lt;/label>&lt;/p>
  &lt;/fieldset>
  &lt;p>&lt;label>Input: &lt;textarea id="input">&lt;/label>&lt;/p>
  &lt;p>&lt;button onclick="enc()">Encrypt&lt;/button> &lt;button onclick="dec()">Decrypt&lt;/button>&lt;/p>
 &lt;/body>
&lt;/html></pre>

  <p>A later version of the API, though, might want to offload all the crypto
   work onto subworkers. This could be done as follows:

  <pre>function handleMessage(e) {
  if (e.message == "genkeys")
    genkeys(e.port);
  else if (e.message == "encrypt")
    encrypt(e.port);
  else if (e.message == "decrypt")
    decrypt(e.port);
}

function genkeys(p) {
  var generator = createWorker('libcrypto-v2-generator.js');
  generator.postMessage('', p);
}

function encrypt(p) {
  p.onmessage = function (e) {
    var key = e.message;
    var encryptor = createWorker('libcrypto-v2-encryptor.js');
    encryptor.postMessage(key, p);
  };
}

function encrypt(p) {
  p.onmessage = function (e) {
    var key = e.message;
    var decryptor = createWorker('libcrypto-v2-decryptor.js');
    decryptor.postMessage(key, p);
  };
}

onconnect = function (e) { e.port.onmessage = handleMessage; }
</pre>

  <p>The little subworkers would then be as follows.

  <p>For generating key pairs:

  <pre>port.onmessage = function (e) {
  e.port.postMessage(Math.random());
  e.port.postMessage(Math.random());
  close();
}
</pre>

  <p>For encrypting:

  <pre>port.onmessage = function (e) {
  var key = e.message;
  e.port.onmessage = function (e) {
    var s = e.message;
    port.postMessage('encrypted-' + key + ' ' + s);
  }
  e.port.onunload = function (e) {
    close();
  }
}</pre>

  <p>For decrypting:

  <pre>port.onmessage = function (e) {
  var key = e.message;
  e.port.onmessage = function (e) {
    var s = e.message;
    port.postMessage(s.substr(s.indexOf(' ')+1));
  }
  e.port.onunload = function (e) {
    close();
  }
}</pre>

  <p>Notice how the users of the API don't have to even know that this is
   happening &mdash; the API hasn't changed; the library can delegate to
   subworkers without changing its API, even though it is accepting data
   using message channels.

  <p><a href="http://www.whatwg.org/demos/workers/crypto/page.html">View this
   example online</a>.

  <h4 id=granting><span class=secno>1.1.7 </span>Granting capabilities</h4>

  <p><em>This section is non-normative.</em>

  <p class=big-issue>...

  <h3 id=conformance><span class=secno>1.2 </span>Conformance requirements</h3>

  <p>All diagrams, examples, and notes in this specification are
   non-normative, as are all sections explicitly marked non-normative.
   Everything else in this specification is normative.

  <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
  NOT",-->
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the
   normative parts of this document are to be interpreted as described in
   RFC2119. For readability, these words do not appear in all uppercase
   letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
  <!-- XXX but they should be
  marked up -->

  <p>Requirements phrased in the imperative as part of algorithms (such as
   "strip any leading space characters" or "return false and abort these
   steps") are to be interpreted with the meaning of the key word ("must",
   "should", "may", etc) used in introducing the algorithm.

  <p>Some conformance requirements are phrased as requirements on attributes,
   methods or objects. Such requirements are to be interpreted as
   requirements on user agents.

  <p>Conformance requirements phrased as algorithms or specific steps may be
   implemented in any manner, so long as the end result is equivalent. (In
   particular, the algorithms defined in this specification are intended to
   be easy to follow, and not intended to be performant.)

  <p>The only conformance class defined by this specification is user agents.

  <p>User agents may impose implementation-specific limits on otherwise
   unconstrained inputs, e.g. to prevent denial of service attacks, to guard
   against running out of memory, or to work around platform-specific
   limitations.

  <h4 id=dependencies><span class=secno>1.2.1 </span>Dependencies</h4>

  <p>This specification relies on several other underlying specifications.

  <dl>
   <dt>HTML5

   <dd>
    <p>Many fundamental concepts from HTML5 are used by this specification.
     <a href="#refsHTML5">[HTML5]</a></p>

   <dt>ECMAScript

   <dd>
    <p>This specification is intended to be used with JavaScript as the
     scripting language. <a href="#refsJS">[JS]</a></p>

   <dt>WebIDL

   <dd>
    <p>The IDL blocks in this specification use the semantics of the WebIDL
     specification. <a href="#refsWebIDL">[WebIDL]</a></p>
  </dl>

  <h3 id=terminology><span class=secno>1.3 </span>Terminology</h3>

  <p>For simplicity, terms such as <em>shown</em>, <em>displayed</em>, and
   <em>visible</em> might sometimes be used when referring to the way a
   document is rendered to the user. These terms are not meant to imply a
   visual medium; they must be considered to apply to other media in
   equivalent ways.

  <p>The construction "a <code title="">Foo</code> object", where <code
   title="">Foo</code> is actually an interface, is sometimes used instead of
   the more accurate "an object implementing the interface <code
   title="">Foo</code>".

  <p>The term DOM is used to refer to the API set made available to scripts
   in Web applications, and does not necessarily imply the existence of an
   actual <code>Document</code> object or of any other <code>Node</code>
   objects as defined in the DOM Core specifications. <a
   href="#refsDOM3CORE">[DOM3CORE]</a>

  <p>A DOM attribute is said to be <em>getting</em> when its value is being
   retrieved (e.g. by author script), and is said to be <em>setting</em> when
   a new value is assigned to it.

  <p>If a DOM object is said to be <dfn id=live>live</dfn>, then that means
   that any attributes returning that object must always return the same
   object (not a new object each time), and the attributes and methods on
   that object must operate on the actual underlying data, not a snapshot of
   the data.

  <h2 id=infrastructure><span class=secno>2. </span>Infrastructure</h2>

  <h3 id=the-workerglobalscope><span class=secno>2.1 </span>The <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> interface</h3>

  <pre
   class=idl>[NoInterfaceObject] interface <dfn id=workerglobalscope>WorkerGlobalScope</dfn> {
  // core worker features
  readonly attribute <a href="#workerglobalscope">WorkerGlobalScope</a> <a href="#self" title=dom-WorkerGlobalScope-self>self</a>;
  readonly attribute <a href="#workerlocation">WorkerLocation</a> <a href="#location" title=dom-WorkerGlobalScope-location>location</a>;
  readonly attribute DOMString <a href="#name" title=dom-WorkerGlobalScope-name>name</a>;
  readonly attribute boolean <a href="#closing" title=dom-WorkerGlobalScope-closing>closing</a>;
  void <a href="#close" title=dom-WorkerGlobalScope-close>close</a>();

  // event handler attributes
           attribute <span>EventListener</span> <a href="#onconnect" title=handler-WorkerGlobalScope-onconnect>onconnect</a>;
           attribute <span>EventListener</span> <a href="#onunload" title=handler-WorkerGlobalScope-onunload>onunload</a>;
};</pre>

  <p>Objects implementing the <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> interface must also
   implement the <code>EventTarget</code> interface.

  <p>The <dfn id=self
   title=dom-WorkerGlobalScope-self><code>self</code></dfn> attribute must
   return the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
   object itself.

  <p>The <dfn id=location
   title=dom-WorkerGlobalScope-location><code>location</code></dfn> attribute
   must return the <code><a href="#workerlocation">WorkerLocation</a></code>
   object created for the <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> object when the
   worker was created. It represents the <span>absolute URL</span> of the
   script that was used to initialize the worker.

  <p>The <dfn id=name
   title=dom-WorkerGlobalScope-name><code>name</code></dfn> attribute must
   return the value it was assigned when the <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> object was created
   by the "<a href="#run-a">run a worker</a>" algorithm. If it has a value
   that isn't the empty string, its value represents the name that can be
   used to obtain a reference to the worker using the <code
   title=dom-WorkerFactory-createSharedWorker><a
   href="#createsharedworker">createSharedWorker()</a></code> method.

  <p>The <dfn id=closing
   title=dom-WorkerGlobalScope-closing><code>closing</code></dfn> attribute
   must return false until it is set to true by one of the algorithms in the
   processing model section below.

  <p>The following are the <span>event handler DOM attributes</span> that
   must be supported by objects implementing the <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> interface:

  <dl>
   <dt><dfn id=onconnect
    title=handler-WorkerGlobalScope-onconnect><code>onconnect</code></dfn>

   <dd>
    <p>Must be invoked whenever a <code
     title=event-WorkerGlobalScope-connect>connect</code> event is targeted
     at or bubbles through the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object.

   <dt><dfn id=onunload
    title=handler-WorkerGlobalScope-onunload><code>onunload</code></dfn>

   <dd>
    <p>Must be invoked whenever a <code title=event-unload>unload</code>
     event is targeted at or bubbles through the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object.
  </dl>

  <p>In addition to the above members, the <a href="#success" title="worker
   creation succeeded">worker creation success steps</a> add a <dfn id=port
   title=dom-WorkerGlobalScope-port><code>port</code></dfn> property to the
   object.

  <h3 id=base-urls><span class=secno>2.2 </span>Base URLs and origins of
   workers</h3>

  <p>The <span>base URL</span> of a <span>URL</span> passed to an API in a
   worker is the <span>absolute URL</span> given that the worker's <code
   title=dom-WorkerGlobalScope-location><a
   href="#location">location</a></code> attribute represents.

  <p>Both the <span>origin</span> and <span>effective script origin</span> of
   scripts running in workers are the <span>origin</span> of the
   <span>absolute URL</span> given that the worker's <code
   title=dom-WorkerGlobalScope-location><a
   href="#location">location</a></code> attribute represents.

  <h3 id=the-queue><span class=secno>2.3 </span>The queue of events</h3>

  <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
   object is asssociated with a <dfn id=queue>queue of events</dfn>, which is
   initially empty.

  <p>An event in the queue can be a DOM event or a timeout callback.

  <p>All asynchronous callbacks and events that would be called or dispatched
   in the worker must be added to the worker's queue, with the "<a
   href="#run-a">run a worker</a>" processing model below taking care of
   actually calling the callbacks or dispatching the events.

  <p>Once the <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code>'s <code
   title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
   attribute is set to true, the queue must discard anything else that would
   be added to it. Effectively, once the <code
   title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
   attribute is true, timers stop firing, notifications for all pending
   asynchronous operations are dropped, etc.

  <h3 id=the-workers><span class=secno>2.4 </span>The worker's ports</h3>

  <p>Workers communicate with other workers and with <span title="browsing
   context">browsing contexts</span> through <span title="channel
   messaging">message channels</span> and their <code>MessagePort</code>
   objects.

  <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
   <var title="">worker</var> has a list of <dfn id=the-workers0>the worker's
   ports</dfn>, which consists of all the <code>MessagePort</code> objects
   that are entangled with another port and that have one (but only one) port
   owned by <var title="">worker</var>. This list includes all the
   <code>MessagePort</code> objects that are in events pending in the <a
   href="#queue">queue of events</a>.

  <hr>

  <p>A worker is said to be a <dfn id=permissible>permissible worker</dfn> if
   either:

  <ul>
   <li>at some point past or present a <code>MessagePort</code> owned by the
    worker was entangled with a <code>MessagePort</code> <var
    title="">p</var> whose owner is a <code>Window</code> object whose
    <span>active document</span> is the <code>Document</code> that was that
    <span>browsing context</span>'s <span>active document</span> when <var
    title="">p</var> was created, and that <code>Document</code> is
    <span>fully active</span>, or

   <li>at some point past or present a <code>MessagePort</code> owned by the
    worker was entangled with a <code>MessagePort</code> owned by another
    worker that is currently a <a href="#permissible">permissible worker</a>.
  </ul>

  <hr>

  <p>A worker is said to be a <dfn id=protected>protected worker</dfn> if
   either:

  <ul>
   <li>it has outstanding timers, database transactions, or network
    connections, and is a <a href="#permissible">permissible worker</a>, or:

   <li>there is a <a href="#protected">protected worker</a> that at some
    point past or present owned a <code>MessagePort</code> that was entangled
    with a <code>MessagePort</code> owned by this worker.
  </ul>

  <hr>

  <p>A worker is said to be an <dfn id=active>active needed worker</dfn> if
   either:

  <ul>
   <li>the worker is a <a href="#protected">protected worker</a>, or

   <li>at least one of the <a href="#the-workers0">the worker's ports</a> is
    entangled with a <code>MessagePort</code> <var title="">p</var> whose
    owner is a <code>Window</code> object whose <span>active document</span>
    is the <code>Document</code> that was that <span>browsing
    context</span>'s <span>active document</span> when that
    <code>MessagePort</code> <var title="">p</var> was created, and that
    <code>Document</code> is <span>fully active</span>, or

   <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
    an entangled <code>MessagePort</code> owned by a <code><a
    href="#workerglobalscope">WorkerGlobalScope</a></code> object that is
    itself an <a href="#active">active needed worker</a>.
  </ul>

  <hr>

  <p>A worker is said to be a <dfn id=suspendable>suspendable worker</dfn> if
   it is not an <a href="#active">active needed worker</a> but either:

  <ul>
   <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
    an entangled <code>MessagePort</code> owned by a <code>Window</code>
    object, or

   <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
    an entangled <code>MessagePort</code> owned by a <code><a
    href="#workerglobalscope">WorkerGlobalScope</a></code> object that is
    itself a <span>needed worker</span>.
  </ul>

  <h3 id=processing><span class=secno>2.5 </span>Processing model</h3>

  <p>When a user agent is to <dfn id=run-a>run a worker</dfn> named <var
   title="">name</var> for a script with <span>URL</span> <var
   title="">url</var>, a browsing context <var title="">owner browsing
   context</var> and a <code>Document</code> <var title="">owner
   document</var>, it must run the following steps in a completely separate
   and parallel execution environment:

  <ol>
   <li>
    <p>Attempt to <span>fetch</span><!-- XXX --> the resource identified by
     <var title="">url</var>.</p>

    <p>If the attempt fails, then abort these steps and invoke the <a
     href="#worker2" title="worker creation failed">error handling steps</a>
     defined by the algorithm that called this one.</p>

    <p>If the attempt succeeds, then let <var title="">script</var> be the
     resource that was obtained.</p>

    <p class=note>As with <code>script</code> elements, the MIME type of the
     script is ignored. Unlike with <code>script</code> elements, there is no
     way to override the type. It's always assumed to be JavaScript.</p>
    <!-- XXX people will complain about
    this. I guess we might want to examine the MIME type... -->
    

   <li>
    <p>Create a new <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object, <var
     title="">worker</var>.</p>

   <li>
    <p>Set the <code title=dom-WorkerGlobalScope-name><a
     href="#name">name</a></code> attribute of <var title="">worker</var> to
     the value of <var title="">name</var>.</p>

   <li>
    <p>Create a new <code><a href="#workerlocation">WorkerLocation</a></code>
     object for the <code title=dom-WorkerGlobalScope-location><a
     href="#location">location</a></code> attribute of <var
     title="">worker</var>, representing <var title="">url</var>.</p>

   <li>
    <p>Let <var title="">script</var>'s <span>script execution context</span>
     (and thus also <span>global object</span>) be <var
     title="">worker</var>.</p>

   <li>
    <p>Let <var title="">script</var>'s <span>script browsing context</span>
     be <var title="">owner browsing context</var>.</p>

   <li>
    <p>Let <var title="">script</var>'s <span>script document context</span>
     be <var title="">owner document</var>.</p>

   <li>
    <p>Invoke the <a href="#success" title="worker creation
     succeeded">success steps</a> defined by the algorithm that called this
     one.</p>

    <p class=note>This will usually add an event to the <a
     href="#queue">queue of events</a> and set the <code
     title=dom-WorkerGlobalScope-port><a href="#port">port</a></code>
     property on the <var title="">worker</var> object. If it does, that
     event will have a <code>MessagePort</code> and thus the list of <a
     href="#the-workers0">the worker's ports</a> will not be empty. If it
     doesn't, then the next step will set the <var title="">worker</var>
     object's <code title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute to true.</p>

   <li>
    <p><strong>Closing orphan workers</strong>: Start monitoring <var
     title="">worker</var>, such that as soon as the worker stops being
     either an <a href="#active">active needed worker</a> or a <a
     href="#suspendable">suspendable worker</a>, the <var
     title="">worker</var> object's <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute is set to true and an event
     named <code title=event-unload>unload</code>, which uses the
     <code>Event</code> object, which does not bubble, and which is not
     cancelable, is added it to the worker's <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
     href="#queue">queue of events</a>, targetted at the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object.</p>

   <li>
    <p><strong>Suspending workers</strong>: Start monitoring <var
     title="">worker</var>, such that whenever the <var title="">worker</var>
     object's <code title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute is false and the worker is
     a <a href="#suspendable">suspendable worker</a>, the user agent suspends
     execution of script in that worker until such time as either the <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute switches to true or the
     worker stops being a <a href="#suspendable">suspendable worker</a>.</p>

   <li>
    <p>Run <var title="">script</var> until it either returns, fails to catch
     an exception, or gets prematurely aborted by the "<a href="#kill-a">kill
     a worker</a>" algorithm below.</p>

    <p class=note>If the script gets aborted by the "<a href="#kill-a">kill a
     worker</a>" algorithm, then that same algorithm will cause there to only
     be a single event in the <a href="#queue">queue of events</a> at the
     next step, namely the <code title=message-unload>unload</code> event.</p>

   <li>
    <p><i>Event loop</i>: Wait until either there is an event in the <a
     href="#queue">queue of events</a> associated with <var
     title="">worker</var> or the <var title="">worker</var> object's <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute is set to true.</p>

   <li>
    <p>Dispatch the oldest event or callback in the <a href="#queue">queue of
     events</a>, if any. The handling of this event or the execution of this
     callback might get prematurely aborted by the "<a href="#kill-a">kill a
     worker</a>" algorithm below.</p>

   <li>
    <p>If there are any more events in the <a href="#queue">queue of
     events</a> or if the <var title="">worker</var> object's <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute is set to false, then jump
     back to the step above labeled <i>event loop</i>.</p>

   <li>
    <p class=big-issue>timers, intervals, XMLHttpRequests, database
     transactions, etc, must be killed; ports must be unentangled</p>

   <li>
    <p>At the next available opportunity, after any scripts have finished
     executing<!-- XXX queue -->, <span>fire a simple event</span> called
     <code title=event-unload>unload</code> at any <code><a
     href="#worker1">Worker</a></code> objects associated with this worker.</p>
  </ol>

  <hr>

  <p>When a user agent is to <dfn id=kill-a>kill a worker</dfn>, it must run
   the following steps in parallel with the worker's main loop (the "<a
   href="#run-a">run a worker</a>" processing model defined above):

  <ol>
   <li>
    <p>Create an <code>Event</code> object with the event name <code
     title=event-unload>unload</code>, which does not bubble and is not
     cancelable, and add it to the worker's <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
     href="#queue">queue of events</a>, targetted at the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
   </li>
   <!-- XXX shouldn't add one if closing is
   already true, assuming unload has already been added to the queue
   (?) -->

   <li>
    <p>Set the worker's <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object's <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute to true.

   <li>
    <p>Wait a user-agent-defined amount of time. If the "<a href="#run-a">run
     a worker</a>" processing model defined above immediately starts running
     event listeners registered for the <code
     title=event-unload>unload</code> event, this time should not be zero
     &mdash; the idea is that the <code title=event-unload>unload</code>
     event can be used to clean up when shutting down unexpectedly.

   <li>
    <p>If there are any events in the <a href="#queue">queue of events</a>
     other than the <code title=event-unload>unload</code> event that this
     algorithm just added, discard them without dispatching them.

   <li>
    <p>If the <code title=event-unload>unload</code> event that this
     algorithm just added hasn't yet been dispatched, then abort the script
     currently running in the worker.

   <li>
    <p>Wait a user-agent-defined amount of time.

   <li>
    <p>Abort the script currently running in the worker (if any script is
     running, then it will be a handler for the <code
     title=event-unload>unload</code> event).
  </ol>

  <p>User agents may invoke the "<a href="#kill-a">kill a worker</a>"
   processing model on a worker at any time, e.g. in response to user
   requests, in response to CPU quota management, or when a worker stops
   being an <a href="#active">active needed worker</a> if the worker
   continues executing even after its <code
   title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
   attribute was set to true.

  <hr>

  <p>When a script invokes the <dfn id=close
   title=dom-WorkerGlobalScope-close><code>close()</code></dfn> method on a
   <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object,
   the user agent must run the following steps:

  <ol>
   <li>
    <p>Create an <code>Event</code> object with the event name <code
     title=event-unload>unload</code>, which does not bubble and is not
     cancelable, and add it to the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
     href="#queue">queue of events</a>, targetted at the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.

   <li>
    <p>Set the worker's <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object's <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute to true.

   <li>
    <p>For each <code>MessagePort</code> object that is entangled with
     another port and that has one (but only one) port whose owner is the
     <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object
     on which the method was invoked, run the following substeps:</p>

    <ol>
     <li>
      <p>Unentangle the two ports.

     <li>
      <p>At the next available opportunity, after any scripts have finished
       executing<!-- XXX queue -->, <span>fire a simple event</span> called
       <code title=event-unload>unload</code> at the other port (the one
       whose owner is not the <code><a
       href="#workerglobalscope">WorkerGlobalScope</a></code> object on which
       the <code title=dom-WorkerGlobalScope-close><a
       href="#close">close()</a></code> method was called).
    </ol>
  </ol>

  <h3 id=creating><span class=secno>2.6 </span>Creating workers</h3>

  <pre
   class=idl>[NoInterfaceObject] interface <dfn id=workerfactory>WorkerFactory</dfn> {
  <a href="#worker1">Worker</a> <a href="#createworker" title=dom-WorkerFactory-createWorker>createWorker</a>(in DOMString scriptURL);
  <a href="#worker1">Worker</a> <a href="#createsharedworker" title=dom-WorkerFactory-createSharedWorker>createSharedWorker</a>(in DOMString name, in DOMString scriptURL);
};

interface <dfn id=worker1>Worker</dfn> {
  <span>MessagePort</span> <a href="#port0" title=dom-Worker-port>port</a>();

  // event handler attributes
           attribute <span>EventListener</span> <a href="#onload" title=handler-Worker-onload>onload</a>;
           attribute <span>EventListener</span> <a href="#onerror" title=handler-Worker-onerror>onerror</a>;
           attribute <span>EventListener</span> <a href="#onunload0" title=handler-Worker-onunload>onunload</a>;
};</pre>

  <p>Objects that implement the <code>Window</code> and <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> interfaces must
   also implement the <code><a href="#workerfactory">WorkerFactory</a></code>
   interface.

  <hr>

  <p>When the <dfn id=createworker
   title=dom-WorkerFactory-createWorker><code>createWorker(<var
   title="">scriptURL</var>)</code></dfn> method is invoked, the user agent
   must run the following steps:

  <ol>
   <li>
    <p><span title="resolve a url">Resolve</span> the <var
     title="">scriptURL</var> argument.

   <li>
    <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.

   <li>
    <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
     is not the <span title="same origin">same</span> as the origin of the
     script that invoked the method, then throw a <span>security
     exception</span>.

   <li>
    <p><a href="#create">Create a worker</a> from the resulting
     <span>absolute URL</span> whose name is the empty string.

   <li>
    <p>Return the <code><a href="#worker1">Worker</a></code> object returned
     from the <a href="#create">create a worker</a> algorithm.
  </ol>

  <hr>

  <p>When the <dfn id=createsharedworker
   title=dom-WorkerFactory-createSharedWorker><code>createSharedWorker(<var
   title="">name</var>, <var title="">scriptURL</var>)</code></dfn> method is
   invoked, the user agent must run the following steps:

  <ol>
   <li>
    <p><span title="resolve a url">Resolve</span> the <var
     title="">scriptURL</var> argument.

   <li>
    <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.

   <li>
    <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
     is not the <span title="same origin">same</span> as the origin of the
     script that invoked the method, then throw a <span>security
     exception</span>.

   <li>
    <p>If the <var title="">name</var> argument is the empty string, <a
     href="#create">create a worker</a> from the resulting <span>absolute
     URL</span>, whose name is the empty string, and return the <code><a
     href="#worker1">Worker</a></code> object returned from the <a
     href="#create">create a worker</a> algorithm. Then, abort these steps.

   <li>
    <p>If there exists a worker whose <code
     title=dom-WorkerGlobalScope-closing><a
     href="#closing">closing</a></code> attribute is false, whose <code
     title=dom-WorkerGlobalScope-name><a href="#name">name</a></code>
     attribute is exactly equal to the <var title="">name</var> argument, and
     whose <code title=dom-WorkerGlobalScope-location><a
     href="#location">location</a></code> attribute represents an
     <span>absolute URL</span> that has the <span>same origin</span> as the
     resulting <span>absolute URL</span>, then run these substeps:</p>

    <ol>
     <li>
      <p>If that worker's <code title=dom-WorkerGlobalScope-location><a
       href="#location">location</a></code> attribute represents an
       <span>absolute URL</span> that is not exactly equal to the resulting
       <span>absolute URL</span>, then throw a <code>URL_MISMATCH_ERR</code>
       exception and abort these steps. <span class=big-issue>code 21</span>

     <li>
      <p><span>Create a new <code>MessagePort</code> object</span> owned by
       the <span>script execution context</span> of the script that invoked
       the method.

     <li>
      <p><span>Create a new <code><a href="#worker1">Worker</a></code>
       object</span> associated with that worker, and assign the newly
       created port to its <code title=dom-Worker-port><a
       href="#port0">port</a></code> attribute.

     <li>
      <p>Return the newly created <code><a href="#worker1">Worker</a></code>
       object.

     <li>
      <p>Asynchronously, <a href="#connect" title="connect to a
       worker">connect</a> to this preexisting worker, with the newly created
       <code>MessagePort</code> and <code><a
       href="#worker1">Worker</a></code> objects.
    </ol>

    <p>Otherwise, <a href="#create">create a worker</a> from the resulting
     <span>absolute URL</span>, whose name is the value of the <var
     title="">name</var> argument, and return the <code><a
     href="#worker1">Worker</a></code> object returned from the <a
     href="#create">create a worker</a> algorithm.</p>
  </ol>

  <hr>

  <p>The steps to <dfn id=create>create a worker</dfn> from a
   <span>URL</span> <var title="">url</var> and whose name is <var
   title="">name</var>, in the context of a method call, are as follows:

  <ol>
   <li>
    <p><span>Create a new <code>MessagePort</code> object</span> owned by the
     <span>script execution context</span> of the script that invoked the
     method.

   <li>
    <p><span>Create a new <code><a href="#worker1">Worker</a></code>
     object</span>, associated with the worker that will be created below,
     and assign the newly created port to its <code title=dom-Worker-port><a
     href="#port0">port</a></code> attribute.

   <li>
    <p>Return that <code><a href="#worker1">Worker</a></code> object.

   <li>
    <p>In a parallel execution context (i.e. a separate thread or process or
     equivalent construct), <a href="#run-a">run a worker</a> named <var
     title="">name</var> for the script with <span>URL</span> <var
     title="">url</var>, with the <span>script browsing context</span> of the
     script that invoked the method as the <var title="">owner browsing
     context</var> and with the <span>script document context</span> of the
     script that invoked the method as the <var title="">owner
     document</var>.</p>

    <p>If that algorithm invokes the steps for <dfn id=success title="worker
     creation succeeded">success steps</dfn>, then <a href="#connect"
     title="connect to a worker">connect</a> to this new worker, with the
     newly created port, and if that algorithm returns a second new port,
     then add a new property <code title=dom-WorkerGlobalScope-port><a
     href="#port">port</a></code> on the new worker's <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object, whose
     value is the <code>MessagePort</code> object returned by the <a
     href="#connect">connect to a worker</a> algorithm.</p>

    <p>Otherwise, if the <dfn id=worker2>worker creation failed</dfn>, then
     at the next available opportunity, after any scripts have finished
     executing<!-- XXX queue -->, <span>fire a simple event</span> called
     <code title=event-error>error</code> at the newly created <code><a
     href="#worker1">Worker</a></code> object.</p>
  </ol>

  <hr>

  <p>The steps to <dfn id=connect>connect to a worker</dfn> given a
   <code>MessagePort</code> object <var title="">port</var> and a <code><a
   href="#worker1">Worker</a></code> object <var title="">worker</var> are as
   follows:

  <ol>
   <li>
    <p>If <var title="">port</var> would have been garbage collected, or if
     the <span>active document</span> of the owner of <var
     title="">port</var> is no longer the same <code>Document</code> object
     as when <var title="">port</var> was created, then do nothing. Abort
     these steps. If the worker was just created, it'll get killed
     immediately.</p>

   <li>
    <p><span>Create a new <code>MessagePort</code> object</span> owned by the
     <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> of the
     worker.

   <li>
    <p><span>Entangle</span> this newly created port and the port <var
     title="">port</var> that was passed to these steps.

   <li>
    <p>At the next available opportunity, after any scripts have finished
     executing<!-- XXX queue -->, <span>fire a simple event</span> called
     <code title=event-load>load</code> at <var title="">worker</var>.

   <li>
    <p>Create an event that uses the <code>MessageEvent</code> interface,
     with the name <code title=event-connect>connect</code>, which does not
     bubble, is cancelable, has no default action, has a <code
     title=dom-MessageEvent-data>data</code> attribute whose value is the
     empty string and has a <code
     title=dom-MessageEvent-messagePort>messagePort</code> attribute whose
     value is the newly created port, and add it to the worker's <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
     href="#queue">queue of events</a>, targetted at the <code><a
     href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.

   <li>
    <p>Return the newly created port.
  </ol>

  <hr>

  <p>The <dfn id=port0 title=dom-Worker-port><code>port</code></dfn>
   attribute on a <code><a href="#worker1">Worker</a></code> object must
   return the value it was assigned when the <code><a
   href="#worker1">Worker</a></code> object was created by the methods on the
   <code><a href="#workerfactory">WorkerFactory</a></code> interface.

  <p>The following are the <span>event handler DOM attributes</span> that
   must be supported by objects implementing the <code><a
   href="#worker1">Worker</a></code> interface:

  <dl>
   <dt><dfn id=onload title=handler-Worker-onload><code>onload</code></dfn>

   <dd>
    <p>Must be invoked whenever a <code title=event-load>load</code> event is
     targeted at or bubbles through the <code><a
     href="#worker1">Worker</a></code> object.

   <dt><dfn id=onerror
    title=handler-Worker-onerror><code>onerror</code></dfn>

   <dd>
    <p>Must be invoked whenever an <code title=event-error>error</code> event
     is targeted at or bubbles through the <code><a
     href="#worker1">Worker</a></code> object.

   <dt><dfn id=onunload0
    title=handler-Worker-onunload><code>onunload</code></dfn>

   <dd>
    <p>Must be invoked whenever an <code title=event-unload>unload</code>
     event is targeted at or bubbles through the <code><a
     href="#worker1">Worker</a></code> object.
  </dl>

  <h2 id=apis-available><span class=secno>3. </span>APIs available to workers</h2>

  <pre
   class=idl>[NoInterfaceObject] interface <dfn id=workerutils>WorkerUtils</dfn> {
  void <a href="#importscripts" title=dom-WorkerGlobalScope-importScripts>importScripts</a>([Variadic] in DOMString urls);
  readonly attribute <span>Storage</span> <a href="#localstorage" title=dom-localStorage>localStorage</a>;
  <span>Database</span> <a href="#opendatabase" title=dom-opendatabase>openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
  void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description);
  void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
};</pre>

  <p>Objects that implement the <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> interface must also
   implement the <code><a href="#workerutils">WorkerUtils</a></code>
   interface.

  <p class=big-issue>Need to define a sync database API.

  <p class=big-issue>May need to define a browser sniffing API (like
   window.navigator).</p>
  <!-- XXX ApplicationCache -->
  <!-- XXX a way to set cookies on the URL for the script -->
  <!-- XXX debugging: void log(in DOMString s); // log to console -->
  <!-- XXX debugging: onerror -->

  <hr>

  <p>The DOM APIs (<code>Node</code> objects, <code>Document</code> objects,
   etc) are not available to workers in this version of this specification.

  <h3 id=importing><span class=secno>3.1 </span>Importing scripts and
   libraries</h3>

  <p>When a script invokes the <dfn id=importscripts
   title=dom-WorkerGlobalScope-importScripts><code>importScripts(<var
   title="">urls</var>)</code></dfn> method on a <code><a
   href="#workerglobalscope">WorkerGlobalScope</a></code> object, the user
   agent must run the following steps:

  <ol>
   <li>
    <p>If there are no arguments, return without doing anything. Abort these
     steps.

   <li>
    <p><span title="resolve a url">Resolve</span> each argument.

   <li>
    <p>If any fail, throw a <code>SYNTAX_ERR</code> exception.

   <li>
    <p>If any of the resulting <span title="absolute URL">absolute
     URLs</span> have an <span>origin</span> that is not the <span
     title="same origin">same</span> as the origin of the script that invoked
     the method, then throw a <span>security exception</span>.

   <li>
    <p>Attempt to <span>fetch</span> each resource identified by the
     resulting <span title="absolute URLs">absolute URL</span>.</p>

   <li>
    <p>For each argument in turn, in the order given, starting with the first
     one, run these substeps:</p>

    <ol>
     <li>
      <p>Wait for the fetching attempt for the corresponding resource to
       complete.</p>

      <p>If the fetching attempt failed, throw a <code>NETWORK_ERR</code>
       exception and abort all these steps. <a
       href="#refsXHR">[XHR]</a><!-- XXX get DOM Core updated instead
      --></p>

      <p>If the fetching attempt succeeded, then let <var
       title="">script</var> be the resource that was obtained.</p>

      <p class=note>As with the worker's script, the script here is always
       assumed to be JavaScript, regardless of the MIME type.</p>
      <!-- XXX -->

     <li>
      <p>Let <var title="">script</var>'s <span>script execution
       context</span>, <span>script browsing context</span>, and <span>script
       document context</span> be the same as for the script that was
       executed by the <a href="#run-a">run a worker</a> processing model for
       this worker.</p>

     <li>
      <p>Run <var title="">script</var> until it either returns, fails to
       catch an exception, or gets prematurely aborted by the "<a
       href="#kill-a">kill a worker</a>" algorithm above.</p>

      <p>If an exception was raised or if the script was prematurely aborted,
       then abort all these steps, letting the exception or aborting continue
       to be processed by the script that called the <code
       title=dom-WorkerGlobalScope-importScripts><a
       href="#importscripts">importScripts()</a></code> method.</p>

      <p>If the "<a href="#kill-a">kill a worker</a>" algorithm aborts the
       script then abort all these steps.</p>
    </ol>
  </ol>

  <h3 id=apis-defined><span class=secno>3.2 </span>APIs defined in other
   specifications</h3>

  <p>The <dfn id=localstorage
   title=dom-localStorage><code>localStorage</code></dfn>, <dfn
   id=opendatabase title=dom-opendatabase><code>openDatabase()</code></dfn>
   must act as defined for the APIs with the same names on the
   <code>Window</code> object in the HTML5 specification, with the exception
   that where the API would use the <span>origin</span> of the <span>active
   document</span> of the <span>browsing context</span> of the
   <code>Window</code> object on which the method was supposedly invoked, it
   must instead use the <span>origin</span> of the script that invoked the
   method. <a href="#refsHTML5">[HTML5]</a>

  <p>The <dfn id=shownotification
   title=dom-showNotification><code>showNotification()</code></dfn> methods
   must act as defined for the APIs with the same names on the
   <code>Window</code> object in the HTML5 specification. <a
   href="#refsHTML5">[HTML5]</a>

  <h3 id=interface><span class=secno>3.3 </span>Interface objects and
   constructors</h3>

  <p>There must be no interface objects and constructors available in the
   global scope of scripts whose <span>script execution context</span> is a
   <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object
   except for the following:

  <ul>
   <li>
    <p><code>XMLHttpRequest</code> and all interface objects and constructors
     defined by the XMLHttpRequest specifications, except that the
     <span>document response entity body</span> must always be null. <a
     href="#refsXHR">[XHR]</a>

   <li>
    <p>The <code>WebSocket</code> interface object and constructor.

   <li>
    <p>The <code>MessageChannel</code> interface object and constructor.
  </ul>

  <h3 id=worker0><span class=secno>3.4 </span>Worker locations</h3>

  <pre
   class=idl>[NoInterfaceObject] interface <dfn id=workerlocation>WorkerLocation</dfn> {
  readonly attribute DOMString <a href="#href" title=dom-WorkerLocation-href>href</a>;
  readonly attribute DOMString <a href="#protocol" title=dom-WorkerLocation-protocol>protocol</a>;
  readonly attribute DOMString <a href="#host" title=dom-WorkerLocation-host>host</a>;
  readonly attribute DOMString <a href="#hostname" title=dom-WorkerLocation-hostname>hostname</a>;
  readonly attribute DOMString <a href="#port1" title=dom-WorkerLocation-port>port</a>;
  readonly attribute DOMString <a href="#pathname" title=dom-WorkerLocation-pathname>pathname</a>;
  readonly attribute DOMString <a href="#search" title=dom-WorkerLocation-search>search</a>;
  readonly attribute DOMString <a href="#hash" title=dom-WorkerLocation-hash>hash</a>;
};</pre>

  <p>A <code><a href="#workerlocation">WorkerLocation</a></code> object
   represents an <span>absolute URL</span> set at its creation.

  <p>The <dfn id=href title=dom-WorkerLocation-href><code>href</code></dfn>
   attribute must return the <span>absolute URL</span> that the object
   represents.

  <p>The <code><a href="#workerlocation">WorkerLocation</a></code> interface
   also has the complement of <span>URL decomposition attributes</span>, <dfn
   id=protocol title=dom-WorkerLocation-protocol><code>protocol</code></dfn>,
   <dfn id=host title=dom-WorkerLocation-host><code>host</code></dfn>, <dfn
   id=port1 title=dom-WorkerLocation-port><code>port</code></dfn>, <dfn
   id=hostname title=dom-WorkerLocation-hostname><code>hostname</code></dfn>,
   <dfn id=pathname
   title=dom-WorkerLocation-pathname><code>pathname</code></dfn>, <dfn
   id=search title=dom-WorkerLocation-search><code>search</code></dfn>, and
   <dfn id=hash title=dom-WorkerLocation-hash><code>hash</code></dfn>. These
   must follow the rules given for URL decomposition attributes, with the
   <span title=concept-uda-input>input</span> being the <span>absolute
   URL</span> that the object represents (same as the <code
   title=dom-WorkerLocation-href><a href="#href">href</a></code> attribute),
   and the <span title=concept-uda-setter>common setter action</span> being a
   no-op, since the attributes are defined to be readonly. <a
   href="#refsHTML5">[HTML5]</a>

  <h2 class=no-num id=references>References</h2>

  <p class=big-issue>This section will be written in a future
   draft.<!--XXX-->

  <h2 class=no-num id=acknowledgements>Acknowledgements</h2>
  <!-- ACKS -->

  <p>Thanks to Aaron Boodman, Jonas Sicking, Maciej Stachowiak, Mike Smith,
   and Philip Taylor for their useful and substantial comments.

  <p>Huge thanks to the whole Gears team, who pioneered this technology and
   whose experience has been a huge influence on this specification.