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