Annotation of html5/workers/Overview.html, revision 1.30
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.26 ihickson 22: Draft <!--ZZZ--> 6 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.26 ihickson 147: the W3C Recommendation track. <!--ZZZ:--> This specification is the 6
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
187: background number-crunching thread</a>
188: </ul>
1.1 ihickson 189:
1.22 ihickson 190: <li><a href="#conformance"><span class=secno>1.2 </span>Conformance
1.1 ihickson 191: requirements</a>
192: <ul class=toc>
1.22 ihickson 193: <li><a href="#dependencies"><span class=secno>1.2.1
1.1 ihickson 194: </span>Dependencies</a>
195: </ul>
196:
1.22 ihickson 197: <li><a href="#terminology"><span class=secno>1.3 </span>Terminology</a>
1.4 ihickson 198: </ul>
199:
1.12 ihickson 200: <li><a href="#infrastructure"><span class=secno>2.
201: </span>Infrastructure</a>
1.4 ihickson 202: <ul class=toc>
1.26 ihickson 203: <li><a href="#the-workerglobalscope"><span class=secno>2.1 </span>The
204: <code>WorkerGlobalScope</code> interface</a>
1.4 ihickson 205:
1.15 ihickson 206: <li><a href="#base-urls"><span class=secno>2.2 </span>Base URLs and
207: origins of workers</a>
208:
209: <li><a href="#the-queue"><span class=secno>2.3 </span>The queue of
1.4 ihickson 210: events</a>
211:
1.15 ihickson 212: <li><a href="#the-workers"><span class=secno>2.4 </span>The worker's
1.9 ihickson 213: ports</a>
214:
1.15 ihickson 215: <li><a href="#processing"><span class=secno>2.5 </span>Processing
1.4 ihickson 216: model</a>
1.12 ihickson 217:
1.15 ihickson 218: <li><a href="#creating"><span class=secno>2.6 </span>Creating
1.12 ihickson 219: workers</a>
1.1 ihickson 220: </ul>
221:
1.12 ihickson 222: <li><a href="#apis-available"><span class=secno>3. </span>APIs available
223: to workers</a>
1.26 ihickson 224: <ul class=toc>
225: <li><a href="#importing"><span class=secno>3.1 </span>Importing scripts
226: and libraries</a>
227:
228: <li><a href="#apis-defined"><span class=secno>3.2 </span>APIs defined in
229: other specifications</a>
230:
231: <li><a href="#interface"><span class=secno>3.3 </span>Interface objects
232: and constructors</a>
233: </ul>
1.4 ihickson 234:
1.1 ihickson 235: <li class=no-num><a href="#references">References</a>
236:
237: <li class=no-num><a href="#acknowledgements">Acknowledgements</a>
238: </ul>
239: <!--end-toc-->
240:
241: <hr>
242:
243: <h2 id=introduction><span class=secno>1. </span>Introduction</h2>
244:
1.4 ihickson 245: <h3 id=tutorial><span class=secno>1.1 </span>Tutorial</h3>
1.1 ihickson 246:
247: <p><em>This section is non-normative.</em>
248:
1.29 ihickson 249: <p>There are a variety of uses that workers can be put to. The following
250: subsections show various examples of this use.
251:
252: <h4 id=a-background><span class=secno>1.1.1 </span>A background
253: number-crunching thread</h4>
254:
255: <p><em>This section is non-normative.</em>
256:
257: <p>The simplest use of workers is for performing a computationally
258: expensive task without interrupting the user interface.
259:
260: <p>In this example, the main document spawns a thread to (naïvely)
261: compute prime numbers, and progressively displays the most recently found
262: prime number.
263:
264: <p>The main page is as follows:
265:
266: <pre><!DOCTYPE HTML>
267: <html>
268: <head>
269: <title>Worker example: Computation</title>
270: </head>
271: <body>
272: <p>The highest prime number discovered so far is: <output id="result"></output></p>
273: <script>
274: var worker = createWorker('worker.js');
275: worker.onmessage = function (event) {
276: document.getElementById('result').textContent = event.message;
277: };
278: </script>
279: </body>
280: </html></pre>
281:
282: <p>The <code title=dom-WorkerFactory-createWorker><a
283: href="#createworker">createWorker()</a></code> method call creates a
284: worker and returns a <code>MessagePort</code> object, which is used to
285: communicate with the worker. That object's <code
286: title=dom-MessagePort-onmessage>onmessage</code> event handler attribute
287: allows the code to receive messages from the worker.
288:
289: <p>The worker itself is as follows:
290:
291: <pre>var n = 1;
292: search: while (true) {
293: n += 1;
294: for (var i = 2; i <= Math.sqrt(n); i += 1)
295: if (n % i == 0)
296: continue search;
297: // found a prime!
298: port.postMessage(n);
299: }</pre>
300:
301: <p>The bulk of this code is simply an unoptimised search for a prime
302: number. To send a message back to the page, the <code
1.30 ! ihickson 303: title=dom-WorkerGlobalScope-port><a href="#port">port</a></code> variable
! 304: (defined automatically when the worker is created) is used to post a
! 305: message when a prime is found.
1.29 ihickson 306:
307: <p><a href="http://www.whatwg.org/demos/workers/primes/page.html">View this
308: example online</a>.
1.4 ihickson 309:
1.22 ihickson 310: <h3 id=conformance><span class=secno>1.2 </span>Conformance requirements</h3>
1.1 ihickson 311:
312: <p>All diagrams, examples, and notes in this specification are
313: non-normative, as are all sections explicitly marked non-normative.
314: Everything else in this specification is normative.
315:
316: <p>The key words "MUST", "MUST NOT", "REQUIRED", <!--"SHALL", "SHALL
317: NOT",-->
318: "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in the
319: normative parts of this document are to be interpreted as described in
320: RFC2119. For readability, these words do not appear in all uppercase
321: letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
322: <!-- XXX but they should be
323: marked up -->
324:
325: <p>Requirements phrased in the imperative as part of algorithms (such as
326: "strip any leading space characters" or "return false and abort these
327: steps") are to be interpreted with the meaning of the key word ("must",
328: "should", "may", etc) used in introducing the algorithm.
329:
330: <p>Some conformance requirements are phrased as requirements on attributes,
331: methods or objects. Such requirements are to be interpreted as
332: requirements on user agents.
333:
334: <p>Conformance requirements phrased as algorithms or specific steps may be
335: implemented in any manner, so long as the end result is equivalent. (In
336: particular, the algorithms defined in this specification are intended to
337: be easy to follow, and not intended to be performant.)
338:
339: <p>The only conformance class defined by this specification is user agents.
340:
341: <p>User agents may impose implementation-specific limits on otherwise
342: unconstrained inputs, e.g. to prevent denial of service attacks, to guard
343: against running out of memory, or to work around platform-specific
344: limitations.
345:
1.22 ihickson 346: <h4 id=dependencies><span class=secno>1.2.1 </span>Dependencies</h4>
1.1 ihickson 347:
348: <p>This specification relies on several other underlying specifications.
349:
350: <dl>
351: <dt>HTML5
352:
353: <dd>
354: <p>Many fundamental concepts from HTML5 are used by this specification.
355: <a href="#refsHTML5">[HTML5]</a></p>
356:
357: <dt>ECMAScript
358:
359: <dd>
360: <p>This specification is intended to be used with JavaScript as the
361: scripting language. <a href="#refsJS">[JS]</a></p>
362:
363: <dt>WebIDL
364:
365: <dd>
366: <p>The IDL blocks in this specification use the semantics of the WebIDL
367: specification. <a href="#refsWebIDL">[WebIDL]</a></p>
368: </dl>
369:
1.22 ihickson 370: <h3 id=terminology><span class=secno>1.3 </span>Terminology</h3>
1.1 ihickson 371:
372: <p>For simplicity, terms such as <em>shown</em>, <em>displayed</em>, and
373: <em>visible</em> might sometimes be used when referring to the way a
374: document is rendered to the user. These terms are not meant to imply a
375: visual medium; they must be considered to apply to other media in
376: equivalent ways.
377:
1.4 ihickson 378: <p>The construction "a <code title="">Foo</code> object", where <code
379: title="">Foo</code> is actually an interface, is sometimes used instead of
380: the more accurate "an object implementing the interface <code
381: title="">Foo</code>".
1.1 ihickson 382:
383: <p>The term DOM is used to refer to the API set made available to scripts
384: in Web applications, and does not necessarily imply the existence of an
385: actual <code>Document</code> object or of any other <code>Node</code>
386: objects as defined in the DOM Core specifications. <a
387: href="#refsDOM3CORE">[DOM3CORE]</a>
388:
389: <p>A DOM attribute is said to be <em>getting</em> when its value is being
390: retrieved (e.g. by author script), and is said to be <em>setting</em> when
391: a new value is assigned to it.
392:
393: <p>If a DOM object is said to be <dfn id=live>live</dfn>, then that means
394: that any attributes returning that object must always return the same
395: object (not a new object each time), and the attributes and methods on
396: that object must operate on the actual underlying data, not a snapshot of
397: the data.
398:
1.12 ihickson 399: <h2 id=infrastructure><span class=secno>2. </span>Infrastructure</h2>
1.4 ihickson 400:
1.26 ihickson 401: <h3 id=the-workerglobalscope><span class=secno>2.1 </span>The <code><a
402: href="#workerglobalscope">WorkerGlobalScope</a></code> interface</h3>
1.4 ihickson 403:
404: <pre
1.26 ihickson 405: class=idl>[NoInterfaceObject] interface <dfn id=workerglobalscope>WorkerGlobalScope</dfn> {
406: // core worker features
407: readonly attribute <a href="#workerglobalscope">WorkerGlobalScope</a> <a href="#self" title=dom-WorkerGlobalScope-self>self</a>;
408: readonly attribute DOMString <a href="#url" title=dom-WorkerGlobalScope-URL>URL</a>;
409: readonly attribute DOMString <a href="#name" title=dom-WorkerGlobalScope-name>name</a>;
410: readonly attribute boolean <a href="#closing" title=dom-WorkerGlobalScope-closing>closing</a>;
411: void <a href="#close" title=dom-WorkerGlobalScope-close>close</a>();
412:
413: // other APIs
414: readonly attribute WorkerUtils <a href="#utils" title=dom-WorkerGlobalScope-utils>utils</a>;
1.9 ihickson 415:
416: // event handler attributes
1.26 ihickson 417: attribute <span>EventListener</span> <a href="#onconnect" title=handler-WorkerGlobalScope-onconnect>onconnect</a>;
418: attribute <span>EventListener</span> <a href="#onunload" title=handler-WorkerGlobalScope-onunload>onunload</a>;
1.4 ihickson 419: };</pre>
420:
1.26 ihickson 421: <p>The <dfn id=self
422: title=dom-WorkerGlobalScope-self><code>self</code></dfn> attribute must
423: return the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
424: object itself.
1.9 ihickson 425:
1.26 ihickson 426: <p>The <dfn id=url title=dom-WorkerGlobalScope-URL><code>URL</code></dfn>
1.6 ihickson 427: attribute must return the value it was assigned when the <code><a
1.26 ihickson 428: href="#workerglobalscope">WorkerGlobalScope</a></code> object was created
429: by the "<a href="#run-a">run a worker</a>" algorithm. It gives the
430: <span>absolute URL</span> of the script that was used to initialize the
431: worker.
432:
433: <p>The <dfn id=name
434: title=dom-WorkerGlobalScope-name><code>name</code></dfn> attribute must
435: return the value it was assigned when the <code><a
436: href="#workerglobalscope">WorkerGlobalScope</a></code> object was created
437: by the "<a href="#run-a">run a worker</a>" algorithm. If it has a value
438: that isn't the empty string, its value represents the name that can be
439: used to obtain a reference to the worker using the <code
440: title=dom-WorkerFactory-createNamedWorker><a
1.11 ihickson 441: href="#createnamedworker">createNamedWorker()</a></code> method.
1.6 ihickson 442:
1.4 ihickson 443: <p>The <dfn id=closing
1.26 ihickson 444: title=dom-WorkerGlobalScope-closing><code>closing</code></dfn> attribute
445: must return false until it is set to true by one of the algorithms in the
1.19 ihickson 446: processing model section below.
1.4 ihickson 447:
1.9 ihickson 448: <p>The following are the <span>event handler DOM attributes</span> that
449: must be supported by objects implementing the <code><a
1.26 ihickson 450: href="#workerglobalscope">WorkerGlobalScope</a></code> interface:
1.9 ihickson 451:
452: <dl>
1.20 ihickson 453: <dt><dfn id=onconnect
1.26 ihickson 454: title=handler-WorkerGlobalScope-onconnect><code>onconnect</code></dfn>
1.9 ihickson 455:
456: <dd>
457: <p>Must be invoked whenever a <code
1.26 ihickson 458: title=event-WorkerGlobalScope-connect>connect</code> event is targeted
459: at or bubbles through the <code><a
460: href="#workerglobalscope">WorkerGlobalScope</a></code> object.
1.9 ihickson 461:
462: <dt><dfn id=onunload
1.26 ihickson 463: title=handler-WorkerGlobalScope-onunload><code>onunload</code></dfn>
1.9 ihickson 464:
465: <dd>
466: <p>Must be invoked whenever a <code title=event-unload>unload</code>
467: event is targeted at or bubbles through the <code><a
1.26 ihickson 468: href="#workerglobalscope">WorkerGlobalScope</a></code> object.
1.9 ihickson 469: </dl>
470:
1.26 ihickson 471: <p>The <dfn id=utils
472: title=dom-WorkerGlobalScope-utils><code>utils</code></dfn> attribute must
473: return the <code><a href="#workerutils">WorkerUtils</a></code> object
474: created for the <code><a
475: href="#workerglobalscope">WorkerGlobalScope</a></code> object when the
476: worker was created.
477:
1.30 ! ihickson 478: <p>In addition to the above members, the <a href="#success" title="worker
! 479: creation succeeded">worker creation success steps</a> add a <dfn id=port
! 480: title=dom-WorkerGlobalScope-port><code>port</code></dfn> property to the
! 481: object.
! 482:
1.15 ihickson 483: <h3 id=base-urls><span class=secno>2.2 </span>Base URLs and origins of
484: workers</h3>
485:
486: <p>The <span>base URL</span> of a <span>URL</span> passed to an API in a
1.16 ihickson 487: worker is the <span>absolute URL</span> given by the value of the <code
1.26 ihickson 488: title=dom-WorkerGlobalScope-URL><a href="#url">URL</a></code> attribute of
489: the worker's <code><a
490: href="#workerglobalscope">WorkerGlobalScope</a></code> object.
1.15 ihickson 491:
1.25 ihickson 492: <p>Both the <span>origin</span> and <span>effective script origin</span> of
493: scripts running in workers are the <span>origin</span> of the
1.16 ihickson 494: <span>absolute URL</span> given by the value of the <code
1.26 ihickson 495: title=dom-WorkerGlobalScope-URL><a href="#url">URL</a></code> attribute of
496: the worker's <code><a
497: href="#workerglobalscope">WorkerGlobalScope</a></code> object.
1.15 ihickson 498:
499: <h3 id=the-queue><span class=secno>2.3 </span>The queue of events</h3>
1.4 ihickson 500:
1.26 ihickson 501: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
502: object is asssociated with a <dfn id=queue>queue of events</dfn>, which is
503: initially empty.
1.4 ihickson 504:
505: <p>An event in the queue can be a DOM event or a timeout callback.
506:
1.8 ihickson 507: <p>All asynchronous callbacks and events that would be called or dispatched
508: in the worker must be added to the worker's queue, with the "<a
509: href="#run-a">run a worker</a>" processing model below taking care of
510: actually calling the callbacks or dispatching the events.
511:
1.26 ihickson 512: <p>Once the <code><a
513: href="#workerglobalscope">WorkerGlobalScope</a></code>'s <code
514: title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
1.8 ihickson 515: attribute is set to true, the queue must discard anything else that would
516: be added to it. Effectively, once the <code
1.26 ihickson 517: title=dom-WorkerGlobalScope-closing><a href="#closing">closing</a></code>
1.8 ihickson 518: attribute is true, timers stop firing, notifications for all pending
519: asynchronous operations are dropped, etc.
520:
1.15 ihickson 521: <h3 id=the-workers><span class=secno>2.4 </span>The worker's ports</h3>
1.9 ihickson 522:
523: <p>Workers communicate with other workers and with <span title="browsing
524: context">browsing contexts</span> through <span title="channel
525: messaging">message channels</span> and their <code>MessagePort</code>
526: objects.
527:
1.26 ihickson 528: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
529: <var title="">worker</var> has a list of <dfn id=the-workers0>the worker's
1.9 ihickson 530: ports</dfn>, which consists of all the <code>MessagePort</code> objects
531: that are entangled with another port and that have one (but only one) port
1.26 ihickson 532: owned by <var title="">worker</var>. This list includes all the
533: <code>MessagePort</code> objects that are in events pending in the <a
534: href="#queue">queue of events</a>.
1.9 ihickson 535:
1.17 ihickson 536: <hr>
537:
538: <p>A worker is said to be a <dfn id=front-line>front-line worker</dfn> if
539: at least one of the <a href="#the-workers0">the worker's ports</a> has an
1.26 ihickson 540: entangled <code>MessagePort</code> owned by a <code>Window</code> object.
1.17 ihickson 541:
542: <p>A worker is said to be a <dfn id=needed>needed worker</dfn> if either:
543:
544: <ul>
545: <li>it is a <a href="#front-line">front-line worker</a>, or
546:
547: <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
1.26 ihickson 548: an entangled <code>MessagePort</code> owned by a <code><a
549: href="#workerglobalscope">WorkerGlobalScope</a></code> object that is
550: itself a <a href="#needed">needed worker</a>.
1.17 ihickson 551: </ul>
552:
553: <hr>
554:
555: <p>A worker is said to be an <dfn id=active>active front-line worker</dfn>
1.28 ihickson 556: if at least one of the <a href="#the-workers0">the worker's ports</a> is
557: entangled with a <code>MessagePort</code> <var title="">p</var> whose
558: owner is a <code>Window</code> object whose <span>active document</span>
559: is the <code>Document</code> that was that <span>browsing context</span>'s
560: <span>active document</span> when that <code>MessagePort</code> <var
561: title="">p</var> was created, and that <code>Document</code> is
562: <span>fully active</span>.
1.17 ihickson 563:
564: <p>A worker is said to be an <dfn id=active0>active needed worker</dfn> if
565: either:
566:
567: <ul>
568: <li>it is an <a href="#active">active front-line worker</a>, or
569:
570: <li>at least one of the <a href="#the-workers0">the worker's ports</a> has
1.26 ihickson 571: an entangled <code>MessagePort</code> owned by a <code><a
572: href="#workerglobalscope">WorkerGlobalScope</a></code> object that is
573: itself an <a href="#active0">active needed worker</a>.
1.17 ihickson 574: </ul>
575:
1.15 ihickson 576: <h3 id=processing><span class=secno>2.5 </span>Processing model</h3>
1.4 ihickson 577:
1.6 ihickson 578: <p>When a user agent is to <dfn id=run-a>run a worker</dfn> named <var
1.7 ihickson 579: title="">name</var> for a script with <span>URL</span> <var
580: title="">url</var>, a browsing context <var title="">owner browsing
581: context</var> and a <code>Document</code> <var title="">owner
582: document</var>, it must run the following steps in a completely separate
583: and parallel execution environment:
1.4 ihickson 584:
585: <ol>
586: <li>
1.7 ihickson 587: <p>Attempt to <span>fetch</span><!-- XXX --> the resource identified by
588: <var title="">url</var>.</p>
589:
590: <p>If the attempt fails, then abort these steps and invoke the <a
1.9 ihickson 591: href="#worker" title="worker creation failed">error handling steps</a>
1.7 ihickson 592: defined by the algorithm that called this one.</p>
593:
594: <p>If the attempt succeeds, then let <var title="">script</var> be the
595: resource that was obtained.</p>
596:
597: <p class=note>As with <code>script</code> elements, the MIME type of the
598: script is ignored. Unlike with <code>script</code> elements, there is no
599: way to override the type. It's always assumed to be JavaScript.</p>
600: <!-- XXX people will complain about
601: this. I guess we might want to examine the MIME type... -->
602:
603:
604: <li>
1.26 ihickson 605: <p>Create a new <code><a
606: href="#workerglobalscope">WorkerGlobalScope</a></code> object, <var
607: title="">worker</var>.</p>
1.4 ihickson 608:
609: <li>
1.26 ihickson 610: <p>Set the <code title=dom-WorkerGlobalScope-URL><a
611: href="#url">URL</a></code> attribute of <var title="">worker</var> to
612: the value of <var title="">url</var>.</p>
1.9 ihickson 613:
614: <li>
1.26 ihickson 615: <p>Set the <code title=dom-WorkerGlobalScope-name><a
1.19 ihickson 616: href="#name">name</a></code> attribute of <var title="">worker</var> to
1.6 ihickson 617: the value of <var title="">name</var>.</p>
618:
619: <li>
1.26 ihickson 620: <p>Create a new <code><a href="#workerutils">WorkerUtils</a></code>
621: object for the <code title=dom-WorkerGlobalScope-utils><a
622: href="#utils">utils</a></code> attribute of <var title="">worker</var>.
623:
624: <li>
1.4 ihickson 625: <p>Let <var title="">script</var>'s <span>script execution context</span>
626: (and thus also <span>global object</span>) be <var
1.19 ihickson 627: title="">worker</var>.</p>
1.4 ihickson 628:
629: <li>
630: <p>Let <var title="">script</var>'s <span>script browsing context</span>
631: be <var title="">owner browsing context</var>.</p>
632:
633: <li>
634: <p>Let <var title="">script</var>'s <span>script document context</span>
635: be <var title="">owner document</var>.</p>
636:
637: <li>
1.9 ihickson 638: <p>Invoke the <a href="#success" title="worker creation
639: succeeded">success steps</a> defined by the algorithm that called this
1.17 ihickson 640: one.</p>
641:
642: <p class=note>This will usually add an event to the <a
1.28 ihickson 643: href="#queue">queue of events</a> and set the <code
1.30 ! ihickson 644: title=dom-WorkerGlobalScope-port><a href="#port">port</a></code>
! 645: property on the <var title="">worker</var> object. If it does, that
! 646: event will have a <code>MessagePort</code> and thus the list of <a
1.17 ihickson 647: href="#the-workers0">the worker's ports</a> will not be empty. If it
1.19 ihickson 648: doesn't, then the next step will set the <var title="">worker</var>
1.26 ihickson 649: object's <code title=dom-WorkerGlobalScope-closing><a
1.17 ihickson 650: href="#closing">closing</a></code> attribute to true.</p>
651:
652: <li>
1.28 ihickson 653: <p><strong>Closing orphan workers</strong>: Start monitoring <var
654: title="">worker</var>, such that as soon as the worker stops being a <a
655: href="#needed">needed worker</a>, the <var title="">worker</var>
656: object's <code title=dom-WorkerGlobalScope-closing><a
1.17 ihickson 657: href="#closing">closing</a></code> attribute is set to true.</p>
1.9 ihickson 658:
659: <li>
1.28 ihickson 660: <p><strong>Suspending workers</strong>: Start monitoring <var
661: title="">worker</var>, such that whenever the <var title="">worker</var>
662: object's <code title=dom-WorkerGlobalScope-closing><a
1.26 ihickson 663: href="#closing">closing</a></code> attribute is false and the worker is
664: not an <a href="#active0">active needed worker</a>, the user agent
665: suspends execution of script in that worker until such time as either
666: the <code title=dom-WorkerGlobalScope-closing><a
667: href="#closing">closing</a></code> attribute switches to true or the
668: worker becomes an <a href="#active0">active needed worker</a>.</p>
1.7 ihickson 669:
670: <li>
671: <p>Run <var title="">script</var> until it either returns, fails to catch
672: an exception, or gets prematurely aborted by the "<a href="#kill-a">kill
673: a worker</a>" algorithm below.</p>
674:
675: <p class=note>If the script gets aborted by the "<a href="#kill-a">kill a
676: worker</a>" algorithm, then that same algorithm will cause there to only
677: be a single event in the <a href="#queue">queue of events</a> at the
1.28 ihickson 678: next step, namely the <code title=message-unload>unload</code> event.</p>
1.4 ihickson 679:
680: <li>
1.9 ihickson 681: <p><i>Event loop</i>: Wait until either there is an event in the <a
1.4 ihickson 682: href="#queue">queue of events</a> associated with <var
1.19 ihickson 683: title="">worker</var> or the <var title="">worker</var> object's <code
1.26 ihickson 684: title=dom-WorkerGlobalScope-closing><a
685: href="#closing">closing</a></code> attribute is set to true.</p>
1.4 ihickson 686:
687: <li>
688: <p>Dispatch the oldest event or callback in the <a href="#queue">queue of
1.9 ihickson 689: events</a>, if any. The handling of this event or the execution of this
690: callback might get prematurely aborted by the "<a href="#kill-a">kill a
1.8 ihickson 691: worker</a>" algorithm below.</p>
1.4 ihickson 692:
693: <li>
694: <p>If there are any more events in the <a href="#queue">queue of
1.19 ihickson 695: events</a> or if the <var title="">worker</var> object's <code
1.26 ihickson 696: title=dom-WorkerGlobalScope-closing><a
697: href="#closing">closing</a></code> attribute is set to false, then jump
698: back to the step above labeled <i>event loop</i>.</p>
1.4 ihickson 699:
700: <li>
701: <p class=big-issue>timers, intervals, XMLHttpRequests, database
1.28 ihickson 702: transactions, etc, must be killed; ports must be unentangled</p>
1.4 ihickson 703: </ol>
704:
705: <hr>
706:
707: <p>When a user agent is to <dfn id=kill-a>kill a worker</dfn>, it must run
708: the following steps in parallel with the worker's main loop (the "<a
709: href="#run-a">run a worker</a>" processing model defined above):
710:
711: <ol>
712: <li>
713: <p>Create an <code>Event</code> object with the event name <code
714: title=event-unload>unload</code>, which does not bubble and is not
715: cancelable, and add it to the worker's <code><a
1.26 ihickson 716: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1.8 ihickson 717: href="#queue">queue of events</a>, targetted at the <code><a
1.26 ihickson 718: href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
1.28 ihickson 719: </li>
720: <!-- XXX shouldn't add one if closing is
721: already true, assuming unload has already been added to the queue
722: (?) -->
1.4 ihickson 723:
724: <li>
1.26 ihickson 725: <p>Set the worker's <code><a
726: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <code
727: title=dom-WorkerGlobalScope-closing><a
1.8 ihickson 728: href="#closing">closing</a></code> attribute to true.
729:
730: <li>
731: <p>Wait a user-agent-defined amount of time. If the "<a href="#run-a">run
732: a worker</a>" processing model defined above immediately starts running
1.28 ihickson 733: event listeners registered for the <code
734: title=event-unload>unload</code> event, this time should not be zero
735: — the idea is that the <code title=event-unload>unload</code>
736: event can be used to clean up when shutting down unexpectedly.
1.4 ihickson 737:
738: <li>
739: <p>If there are any events in the <a href="#queue">queue of events</a>
740: other than the <code title=event-unload>unload</code> event that this
741: algorithm just added, discard them without dispatching them.
742:
743: <li>
744: <p>If the <code title=event-unload>unload</code> event that this
745: algorithm just added hasn't yet been dispatched, then abort the script
746: currently running in the worker.
747:
748: <li>
749: <p>Wait a user-agent-defined amount of time.
750:
751: <li>
752: <p>Abort the script currently running in the worker (if any script is
753: running, then it will be a handler for the <code
754: title=event-unload>unload</code> event).
755: </ol>
756:
1.19 ihickson 757: <p>User agents may invoke the "<a href="#kill-a">kill a worker</a>"
758: processing model on a worker at any time, e.g. in response to user
759: requests, in response to CPU quota management, or when a worker stops
760: being a <a href="#needed">needed worker</a> if the worker continues
1.26 ihickson 761: executing even after its <code title=dom-WorkerGlobalScope-closing><a
1.19 ihickson 762: href="#closing">closing</a></code> attribute was set to true.
763:
1.8 ihickson 764: <hr>
765:
766: <p>When a script invokes the <dfn id=close
1.26 ihickson 767: title=dom-WorkerGlobalScope-close><code>close()</code></dfn> method on a
768: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object,
769: the user agent must run the following steps:
1.8 ihickson 770:
771: <ol>
772: <li>
773: <p>Create an <code>Event</code> object with the event name <code
774: title=event-unload>unload</code>, which does not bubble and is not
775: cancelable, and add it to the <code><a
1.26 ihickson 776: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1.8 ihickson 777: href="#queue">queue of events</a>, targetted at the <code><a
1.26 ihickson 778: href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
1.8 ihickson 779:
780: <li>
1.26 ihickson 781: <p>Set the worker's <code><a
782: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <code
783: title=dom-WorkerGlobalScope-closing><a
1.8 ihickson 784: href="#closing">closing</a></code> attribute to true.
785:
786: <li>
787: <p>For each <code>MessagePort</code> object that is entangled with
1.26 ihickson 788: another port and that has one (but only one) port whose owner is the
789: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object
790: on which the method was invoked, run the following substeps:</p>
1.8 ihickson 791:
792: <ol>
793: <li>
794: <p>Unentangle the two ports.
795:
796: <li>
797: <p>At the next available opportunity, after any scripts have finished
798: executing<!-- XXX queue -->, <span>fire a simple event</span> called
799: <code title=event-unload>unload</code> at the other port (the one
1.26 ihickson 800: whose owner is not the <code><a
801: href="#workerglobalscope">WorkerGlobalScope</a></code> object on which
802: the <code title=dom-WorkerGlobalScope-close><a
1.8 ihickson 803: href="#close">close()</a></code> method was called).
804: </ol>
805: </ol>
806:
1.15 ihickson 807: <h3 id=creating><span class=secno>2.6 </span>Creating workers</h3>
1.5 ihickson 808:
809: <pre
1.26 ihickson 810: class=idl>[NoInterfaceObject] interface <dfn id=workerfactory>WorkerFactory</dfn> {
811: <span>MessagePort</span> <a href="#createworker" title=dom-WorkerFactory-createWorker>createWorker</a>(in DOMString scriptURL);
812: <span>MessagePort</span> <a href="#createnamedworker" title=dom-WorkerFactory-createNamedWorker>createNamedWorker</a>(in DOMString name, in DOMString scriptURL);
1.5 ihickson 813: };</pre>
814:
1.26 ihickson 815: <p>Objects that implement the <code>Window</code> and <code><a
816: href="#workerutils">WorkerUtils</a></code> interfaces must also implement
817: the <code><a href="#workerfactory">WorkerFactory</a></code> interface.
1.5 ihickson 818:
1.9 ihickson 819: <hr>
820:
1.11 ihickson 821: <p>When the <dfn id=createworker
1.26 ihickson 822: title=dom-WorkerFactory-createWorker><code>createWorker(<var
1.11 ihickson 823: title="">scriptURL</var>)</code></dfn> method is invoked, the user agent
824: must run the following steps:
1.9 ihickson 825:
826: <ol>
827: <li>
828: <p><span title="resolve a url">Resolve</span> the <var
829: title="">scriptURL</var> argument.
830:
831: <li>
832: <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.
833:
834: <li>
835: <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
836: is not the <span title="same origin">same</span> as the origin of the
837: script that invoked the method, then throw a <span>security
838: exception</span>.
839:
840: <li>
841: <p><a href="#create">Create a worker</a> from the resulting
842: <span>absolute URL</span> whose name is the empty string.
843:
844: <li>
845: <p>Return the <code>MessagePort</code> object returned from the <a
846: href="#create">create a worker</a> algorithm.
847: </ol>
848:
849: <hr>
850:
1.11 ihickson 851: <p>When the <dfn id=createnamedworker
1.26 ihickson 852: title=dom-WorkerFactory-createNamedWorker><code>createNamedWorker(<var
1.11 ihickson 853: title="">name</var>, <var title="">scriptURL</var>)</code></dfn> method is
1.9 ihickson 854: invoked, the user agent must run the following steps:
855:
856: <ol>
857: <li>
858: <p><span title="resolve a url">Resolve</span> the <var
859: title="">scriptURL</var> argument.
1.4 ihickson 860:
1.9 ihickson 861: <li>
862: <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.
863:
864: <li>
865: <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
866: is not the <span title="same origin">same</span> as the origin of the
867: script that invoked the method, then throw a <span>security
868: exception</span>.
869:
870: <li>
871: <p>If the <var title="">name</var> argument is the empty string, <a
872: href="#create">create a worker</a> from the resulting <span>absolute
873: URL</span>, whose name is the empty string, and return the
874: <code>MessagePort</code> object returned from the <a
875: href="#create">create a worker</a> algorithm. Then, abort these steps.
876:
877: <li>
1.26 ihickson 878: <p>If there exists a worker whose <code
879: title=dom-WorkerGlobalScope-closing><a
1.9 ihickson 880: href="#closing">closing</a></code> attribute is false, whose <code
1.26 ihickson 881: title=dom-WorkerGlobalScope-name><a href="#name">name</a></code>
882: attribute is exactly equal to the <var title="">name</var> argument, and
883: whose <code title=dom-WorkerGlobalScope-URL><a
884: href="#url">URL</a></code> attribute has the <span>same origin</span> as
885: the resulting <span>absolute URL</span>, then run these substeps:</p>
1.9 ihickson 886:
887: <ol>
888: <li>
1.26 ihickson 889: <p>If that worker's <code title=dom-WorkerGlobalScope-URL><a
1.9 ihickson 890: href="#url">URL</a></code> attribute is not exactly equal to the
891: resulting <span>absolute URL</span>, then throw a
892: <code>URL_MISMATCH_ERR</code> exception and abort these steps. <span
893: class=big-issue>code 19</span>
894:
895: <li>
896: <p><span>Create a new <code>MessagePort</code> object</span> owned by
897: the <span>script execution context</span> of the script that invoked
898: the method.
899:
900: <li>
901: <p>Return that port.
902:
903: <li>
1.20 ihickson 904: <p>Asynchronously, <a href="#connect" title="connect to a
905: worker">connect</a> to this preexisting worker, with the newly created
1.9 ihickson 906: port.
907: </ol>
908:
909: <p>Otherwise, <a href="#create">create a worker</a> from the resulting
910: <span>absolute URL</span>, whose name is the value of the <var
911: title="">name</var> argument, and return the <code>MessagePort</code>
912: object returned from the <a href="#create">create a worker</a>
913: algorithm.</p>
914: </ol>
915:
916: <hr>
917:
918: <p>The steps to <dfn id=create>create a worker</dfn> from a
919: <span>URL</span> <var title="">url</var> and whose name is <var
920: title="">name</var>, in the context of a method call, are as follows:
921:
922: <ol>
923: <li>
924: <p><span>Create a new <code>MessagePort</code> object</span> owned by the
925: <span>script execution context</span> of the script that invoked the
926: method.
927:
928: <li>
929: <p>Return that port.
930:
931: <li>
932: <p>In a parallel execution context (i.e. a separate thread or process or
933: equivalent construct), <a href="#run-a">run a worker</a> named <var
934: title="">name</var> for the script with <span>URL</span> <var
935: title="">url</var>, with the <span>script browsing context</span> of the
936: script that invoked the method as the <var title="">owner browsing
937: context</var> and with the <span>script document context</span> of the
938: script that invoked the method as the <var title="">owner
939: document</var>.</p>
940:
941: <p>If that algorithm invokes the steps for <dfn id=success title="worker
1.20 ihickson 942: creation succeeded">success steps</dfn>, then <a href="#connect"
943: title="connect to a worker">connect</a> to this new worker, with the
1.28 ihickson 944: newly created port, and if that algorithm returns a second new port,
1.30 ! ihickson 945: then add a new property <code title=dom-WorkerGlobalScope-port><a
! 946: href="#port">port</a></code> on the new worker's <code><a
! 947: href="#workerglobalscope">WorkerGlobalScope</a></code> object, whose
! 948: value is the <code>MessagePort</code> object return by the <a
1.28 ihickson 949: href="#connect">connect to a worker</a> algorithm.</p>
1.9 ihickson 950:
951: <p>Otherwise, if the <dfn id=worker>worker creation failed</dfn>, then at
952: the next available opportunity, after any scripts have finished
953: executing<!-- XXX queue -->, <span>fire a simple event</span> called
954: <code title=event-error>error</code> at the newly created port.</p>
955: </ol>
956:
957: <hr>
958:
1.20 ihickson 959: <p>The steps to <dfn id=connect>connect to a worker</dfn> given a
1.9 ihickson 960: <code>MessagePort</code> object <var title="">port</var> are as follows:
961:
962: <ol>
963: <li>
964: <p>If <var title="">port</var> would have been garbage collected, or if
1.26 ihickson 965: the <span>active document</span> of the owner of <var
1.9 ihickson 966: title="">port</var> is no longer the same <code>Document</code> object
967: as when <var title="">port</var> was created, then do nothing. Abort
968: these steps. If the worker was just created, it'll get killed
969: immediately.</p>
970:
971: <li>
972: <p><span>Create a new <code>MessagePort</code> object</span> owned by the
1.26 ihickson 973: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> of the
974: worker.
1.9 ihickson 975:
976: <li>
977: <p><span>Entangle</span> this newly created port and the port <var
978: title="">port</var> that was passed to these steps.
979:
980: <li>
981: <p>At the next available opportunity, after any scripts have finished
982: executing<!-- XXX queue -->, <span>fire a simple event</span> called
983: <code title=event-load>load</code> at <var title="">port</var>.
984:
985: <li>
986: <p>Create an event that uses the <code>MessageEvent</code> interface,
1.20 ihickson 987: with the name <code title=event-connect>connect</code>, which does not
1.9 ihickson 988: bubble, is cancelable, has no default action, has a <code
989: title=dom-MessageEvent-data>data</code> attribute whose value is the
990: empty string and has a <code
991: title=dom-MessageEvent-messagePort>messagePort</code> attribute whose
992: value is the newly created port, and add it to the worker's <code><a
1.26 ihickson 993: href="#workerglobalscope">WorkerGlobalScope</a></code> object's <a
1.9 ihickson 994: href="#queue">queue of events</a>, targetted at the <code><a
1.26 ihickson 995: href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.
1.28 ihickson 996:
997: <li>
998: <p>Return the newly created port.
1.9 ihickson 999: </ol>
1.7 ihickson 1000:
1.12 ihickson 1001: <h2 id=apis-available><span class=secno>3. </span>APIs available to workers</h2>
1002:
1.26 ihickson 1003: <pre
1004: class=idl>[NoInterfaceObject] interface <dfn id=workerutils>WorkerUtils</dfn> {
1.27 ihickson 1005: boolean <a href="#importscript" title=dom-WorkerGlobalScope-importScript>importScript</a>(in DOMString url);
1.26 ihickson 1006: readonly attribute <span>Storage</span> <a href="#localstorage" title=dom-localStorage>localStorage</a>;
1007: <span>Database</span> <a href="#opendatabase" title=dom-opendatabase>openDatabase</a>(in DOMString name, in DOMString version, in DOMString displayName, in unsigned long estimatedSize);
1008: void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description);
1009: void <a href="#shownotification" title=dom-showNotification>showNotification</a>(in DOMString title, in DOMString subtitle, in DOMString description, in VoidCallback onclick);
1010: };</pre>
1.18 ihickson 1011:
1.12 ihickson 1012: <p>Objects that implement the <code><a
1.26 ihickson 1013: href="#workerutils">WorkerUtils</a></code> interface must also implement
1.12 ihickson 1014: the following interfaces:
1015:
1016: <ul>
1.26 ihickson 1017: <li>The <code>WindowTimers</code> interface
1.12 ihickson 1018:
1.26 ihickson 1019: <li>The <code>EventTarget</code> interface
1.12 ihickson 1020:
1.26 ihickson 1021: <li>The <code><a href="#workerfactory">WorkerFactory</a></code> interface,
1022: as noted earlier in this specification
1.12 ihickson 1023: </ul>
1024:
1.23 ihickson 1025: <p class=big-issue>Need to define a sync database API.
1026:
1027: <p class=big-issue>May need to define a browser sniffing API (like
1028: window.navigator).</p>
1.18 ihickson 1029: <!-- XXX ApplicationCache -->
1030: <!-- XXX a way to set cookies on the URL for the script -->
1.24 ihickson 1031: <!-- XXX debugging: void log(in DOMString s); // log to console -->
1032: <!-- XXX debugging: onerror -->
1.13 ihickson 1033:
1.18 ihickson 1034: <hr>
1.13 ihickson 1035:
1.18 ihickson 1036: <p>The DOM APIs (<code>Node</code> objects, <code>Document</code> objects,
1037: etc) are not available to workers in this version of this specification.
1.13 ihickson 1038:
1.26 ihickson 1039: <h3 id=importing><span class=secno>3.1 </span>Importing scripts and
1040: libraries</h3>
1041:
1.27 ihickson 1042: <p>When a script invokes the <dfn id=importscript
1043: title=dom-WorkerGlobalScope-importScript><code>importScript(<var
1.26 ihickson 1044: title="">url</var>)</code></dfn> method on a <code><a
1045: href="#workerglobalscope">WorkerGlobalScope</a></code> object, the user
1046: agent must run the following steps:
1047:
1048: <ol>
1049: <li>
1050: <p><span title="resolve a url">Resolve</span> the <var title="">url</var>
1051: argument.
1052:
1053: <li>
1054: <p>If this fails, throw a <code>SYNTAX_ERR</code> exception.
1055:
1056: <li>
1057: <p>If the <span>origin</span> of the resulting <span>absolute URL</span>
1058: is not the <span title="same origin">same</span> as the origin of the
1059: script that invoked the method, then throw a <span>security
1060: exception</span>.
1061:
1062: <li>
1063: <p>Attempt to <span>fetch</span><!-- XXX --> the resource identified by
1064: the resulting <span>absolute URL</span>.</p>
1065:
1066: <p>If the attempt fails, return false and abort these steps.</p>
1067:
1068: <p>If the attempt succeeds, then let <var title="">script</var> be the
1069: resource that was obtained.</p>
1070:
1071: <p class=note>As with the initial script, the script here is always
1072: assumed to be JavaScript, regardless of the MIME type.</p>
1073: <!-- XXX -->
1074:
1075: <li>
1076: <p>Let <var title="">script</var>'s <span>script execution
1077: context</span>, <span>script browsing context</span>, and <span>script
1078: document context</span> be the same as for the script that was executed
1079: by the <a href="#run-a">run a worker</a> processing model for this
1080: worker.</p>
1081:
1082: <li>
1083: <p>Run <var title="">script</var> until it either returns, fails to catch
1084: an exception, or gets prematurely aborted by the "<a href="#kill-a">kill
1085: a worker</a>" algorithm above.</p>
1086:
1087: <p>If an exception was raised or if the script was prematurely aborted,
1088: then abort these steps, letting the exception or aborting continue to be
1089: processed by the script that called the <code
1.27 ihickson 1090: title=dom-WorkerGlobalScope-importScript><a
1091: href="#importscript">importScript()</a></code> method.</p>
1.26 ihickson 1092:
1093: <p>Otherwise, return true.</p>
1094: </ol>
1095:
1096: <h3 id=apis-defined><span class=secno>3.2 </span>APIs defined in other
1097: specifications</h3>
1098:
1.27 ihickson 1099: <p>The <dfn id=localstorage
1.26 ihickson 1100: title=dom-localStorage><code>localStorage</code></dfn>, <dfn
1101: id=opendatabase title=dom-opendatabase><code>openDatabase()</code></dfn>
1102: must act as defined for the APIs with the same names on the
1103: <code>Window</code> object in the HTML5 specification, with the exception
1104: that where the API would use the <span>origin</span> of the <span>active
1105: document</span> of the <span>browsing context</span> of the
1106: <code>Window</code> object on which the method was supposedly invoked, it
1107: must instead use the <span>origin</span> of the script that invoked the
1108: method. <a href="#refsHTML5">[HTML5]</a>
1109:
1110: <p>The <dfn id=shownotification
1111: title=dom-showNotification><code>showNotification()</code></dfn> methods
1112: must act as defined for the APIs with the same names on the
1113: <code>Window</code> object in the HTML5 specification. <a
1114: href="#refsHTML5">[HTML5]</a>
1115:
1116: <h3 id=interface><span class=secno>3.3 </span>Interface objects and
1117: constructors</h3>
1118:
1119: <p>There must be no interface objects and constructors available in the
1120: global scope of scripts whose <span>script execution context</span> is a
1121: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object
1122: except for the following:
1123:
1124: <ul>
1125: <li>
1126: <p><code>XMLHttpRequest</code> and all interface objects and constructors
1127: defined by the XMLHttpRequest specifications, except that the
1128: <span>document response entity body</span> must always be null. <a
1129: href="#refsXHR">[XHR]</a>
1130:
1131: <li>
1132: <p>The <code>WebSocket</code> interface object and constructor.
1133:
1134: <li>
1135: <p>The <code>MessageChannel</code> interface object and constructor.
1136: </ul>
1137:
1.1 ihickson 1138: <h2 class=no-num id=references>References</h2>
1139:
1140: <p class=big-issue>This section will be written in a future
1141: draft.<!--XXX-->
1142:
1143: <h2 class=no-num id=acknowledgements>Acknowledgements</h2>
1144: <!-- ACKS -->
1145:
1.26 ihickson 1146: <p>Thanks to Aaron Boodman, Jonas Sicking, Maciej Stachowiak, Mike Smith,
1147: and Philip Taylor for their useful and substantial comments.
1.4 ihickson 1148:
1149: <p>Huge thanks to the whole Gears team, who pioneered this technology and
1150: 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