Annotation of html5/workers/Overview.html, revision 1.46
1.1 ihickson 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
2: <!-- when publishing, change bits marked ZZZ -->
3:
4: <html lang=en-US-x-Hixie>
5: <head>
6: <title>Web Workers</title>
7: <link href="http://www.w3.org/StyleSheets/TR/%57%33%43-ED" rel=stylesheet
8: type="text/css">
9: <!-- ZZZ ED vs WD -->
10:
11: <body>
12: <div class=head>
13: <p><a href="http://www.w3.org/"><img alt=W3C height=48
14: src="http://www.w3.org/Icons/w3c_home" width=72></a></p>
15:
16: <h1 id=web-workers>Web Workers</h1>
17:
18: <h2 class="no-num no-toc" id=an-accompaniment>An accompaniment
19: specification for HTML5</h2>
20:
21: <h2 class="no-num no-toc" id=editors><!-- "W3C Working Draft" --> Editor's
1.42 ihickson 22: Draft <!--ZZZ--> 8 August 2008</h2>
1.1 ihickson 23:
24: <dl><!-- ZZZ: update the month/day
25: <dt>This Version:</dt>
26: <dd><a href="http://www.w3.org/TR/2008/WD-workers-20080101/">http://www.w3.org/TR/2008/WD-workers-20080101/</a></dd>
1.2 ihickson 27: <dt>Latest Published Version:</dt>
28: <dd><a href="http://www.w3.org/TR/workers/">http://www.w3.org/TR/workers/</a></dd>
1.1 ihickson 29: :ZZZ -->
30:
31: <dt>Latest Editor's Draft:
32:
33: <dd><a
34: href="http://dev.w3.org/html5/workers/">http://dev.w3.org/html5/workers/</a></dd>
1.2 ihickson 35: <!-- ZZZ: add the new version after it has shipped
36: <dt>Previous Versions:</dt>
37: <dd><a href="http://www.w3.org/TR/2008/WD-workers-20080101/">http://www.w3.org/TR/2008/WD-workers-20080101/</a>
38: :ZZZ -->
1.1 ihickson 39:
40: <dt>Editors:
41:
42: <dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.
43: </dl>
44:
45: <p class=copyright><a
46: href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
47: © 2008 <a href="http://www.w3.org/"><abbr title="World Wide Web
48: Consortium">W3C</abbr></a><sup>®</sup> (<a
49: href="http://www.csail.mit.edu/"><abbr title="Massachusetts Institute of
50: Technology">MIT</abbr></a>, <a href="http://www.ercim.org/"><abbr
51: title="European Research Consortium for Informatics and
52: Mathematics">ERCIM</abbr></a>, <a
53: href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C <a
54: href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
55: <a
56: href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
57: and <a
58: href="http://www.w3.org/Consortium/Legal/copyright-documents">document
59: use</a> rules apply.</p>
60: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
61:
62: <p class="alt copyright">The <a
63: href="http://www.whatwg.org/specs/web-workers/current-work/">WHATWG
64: version</a> of this specification is available under a more permissive
65: license.</p>
66: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
67: </div>
68:
69: <hr>
70:
71: <h2 class="no-num no-toc" id=abstract>Abstract</h2>
72:
73: <p>This specification defines an API that allows Web application authors to
74: spawn background workers running scripts in parallel to their main page.
75: This allows for thread-like operation with message-passing as the
76: coordination mechanism.
77:
78: <h2 class="no-num no-toc" id=status>Status of this document</h2>
79: <!-- intro boilerplate (required) -->
80:
81: <p><em>This section describes the status of this document at the time of
82: its publication. Other documents may supersede this document. A list of
83: current W3C publications and the most recently formally published revision
84: of this technical report can be found in the <a
85: href="http://www.w3.org/TR/">W3C technical reports index</a> at
86: http://www.w3.org/TR/.</em></p>
87: <!-- where to send feedback (required) -->
88:
89: <p>If you wish to make comments regarding this document, please send them
90: to <a
91: href="mailto:public-html-comments@w3.org">public-html-comments@w3.org</a>
92: (<a
93: href="mailto:public-html-comments-request@w3.org?subject=subscribe">subscribe</a>,
94: <a
95: href="http://lists.w3.org/Archives/Public/public-html-comments/">archives</a>)
96: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING SENTENCE TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
97: or <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a> (<a
98: href="http://lists.whatwg.org/listinfo.cgi/whatwg-whatwg.org">subscribe</a>,
99: <a
100: href="http://lists.whatwg.org/pipermail/whatwg-whatwg.org/">archives</a>).
101: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING SENTENCE TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
102: All feedback is welcome.</p>
103: <!-- stability (required) -->
104:
105: <p>Implementors should be aware that this specification is not stable.
106: <strong>Implementors who are not taking part in the discussions are likely
107: to find the specification changing out from under them in incompatible
108: ways.</strong> Vendors interested in implementing this specification
109: before it eventually reaches the Candidate Recommendation stage should
110: join the aforementioned mailing lists and take part in the discussions.</p>
111: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
112: <!-- version history or list of changes (required) -->
113:
114: <p>The latest stable version of the editor's draft of this specification is
115: always available on <a
116: href="http://dev.w3.org/html5/workers/Overview.html">the W3C CVS
117: server</a> and in the <a href="http://svn.whatwg.org/webworkers/">WHATWG
118: Subversion repository</a>. The latest editor's working copy (which may
119: contain unfinished text in the process of being prepared) is available <a
120: href="http://www.whatwg.org/specs/web-workers/current-work/">on the WHATWG
121: site</a>. Detailed change history can be obtained from the following
122: locations:</p>
123: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
124: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING LIST TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
125:
126: <ul>
127: <li>Twitter messages (non-editorial changes only): <a
128: href="http://twitter.com/WHATWG">http://twitter.com/WHATWG</a>
129:
130: <li>Interactive Web interface: <a
131: href="http://html5.org/tools/web-workers-tracker">http://html5.org/tools/web-workers-tracker</a>
132:
133: <li>Commit-Watchers mailing list: <a
134: href="http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org">http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a>
135:
136: <li>Subversion interface: <a
137: href="http://svn.whatwg.org/webworkers/">http://svn.whatwg.org/webworkers/</a>
138:
139: <li>CVS log: <a
140: href="http://dev.w3.org/cvsweb/html5/workers/Overview.html">http://dev.w3.org/cvsweb/html5/workers/Overview.html</a>
141: </ul>
142: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING LIST TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
143: <!-- status of document, group responsible (required) -->
144:
145: <p>The W3C <a href="http://www.w3.org/html/wg/">HTML Working Group</a> is
146: the W3C working group responsible for this specification's progress along
1.42 ihickson 147: the W3C Recommendation track. <!--ZZZ:--> This specification is the 8
1.25 ihickson 148: August 2008 <!--ZZZ "Working Draft"-->Editor's Draft. <!--:ZZZ--></p>
1.1 ihickson 149: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
150: <!-- relationship to other work (required) -->
151:
152: <p>This specification is also being produced by the <a
153: href="http://www.whatwg.org/">WHATWG</a>. The two specifications are
154: identical from the table of contents onwards.</p>
155: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
156: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
157: <!-- context and rationale (required) -->
158:
159: <p>This specification is intended to specify a part of the Web platform
160: closely related to HTML5. It is defined in a separate document primarily
161: to ease the cognitive load on reviewers.</p>
162: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
163: <!-- required patent boilerplate -->
164:
165: <p>This document was produced by a group operating under the <a
166: href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5 February
167: 2004 W3C Patent Policy</a>. W3C maintains a <a
168: href="http://www.w3.org/2004/01/pp-impl/40318/status"
169: rel=disclosure>public list of any patent disclosures</a> made in
170: connection with the deliverables of the group; that page also includes
171: instructions for disclosing a patent. An individual who has actual
172: knowledge of a patent which the individual believes contains <a
173: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
174: Claim(s)</a> must disclose the information in accordance with <a
175: href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
176: 6 of the W3C Patent Policy</a>.
177:
178: <h2 class="no-num no-toc" id=contents>Table of contents</h2>
179: <!--begin-toc-->
180:
181: <ul class=toc>
182: <li><a href="#introduction"><span class=secno>1. </span>Introduction</a>
183: <ul class=toc>
1.4 ihickson 184: <li><a href="#tutorial"><span class=secno>1.1 </span>Tutorial</a>
1.29 ihickson 185: <ul class=toc>
186: <li><a href="#a-background"><span class=secno>1.1.1 </span>A
1.32 ihickson 187: background number-crunching worker</a>
1.31 ihickson 188:
189: <li><a href="#a-worker"><span class=secno>1.1.2 </span>A worker for
190: updating a client-side database</a>
1.33 ihickson 191:
192: <li><a href="#worker"><span class=secno>1.1.3 </span>Worker used for
193: backgroud I/O</a>
1.34 ihickson 194:
195: <li><a href="#shared"><span class=secno>1.1.4 </span>Shared
196: workers</a>
197:
1.40 ihickson 198: <li><a href="#delegation"><span class=secno>1.1.5
199: </span>Delegation</a>
200:
201: <li><a href="#granting"><span class=secno>1.1.6 </span>Granting
1.34 ihickson 202: capabilities</a>
1.29 ihickson 203: </ul>
1.1 ihickson 204:
1.22 ihickson 205: <li><a href="#conformance"><span class=secno>1.2 </span>Conformance
1.1 ihickson 206: requirements</a>
207: <ul class=toc>
1.22 ihickson 208: <li><a href="#dependencies"><span class=secno>1.2.1
1.1 ihickson 209: </span>Dependencies</a>
210: </ul>
211:
1.22 ihickson 212: <li><a href="#terminology"><span class=secno>1.3 </span>Terminology</a>
1.4 ihickson 213: </ul>
214:
1.12 ihickson 215: <li><a href="#infrastructure"><span class=secno>2.
216: </span>Infrastructure</a>
1.4 ihickson 217: <ul class=toc>
1.26 ihickson 218: <li><a href="#the-workerglobalscope"><span class=secno>2.1 </span>The
219: <code>WorkerGlobalScope</code> interface</a>
1.4 ihickson 220:
1.15 ihickson 221: <li><a href="#base-urls"><span class=secno>2.2 </span>Base URLs and
222: origins of workers</a>
223:
224: <li><a href="#the-queue"><span class=secno>2.3 </span>The queue of
1.4 ihickson 225: events</a>
226:
1.15 ihickson 227: <li><a href="#the-workers"><span class=secno>2.4 </span>The worker's
1.9 ihickson 228: ports</a>
229:
1.15 ihickson 230: <li><a href="#processing"><span class=secno>2.5 </span>Processing
1.4 ihickson 231: model</a>
1.12 ihickson 232:
1.15 ihickson 233: <li><a href="#creating"><span class=secno>2.6 </span>Creating
1.12 ihickson 234: workers</a>
1.1 ihickson 235: </ul>
236:
1.12 ihickson 237: <li><a href="#apis-available"><span class=secno>3. </span>APIs available
238: to workers</a>
1.26 ihickson 239: <ul class=toc>
240: <li><a href="#importing"><span class=secno>3.1 </span>Importing scripts
241: and libraries</a>
242:
243: <li><a href="#apis-defined"><span class=secno>3.2 </span>APIs defined in
244: other specifications</a>
245:
246: <li><a href="#interface"><span class=secno>3.3 </span>Interface objects
247: and constructors</a>
1.34 ihickson 248:
249: <li><a href="#worker0"><span class=secno>3.4 </span>Worker locations</a>
250:
1.26 ihickson 251: </ul>
1.4 ihickson 252:
1.1 ihickson 253: <li class=no-num><a href="#references">References</a>
254:
255: <li class=no-num><a href="#acknowledgements">Acknowledgements</a>
256: </ul>
257: <!--end-toc-->
258:
259: <hr>
260:
261: <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
262:
1.4 ihickson 263: <h3 id=tutorial><span class=secno>1.1 </span>Tutorial</h3>
1.1 ihickson 264:
265: <p><em>This section is non-normative.</em>
266:
1.29 ihickson 267: <p>There are a variety of uses that workers can be put to. The following
268: subsections show various examples of this use.
269:
270: <h4 id=a-background><span class=secno>1.1.1 </span>A background
1.32 ihickson 271: number-crunching worker</h4>
1.29 ihickson 272:
273: <p><em>This section is non-normative.</em>
274:
275: <p>The simplest use of workers is for performing a computationally
276: expensive task without interrupting the user interface.
277:
1.32 ihickson 278: <p>In this example, the main document spawns a worker to (naïvely)
1.29 ihickson 279: compute prime numbers, and progressively displays the most recently found
280: prime number.
281:
282: <p>The main page is as follows:
283:
284: <pre><!DOCTYPE HTML>
285: <html>
286: <head>
1.40 ihickson 287: <title>Worker example: One-core computation</title>
1.29 ihickson 288: </head>
289: <body>
290: <p>The highest prime number discovered so far is: <output id="result"></output></p>
291: <script>
292: var worker = createWorker('worker.js');
1.43 ihickson 293: worker.port.onmessage = function (event) {
1.29 ihickson 294: document.getElementById('result').textContent = event.message;
295: };
296: </script>
297: </body>
298: </html></pre>
299:
300: <p>The <code title=dom-WorkerFactory-createWorker><a
301: href="#createworker">createWorker()</a></code> method call creates a
1.43 ihickson 302: worker and returns a <code><a href="#worker1">Worker</a></code> object
303: representing that worker and containing a <code>MessagePort</code> object,
304: which is used to communicate with the worker. That object's <code
1.29 ihickson 305: title=dom-MessagePort-onmessage>onmessage</code> event handler attribute
306: allows the code to receive messages from the worker.
307:
308: <p>The worker itself is as follows:
309:
310: <pre>var n = 1;
311: search: while (true) {
312: n += 1;
313: for (var i = 2; i <= Math.sqrt(n); i += 1)
314: if (n % i == 0)
315: continue search;
316: // found a prime!
317: port.postMessage(n);
318: }</pre>
319:
320: <p>The bulk of this code is simply an unoptimised search for a prime
321: number. To send a message back to the page, the <code
1.30 ihickson 322: title=dom-WorkerGlobalScope-port><a href="#port">port</a></code> variable
323: (defined automatically when the worker is created) is used to post a
324: message when a prime is found.
1.29 ihickson 325:
326: <p><a href="http://www.whatwg.org/demos/workers/primes/page.html">View this
327: example online</a>.
1.4 ihickson 328:
1.31 ihickson 329: <h4 id=a-worker><span class=secno>1.1.2 </span>A worker for updating a
330: client-side database</h4>
331:
332: <p><em>This section is non-normative.</em>
333:
334: <p>In this example, the main document spawns a worker whose only task is to
335: listen for notifications from the server, and, when appropriate, either
336: add or remove data from the client-side database.
337:
338: <p>Since no communication occurs between the worker and the main page, the
339: main page can start the worker by just doing:
340:
341: <pre><script>
342: createWorker('worker.js');
343: </script></pre>
344:
345: <p>The worker itself is as follows:
346:
347: <pre>var server = new WebSocket('ws://whatwg.org/database');
1.42 ihickson 348: var database = openDatabase('demobase', '1.0', 'Demo Database', 10240);
1.31 ihickson 349: server.onmessage = function (event) {
350: // data is in the format "command key value"
351: var data = event.message.split(' ');
352: switch (data[0]) {
353: case '+':
354: database.transaction(function(tx) {
355: tx.executeSql('INSERT INTO pairs (key, value) VALUES (?, ?)', data[1], data[2]);
356: });
357: case '-':
358: database.transaction(function(tx) {
359: tx.executeSql('DELETE FROM pairs WHERE key=? AND value=?', data[1], data[2]);
360: });
361: }
362: };</pre>
363:
364: <p>This connects to the server using the <code>WebSocket</code> mechanism
365: and opens the local database (which, we presume, has been created
366: earlier). The worker then just listens for messages from the worker and
367: acts on them as appropriate, forever (or until the main page is closed).
368:
369: <p><a
370: href="http://www.whatwg.org/demos/workers/database-updater/page.html">View
371: this example online</a>. (This example will not actually function, since
372: the server does not actually exist and the database is not created by this
373: sample code.)
374:
1.33 ihickson 375: <h4 id=worker><span class=secno>1.1.3 </span>Worker used for backgroud I/O</h4>
376:
377: <p><em>This section is non-normative.</em>
378:
379: <p>In this example, the main document uses two workers, one for fetching
380: stock updates for at regular intervals, and one for fetching performing
381: search queries that the user requests.
382:
383: <p>The main page is as follows:
384:
385: <pre><!DOCTYPE HTML>
386: <html>
387: <head>
388: <title>Worker example: Stock ticker</title>
389: <script>
390: // TICKER
391: var symbol = 'GOOG'; // default symbol to watch
392: var ticker = createWorker('ticker.js');
1.43 ihickson 393: ticker.port.postMessage(symbol);
1.33 ihickson 394:
395: // SEARCHER
396: var searcher = createWorker('searcher.js');
397: function search(query) {
1.43 ihickson 398: searcher.port.postMessage(query);
1.33 ihickson 399: }
400:
401: // SYMBOL SELECTION UI
402: function select(newSymbol) {
403: symbol = newSymbol;
1.43 ihickson 404: ticker.port.postMessage(symbol);
1.33 ihickson 405: }
406: </script>
407: </head>
408: <body>
409: <p><output id="symbol"></output> <output id="value"></output></p>
410: <script>
1.43 ihickson 411: ticker.port.onmessage = function (event) {
1.33 ihickson 412: var data = event.message.split(' ');
413: document.getElementById('symbol').textContent = data[0];
414: document.getElementById('value').textContent = data[1];
415: };
416: </script>
417: <p><label>Search: <input type="text" oninput="search(this.value)"></label></p>
418: <ul id="results"></ul>
419: <script>
1.43 ihickson 420: searcher.port.onmessage = function (event) {
1.33 ihickson 421: var data = event.message.split(' ');
422: var results = document.getElementById('results');
423: while (results.hasChildNodes()) // clear previous results
424: results.removeChild(results.firstChild);
425: for (var i = 0; i < data.length; i += 1) {
426: // add a list item with a button for each result
427: var li = document.createElement('li');
428: var button = document.createElement('button');
429: button.value = data[i];
430: button.type = 'button';
431: button.onclick = function () { select(this.value); };
432: button.textContent = data[i];
433: li.appendChild(button);
434: results.appendChild(li);
435: }
436: };
437: </script>
438: <p>(The data in this example is not real. Try searching for "Google" or "Apple".)</p>
439: </body>
440: </html></pre>
441:
442: <p>Messages are queued until the <code
443: title=handler-MessagePort-onmessage>onmessage</code> handler is set, so
444: even if it takes a while for the message handler to be attached, no data
445: is lost.
446:
447: <p>The two workers use a common library for performing the actual network
448: calls. This library is as follows:
449:
450: <pre>function get(url) {
451: try {
452: var xhr = new XMLHttpRequest();
453: xhr.open('GET', url, false);
454: xhr.send();
455: return xhr.responseText;
1.34 ihickson 456: } catch (e) {
1.33 ihickson 457: return ''; // turn all errors into empty results
458: }
459: }</pre>
460:
461: <p>The stock updater worker is as follows:
462:
1.45 ihickson 463: <pre>importScripts('io.js');
1.33 ihickson 464: var timer;
465: var symbol;
466: function update() {
467: port.postMessage(symbol + ' ' + get('stock.cgi?' + symbol));
468: timer = setTimeout(update, 10000);
469: }
470: port.onmessage = function (event) {
471: if (timer)
472: clearTimeout(timer);
473: symbol = event.message;
474: update();
475: };</pre>
476:
477: <p>The search query worker is as follows:
478:
1.45 ihickson 479: <pre>importScripts('io.js');
1.33 ihickson 480: port.onmessage = function (event) {
481: port.postMessage(get('search.cgi?' + event.message));
482: };</pre>
483:
1.36 ihickson 484: <p><a href="http://www.whatwg.org/demos/workers/stocks/page.html">View this
1.33 ihickson 485: example online</a>.
486:
1.34 ihickson 487: <h4 id=shared><span class=secno>1.1.4 </span>Shared workers</h4>
488:
1.36 ihickson 489: <p><em>This section is non-normative.</em>
490:
491: <p>In this example, multiple windows (viewers) can be opened that are all
492: viewing the same map. All the windows share the same map information, with
493: a single worker coordinating all the viewers. Each viewer can move around
494: idependently, but if they set any data on the map, all the viewers are
495: updated.
496:
497: <p>The main page isn't interesting, it merely provides a way to open the
498: viewers:
499:
500: <pre><!DOCTYPE HTML>
501: <html>
502: <head>
503: <title>Workers example: Multiviewer</title>
504: <script>
505: function openViewer() {
506: window.open('viewer.html');
507: }
508: </script>
509: </head>
510: <body>
511: <p><button type=button onclick="openViewer()">Open a new
512: viewer</button></p>
513: <p>Each viewer opens in a new window. You can have as many viewers
514: as you like, they all view the same data.</p>
515: </body>
516: </html></pre>
517:
518: <p>The viewer is more involved:
519:
520: <pre><!DOCTYPE HTML>
521: <html>
522: <head>
523: <title>Workers example: Multiviewer viewer</title>
524: <script>
525: var worker = createNamedWorker('worker.js', 'core');
526:
527: // CONFIGURATION
528: function configure(event) {
529: if (event.message.substr(0, 4) != 'cfg ') return;
530: var name = event.message.substr(4).split(' ', 1);
531: // update display to mention our name is name
532: document.getElementsByTagName('h1')[0].textContent += ' ' + name;
533: // no longer need this listener
1.43 ihickson 534: worker.port.removeEventListener('message', configure, false);
1.36 ihickson 535: }
1.43 ihickson 536: worker.port.addEventListener('message', configure, false);
1.36 ihickson 537:
538: // MAP
539: function paintMap(event) {
540: if (event.message.substr(0, 4) != 'map ') return;
541: var data = event.message.substr(4).split(',');
542: // display tiles data[0] .. data[8]
543: var canvas = document.getElementById('map');
544: var context = canvas.getContext('2d');
545: for (var y = 0; y < 3; y += 1) {
546: for (var x = 0; x < 3; x += 1) {
547: var tile = data[y * 3 + x];
548: if (tile == '0')
549: context.fillStyle = 'green';
550: else
551: context.fillStyle = 'maroon';
552: fillRect(x * 50, y * 50, 50, 50);
553: }
554: }
555: }
1.43 ihickson 556: worker.port.addEventListener('message', paintMap, false);
1.36 ihickson 557:
558: // PUBLIC CHAT
559: function updatePublicChat(event) {
560: if (event.message.substr(0, 4) != 'txt ') return;
561: var name = event.message.substr(4).split(' ', 1);
562: var message = event.message.substr(4 + length(name) + 1);
563: // display "<name> message" in public chat
564: var dialog = document.getElementById('public');
565: var dt = document.createElement('dt');
566: dt.textContent = name;
567: dialog.appendChild(dt);
568: var dd = document.createElement('dd');
569: dd.textContent = message;
570: dialog.appendChild(dd);
571: }
1.43 ihickson 572: worker.port.addEventListener('message', updatePublicChat, false);
1.36 ihickson 573:
574: // PRIVATE CHAT
575: function startPrivateChat(event) {
576: if (event.message.substr(0, 4) != 'msg ') return;
577: var name = event.message.substr(4).split(' ', 1);
578: var port = event.port;
579: // display a private chat UI
580: var ul = document.getElementById('private');
581: var li = document.createElement('li');
582: var h3 = document.createElement('h3');
583: h3.textContent = 'Private chat with ' + name;
584: li.appendChild(h3);
585: var dialog = document.createElement('dialog');
586: var addMessage = function(name, message) {
587: var dt = document.createElement('dt');
588: dt.textContent = name;
589: dialog.appendChild(dt);
590: var dd = document.createElement('dd');
591: dd.textContent = message;
592: dialog.appendChild(dd);
593: };
594: port.onmessage = function (event) {
595: addMessage(name, event.message);
596: };
597: li.appendChild(dialog);
598: var form = document.createElement('form');
599: var p = document.createElement('p');
600: var input = document.createElement('input');
601: input.size = 50;
602: p.appendChild(input);
603: p.appendChild(document.createTextNode(' '));
604: var button = document.createElement('button');
605: button.textContent = 'Post';
606: p.appendChild(button);
607: form.onsubmit = function () {
608: port.postMessage(input.value);
609: addMessage('me', input.value);
610: input.value = '';
611: return false;
612: };
613: form.appendChild(p);
614: li.appendChild(form);
615: }
1.43 ihickson 616: worker.port.addEventListener('message', startPrivateChat, false);
1.36 ihickson 617:
618: function init() {
1.43 ihickson 619: // begin receiving messages (messages are queued until you either
620: // set worker.port.onmessage or call worker.port.start())
621: worker.port.start();
1.36 ihickson 622: }
623: </script>
624: </head>
625: <body onload="init()">
626: <h1>Viewer</h1>
627: <h2>Map</h2>
628: <p><canvas id="map" height=150 width=150></canvas></p>
629: <p>
1.43 ihickson 630: <button type=button onclick="worker.port.postMessage('mov left')">Left</button>
631: <button type=button onclick="worker.port.postMessage('mov up')">Up</button>
632: <button type=button onclick="worker.port.postMessage('mov down')">Down</button>
633: <button type=button onclick="worker.port.postMessage('mov right')">Right</button>
634: <button type=button onclick="worker.port.postMessage('set 0')">Set 0</button>
635: <button type=button onclick="worker.port.postMessage('set 1')">Set 1</button>
1.36 ihickson 636: </p>
637: <h2>Public Chat</h2>
638: <dialog id="public"></dialog>
1.43 ihickson 639: <form onsubmit="worker.port.postMessage('txt ' + message.value); message.value = ''; return false;">
1.36 ihickson 640: <p>
641: <input type="text" name="message" size="50">
642: <button>Post</button>
643: </p>
644: </form>
645: <h2>Private Chat</h2>
646: <ul id="private"></ul>
647: </body>
1.43 ihickson 648: </html>
649: </pre>
1.36 ihickson 650:
651: <p>There are several key things worth noting about the way the viewer is
652: written.
653:
654: <p><strong>Multiple listeners</strong>. Instead of a single message
655: processing function, the code here attaches multiple event listeners, each
656: one performing a quick check to see if it is relevant for the message. In
657: this example it doesn't make much difference, but if multiple authors
658: wanted to collaborate using a single port to communicate with a worker, it
659: would allow for independent code instead of changes having to all be made
660: to a single event handling function.
661:
662: <p>Because event listeners are registered using <code
663: title="">addEventListener()</code> instead of <code
664: title=handler-MessagePort-onmessage>onmessge</code>, the events remain
665: queued until the <code title=dom-MessagePort-start>start()</code> method
666: is called on the message port, in the <code title="">init()</code>
667: function called from the <code title=handler-onload>onload</code> handler.
668:
669: <p>Registering event listeners in this way also allows you to unregister
670: specific listeners when you are done with them, as is done with the <code
671: title="">configure()</code> method in this example.
672:
673: <p>Finally, the worker:
674:
675: <pre>
676: var nextName = 0;
677: function getNextName() {
678: // this could use more friendly names
679: // but for now just return a number
680: return nextName++;
681: }
682:
683: var map = [
684: [0, 0, 0, 0, 0, 0, 0],
685: [1, 1, 0, 1, 0, 1, 1],
686: [0, 1, 0, 1, 0, 0, 0],
687: [0, 1, 0, 1, 0, 1, 1],
688: [0, 0, 0, 1, 0, 0, 0],
689: [1, 0, 0, 1, 1, 1, 1],
690: [1, 1, 0, 1, 1, 0, 1],
691: ];
692:
693: function wrapX(x) {
694: if (x < 0) return wrapX(x + map[0].length);
695: if (x >= map[0].length) return wrapX(x - map[0].length);
696: return x;
697: }
698:
699: function wrapY(y) {
700: if (y < 0) return wrapY(y + map.length);
701: if (y >= map[0].length) return wrapY(y - map.length);
702: return y;
703: }
704:
705: function sendMapData(viewer) {
706: var data = '';
707: for (var y = viewer.y-1; y <= viewer.y+1; y += 1) {
708: for (var x = viewer.x-1; x <= viewer.x+1; x += 1) {
709: if (data != '')
710: data += ',';
711: data += map[y][x];
712: }
713: }
714: viewer.port.postMessage('map ' + data);
715: }
716:
717: var viewers = {};
718: onconnect = function (event) {
719: event.port._name = getNextName();
720: event.port._data = { port: event.port, x: 0, y: 0, };
721: viewers[event.port._name] = event.port._data;
722: event.port.postMessage('cfg ' + name);
723: event.port.onmessage = getMessage;
724: sendMapData(event.port._data);
725: };
726:
727: function getMessage(event) {
728: switch (event.message.substr(0, 4)) {
729: case 'mov ':
730: var direction = event.message.substr(4);
731: var dx = 0;
732: var dy = 0;
733: switch (direction) {
734: case 'up': dy = -1; break;
735: case 'down': dy = 1; break;
736: case 'left': dx = -1; break;
737: case 'right': dx = 1; break;
738: }
739: event.target._data.x = wrapX(event.target._data.x + dx);
740: event.target._data.y = wrapY(event.target._data.y + dy);
741: sendMapData(event.target._data);
742: break;
743: case 'set ':
744: var value = event.message.substr(4);
745: map[event.target._data.y][event.target._data.x] = value;
746: for (var viewer in viewers)
747: sendMapData(viewers[viewer]);
748: break;
749: case 'txt ':
750: var name = event.target._name;
751: var message = event.message.substr(4);
752: for (var viewer in viewers)
753: viewers[viewer].port.postMessage('txt ' + name + ' ' + message);
754: break;
755: case 'msg ':
756: var party1 = event._data;
757: var party2 = viewers[event.message.substr(4).split(' ', 1)];
758: if (party2) {
759: var channel = new MessageChannel();
760: party1.port.postMessage('msg ' + party2.name, channel.port1);
761: party2.port.postMessage('msg ' + party1.name, channel.port2);
762: }
763: break;
764: }
765: }</pre>
766:
767: <p><strong>Connecting to multiple pages</strong>. Instead of using the
1.37 ihickson 768: <code title=dom-WorkerGlobalScope-port><a href="#port">port</a></code>
769: global variable in the worker, the script uses the <code
770: title=handler-WorkerGlobalScope-onconnect><a
771: href="#onconnect">onconnect</a></code> event listener to listen for
772: multiple connections.
1.36 ihickson 773:
774: <p><strong>Direct channels</strong>. When the worker receives a "msg"
775: message from one viewer naming another viewer, it sets up a direct
776: connection between the two, so that the two viewers can communicate
777: directly without the worker having to proxy all the messages.
778:
779: <p><a href="http://www.whatwg.org/demos/workers/multiviewer/page.html">View
780: this example online</a>.
1.34 ihickson 781:
1.40 ihickson 782: <h4 id=delegation><span class=secno>1.1.5 </span>Delegation</h4>
1.34 ihickson 783:
1.36 ihickson 784: <p><em>This section is non-normative.</em>
785:
1.40 ihickson 786: <p>With multicore CPUs becoming prevalent, one way to obtain better
787: performance is to split computationally expensive tasks amongst multiple
788: workers. In this example, a computationally expensive task that is to be
789: performed for every number from 1 to 10,000,000 is farmed out to ten
790: subworkers.
791:
792: <p>The main page is as follows, it just reports the result:
793:
794: <pre><!DOCTYPE HTML>
795: <html>
796: <head>
797: <title>Worker example: One-core computation</title>
798: </head>
799: <body>
800: <p>The highest prime number discovered so far is: <output id="result"></output></p>
801: <script>
802: var worker = createWorker('worker.js');
1.43 ihickson 803: worker.port.onmessage = function (event) {
1.40 ihickson 804: document.getElementById('result').textContent = event.message;
805: };
806: </script>
807: </body>
808: </html></pre>
809:
810: <p>The worker itself is as follows:
811:
812: <pre>// settings
813: var num_workers = 10;
814: var items_per_worker = 1000000;
815:
816: // start the workers
817: var result = 0;
818: var pending_workers = num_workers;
819: for (var i = 0; i < num_workers; i += 1) {
820: var worker = createWorker('core.js');
1.43 ihickson 821: worker.port.postMessage(i * items_per_worker);
822: worker.port.postMessage((i+1) * items_per_worker);
823: worker.port.onmessage = storeResult;
1.40 ihickson 824: }
825:
826: // handle the results
827: function storeResult(event) {
828: result += 1*event.message;
829: pending_workers -= 1;
830: if (pending_workers <= 0)
831: port.postMessage(result); // finished!
832: }</pre>
833:
834: <p>It consists of a loop to start the subworkers, and then a handler that
835: waits for all the subworkers to respond.
836:
837: <p>The subworkers are implemented as follows:
838:
839: <pre>var start;
1.41 ihickson 840: onmessage = getStart;
1.40 ihickson 841: function getStart(event) {
842: start = 1*event.message;
843: onmessage = getEnd;
844: }
845:
846: var end;
847: function getEnd(event) {
848: end = 1*event.message;
849: onmessage = null;
850: do();
851: }
852:
853: function do() {
854: var result = 0;
855: for (var i = start; i < end; i += 1) {
856: // perform some complex calculation here
857: result += 1;
858: }
859: port.postMessage(result);
860: }</pre>
861:
862: <p>They receive two numbers in two events, perform the computation for the
863: range of numbers thus specified, and then report the result back to the
864: parent.
865:
866: <p><a href="http://www.whatwg.org/demos/workers/multicore/page.html">View
867: this example online</a>.
1.34 ihickson 868:
1.40 ihickson 869: <h4 id=granting><span class=secno>1.1.6 </span>Granting capabilities</h4>
1.34 ihickson 870:
1.36 ihickson 871: <p><em>This section is non-normative.</em>
872:
1.35 ihickson 873: <p class=big-issue>...
1.34 ihickson 874:
1.22 ihickson 875: <h3 id=conformance><span class=secno>1.2 </span>Conformance requirements</h3>
1.1 ihickson 876:
877: <p>All diagrams, examples, and notes in this specification are
878: non-normative, as are all sections explicitly marked non-normative.
879: Everything else in this specification is normative.
880:
881: <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
882: NOT",-->
883: "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the
884: normative parts of this document are to be interpreted as described in
885: RFC2119. For readability, these words do not appear in all uppercase
886: letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
887: <!-- XXX but they should be
888: marked up -->
889:
890: <p>Requirements phrased in the imperative as part of algorithms (such as
891: "strip any leading space characters" or "return false and abort these
892: steps") are to be interpreted with the meaning of the key word ("must",
893: "should", "may", etc) used in introducing the algorithm.
894:
895: <p>Some conformance requirements are phrased as requirements on attributes,
896: methods or objects. Such requirements are to be interpreted as
897: requirements on user agents.
898:
899: <p>Conformance requirements phrased as algorithms or specific steps may be
900: implemented in any manner, so long as the end result is equivalent. (In
901: particular, the algorithms defined in this specification are intended to
902: be easy to follow, and not intended to be performant.)
903:
904: <p>The only conformance class defined by this specification is user agents.
905:
906: <p>User agents may impose implementation-specific limits on otherwise
907: unconstrained inputs, e.g. to prevent denial of service attacks, to guard
908: against running out of memory, or to work around platform-specific
909: limitations.
910:
1.22 ihickson 911: <h4 id=dependencies><span class=secno>1.2.1 </span>Dependencies</h4>
1.1 ihickson 912:
913: <p>This specification relies on several other underlying specifications.
914:
915: <dl>
916: <dt>HTML5
917:
918: <dd>
919: <p>Many fundamental concepts from HTML5 are used by this specification.
920: <a href="#refsHTML5">[HTML5]</a></p>
921:
922: <dt>ECMAScript
923:
924: <dd>
925: <p>This specification is intended to be used with JavaScript as the
926: scripting language. <a href="#refsJS">[JS]</a></p>
927:
928: <dt>WebIDL
929:
930: <dd>
931: <p>The IDL blocks in this specification use the semantics of the WebIDL
932: specification. <a href="#refsWebIDL">[WebIDL]</a></p>
933: </dl>
934:
1.22 ihickson 935: <h3 id=terminology><span class=secno>1.3 </span>Terminology</h3>
1.1 ihickson 936:
937: <p>For simplicity, terms such as <em>shown</em>, <em>displayed</em>, and
938: <em>visible</em> might sometimes be used when referring to the way a
939: document is rendered to the user. These terms are not meant to imply a
940: visual medium; they must be considered to apply to other media in
941: equivalent ways.
942:
1.4 ihickson 943: <p>The construction "a <code title="">Foo</code> object", where <code
944: title="">Foo</code> is actually an interface, is sometimes used instead of
945: the more accurate "an object implementing the interface <code
946: title="">Foo</code>".
1.1 ihickson 947:
948: <p>The term DOM is used to refer to the API set made available to scripts
949: in Web applications, and does not necessarily imply the existence of an
950: actual <code>Document</code> object or of any other <code>Node</code>
951: objects as defined in the DOM Core specifications. <a
952: href="#refsDOM3CORE">[DOM3CORE]</a>
953:
954: <p>A DOM attribute is said to be <em>getting</em> when its value is being
955: retrieved (e.g. by author script), and is said to be <em>setting</em> when
956: a new value is assigned to it.
957:
958: <p>If a DOM object is said to be <dfn id=live>live</dfn>, then that means
959: that any attributes returning that object must always return the same
960: object (not a new object each time), and the attributes and methods on
961: that object must operate on the actual underlying data, not a snapshot of
962: the data.
963:
1.12 ihickson 964: <h2 id=infrastructure><span class=secno>2. </span>Infrastructure</h2>
1.4 ihickson 965:
1.26 ihickson 966: <h3 id=the-workerglobalscope><span class=secno>2.1 </span>The <code><a
967: href="#workerglobalscope">WorkerGlobalScope</a></code> interface</h3>
1.4 ihickson 968:
969: <pre
1.26 ihickson 970: class=idl>[NoInterfaceObject] interface <dfn id=workerglobalscope>WorkerGlobalScope</dfn> {
971: // core worker features
972: readonly attribute <a href="#workerglobalscope">WorkerGlobalScope</a> <a href="#self" title=dom-WorkerGlobalScope-self>self</a>;
1.34 ihickson 973: readonly attribute <a href="#workerlocation">WorkerLocation</a> <a href="#location" title=dom-WorkerGlobalScope-location>location</a>;
1.26 ihickson 974: readonly attribute DOMString <a href="#name" title=dom-WorkerGlobalScope-name>name</a>;
975: readonly attribute boolean <a href="#closing" title=dom-WorkerGlobalScope-closing>closing</a>;
976: void <a href="#close" title=dom-WorkerGlobalScope-close>close</a>();
977:
1.9 ihickson 978: // event handler attributes
1.26 ihickson 979: attribute <span>EventListener</span> <a href="#onconnect" title=handler-WorkerGlobalScope-onconnect>onconnect</a>;
980: attribute <span>EventListener</span> <a href="#onunload" title=handler-WorkerGlobalScope-onunload>onunload</a>;
1.4 ihickson 981: };</pre>
982:
1.39 ihickson 983: <p>Objects implementing the <code><a
984: href="#workerglobalscope">WorkerGlobalScope</a></code> interface must also
985: implement the <code>EventTarget</code> interface.
986:
1.26 ihickson 987: <p>The <dfn id=self
988: title=dom-WorkerGlobalScope-self><code>self</code></dfn> attribute must
989: return the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
990: object itself.
1.9 ihickson 991:
1.34 ihickson 992: <p>The <dfn id=location
993: title=dom-WorkerGlobalScope-location><code>location</code></dfn> attribute
994: must return the <code><a href="#workerlocation">WorkerLocation</a></code>
995: object created for the <code><a
996: href="#workerglobalscope">WorkerGlobalScope</a></code> object when the
997: worker was created. It represents the <span>absolute URL</span> of the
998: script that was used to initialize the worker.
1.26 ihickson 999:
1000: <p>The <dfn id=name
1001: title=dom-WorkerGlobalScope-name><code>name</code></dfn> attribute must
1002: return the value it was assigned when the <code><a
1003: href="#workerglobalscope">WorkerGlobalScope</a></code> object was created
1004: by the "<a href="#run-a">run a worker</a>" algorithm. If it has a value
1005: that isn't the empty string, its value represents the name that can be
1006: used to obtain a reference to the worker using the <code
1007: title=dom-WorkerFactory-createNamedWorker><a
1.11 ihickson 1008: href="#createnamedworker">createNamedWorker()</a></code> method.
1.6 ihickson 1009:
1.4 ihickson 1010: <p>The <dfn id=closing
1.26 ihickson 1011: title=dom-WorkerGlobalScope-closing><code>closing</code></dfn> attribute
1012: must return false until it is set to true by one of the algorithms in the
1.19 ihickson 1013: processing model section below.
1.4 ihickson 1014:
1.9 ihickson 1015: <p>The following are the <span>event handler DOM attributes</span> that
1016: must be supported by objects implementing the <code><a
1.26 ihickson 1017: href="#workerglobalscope">WorkerGlobalScope</a></code> interface:
1.9 ihickson 1018:
1019: <dl>
1.20 ihickson 1020: <dt><dfn id=onconnect
1.26 ihickson 1021: title=handler-WorkerGlobalScope-onconnect><code>onconnect</code></dfn>
1.9 ihickson 1022:
1023: <dd>
1024: <p>Must be invoked whenever a <code
1.26 ihickson 1025: title=event-WorkerGlobalScope-connect>connect</code> event is targeted
1026: at or bubbles through the <code><a
1027: href="#workerglobalscope">WorkerGlobalScope</a></code> object.
1.9 ihickson 1028:
1029: <dt><dfn id=onunload
1.26 ihickson 1030: title=handler-WorkerGlobalScope-onunload><code>onunload</code></dfn>
1.9 ihickson 1031:
1032: <dd>
1033: <p>Must be invoked whenever a <code title=event-unload>unload</code>
1034: event is targeted at or bubbles through the <code><a
1.26 ihickson 1035: href="#workerglobalscope">WorkerGlobalScope</a></code> object.
1.9 ihickson 1036: </dl>
1037:
1.30 ihickson 1038: <p>In addition to the above members, the <a href="#success" title="worker
1039: creation succeeded">worker creation success steps</a> add a <dfn id=port
1040: title=dom-WorkerGlobalScope-port><code>port</code></dfn> property to the
1041: object.
1042:
1.15 ihickson 1043: <h3 id=base-urls><span class=secno>2.2 </span>Base URLs and origins of
1044: workers</h3>
1045:
1046: <p>The <span>base URL</span> of a <span>URL</span> passed to an API in a
1.34 ihickson 1047: worker is the <span>absolute URL</span> given that the worker's <code
1048: title=dom-WorkerGlobalScope-location><a
1049: href="#location">location</a></code> attribute represents.
1.15 ihickson 1050:
1.25 ihickson 1051: <p>Both the <span>origin</span> and <span>effective script origin</span> of
1052: scripts running in workers are the <span>origin</span> of the
1.34 ihickson 1053: <span>absolute URL</span> given that the worker's <code
1054: title=dom-WorkerGlobalScope-location><a
1055: href="#location">location</a></code> attribute represents.
1.15 ihickson 1056:
1057: <h3 id=the-queue><span class=secno>2.3 </span>The queue of events</h3>
1.4 ihickson 1058:
1.26 ihickson 1059: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
1060: object is asssociated with a <dfn id=queue>queue of events</dfn>, which is
1061: initially empty.
1.4 ihickson 1062:
1063: <p>An event in the queue can be a DOM event or a timeout callback.
1064:
1.8 ihickson 1065: <p>All asynchronous callbacks and events that would be called or dispatched
1066: in the worker must be added to the worker's queue, with the "<a
1067: href="#run-a">run a worker</a>" processing model below taking care of
1068: actually calling the callbacks or dispatching the events.
1069:
1.26 ihickson 1070: <p>Once the <code><a
1071: href="#workerglobalscope">WorkerGlobalScope</a></code>'s <code
1072: title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
1.8 ihickson 1073: attribute is set to true, the queue must discard anything else that would
1074: be added to it. Effectively, once the <code
1.26 ihickson 1075: title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
1.8 ihickson 1076: attribute is true, timers stop firing, notifications for all pending
1077: asynchronous operations are dropped, etc.
1078:
1.15 ihickson 1079: <h3 id=the-workers><span class=secno>2.4 </span>The worker's ports</h3>
1.9 ihickson 1080:
1081: <p>Workers communicate with other workers and with <span title="browsing
1082: context">browsing contexts</span> through <span title="channel
1083: messaging">message channels</span> and their <code>MessagePort</code>
1084: objects.
1085:
1.26 ihickson 1086: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
1087: <var title="">worker</var> has a list of <dfn id=the-workers0>the worker's
1.9 ihickson 1088: ports</dfn>, which consists of all the <code>MessagePort</code> objects
1089: that are entangled with another port and that have one (but only one) port
1.26 ihickson 1090: owned by <var title="">worker</var>. This list includes all the
1091: <code>MessagePort</code> objects that are in events pending in the <a
1092: href="#queue">queue of events</a>.
1.9 ihickson 1093:
1.17 ihickson 1094: <hr>
1095:
1.38 ihickson 1096: <p>A worker is said to be a <dfn id=permissible>permissible worker</dfn> if
1097: either:
1098:
1099: <ul>
1100: <li>at some point past or present a <code>MessagePort</code> owned by the
1101: worker was entangled with a <code>MessagePort</code> <var
1102: title="">p</var> whose owner is a <code>Window</code> object whose
1103: <span>active document</span> is the <code>Document</code> that was that
1104: <span>browsing context</span>'s <span>active document</span> when <var
1105: title="">p</var> was created, and that <code>Document</code> is
1106: <span>fully active</span>, or
1107:
1108: <li>at some point past or present a <code>MessagePort</code> owned by the
1109: worker was entangled with a <code>MessagePort</code> owned by another
1110: worker that is currently a <a href="#permissible">permissible worker</a>.
1111: </ul>
1112:
1113: <hr>
1114:
1115: <p>A worker is said to be a <dfn id=protected>protected worker</dfn> if
1116: either:
1117:
1118: <ul>
1119: <li>it has outstanding timers, database transactions, or network
1120: connections, and is a <a href="#permissible">permissible worker</a>, or:
1121:
1122: <li>there is a <a href="#protected">protected worker</a> that at some
1123: point past or present owned a <code>MessagePort</code> that was entangled
1124: with a <code>MessagePort</code> owned by this worker.
1125: </ul>
1126:
1127: <hr>
1.17 ihickson 1128:
1.38 ihickson 1129: <p>A worker is said to be an <dfn id=active>active needed worker</dfn> if
1130: either:
1.17 ihickson 1131:
1132: <ul>
1.38 ihickson 1133: <li>the worker is a <a href="#protected">protected worker</a>, or
1134:
1135: <li>at least one of the <a href="#the-workers0">the worker's ports</a> is
1136: entangled with a <code>MessagePort</code> <var title="">p</var> whose
1137: owner is a <code>Window</code> object whose <span>active document</span>
1138: is the <code>Document</code> that was that <span>browsing
1139: context</span>'s <span>active document</span> when that
1140: <code>MessagePort</code> <var title="">p</var> was created, and that
1141: <code>Document</code> is <span>fully active</span>, or
1.17 ihickson 1142:
1143: <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
1.26 ihickson 1144: an entangled <code>MessagePort</code> owned by a <code><a
1145: href="#workerglobalscope">WorkerGlobalScope</a></code> object that is
1.38 ihickson 1146: itself an <a href="#active">active needed worker</a>.
1.17 ihickson 1147: </ul>
1148:
1149: <hr>
1150:
1.38 ihickson 1151: <p>A worker is said to be a <dfn id=suspendable>suspendable worker</dfn> if
1152: it is not an <a href="#active">active needed worker</a> but either:
1.17 ihickson 1153:
1154: <ul>
1.38 ihickson 1155: <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
1156: an entangled <code>MessagePort</code> owned by a <code>Window</code>
1157: object, or
1.17 ihickson 1158:
1159: <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
1.26 ihickson 1160: an entangled <code>MessagePort</code> owned by a <code><a
1161: href="#workerglobalscope">WorkerGlobalScope</a></code> object that is
1.38 ihickson 1162: itself a <span>needed worker</span>.
1.17 ihickson 1163: </ul>
1164:
1.15 ihickson 1165: <h3 id=processing><span class=secno>2.5 </span>Processing model</h3>
1.4 ihickson 1166:
1.6 ihickson 1167: <p>When a user agent is to <dfn id=run-a>run a worker</dfn> named <var
1.7 ihickson 1168: title="">name</var> for a script with <span>URL</span> <var
1169: title="">url</var>, a browsing context <var title="">owner browsing
1170: context</var> and a <code>Document</code> <var title="">owner
1171: document</var>, it must run the following steps in a completely separate
1172: and parallel execution environment:
1.4 ihickson 1173:
1174: <ol>
1175: <li>
1.7 ihickson 1176: <p>Attempt to <span>fetch</span><!-- XXX --> the resource identified by
1177: <var title="">url</var>.</p>
1178:
1179: <p>If the attempt fails, then abort these steps and invoke the <a
1.43 ihickson 1180: href="#worker2" title="worker creation failed">error handling steps</a>
1.7 ihickson 1181: defined by the algorithm that called this one.</p>
1182:
1183: <p>If the attempt succeeds, then let <var title="">script</var> be the
1184: resource that was obtained.</p>
1185:
1186: <p class=note>As with <code>script</code> elements, the MIME type of the
1187: script is ignored. Unlike with <code>script</code> elements, there is no
1188: way to override the type. It's always assumed to be JavaScript.</p>
1189: <!-- XXX people will complain about
1190: this. I guess we might want to examine the MIME type... -->
1191:
1192:
1193: <li>
1.26 ihickson 1194: <p>Create a new <code><a
1195: href="#workerglobalscope">WorkerGlobalScope</a></code> object, <var
1196: title="">worker</var>.</p>
1.4 ihickson 1197:
1198: <li>
1.26 ihickson 1199: <p>Set the <code title=dom-WorkerGlobalScope-name><a
1.19 ihickson 1200: href="#name">name</a></code> attribute of <var title="">worker</var> to
1.6 ihickson 1201: the value of <var title="">name</var>.</p>
1202:
1203: <li>
1.34 ihickson 1204: <p>Create a new <code><a href="#workerlocation">WorkerLocation</a></code>
1205: object for the <code title=dom-WorkerGlobalScope-location><a
1206: href="#location">location</a></code> attribute of <var
1207: title="">worker</var>, representing <var title="">url</var>.</p>
1208:
1209: <li>
1.4 ihickson 1210: <p>Let <var title="">script</var>'s <span>script execution context</span>
1211: (and thus also <span>global object</span>) be <var
1.19 ihickson 1212: title="">worker</var>.</p>
1.4 ihickson 1213:
1214: <li>
1215: <p>Let <var title="">script</var>'s <span>script browsing context</span>
1216: be <var title="">owner browsing context</var>.</p>
1217:
1218: <li>
1219: <p>Let <var title="">script</var>'s <span>script document context</span>
1220: be <var title="">owner document</var>.</p>
1221:
1222: <li>
1.9 ihickson 1223: <p>Invoke the <a href="#success" title="worker creation
1224: succeeded">success steps</a> defined by the algorithm that called this
1.17 ihickson 1225: one.</p>
1226:
1227: <p class=note>This will usually add an event to the <a
1.28 ihickson 1228: href="#queue">queue of events</a> and set the <code
1.30 ihickson 1229: title=dom-WorkerGlobalScope-port><a href="#port">port</a></code>
1230: property on the <var title="">worker</var> object. If it does, that
1231: event will have a <code>MessagePort</code> and thus the list of <a
1.17 ihickson 1232: href="#the-workers0">the worker's ports</a> will not be empty. If it
1.19 ihickson 1233: doesn't, then the next step will set the <var title="">worker</var>
1.26 ihickson 1234: object's <code title=dom-WorkerGlobalScope-closing><a
1.17 ihickson 1235: href="#closing">closing</a></code> attribute to true.</p>
1236:
1237: <li>
1.28 ihickson 1238: <p><strong>Closing orphan workers</strong>: Start monitoring <var
1.38 ihickson 1239: title="">worker</var>, such that as soon as the worker stops being
1240: either an <a href="#active">active needed worker</a> or a <a
1241: href="#suspendable">suspendable worker</a>, the <var
1242: title="">worker</var> object's <code
1243: title=dom-WorkerGlobalScope-closing><a
1.44 ihickson 1244: href="#closing">closing</a></code> attribute is set to true and an event
1245: named <code title=event-unload>unload</code>, which uses the
1246: <code>Event</code> object, which does not bubble, and which is not
1247: cancelable, is added it to the worker's <code><a
1248: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1249: href="#queue">queue of events</a>, targetted at the <code><a
1250: href="#workerglobalscope">WorkerGlobalScope</a></code> object.</p>
1.9 ihickson 1251:
1252: <li>
1.28 ihickson 1253: <p><strong>Suspending workers</strong>: Start monitoring <var
1254: title="">worker</var>, such that whenever the <var title="">worker</var>
1255: object's <code title=dom-WorkerGlobalScope-closing><a
1.26 ihickson 1256: href="#closing">closing</a></code> attribute is false and the worker is
1.38 ihickson 1257: a <a href="#suspendable">suspendable worker</a>, the user agent suspends
1258: execution of script in that worker until such time as either the <code
1259: title=dom-WorkerGlobalScope-closing><a
1.26 ihickson 1260: href="#closing">closing</a></code> attribute switches to true or the
1.38 ihickson 1261: worker stops being a <a href="#suspendable">suspendable worker</a>.</p>
1.7 ihickson 1262:
1263: <li>
1264: <p>Run <var title="">script</var> until it either returns, fails to catch
1265: an exception, or gets prematurely aborted by the "<a href="#kill-a">kill
1266: a worker</a>" algorithm below.</p>
1267:
1268: <p class=note>If the script gets aborted by the "<a href="#kill-a">kill a
1269: worker</a>" algorithm, then that same algorithm will cause there to only
1270: be a single event in the <a href="#queue">queue of events</a> at the
1.28 ihickson 1271: next step, namely the <code title=message-unload>unload</code> event.</p>
1.4 ihickson 1272:
1273: <li>
1.9 ihickson 1274: <p><i>Event loop</i>: Wait until either there is an event in the <a
1.4 ihickson 1275: href="#queue">queue of events</a> associated with <var
1.19 ihickson 1276: title="">worker</var> or the <var title="">worker</var> object's <code
1.26 ihickson 1277: title=dom-WorkerGlobalScope-closing><a
1278: href="#closing">closing</a></code> attribute is set to true.</p>
1.4 ihickson 1279:
1280: <li>
1281: <p>Dispatch the oldest event or callback in the <a href="#queue">queue of
1.9 ihickson 1282: events</a>, if any. The handling of this event or the execution of this
1283: callback might get prematurely aborted by the "<a href="#kill-a">kill a
1.8 ihickson 1284: worker</a>" algorithm below.</p>
1.4 ihickson 1285:
1286: <li>
1287: <p>If there are any more events in the <a href="#queue">queue of
1.19 ihickson 1288: events</a> or if the <var title="">worker</var> object's <code
1.26 ihickson 1289: title=dom-WorkerGlobalScope-closing><a
1290: href="#closing">closing</a></code> attribute is set to false, then jump
1291: back to the step above labeled <i>event loop</i>.</p>
1.4 ihickson 1292:
1293: <li>
1294: <p class=big-issue>timers, intervals, XMLHttpRequests, database
1.28 ihickson 1295: transactions, etc, must be killed; ports must be unentangled</p>
1.43 ihickson 1296:
1297: <li>
1298: <p>At the next available opportunity, after any scripts have finished
1299: executing<!-- XXX queue -->, <span>fire a simple event</span> called
1300: <code title=event-unload>unload</code> at any <code><a
1301: href="#worker1">Worker</a></code> objects associated with this worker.</p>
1.4 ihickson 1302: </ol>
1303:
1304: <hr>
1305:
1306: <p>When a user agent is to <dfn id=kill-a>kill a worker</dfn>, it must run
1307: the following steps in parallel with the worker's main loop (the "<a
1308: href="#run-a">run a worker</a>" processing model defined above):
1309:
1310: <ol>
1311: <li>
1312: <p>Create an <code>Event</code> object with the event name <code
1313: title=event-unload>unload</code>, which does not bubble and is not
1314: cancelable, and add it to the worker's <code><a
1.26 ihickson 1315: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1.8 ihickson 1316: href="#queue">queue of events</a>, targetted at the <code><a
1.26 ihickson 1317: href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
1.28 ihickson 1318: </li>
1319: <!-- XXX shouldn't add one if closing is
1320: already true, assuming unload has already been added to the queue
1321: (?) -->
1.4 ihickson 1322:
1323: <li>
1.26 ihickson 1324: <p>Set the worker's <code><a
1325: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <code
1326: title=dom-WorkerGlobalScope-closing><a
1.8 ihickson 1327: href="#closing">closing</a></code> attribute to true.
1328:
1329: <li>
1330: <p>Wait a user-agent-defined amount of time. If the "<a href="#run-a">run
1331: a worker</a>" processing model defined above immediately starts running
1.28 ihickson 1332: event listeners registered for the <code
1333: title=event-unload>unload</code> event, this time should not be zero
1334: — the idea is that the <code title=event-unload>unload</code>
1335: event can be used to clean up when shutting down unexpectedly.
1.4 ihickson 1336:
1337: <li>
1338: <p>If there are any events in the <a href="#queue">queue of events</a>
1339: other than the <code title=event-unload>unload</code> event that this
1340: algorithm just added, discard them without dispatching them.
1341:
1342: <li>
1343: <p>If the <code title=event-unload>unload</code> event that this
1344: algorithm just added hasn't yet been dispatched, then abort the script
1345: currently running in the worker.
1346:
1347: <li>
1348: <p>Wait a user-agent-defined amount of time.
1349:
1350: <li>
1351: <p>Abort the script currently running in the worker (if any script is
1352: running, then it will be a handler for the <code
1353: title=event-unload>unload</code> event).
1354: </ol>
1355:
1.19 ihickson 1356: <p>User agents may invoke the "<a href="#kill-a">kill a worker</a>"
1357: processing model on a worker at any time, e.g. in response to user
1358: requests, in response to CPU quota management, or when a worker stops
1.38 ihickson 1359: being an <a href="#active">active needed worker</a> if the worker
1360: continues executing even after its <code
1361: title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
1362: attribute was set to true.
1.19 ihickson 1363:
1.8 ihickson 1364: <hr>
1365:
1366: <p>When a script invokes the <dfn id=close
1.26 ihickson 1367: title=dom-WorkerGlobalScope-close><code>close()</code></dfn> method on a
1368: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object,
1369: the user agent must run the following steps:
1.8 ihickson 1370:
1371: <ol>
1372: <li>
1373: <p>Create an <code>Event</code> object with the event name <code
1374: title=event-unload>unload</code>, which does not bubble and is not
1375: cancelable, and add it to the <code><a
1.26 ihickson 1376: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1.8 ihickson 1377: href="#queue">queue of events</a>, targetted at the <code><a
1.26 ihickson 1378: href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
1.8 ihickson 1379:
1380: <li>
1.26 ihickson 1381: <p>Set the worker's <code><a
1382: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <code
1383: title=dom-WorkerGlobalScope-closing><a
1.8 ihickson 1384: href="#closing">closing</a></code> attribute to true.
1385:
1386: <li>
1387: <p>For each <code>MessagePort</code> object that is entangled with
1.26 ihickson 1388: another port and that has one (but only one) port whose owner is the
1389: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object
1390: on which the method was invoked, run the following substeps:</p>
1.8 ihickson 1391:
1392: <ol>
1393: <li>
1394: <p>Unentangle the two ports.
1395:
1396: <li>
1397: <p>At the next available opportunity, after any scripts have finished
1398: executing<!-- XXX queue -->, <span>fire a simple event</span> called
1399: <code title=event-unload>unload</code> at the other port (the one
1.26 ihickson 1400: whose owner is not the <code><a
1401: href="#workerglobalscope">WorkerGlobalScope</a></code> object on which
1402: the <code title=dom-WorkerGlobalScope-close><a
1.8 ihickson 1403: href="#close">close()</a></code> method was called).
1404: </ol>
1405: </ol>
1406:
1.15 ihickson 1407: <h3 id=creating><span class=secno>2.6 </span>Creating workers</h3>
1.5 ihickson 1408:
1409: <pre
1.26 ihickson 1410: class=idl>[NoInterfaceObject] interface <dfn id=workerfactory>WorkerFactory</dfn> {
1.43 ihickson 1411: <a href="#worker1">Worker</a> <a href="#createworker" title=dom-WorkerFactory-createWorker>createWorker</a>(in DOMString scriptURL);
1412: <a href="#worker1">Worker</a> <a href="#createnamedworker" title=dom-WorkerFactory-createNamedWorker>createNamedWorker</a>(in DOMString name, in DOMString scriptURL);
1413: };
1414:
1415: interface <dfn id=worker1>Worker</dfn> {
1416: <span>MessagePort</span> <a href="#port0" title=dom-Worker-port>port</a>();
1417:
1418: // event handler attributes
1419: attribute <span>EventListener</span> <a href="#onload" title=handler-Worker-onload>onload</a>;
1420: attribute <span>EventListener</span> <a href="#onerror" title=handler-Worker-onerror>onerror</a>;
1421: attribute <span>EventListener</span> <a href="#onunload0" title=handler-Worker-onunload>onunload</a>;
1.5 ihickson 1422: };</pre>
1423:
1.26 ihickson 1424: <p>Objects that implement the <code>Window</code> and <code><a
1.42 ihickson 1425: href="#workerglobalscope">WorkerGlobalScope</a></code> interfaces must
1426: also implement the <code><a href="#workerfactory">WorkerFactory</a></code>
1427: interface.
1.5 ihickson 1428:
1.9 ihickson 1429: <hr>
1430:
1.11 ihickson 1431: <p>When the <dfn id=createworker
1.26 ihickson 1432: title=dom-WorkerFactory-createWorker><code>createWorker(<var
1.11 ihickson 1433: title="">scriptURL</var>)</code></dfn> method is invoked, the user agent
1434: must run the following steps:
1.9 ihickson 1435:
1436: <ol>
1437: <li>
1438: <p><span title="resolve a url">Resolve</span> the <var
1439: title="">scriptURL</var> argument.
1440:
1441: <li>
1442: <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.
1443:
1444: <li>
1445: <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
1446: is not the <span title="same origin">same</span> as the origin of the
1447: script that invoked the method, then throw a <span>security
1448: exception</span>.
1449:
1450: <li>
1451: <p><a href="#create">Create a worker</a> from the resulting
1452: <span>absolute URL</span> whose name is the empty string.
1453:
1454: <li>
1.43 ihickson 1455: <p>Return the <code><a href="#worker1">Worker</a></code> object returned
1456: from the <a href="#create">create a worker</a> algorithm.
1.9 ihickson 1457: </ol>
1458:
1459: <hr>
1460:
1.11 ihickson 1461: <p>When the <dfn id=createnamedworker
1.26 ihickson 1462: title=dom-WorkerFactory-createNamedWorker><code>createNamedWorker(<var
1.11 ihickson 1463: title="">name</var>, <var title="">scriptURL</var>)</code></dfn> method is
1.9 ihickson 1464: invoked, the user agent must run the following steps:
1465:
1466: <ol>
1467: <li>
1468: <p><span title="resolve a url">Resolve</span> the <var
1469: title="">scriptURL</var> argument.
1.4 ihickson 1470:
1.9 ihickson 1471: <li>
1472: <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.
1473:
1474: <li>
1475: <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
1476: is not the <span title="same origin">same</span> as the origin of the
1477: script that invoked the method, then throw a <span>security
1478: exception</span>.
1479:
1480: <li>
1481: <p>If the <var title="">name</var> argument is the empty string, <a
1482: href="#create">create a worker</a> from the resulting <span>absolute
1.43 ihickson 1483: URL</span>, whose name is the empty string, and return the <code><a
1484: href="#worker1">Worker</a></code> object returned from the <a
1.9 ihickson 1485: href="#create">create a worker</a> algorithm. Then, abort these steps.
1486:
1487: <li>
1.26 ihickson 1488: <p>If there exists a worker whose <code
1489: title=dom-WorkerGlobalScope-closing><a
1.9 ihickson 1490: href="#closing">closing</a></code> attribute is false, whose <code
1.26 ihickson 1491: title=dom-WorkerGlobalScope-name><a href="#name">name</a></code>
1492: attribute is exactly equal to the <var title="">name</var> argument, and
1.34 ihickson 1493: whose <code title=dom-WorkerGlobalScope-location><a
1494: href="#location">location</a></code> attribute represents an
1495: <span>absolute URL</span> that has the <span>same origin</span> as the
1496: resulting <span>absolute URL</span>, then run these substeps:</p>
1.9 ihickson 1497:
1498: <ol>
1499: <li>
1.34 ihickson 1500: <p>If that worker's <code title=dom-WorkerGlobalScope-location><a
1501: href="#location">location</a></code> attribute represents an
1502: <span>absolute URL</span> that is not exactly equal to the resulting
1503: <span>absolute URL</span>, then throw a <code>URL_MISMATCH_ERR</code>
1504: exception and abort these steps. <span class=big-issue>code 19</span>
1.9 ihickson 1505:
1506: <li>
1507: <p><span>Create a new <code>MessagePort</code> object</span> owned by
1508: the <span>script execution context</span> of the script that invoked
1509: the method.
1510:
1511: <li>
1.43 ihickson 1512: <p><span>Create a new <code><a href="#worker1">Worker</a></code>
1513: object</span> associated with that worker, and assign the newly
1514: created port to its <code title=dom-Worker-port><a
1515: href="#port0">port</a></code> attribute.
1516:
1517: <li>
1518: <p>Return the newly created <code><a href="#worker1">Worker</a></code>
1519: object.
1.9 ihickson 1520:
1521: <li>
1.20 ihickson 1522: <p>Asynchronously, <a href="#connect" title="connect to a
1523: worker">connect</a> to this preexisting worker, with the newly created
1.43 ihickson 1524: <code>MessagePort</code> and <code><a
1525: href="#worker1">Worker</a></code> objects.
1.9 ihickson 1526: </ol>
1527:
1528: <p>Otherwise, <a href="#create">create a worker</a> from the resulting
1529: <span>absolute URL</span>, whose name is the value of the <var
1.43 ihickson 1530: title="">name</var> argument, and return the <code><a
1531: href="#worker1">Worker</a></code> object returned from the <a
1532: href="#create">create a worker</a> algorithm.</p>
1.9 ihickson 1533: </ol>
1534:
1535: <hr>
1536:
1537: <p>The steps to <dfn id=create>create a worker</dfn> from a
1538: <span>URL</span> <var title="">url</var> and whose name is <var
1539: title="">name</var>, in the context of a method call, are as follows:
1540:
1541: <ol>
1542: <li>
1543: <p><span>Create a new <code>MessagePort</code> object</span> owned by the
1544: <span>script execution context</span> of the script that invoked the
1545: method.
1546:
1547: <li>
1.43 ihickson 1548: <p><span>Create a new <code><a href="#worker1">Worker</a></code>
1549: object</span>, associated with the worker that will be created below,
1550: and assign the newly created port to its <code title=dom-Worker-port><a
1551: href="#port0">port</a></code> attribute.
1552:
1553: <li>
1554: <p>Return that <code><a href="#worker1">Worker</a></code> object.
1.9 ihickson 1555:
1556: <li>
1557: <p>In a parallel execution context (i.e. a separate thread or process or
1558: equivalent construct), <a href="#run-a">run a worker</a> named <var
1559: title="">name</var> for the script with <span>URL</span> <var
1560: title="">url</var>, with the <span>script browsing context</span> of the
1561: script that invoked the method as the <var title="">owner browsing
1562: context</var> and with the <span>script document context</span> of the
1563: script that invoked the method as the <var title="">owner
1564: document</var>.</p>
1565:
1566: <p>If that algorithm invokes the steps for <dfn id=success title="worker
1.20 ihickson 1567: creation succeeded">success steps</dfn>, then <a href="#connect"
1568: title="connect to a worker">connect</a> to this new worker, with the
1.28 ihickson 1569: newly created port, and if that algorithm returns a second new port,
1.30 ihickson 1570: then add a new property <code title=dom-WorkerGlobalScope-port><a
1571: href="#port">port</a></code> on the new worker's <code><a
1572: href="#workerglobalscope">WorkerGlobalScope</a></code> object, whose
1.43 ihickson 1573: value is the <code>MessagePort</code> object returned by the <a
1.28 ihickson 1574: href="#connect">connect to a worker</a> algorithm.</p>
1.9 ihickson 1575:
1.43 ihickson 1576: <p>Otherwise, if the <dfn id=worker2>worker creation failed</dfn>, then
1.33 ihickson 1577: at the next available opportunity, after any scripts have finished
1.9 ihickson 1578: executing<!-- XXX queue -->, <span>fire a simple event</span> called
1.43 ihickson 1579: <code title=event-error>error</code> at the newly created <code><a
1580: href="#worker1">Worker</a></code> object.</p>
1.9 ihickson 1581: </ol>
1582:
1583: <hr>
1584:
1.20 ihickson 1585: <p>The steps to <dfn id=connect>connect to a worker</dfn> given a
1.43 ihickson 1586: <code>MessagePort</code> object <var title="">port</var> and a <code><a
1587: href="#worker1">Worker</a></code> object <var title="">worker</var> are as
1588: follows:
1.9 ihickson 1589:
1590: <ol>
1591: <li>
1592: <p>If <var title="">port</var> would have been garbage collected, or if
1.26 ihickson 1593: the <span>active document</span> of the owner of <var
1.9 ihickson 1594: title="">port</var> is no longer the same <code>Document</code> object
1595: as when <var title="">port</var> was created, then do nothing. Abort
1596: these steps. If the worker was just created, it'll get killed
1597: immediately.</p>
1598:
1599: <li>
1600: <p><span>Create a new <code>MessagePort</code> object</span> owned by the
1.26 ihickson 1601: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> of the
1602: worker.
1.9 ihickson 1603:
1604: <li>
1605: <p><span>Entangle</span> this newly created port and the port <var
1606: title="">port</var> that was passed to these steps.
1607:
1608: <li>
1609: <p>At the next available opportunity, after any scripts have finished
1610: executing<!-- XXX queue -->, <span>fire a simple event</span> called
1.43 ihickson 1611: <code title=event-load>load</code> at <var title="">worker</var>.
1.9 ihickson 1612:
1613: <li>
1614: <p>Create an event that uses the <code>MessageEvent</code> interface,
1.20 ihickson 1615: with the name <code title=event-connect>connect</code>, which does not
1.9 ihickson 1616: bubble, is cancelable, has no default action, has a <code
1617: title=dom-MessageEvent-data>data</code> attribute whose value is the
1618: empty string and has a <code
1619: title=dom-MessageEvent-messagePort>messagePort</code> attribute whose
1620: value is the newly created port, and add it to the worker's <code><a
1.26 ihickson 1621: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1.9 ihickson 1622: href="#queue">queue of events</a>, targetted at the <code><a
1.26 ihickson 1623: href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
1.28 ihickson 1624:
1625: <li>
1626: <p>Return the newly created port.
1.9 ihickson 1627: </ol>
1.7 ihickson 1628:
1.43 ihickson 1629: <hr>
1630:
1631: <p>The <dfn id=port0 title=dom-Worker-port><code>port</code></dfn>
1632: attribute on a <code><a href="#worker1">Worker</a></code> object must
1633: return the value it was assigned when the <code><a
1634: href="#worker1">Worker</a></code> object was created by the methods on the
1635: <code><a href="#workerfactory">WorkerFactory</a></code> interface.
1636:
1637: <p>The following are the <span>event handler DOM attributes</span> that
1638: must be supported by objects implementing the <code><a
1639: href="#worker1">Worker</a></code> interface:
1640:
1641: <dl>
1642: <dt><dfn id=onload title=handler-Worker-onload><code>onload</code></dfn>
1643:
1644: <dd>
1645: <p>Must be invoked whenever a <code title=event-load>load</code> event is
1646: targeted at or bubbles through the <code><a
1647: href="#worker1">Worker</a></code> object.
1648:
1649: <dt><dfn id=onerror
1650: title=handler-Worker-onerror><code>onerror</code></dfn>
1651:
1652: <dd>
1653: <p>Must be invoked whenever an <code title=event-error>error</code> event
1654: is targeted at or bubbles through the <code><a
1655: href="#worker1">Worker</a></code> object.
1656:
1657: <dt><dfn id=onunload0
1658: title=handler-Worker-onunload><code>onunload</code></dfn>
1659:
1660: <dd>
1661: <p>Must be invoked whenever an <code title=event-unload>unload</code>
1662: event is targeted at or bubbles through the <code><a
1663: href="#worker1">Worker</a></code> object.
1664: </dl>
1665:
1.12 ihickson 1666: <h2 id=apis-available><span class=secno>3. </span>APIs available to workers</h2>
1667:
1.26 ihickson 1668: <pre
1669: class=idl>[NoInterfaceObject] interface <dfn id=workerutils>WorkerUtils</dfn> {
1.46 ! ihickson 1670: void <a href="#importscripts" title=dom-WorkerGlobalScope-importScripts>importScripts</a>([Variadic] in DOMString urls);
1.26 ihickson 1671: readonly attribute <span>Storage</span> <a href="#localstorage" title=dom-localStorage>localStorage</a>;
1672: <span>Database</span> <a href="#opendatabase" title=dom-opendatabase>openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
1673: void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description);
1674: void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
1675: };</pre>
1.18 ihickson 1676:
1.12 ihickson 1677: <p>Objects that implement the <code><a
1.42 ihickson 1678: href="#workerglobalscope">WorkerGlobalScope</a></code> interface must also
1679: implement the <code><a href="#workerutils">WorkerUtils</a></code>
1680: interface.
1.12 ihickson 1681:
1.23 ihickson 1682: <p class=big-issue>Need to define a sync database API.
1683:
1684: <p class=big-issue>May need to define a browser sniffing API (like
1685: window.navigator).</p>
1.18 ihickson 1686: <!-- XXX ApplicationCache -->
1687: <!-- XXX a way to set cookies on the URL for the script -->
1.24 ihickson 1688: <!-- XXX debugging: void log(in DOMString s); // log to console -->
1689: <!-- XXX debugging: onerror -->
1.13 ihickson 1690:
1.18 ihickson 1691: <hr>
1.13 ihickson 1692:
1.18 ihickson 1693: <p>The DOM APIs (<code>Node</code> objects, <code>Document</code> objects,
1694: etc) are not available to workers in this version of this specification.
1.13 ihickson 1695:
1.26 ihickson 1696: <h3 id=importing><span class=secno>3.1 </span>Importing scripts and
1697: libraries</h3>
1698:
1.45 ihickson 1699: <p>When a script invokes the <dfn id=importscripts
1700: title=dom-WorkerGlobalScope-importScripts><code>importScripts(<var
1701: title="">urls</var>)</code></dfn> method on a <code><a
1.26 ihickson 1702: href="#workerglobalscope">WorkerGlobalScope</a></code> object, the user
1703: agent must run the following steps:
1704:
1705: <ol>
1706: <li>
1.46 ! ihickson 1707: <p>If there are no arguments, return without doing anything. Abort these
! 1708: steps.
! 1709:
! 1710: <li>
1.45 ihickson 1711: <p><span title="resolve a url">Resolve</span> each argument.
1.26 ihickson 1712:
1713: <li>
1.45 ihickson 1714: <p>If any fail, throw a <code>SYNTAX_ERR</code> exception.
1715:
1716: <li>
1717: <p>If any of the resulting <span title="absolute URL">absolute
1718: URLs</span> have an <span>origin</span> that is not the <span
1719: title="same origin">same</span> as the origin of the script that invoked
1720: the method, then throw a <span>security exception</span>.
1.26 ihickson 1721:
1722: <li>
1.45 ihickson 1723: <p>Attempt to <span>fetch</span> each resource identified by the
1724: resulting <span title="absolute URLs">absolute URL</span>.</p>
1.26 ihickson 1725:
1726: <li>
1.45 ihickson 1727: <p>For each argument in turn, in the order given, starting with the first
1728: one, run these substeps:</p>
1.26 ihickson 1729:
1.45 ihickson 1730: <ol>
1731: <li>
1732: <p>Wait for the fetching attempt for the corresponding resource to
1733: complete.</p>
1.26 ihickson 1734:
1.46 ! ihickson 1735: <p>If the fetching attempt failed, throw a <code>NETWORK_ERR</code>
! 1736: exception and abort all these steps.</p>
1.26 ihickson 1737:
1.45 ihickson 1738: <p>If the fetching attempt succeeded, then let <var
1739: title="">script</var> be the resource that was obtained.</p>
1.26 ihickson 1740:
1.45 ihickson 1741: <p class=note>As with the worker's script, the script here is always
1742: assumed to be JavaScript, regardless of the MIME type.</p>
1743: <!-- XXX -->
1.26 ihickson 1744:
1.45 ihickson 1745: <li>
1746: <p>Let <var title="">script</var>'s <span>script execution
1747: context</span>, <span>script browsing context</span>, and <span>script
1748: document context</span> be the same as for the script that was
1749: executed by the <a href="#run-a">run a worker</a> processing model for
1750: this worker.</p>
1.26 ihickson 1751:
1.45 ihickson 1752: <li>
1753: <p>Run <var title="">script</var> until it either returns, fails to
1754: catch an exception, or gets prematurely aborted by the "<a
1755: href="#kill-a">kill a worker</a>" algorithm above.</p>
1756:
1757: <p>If an exception was raised or if the script was prematurely aborted,
1758: then abort all these steps, letting the exception or aborting continue
1759: to be processed by the script that called the <code
1760: title=dom-WorkerGlobalScope-importScripts><a
1761: href="#importscripts">importScripts()</a></code> method.</p>
1762:
1763: <p>If the "<a href="#kill-a">kill a worker</a>" algorithm aborts the
1.46 ! ihickson 1764: script then abort all these steps.</p>
1.45 ihickson 1765: </ol>
1.26 ihickson 1766: </ol>
1767:
1768: <h3 id=apis-defined><span class=secno>3.2 </span>APIs defined in other
1769: specifications</h3>
1770:
1.27 ihickson 1771: <p>The <dfn id=localstorage
1.26 ihickson 1772: title=dom-localStorage><code>localStorage</code></dfn>, <dfn
1773: id=opendatabase title=dom-opendatabase><code>openDatabase()</code></dfn>
1774: must act as defined for the APIs with the same names on the
1775: <code>Window</code> object in the HTML5 specification, with the exception
1776: that where the API would use the <span>origin</span> of the <span>active
1777: document</span> of the <span>browsing context</span> of the
1778: <code>Window</code> object on which the method was supposedly invoked, it
1779: must instead use the <span>origin</span> of the script that invoked the
1780: method. <a href="#refsHTML5">[HTML5]</a>
1781:
1782: <p>The <dfn id=shownotification
1783: title=dom-showNotification><code>showNotification()</code></dfn> methods
1784: must act as defined for the APIs with the same names on the
1785: <code>Window</code> object in the HTML5 specification. <a
1786: href="#refsHTML5">[HTML5]</a>
1787:
1788: <h3 id=interface><span class=secno>3.3 </span>Interface objects and
1789: constructors</h3>
1790:
1791: <p>There must be no interface objects and constructors available in the
1792: global scope of scripts whose <span>script execution context</span> is a
1793: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object
1794: except for the following:
1795:
1796: <ul>
1797: <li>
1798: <p><code>XMLHttpRequest</code> and all interface objects and constructors
1799: defined by the XMLHttpRequest specifications, except that the
1800: <span>document response entity body</span> must always be null. <a
1801: href="#refsXHR">[XHR]</a>
1802:
1803: <li>
1804: <p>The <code>WebSocket</code> interface object and constructor.
1805:
1806: <li>
1807: <p>The <code>MessageChannel</code> interface object and constructor.
1808: </ul>
1809:
1.34 ihickson 1810: <h3 id=worker0><span class=secno>3.4 </span>Worker locations</h3>
1811:
1812: <pre
1813: class=idl>[NoInterfaceObject] interface <dfn id=workerlocation>WorkerLocation</dfn> {
1814: readonly attribute DOMString <a href="#href" title=dom-WorkerLocation-href>href</a>;
1815: readonly attribute DOMString <a href="#protocol" title=dom-WorkerLocation-protocol>protocol</a>;
1816: readonly attribute DOMString <a href="#host" title=dom-WorkerLocation-host>host</a>;
1817: readonly attribute DOMString <a href="#hostname" title=dom-WorkerLocation-hostname>hostname</a>;
1.43 ihickson 1818: readonly attribute DOMString <a href="#port1" title=dom-WorkerLocation-port>port</a>;
1.34 ihickson 1819: readonly attribute DOMString <a href="#pathname" title=dom-WorkerLocation-pathname>pathname</a>;
1820: readonly attribute DOMString <a href="#search" title=dom-WorkerLocation-search>search</a>;
1821: readonly attribute DOMString <a href="#hash" title=dom-WorkerLocation-hash>hash</a>;
1822: };</pre>
1823:
1824: <p>A <code><a href="#workerlocation">WorkerLocation</a></code> object
1825: represents an <span>absolute URL</span> set at its creation.
1826:
1827: <p>The <dfn id=href title=dom-WorkerLocation-href><code>href</code></dfn>
1828: attribute must return the <span>absolute URL</span> that the object
1829: represents.
1830:
1831: <p>The <code><a href="#workerlocation">WorkerLocation</a></code> interface
1832: also has the complement of <span>URL decomposition attributes</span>, <dfn
1833: id=protocol title=dom-WorkerLocation-protocol><code>protocol</code></dfn>,
1834: <dfn id=host title=dom-WorkerLocation-host><code>host</code></dfn>, <dfn
1.43 ihickson 1835: id=port1 title=dom-WorkerLocation-port><code>port</code></dfn>, <dfn
1.34 ihickson 1836: id=hostname title=dom-WorkerLocation-hostname><code>hostname</code></dfn>,
1837: <dfn id=pathname
1838: title=dom-WorkerLocation-pathname><code>pathname</code></dfn>, <dfn
1839: id=search title=dom-WorkerLocation-search><code>search</code></dfn>, and
1840: <dfn id=hash title=dom-WorkerLocation-hash><code>hash</code></dfn>. These
1841: must follow the rules given for URL decomposition attributes, with the
1842: <span title=concept-uda-input>input</span> being the <span>absolute
1843: URL</span> that the object represents (same as the <code
1844: title=dom-WorkerLocation-href><a href="#href">href</a></code> attribute),
1845: and the <span title=concept-uda-setter>common setter action</span> being a
1846: no-op, since the attributes are defined to be readonly. <a
1847: href="#refsHTML5">[HTML5]</a>
1848:
1.1 ihickson 1849: <h2 class=no-num id=references>References</h2>
1850:
1851: <p class=big-issue>This section will be written in a future
1852: draft.<!--XXX-->
1853:
1854: <h2 class=no-num id=acknowledgements>Acknowledgements</h2>
1855: <!-- ACKS -->
1856:
1.26 ihickson 1857: <p>Thanks to Aaron Boodman, Jonas Sicking, Maciej Stachowiak, Mike Smith,
1858: and Philip Taylor for their useful and substantial comments.
1.4 ihickson 1859:
1860: <p>Huge thanks to the whole Gears team, who pioneered this technology and
1861: whose experience has been a huge influence on this specification.
Webmaster
![[BACK]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/back.gif?vpn-1){kind=icon}
Return to Overview.html CVS log ![[TXT]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/text.gif?vpn-1){kind=icon}
![[DIR]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/dir.gif?vpn-1){kind=icon}
Up to [Public] / html5 / workers