Annotation of html5/workers/Overview.html, revision 1.340
1.327 ihickson 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"><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; }
1.300 ihickson 20: i, em { font-style: italic; }
1.82 ihickson 21: dt dfn { font-style: italic; }
22: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
23: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
24: pre em { font-weight: bolder; font-style: normal; }
1.89 ihickson 25: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
1.82 ihickson 26: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
27: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
1.249 ihickson 28: table thead, table tbody { border-bottom: solid; }
1.82 ihickson 29: table tbody th:first-child { border-left: solid; }
1.180 ihickson 30: table tbody th { text-align: left; }
1.82 ihickson 31: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
32: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
33:
34: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
35: .matrix, .matrix td { border: none; text-align: right; }
36: .matrix { margin-left: 2em; }
37: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
38: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
39: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
40:
41: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
1.305 ihickson 42: img.extra, p.overview { float: right; }
1.304 ihickson 43: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
1.82 ihickson 44: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
1.304 ihickson 45: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
1.82 ihickson 46: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
47: pre.css:first-line { color: #AAAA50; }
1.231 ihickson 48: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
1.82 ihickson 49: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
50: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
51: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
52: dl.domintro dd p { margin: 0.5em 0; }
1.310 ihickson 53: dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
1.82 ihickson 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; }
1.139 ihickson 66: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
1.82 ihickson 67: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
68:
1.267 ihickson 69: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
70: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.82 ihickson 71:
72: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
73: div.head p { margin: 0; }
74: div.head h1 { margin: 0; }
75: div.head .logo { float: right; margin: 0 1em; }
76: div.head .logo img { border: none } /* remove border from top image */
77: div.head dl { margin: 1em 0; }
1.212 ihickson 78: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
1.82 ihickson 79:
80: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
81: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
82: body > .toc > li > * { margin-bottom: 0.5em; }
83: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
84: .toc, .toc li { list-style: none; }
85:
86: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
87: .brief li { margin: 0; padding: 0; }
88: .brief li p { margin: 0; padding: 0; }
89:
1.137 ihickson 90: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
91: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
92: .category-list li { display: inline; }
93: .category-list li:not(:last-child)::after { content: ', '; }
94: .category-list li > span, .category-list li > a { text-transform: lowercase; }
95: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
96:
1.82 ihickson 97: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
98: .XXX > :first-child { margin-top: 0; }
99: p .XXX { line-height: 3em; }
1.158 ihickson 100: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
101: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
102: .annotation :link, .annotation :visited { color: inherit; }
103: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
104: .annotation span { border: none ! important; }
1.82 ihickson 105: .note { color: green; background: transparent; font-family: sans-serif; }
106: .warning { color: red; background: transparent; }
107: .note, .warning { font-weight: bolder; font-style: italic; }
1.300 ihickson 108: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.82 ihickson 109: p.note, div.note { padding: 0.5em 2em; }
110: span.note { padding: 0 2em; }
111: .note p:first-child, .warning p:first-child { margin-top: 0; }
112: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
113: .warning:before { font-style: normal; }
114: p.note:before { content: 'Note: '; }
115: p.warning:before { content: '\26A0 Warning! '; }
116:
117: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
118: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
119: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.262 ihickson 120: .bookkeeping dt { margin: 0.5em 2em 0; }
121: .bookkeeping dd { margin: 0 3em 0.5em; }
1.82 ihickson 122:
123: h4 { position: relative; z-index: 3; }
124: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
125: .element {
1.88 ihickson 126: background: #EEEEFF;
1.82 ihickson 127: color: black;
128: margin: 0 0 1em 0.15em;
129: padding: 0 1em 0.25em 0.75em;
1.88 ihickson 130: border-left: solid #9999FF 0.25em;
1.82 ihickson 131: position: relative;
132: z-index: 1;
133: }
134: .element:before {
135: position: absolute;
136: z-index: 2;
137: top: 0;
138: left: -1.15em;
139: height: 2em;
140: width: 0.9em;
1.88 ihickson 141: background: #EEEEFF;
1.82 ihickson 142: content: ' ';
143: border-style: none none solid solid;
1.88 ihickson 144: border-color: #9999FF;
1.82 ihickson 145: border-width: 0.25em;
146: }
147:
1.156 ihickson 148: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
149: td > .example:only-child { margin: 0 0 0 0.1em; }
1.82 ihickson 150:
1.131 ihickson 151: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
152: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
153: ul.domTree li li { list-style: none; }
154: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
155: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
156: ul.domTree span { font-style: italic; font-family: serif; }
157: ul.domTree .t1 code { color: purple; font-weight: bold; }
158: ul.domTree .t2 { font-style: normal; font-family: monospace; }
159: ul.domTree .t2 .name { color: black; font-weight: bold; }
160: ul.domTree .t2 .value { color: blue; font-weight: normal; }
161: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
162: ul.domTree .t7 code, .domTree .t8 code { color: green; }
163: ul.domTree .t10 code { color: teal; }
164:
1.225 ihickson 165: body.dfnEnabled dfn { cursor: pointer; }
166: .dfnPanel {
167: display: inline;
168: position: absolute;
169: z-index: 10;
170: height: auto;
171: width: auto;
172: padding: 0.5em 0.75em;
173: font: small sans-serif, Droid Sans Fallback;
174: background: #DDDDDD;
175: color: black;
176: border: outset 0.2em;
177: }
178: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
179: .dfnPanel :link, .dfnPanel :visited { color: black; }
180: .dfnPanel p { font-weight: bolder; }
181: .dfnPanel * + p { margin-top: 0.25em; }
182: .dfnPanel li { list-style-position: inside; }
183:
1.207 ihickson 184: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
185: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
186: #configUI p label { display: block; }
187: #configUI #updateUI, #configUI .loginUI { text-align: center; }
188: #configUI input[type=button] { display: block; margin: auto; }
1.260 ihickson 189:
1.268 ihickson 190: fieldset { margin: 1em; padding: 0.5em 1em; }
191: fieldset > legend + * { margin-top: 0; }
1.266 ihickson 192: fieldset > :last-child { margin-bottom: 0; }
1.268 ihickson 193: fieldset p { margin: 0.5em 0; }
1.266 ihickson 194:
1.329 ihickson 195: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><meta content="noindex" name="robots"><script type="text/javascript">
1.271 ihickson 196: function getCookie(name) {
197: var params = location.search.substr(1).split("&");
198: for (var index = 0; index < params.length; index++) {
199: if (params[index] == name)
200: return "1";
201: var data = params[index].split("=");
202: if (data[0] == name)
203: return unescape(data[1]);
204: }
205: var cookies = document.cookie.split("; ");
206: for (var index = 0; index < cookies.length; index++) {
207: var data = cookies[index].split("=");
208: if (data[0] == name)
209: return unescape(data[1]);
210: }
211: return null;
212: }
1.327 ihickson 213: </script><body>
214: <div class="head" id="head">
1.115 ihickson 215: <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.271 ihickson 216:
1.54 ihickson 217: <h1>Web Workers</h1>
1.281 ihickson 218:
1.340 ! ihickson 219: <h2 class="no-num no-toc" id="editor-s-draft-26-august-2012">Editor's Draft 26 August 2012</h2>
1.218 ihickson 220: <dl><dt>Latest Published Version:</dt>
1.115 ihickson 221: <dd><a href="http://www.w3.org/TR/workers/">http://www.w3.org/TR/workers/</a></dd>
1.109 ihickson 222: <dt>Latest Editor's Draft:</dt>
1.260 ihickson 223: <dd><a class="latest-link" href="http://dev.w3.org/html5/workers/">http://dev.w3.org/html5/workers/</a></dd>
1.284 ihickson 224:
1.318 ihickson 225:
1.2 ihickson 226: <dt>Previous Versions:</dt>
1.279 ihickson 227: <dd><a href="http://www.w3.org/TR/2011/WD-workers-20110310/">http://www.w3.org/TR/2011/WD-workers-20110310/</a></dd>
228: <dd><a href="http://www.w3.org/TR/2011/WD-workers-20110208/">http://www.w3.org/TR/2011/WD-workers-20110208/</a></dd>
1.198 ihickson 229: <dd><a href="http://www.w3.org/TR/2009/WD-workers-20091029/">http://www.w3.org/TR/2009/WD-workers-20091029/</a></dd>
1.279 ihickson 230: <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 231: <!-- :ZZZ -->
1.271 ihickson 232: <dt>Editor:</dt>
1.115 ihickson 233: <dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.</dd>
1.155 ihickson 234: </dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
1.328 ihickson 235: © 2012 <a href="http://www.w3.org/"><abbr title="World Wide
1.155 ihickson 236: Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts
1.297 ihickson 237: Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research
1.115 ihickson 238: Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C
239: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
240: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
241: and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document
1.81 ihickson 242: use</a> rules apply.</p>
1.201 ihickson 243:
1.254 ihickson 244:
1.252 ihickson 245: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
1.255 ihickson 246: <p class="alt">The bulk of the text of this specification is also
1.254 ihickson 247: available in the WHATWG <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html#workers">Web Applications 1.0</a> specification, under a license that permits
248: reuse of the specification text.</p>
1.252 ihickson 249: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
250:
1.254 ihickson 251:
1.327 ihickson 252: </div>
253:
254: <hr class="top"><h2 class="no-num no-toc" id="abstract">Abstract</h2>
255:
256: <p>This specification defines an API that allows Web application
1.81 ihickson 257: authors to spawn background workers running scripts in parallel to
258: their main page. This allows for thread-like operation with
1.327 ihickson 259: message-passing as the coordination mechanism.</p>
260:
261: <h2 class="no-num no-toc" id="status-of-this-document">Status of This document</h2>
262:
263:
264:
265:
266: <p><em>This section describes the status of this document at the
1.81 ihickson 267: time of its publication. Other documents may supersede this
1.297 ihickson 268: document. A list of current W3C publications and the
269:
270: most recently formally published <!-- DO NOT CHANGE THIS BACK TO THE STANDARD BOILERPLATE, AS IT IS INACCURATE -->
271:
272: revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
1.327 ihickson 273: http://www.w3.org/TR/.</em></p>
274:
275:
276:
277:
278: <p>If you wish to make comments regarding this document in a manner
1.271 ihickson 279: that is tracked by the W3C, please submit them via using <a href="http://www.w3.org/Bugs/Public/enter_bug.cgi?product=HTML%20WG">our
280: public bug database</a>. If you do not have an account then you can
1.327 ihickson 281: enter feedback using this form:</p>
282:
283: <form action="http://www.whatwg.org/specs/web-apps/current-work/file-spam.cgi" method="post">
1.271 ihickson 284: <fieldset><legend>Feedback Comments</legend>
285: <input name="id" type="hidden" value="top"><input name="component" type="hidden" value="Web Workers (editor: Ian Hickson)"><input name="response" type="hidden" value="html"><p><label for="feedbackBox">Please enter your feedback, carefully
286: indicating the title of the section for which you are submitting
287: feedback, quoting the text that's wrong today if appropriate. If
288: you're suggesting a new feature, it's really important to say
289: <em>what</em> the problem you're trying to solve is. That's more
290: important than the solution, in fact.</label></p>
291: <p><textarea cols="79" id="feedbackBox" name="text" rows="10"></textarea></p>
292: <p class="note">Please don't use section numbers as these tend to
293: change rapidly and make your feedback harder to understand.</p>
294: <script type="text/javascript">
1.287 ihickson 295: function checkFeedbackForm(form) {
296: if (form.elements.text.value.match(/^ *</)) {
297: alert('Please don\'t start your feedback with an angle bracket, instead explain what topic your feedback is about first.');
298: return true;
299: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
300: if (form.elements.text.value.match(/^Please enter your feedback, carefully/)) {
301: alert('Please enter your feedback, explaining what is wrong, and without repeating the instructions. Thanks!');
302: return true;
303: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
304: form.action = "http://www.whatwg.org/specs/web-apps/current-work/file-bug.cgi";
305: return true;
306: } else {
307: alert('Please include significantly more detail about exactly what problem you are trying to solve.');
308: return false;
309: }
310: }
311: }
1.271 ihickson 312: </script><p>
1.277 ihickson 313: <input onclick="return checkFeedbackForm(form)" type="submit" value="Submit feedback"><small>(Note: Your IP address and user agent will be publicly recorded for spam prevention purposes.)</small>
1.271 ihickson 314: </p>
1.327 ihickson 315: </fieldset></form>
316:
317:
318: <p>You can also e-mail feedback to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>,
1.271 ihickson 319: <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>),
1.115 ihickson 320: or <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a> (<a href="http://lists.whatwg.org/listinfo.cgi/whatwg-whatwg.org">subscribe</a>,
321: <a href="http://lists.whatwg.org/pipermail/whatwg-whatwg.org/">archives</a>).
1.327 ihickson 322: All feedback is welcome.</p>
323:
324:
325: <p>Implementors should be aware that this specification is not
1.81 ihickson 326: stable. <strong>Implementors who are not taking part in the
327: discussions are likely to find the specification changing out from
328: under them in incompatible ways.</strong> Vendors interested in
329: implementing this specification before it eventually reaches the
330: Candidate Recommendation stage should join the aforementioned
1.327 ihickson 331: mailing lists and take part in the discussions.</p>
332:
333: <div id="multipage-common">
334: </div>
335:
336: <p>The latest
1.271 ihickson 337: stable version of the editor's draft of this specification is always
338: available on <a href="http://dev.w3.org/html5/workers/">the W3C CVS server</a>
339: and in the <a href="http://svn.whatwg.org/webapps/">WHATWG
340: Subversion repository</a>. The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html">latest
341: editor's working copy</a> (which may contain unfinished text in the
342: process of being prepared) contains the latest draft text of this
343: specification (amongst others). For more details, please see the <a href="http://wiki.whatwg.org/wiki/FAQ#What_are_the_various_versions_of_the_spec.3F">WHATWG
1.327 ihickson 344: FAQ</a>.</p>
345:
346: <p>Notifications of changes to this specification are sent along
1.271 ihickson 347: with notifications of changes to related specifications using the
1.327 ihickson 348: following mechanisms:</p>
349: <dl><dt>E-mail notifications of changes</dt>
1.271 ihickson 350: <dd>Commit-Watchers mailing list (complete source diffs): <a href="http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org">http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a></dd>
351: <dt>Browsable version-control record of all changes:</dt>
352: <dd>CVSWeb interface with side-by-side diffs: <a href="http://dev.w3.org/cvsweb/html5/">http://dev.w3.org/cvsweb/html5/</a></dd>
353: <dd>Annotated summary with unified diffs: <a href="http://html5.org/tools/web-apps-tracker">http://html5.org/tools/web-apps-tracker</a></dd>
354: <dd>Raw Subversion interface: <code>svn checkout http://svn.whatwg.org/webapps/</code></dd>
355: </dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
1.81 ihickson 356: Working Group</a> is the W3C working group responsible for this
357: specification's progress along the W3C Recommendation track.
1.340 ! ihickson 358: This specification is the 26 August 2012 Editor's Draft.
1.327 ihickson 359: </p>
360:
361:
362:
363: <p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
1.115 ihickson 364: 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 365: any patent disclosures</a> made in connection with the deliverables
366: of the group; that page also includes instructions for disclosing a
367: patent. An individual who has actual knowledge of a patent which the
1.115 ihickson 368: individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
369: Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
1.327 ihickson 370: 6 of the W3C Patent Policy</a>.</p>
371:
372:
373: <h2 class="no-num no-toc" id="contents">Table of Contents</h2>
374:
1.318 ihickson 375:
1.115 ihickson 376: <ol class="toc">
377: <li><a href="#introduction"><span class="secno">1 </span>Introduction</a>
1.81 ihickson 378: <ol>
1.115 ihickson 379: <li><a href="#scope"><span class="secno">1.1 </span>Scope</a></li>
1.303 ihickson 380: <li><a href="#examples"><span class="secno">1.2 </span>Examples</a>
1.81 ihickson 381: <ol>
1.115 ihickson 382: <li><a href="#a-background-number-crunching-worker"><span class="secno">1.2.1 </span>A background number-crunching worker</a></li>
1.323 ihickson 383: <li><a href="#worker-used-for-background-i-o"><span class="secno">1.2.2 </span>Worker used for background I/O</a></li>
384: <li><a href="#shared-workers-introduction"><span class="secno">1.2.3 </span>Shared workers introduction</a></li>
385: <li><a href="#shared-state-using-a-shared-worker"><span class="secno">1.2.4 </span>Shared state using a shared worker</a></li>
386: <li><a href="#delegation"><span class="secno">1.2.5 </span>Delegation</a></ol></li>
1.303 ihickson 387: <li><a href="#tutorials"><span class="secno">1.3 </span>Tutorials</a>
388: <ol>
389: <li><a href="#creating-a-dedicated-worker"><span class="secno">1.3.1 </span>Creating a dedicated worker</a></li>
390: <li><a href="#communicating-with-a-dedicated-worker"><span class="secno">1.3.2 </span>Communicating with a dedicated worker</a></li>
391: <li><a href="#shared-workers"><span class="secno">1.3.3 </span>Shared workers</a></ol></ol></li>
1.148 ihickson 392: <li><a href="#conformance-requirements"><span class="secno">2 </span>Conformance requirements</a>
1.82 ihickson 393: <ol>
1.148 ihickson 394: <li><a href="#dependencies"><span class="secno">2.1 </span>Dependencies</a></ol></li>
395: <li><a href="#terminology"><span class="secno">3 </span>Terminology</a></li>
396: <li><a href="#infrastructure"><span class="secno">4 </span>Infrastructure</a>
397: <ol>
1.301 ihickson 398: <li><a href="#dependencies-0"><span class="secno">4.1 </span>Dependencies</a></li>
399: <li><a href="#the-global-scope"><span class="secno">4.2 </span>The global scope</a>
1.81 ihickson 400: <ol>
1.316 ihickson 401: <li><a href="#the-workerglobalscope-common-interface"><span class="secno">4.2.1 </span>The <code>WorkerGlobalScope</code> common interface</a></li>
1.301 ihickson 402: <li><a href="#dedicated-workers-and-the-dedicatedworkerglobalscope-interface"><span class="secno">4.2.2 </span>Dedicated workers and the <code>DedicatedWorkerGlobalScope</code> interface</a></li>
403: <li><a href="#shared-workers-and-the-sharedworkerglobalscope-interface"><span class="secno">4.2.3 </span>Shared workers and the <code>SharedWorkerGlobalScope</code> interface</a></ol></li>
1.339 ihickson 404: <li><a href="#the-event-loop"><span class="secno">4.3 </span>The event loop</a></li>
405: <li><a href="#the-worker-s-lifetime"><span class="secno">4.4 </span>The worker's lifetime</a></li>
406: <li><a href="#processing-model"><span class="secno">4.5 </span>Processing model</a></li>
407: <li><a href="#runtime-script-errors"><span class="secno">4.6 </span>Runtime script errors</a></li>
408: <li><a href="#creating-workers"><span class="secno">4.7 </span>Creating workers</a>
1.81 ihickson 409: <ol>
1.339 ihickson 410: <li><a href="#the-abstractworker-abstract-interface"><span class="secno">4.7.1 </span>The <code>AbstractWorker</code> abstract interface</a></li>
411: <li><a href="#dedicated-workers-and-the-worker-interface"><span class="secno">4.7.2 </span>Dedicated workers and the <code>Worker</code> interface</a></li>
412: <li><a href="#shared-workers-and-the-sharedworker-interface"><span class="secno">4.7.3 </span>Shared workers and the <code>SharedWorker</code> interface</a></ol></ol></li>
1.148 ihickson 413: <li><a href="#apis-available-to-workers"><span class="secno">5 </span>APIs available to workers</a>
1.81 ihickson 414: <ol>
1.148 ihickson 415: <li><a href="#importing-scripts-and-libraries"><span class="secno">5.1 </span>Importing scripts and libraries</a></li>
1.210 ihickson 416: <li><a href="#the-workernavigator-object"><span class="secno">5.2 </span>The <code>WorkerNavigator</code> object</a></li>
1.272 ihickson 417: <li><a href="#interface-objects-and-constructors"><span class="secno">5.3 </span>Interface objects and constructors</a></li>
418: <li><a href="#worker-locations"><span class="secno">5.4 </span>Worker locations</a></ol></li>
1.115 ihickson 419: <li><a class="no-num" href="#references">References</a></li>
420: <li><a class="no-num" href="#acknowledgements">Acknowledgements</a></ol>
1.327 ihickson 421:
422: <hr><h2 id="introduction"><span class="secno">1 </span>Introduction</h2>
423:
424: <h3 id="scope"><span class="secno">1.1 </span>Scope</h3>
425:
426: <p><i>This section is non-normative.</i></p>
427:
428: <p>This specification defines an API for running scripts in the
429: background independently of any user interface scripts.</p>
430:
431: <p>This allows for long-running scripts that are not interrupted by
1.81 ihickson 432: scripts that respond to clicks or other user interactions, and
433: allows long tasks to be executed without yielding to keep the page
1.327 ihickson 434: responsive.</p>
435:
436: <p>Workers (as these background scripts are called herein) are
1.81 ihickson 437: relatively heavy-weight, and are not intended to be used in large
438: numbers. For example, it would be inappropriate to launch one worker
439: for each pixel of a four megapixel image. The examples below show
1.327 ihickson 440: some appropriate uses of workers.</p>
441:
442: <p>Generally, workers are expected to be long-lived, have a high
443: start-up performance cost, and a high per-instance memory cost.</p>
444:
445:
446: <h3 id="examples"><span class="secno">1.2 </span>Examples</h3>
447:
448: <p><i>This section is non-normative.</i></p>
449:
450: <p>There are a variety of uses that workers can be put to. The
451: following subsections show various examples of this use.</p>
452:
453: <h4 id="a-background-number-crunching-worker"><span class="secno">1.2.1 </span>A background number-crunching worker</h4>
454:
455: <p><i>This section is non-normative.</i></p>
456:
457: <p>The simplest use of workers is for performing a computationally
458: expensive task without interrupting the user interface.</p>
459:
460: <p>In this example, the main document spawns a worker to
1.155 ihickson 461: (naïvely) compute prime numbers, and progressively displays the
1.327 ihickson 462: most recently found prime number.</p>
463:
464: <p>The main page is as follows:</p>
465:
466: <pre><!DOCTYPE HTML>
1.81 ihickson 467: <html>
468: <head>
469: <title>Worker example: One-core computation</title>
470: </head>
471: <body>
472: <p>The highest prime number discovered so far is: <output id="result"></output></p>
473: <script>
1.50 ihickson 474: var worker = new Worker('worker.js');
475: worker.onmessage = function (event) {
1.54 ihickson 476: document.getElementById('result').textContent = event.data;
1.29 ihickson 477: };
1.81 ihickson 478: </script>
479: </body>
1.327 ihickson 480: </html></pre>
481:
482: <p>The <code title="dom-Worker"><a href="#dom-worker">Worker()</a></code> constructor call
1.115 ihickson 483: creates a worker and returns a <code><a href="#worker">Worker</a></code> object
1.81 ihickson 484: representing that worker, which is used to communicate with the
1.327 ihickson 485: worker. That object's <code title="handler-Worker-onmessage"><a href="#handler-worker-onmessage">onmessage</a></code> event handler allows the code to receive messages from the worker.</p>
486:
487: <p>The worker itself is as follows:</p>
488:
489: <pre>var n = 1;
1.29 ihickson 490: search: while (true) {
491: n += 1;
492: for (var i = 2; i <= Math.sqrt(n); i += 1)
493: if (n % i == 0)
494: continue search;
495: // found a prime!
1.50 ihickson 496: postMessage(n);
1.327 ihickson 497: }</pre>
498:
499: <p>The bulk of this code is simply an unoptimized search for a prime
1.295 ihickson 500: number. The <code title="dom-DedicatedWorkerGlobalScope-postMessage"><a href="#dom-dedicatedworkerglobalscope-postmessage">postMessage()</a></code>
501: method is used to send a message back to the page when a prime is
1.327 ihickson 502: found.</p>
503:
504: <p><a href="http://www.whatwg.org/demos/workers/primes/page.html">View this example online</a>.</p>
505:
506:
507:
508:
509: <h4 id="worker-used-for-background-i-o"><span class="secno">1.2.2 </span>Worker used for background I/O</h4>
510:
511: <p><i>This section is non-normative.</i></p>
512:
513: <p>In this example, the main document uses two workers, one for
1.81 ihickson 514: fetching stock updates for at regular intervals, and one for
1.327 ihickson 515: fetching performing search queries that the user requests.</p>
516:
517: <p>The main page is as follows:</p>
518:
519: <pre><!DOCTYPE HTML>
1.81 ihickson 520: <html>
521: <head>
522: <title>Worker example: Stock ticker</title>
523: <script>
1.33 ihickson 524: // TICKER
525: var symbol = 'GOOG'; // default symbol to watch
1.50 ihickson 526: var ticker = new Worker('ticker.js');
1.33 ihickson 527:
528: // SEARCHER
1.50 ihickson 529: var searcher = new Worker('searcher.js');
1.33 ihickson 530: function search(query) {
1.50 ihickson 531: searcher.postMessage(query);
1.33 ihickson 532: }
533:
534: // SYMBOL SELECTION UI
535: function select(newSymbol) {
536: symbol = newSymbol;
1.50 ihickson 537: ticker.postMessage(symbol);
1.33 ihickson 538: }
1.81 ihickson 539: </script>
540: </head>
1.122 ihickson 541: <body onload="search('')">
1.81 ihickson 542: <p><output id="symbol"></output> <output id="value"></output></p>
543: <script>
1.50 ihickson 544: ticker.onmessage = function (event) {
1.54 ihickson 545: var data = event.data.split(' ');
1.33 ihickson 546: document.getElementById('symbol').textContent = data[0];
547: document.getElementById('value').textContent = data[1];
548: };
1.50 ihickson 549: ticker.postMessage(symbol);
1.81 ihickson 550: </script>
1.122 ihickson 551: <p><label>Search: <input type="text" autofocus oninput="search(this.value)"></label></p>
1.81 ihickson 552: <ul id="results"></ul>
553: <script>
1.50 ihickson 554: searcher.onmessage = function (event) {
1.54 ihickson 555: var data = event.data.split(' ');
1.33 ihickson 556: var results = document.getElementById('results');
557: while (results.hasChildNodes()) // clear previous results
558: results.removeChild(results.firstChild);
559: for (var i = 0; i < data.length; i += 1) {
560: // add a list item with a button for each result
561: var li = document.createElement('li');
562: var button = document.createElement('button');
563: button.value = data[i];
564: button.type = 'button';
565: button.onclick = function () { select(this.value); };
566: button.textContent = data[i];
567: li.appendChild(button);
568: results.appendChild(li);
569: }
570: };
1.81 ihickson 571: </script>
572: <p>(The data in this example is not real. Try searching for "Google" or "Apple".)</p>
573: </body>
1.327 ihickson 574: </html></pre>
575:
576: <p>The two workers use a common library for performing the actual
577: network calls. This library is as follows:</p>
578:
579: <pre>function get(url) {
1.50 ihickson 580: try {
581: var xhr = new XMLHttpRequest();
582: xhr.open('GET', url, false);
583: xhr.send();
584: return xhr.responseText;
585: } catch (e) {
586: return ''; // turn all errors into empty results
587: }
1.327 ihickson 588: }</pre>
589:
590: <p>The stock updater worker is as follows:</p>
591:
592: <pre>importScripts('io.js');
1.33 ihickson 593: var timer;
594: var symbol;
595: function update() {
1.50 ihickson 596: postMessage(symbol + ' ' + get('stock.cgi?' + symbol));
1.33 ihickson 597: timer = setTimeout(update, 10000);
598: }
1.50 ihickson 599: onmessage = function (event) {
1.33 ihickson 600: if (timer)
601: clearTimeout(timer);
1.54 ihickson 602: symbol = event.data;
1.33 ihickson 603: update();
1.327 ihickson 604: };</pre>
605:
606: <p>The search query worker is as follows:</p>
607:
608: <pre>importScripts('io.js');
1.50 ihickson 609: onmessage = function (event) {
1.54 ihickson 610: postMessage(get('search.cgi?' + event.data));
1.327 ihickson 611: };</pre>
612:
613: <p><a href="http://www.whatwg.org/demos/workers/stocks/page.html">View this example online</a>.</p>
614:
615:
616: <h4 id="shared-workers-introduction"><span class="secno">1.2.3 </span>Shared workers introduction</h4>
617:
618: <p><i>This section is non-normative.</i></p>
619:
620: <p>This section introduces shared workers using a Hello World
1.238 ihickson 621: example. Shared workers use slightly different APIs, since each
1.327 ihickson 622: worker can have multiple connections.</p>
623:
624: <p>This first example shows how you connect to a worker and how a
1.238 ihickson 625: worker can send a message back to the page when it connects to
1.327 ihickson 626: it. Received messages are displayed in a log.</p>
627:
628: <p>Here is the HTML page:</p>
629:
630: <pre><!DOCTYPE HTML>
1.239 ihickson 631: <title>Shared workers: demo 1</title>
632: <pre id="log">Log:</pre>
633: <script>
634: var worker = new SharedWorker('test.js');
635: var log = document.getElementById('log');
636: worker.port.onmessage = function(e) { // note: not worker.onmessage!
637: log.textContent += '\n' + e.data;
638: }
639: </script>
1.327 ihickson 640: </pre>
641:
642: <p>Here is the JavaScript worker:</p>
643:
644: <pre>onconnect = function(e) {
1.239 ihickson 645: var port = e.ports[0];
646: port.postMessage('Hello World!');
647: }
1.327 ihickson 648: </pre>
649:
650: <p><a href="http://www.whatwg.org/demos/workers/shared/001/test.html">View this example online</a>.</p>
651:
652: <hr><p>This second example extends the first one by changing two things:
1.238 ihickson 653: first, messages are received using <code title="">addEventListener()</code> instead of an <span title="event
654: handler IDL attributes">event handler IDL attribute</span>, and
655: second, a message is sent <em>to</em> the worker, causing the worker
656: to send another message in return. Received messages are again
1.327 ihickson 657: displayed in a log.</p>
658:
659: <p>Here is the HTML page:</p>
660:
661: <pre><!DOCTYPE HTML>
1.240 ihickson 662: <title>Shared workers: demo 2</title>
1.239 ihickson 663: <pre id="log">Log:</pre>
664: <script>
665: var worker = new SharedWorker('test.js');
666: var log = document.getElementById('log');
1.240 ihickson 667: worker.port.addEventListener('message', function(e) {
1.239 ihickson 668: log.textContent += '\n' + e.data;
1.240 ihickson 669: }, false);
670: worker.port.start(); // note: need this when using addEventListener
671: worker.port.postMessage('ping');
1.239 ihickson 672: </script>
1.327 ihickson 673: </pre>
674:
675: <p>Here is the JavaScript worker:</p>
676:
677: <pre>onconnect = function(e) {
1.239 ihickson 678: var port = e.ports[0];
679: port.postMessage('Hello World!');
1.240 ihickson 680: port.onmessage = function(e) {
681: port.postMessage('pong'); // not e.ports[0].postMessage!
682: // e.target.postMessage('pong'); would work also
683: }
1.239 ihickson 684: }
1.327 ihickson 685: </pre>
686:
687: <p><a href="http://www.whatwg.org/demos/workers/shared/002/test.html">View this example online</a>.</p>
688:
689: <hr><p>Finally, the example is extended to show how two pages can
1.238 ihickson 690: connect to the same worker; in this case, the second page is merely
691: in an <code>iframe</code> on the first page, but the same principle
692: would apply to an entirely separate page in a separate
1.327 ihickson 693: <span>top-level browsing context</span>.</p>
694:
695: <p>Here is the outer HTML page:</p>
696:
697: <pre><!DOCTYPE HTML>
1.239 ihickson 698: <title>Shared workers: demo 3</title>
699: <pre id="log">Log:</pre>
700: <script>
701: var worker = new SharedWorker('test.js');
702: var log = document.getElementById('log');
703: worker.port.addEventListener('message', function(e) {
704: log.textContent += '\n' + e.data;
705: }, false);
706: worker.port.start();
707: worker.port.postMessage('ping');
708: </script>
709: <iframe src="inner.html"></iframe>
1.327 ihickson 710: </pre>
711:
712: <p>Here is the inner HTML page:</p>
713:
714: <pre><!DOCTYPE HTML>
1.239 ihickson 715: <title>Shared workers: demo 3 inner frame</title>
716: <pre id=log>Inner log:</pre>
717: <script>
718: var worker = new SharedWorker('test.js');
719: var log = document.getElementById('log');
720: worker.port.onmessage = function(e) {
721: log.textContent += '\n' + e.data;
722: }
723: </script>
1.327 ihickson 724: </pre>
725:
726: <p>Here is the JavaScript worker:</p>
727:
728: <pre>var count = 0;
1.239 ihickson 729: onconnect = function(e) {
730: count += 1;
731: var port = e.ports[0];
732: port.postMessage('Hello World! You are connection #' + count);
733: port.onmessage = function(e) {
734: port.postMessage('pong');
735: }
736: }
1.327 ihickson 737: </pre>
738:
739: <p><a href="http://www.whatwg.org/demos/workers/shared/003/test.html">View this example online</a>.</p>
740:
741:
742: <h4 id="shared-state-using-a-shared-worker"><span class="secno">1.2.4 </span>Shared state using a shared worker</h4>
743:
744: <p><i>This section is non-normative.</i></p>
745:
746: <p>In this example, multiple windows (viewers) can be opened that
1.81 ihickson 747: are all viewing the same map. All the windows share the same map
748: information, with a single worker coordinating all the viewers. Each
749: viewer can move around independently, but if they set any data on
1.327 ihickson 750: the map, all the viewers are updated.</p>
751:
752: <p>The main page isn't interesting, it merely provides a way to open
753: the viewers:</p>
754:
755: <pre><!DOCTYPE HTML>
1.81 ihickson 756: <html>
757: <head>
758: <title>Workers example: Multiviewer</title>
759: <script>
1.36 ihickson 760: function openViewer() {
761: window.open('viewer.html');
762: }
1.81 ihickson 763: </script>
764: </head>
765: <body>
766: <p><button type=button onclick="openViewer()">Open a new
767: viewer</button></p>
768: <p>Each viewer opens in a new window. You can have as many viewers
769: as you like, they all view the same data.</p>
770: </body>
1.327 ihickson 771: </html></pre>
772:
773: <p>The viewer is more involved:</p>
774:
775: <pre><!DOCTYPE HTML>
1.81 ihickson 776: <html>
777: <head>
778: <title>Workers example: Multiviewer viewer</title>
779: <script>
1.50 ihickson 780: var worker = new SharedWorker('worker.js', 'core');
1.36 ihickson 781:
782: // CONFIGURATION
783: function configure(event) {
1.54 ihickson 784: if (event.data.substr(0, 4) != 'cfg ') return;
785: var name = event.data.substr(4).split(' ', 1);
1.36 ihickson 786: // update display to mention our name is name
787: document.getElementsByTagName('h1')[0].textContent += ' ' + name;
788: // no longer need this listener
1.43 ihickson 789: worker.port.removeEventListener('message', configure, false);
1.36 ihickson 790: }
1.53 ihickson 791: worker.port.addEventListener('message', configure, false);
1.36 ihickson 792:
793: // MAP
794: function paintMap(event) {
1.54 ihickson 795: if (event.data.substr(0, 4) != 'map ') return;
796: var data = event.data.substr(4).split(',');
1.36 ihickson 797: // display tiles data[0] .. data[8]
798: var canvas = document.getElementById('map');
799: var context = canvas.getContext('2d');
800: for (var y = 0; y < 3; y += 1) {
801: for (var x = 0; x < 3; x += 1) {
802: var tile = data[y * 3 + x];
803: if (tile == '0')
804: context.fillStyle = 'green';
805: else
806: context.fillStyle = 'maroon';
807: fillRect(x * 50, y * 50, 50, 50);
808: }
809: }
810: }
1.53 ihickson 811: worker.port.addEventListener('message', paintMap, false);
1.36 ihickson 812:
813: // PUBLIC CHAT
814: function updatePublicChat(event) {
1.54 ihickson 815: if (event.data.substr(0, 4) != 'txt ') return;
816: var name = event.data.substr(4).split(' ', 1);
817: var message = event.data.substr(4 + length(name) + 1);
1.81 ihickson 818: // display "<name> message" in public chat
1.36 ihickson 819: var dialog = document.getElementById('public');
820: var dt = document.createElement('dt');
821: dt.textContent = name;
822: dialog.appendChild(dt);
823: var dd = document.createElement('dd');
824: dd.textContent = message;
825: dialog.appendChild(dd);
826: }
1.53 ihickson 827: worker.port.addEventListener('message', updatePublicChat, false);
1.36 ihickson 828:
829: // PRIVATE CHAT
830: function startPrivateChat(event) {
1.54 ihickson 831: if (event.data.substr(0, 4) != 'msg ') return;
832: var name = event.data.substr(4).split(' ', 1);
1.84 ihickson 833: var port = event.ports[0];
1.36 ihickson 834: // display a private chat UI
835: var ul = document.getElementById('private');
836: var li = document.createElement('li');
837: var h3 = document.createElement('h3');
838: h3.textContent = 'Private chat with ' + name;
839: li.appendChild(h3);
840: var dialog = document.createElement('dialog');
841: var addMessage = function(name, message) {
842: var dt = document.createElement('dt');
843: dt.textContent = name;
844: dialog.appendChild(dt);
845: var dd = document.createElement('dd');
846: dd.textContent = message;
847: dialog.appendChild(dd);
848: };
849: port.onmessage = function (event) {
1.54 ihickson 850: addMessage(name, event.data);
1.36 ihickson 851: };
852: li.appendChild(dialog);
853: var form = document.createElement('form');
854: var p = document.createElement('p');
855: var input = document.createElement('input');
856: input.size = 50;
857: p.appendChild(input);
858: p.appendChild(document.createTextNode(' '));
859: var button = document.createElement('button');
860: button.textContent = 'Post';
861: p.appendChild(button);
862: form.onsubmit = function () {
863: port.postMessage(input.value);
864: addMessage('me', input.value);
865: input.value = '';
866: return false;
867: };
868: form.appendChild(p);
869: li.appendChild(form);
870: }
1.53 ihickson 871: worker.port.addEventListener('message', startPrivateChat, false);
1.188 ihickson 872:
873: worker.port.start();
1.81 ihickson 874: </script>
875: </head>
876: <body>
877: <h1>Viewer</h1>
878: <h2>Map</h2>
879: <p><canvas id="map" height=150 width=150></canvas></p>
880: <p>
881: <button type=button onclick="worker.port.postMessage('mov left')">Left</button>
882: <button type=button onclick="worker.port.postMessage('mov up')">Up</button>
883: <button type=button onclick="worker.port.postMessage('mov down')">Down</button>
884: <button type=button onclick="worker.port.postMessage('mov right')">Right</button>
885: <button type=button onclick="worker.port.postMessage('set 0')">Set 0</button>
886: <button type=button onclick="worker.port.postMessage('set 1')">Set 1</button>
887: </p>
888: <h2>Public Chat</h2>
889: <dialog id="public"></dialog>
890: <form onsubmit="worker.port.postMessage('txt ' + message.value); message.value = ''; return false;">
891: <p>
892: <input type="text" name="message" size="50">
893: <button>Post</button>
894: </p>
895: </form>
896: <h2>Private Chat</h2>
897: <ul id="private"></ul>
898: </body>
899: </html>
1.327 ihickson 900: </pre>
901:
902: <p>There are several key things worth noting about the way the
903: viewer is written.</p>
904:
905: <p><strong>Multiple listeners</strong>. Instead of a single message
1.81 ihickson 906: processing function, the code here attaches multiple event
907: listeners, each one performing a quick check to see if it is
908: relevant for the message. In this example it doesn't make much
909: difference, but if multiple authors wanted to collaborate using a
910: single port to communicate with a worker, it would allow for
911: independent code instead of changes having to all be made to a
1.327 ihickson 912: single event handling function.</p>
913:
914: <p>Registering event listeners in this way also allows you to
1.81 ihickson 915: unregister specific listeners when you are done with them, as is
916: done with the <code title="">configure()</code> method in this
1.327 ihickson 917: example.</p>
918:
919: <p>Finally, the worker:</p>
920:
921: <pre>
1.155 ihickson 922: var nextName = 0;
1.36 ihickson 923: function getNextName() {
924: // this could use more friendly names
925: // but for now just return a number
926: return nextName++;
927: }
928:
929: var map = [
930: [0, 0, 0, 0, 0, 0, 0],
931: [1, 1, 0, 1, 0, 1, 1],
932: [0, 1, 0, 1, 0, 0, 0],
933: [0, 1, 0, 1, 0, 1, 1],
934: [0, 0, 0, 1, 0, 0, 0],
935: [1, 0, 0, 1, 1, 1, 1],
936: [1, 1, 0, 1, 1, 0, 1],
937: ];
938:
939: function wrapX(x) {
940: if (x < 0) return wrapX(x + map[0].length);
1.81 ihickson 941: if (x >= map[0].length) return wrapX(x - map[0].length);
1.36 ihickson 942: return x;
943: }
944:
945: function wrapY(y) {
946: if (y < 0) return wrapY(y + map.length);
1.81 ihickson 947: if (y >= map[0].length) return wrapY(y - map.length);
1.36 ihickson 948: return y;
949: }
950:
1.50 ihickson 951: function sendMapData(callback) {
1.36 ihickson 952: var data = '';
953: for (var y = viewer.y-1; y <= viewer.y+1; y += 1) {
954: for (var x = viewer.x-1; x <= viewer.x+1; x += 1) {
955: if (data != '')
956: data += ',';
957: data += map[y][x];
958: }
959: }
1.50 ihickson 960: callback('map ' + data);
1.36 ihickson 961: }
962:
963: var viewers = {};
964: onconnect = function (event) {
1.84 ihickson 965: event.ports[0]._name = getNextName();
966: event.ports[0]._data = { port: event.port, x: 0, y: 0, };
967: viewers[event.ports[0]._name] = event.port._data;
968: event.ports[0].postMessage('cfg ' + name);
969: event.ports[0].onmessage = getMessage;
970: sendMapData(event.ports[0].postMessage);
1.36 ihickson 971: };
972:
973: function getMessage(event) {
1.54 ihickson 974: switch (event.data.substr(0, 4)) {
1.36 ihickson 975: case 'mov ':
1.54 ihickson 976: var direction = event.data.substr(4);
1.36 ihickson 977: var dx = 0;
978: var dy = 0;
979: switch (direction) {
980: case 'up': dy = -1; break;
981: case 'down': dy = 1; break;
982: case 'left': dx = -1; break;
983: case 'right': dx = 1; break;
984: }
985: event.target._data.x = wrapX(event.target._data.x + dx);
986: event.target._data.y = wrapY(event.target._data.y + dy);
1.50 ihickson 987: sendMapData(event.target.postMessage);
1.36 ihickson 988: break;
989: case 'set ':
1.54 ihickson 990: var value = event.data.substr(4);
1.36 ihickson 991: map[event.target._data.y][event.target._data.x] = value;
992: for (var viewer in viewers)
1.50 ihickson 993: sendMapData(viewers[viewer].port.postMessage);
1.36 ihickson 994: break;
995: case 'txt ':
996: var name = event.target._name;
1.54 ihickson 997: var message = event.data.substr(4);
1.36 ihickson 998: for (var viewer in viewers)
999: viewers[viewer].port.postMessage('txt ' + name + ' ' + message);
1000: break;
1001: case 'msg ':
1002: var party1 = event._data;
1.54 ihickson 1003: var party2 = viewers[event.data.substr(4).split(' ', 1)];
1.36 ihickson 1004: if (party2) {
1005: var channel = new MessageChannel();
1.84 ihickson 1006: party1.port.postMessage('msg ' + party2.name, [channel.port1]);
1007: party2.port.postMessage('msg ' + party1.name, [channel.port2]);
1.36 ihickson 1008: }
1009: break;
1010: }
1.327 ihickson 1011: }</pre>
1012:
1013: <p><strong>Connecting to multiple pages</strong>. The script uses
1.115 ihickson 1014: the <code title="handler-SharedWorkerGlobalScope-onconnect"><a href="#handler-sharedworkerglobalscope-onconnect">onconnect</a></code>
1.327 ihickson 1015: event listener to listen for multiple connections.</p>
1016:
1017: <p><strong>Direct channels</strong>. When the worker receives a
1.81 ihickson 1018: "msg" message from one viewer naming another viewer, it sets up a
1019: direct connection between the two, so that the two viewers can
1020: communicate directly without the worker having to proxy all the
1.327 ihickson 1021: messages.</p>
1022:
1023: <p><a href="http://www.whatwg.org/demos/workers/multiviewer/page.html">View this example online</a>.</p>
1024:
1025:
1026: <h4 id="delegation"><span class="secno">1.2.5 </span>Delegation</h4>
1027:
1028: <p><i>This section is non-normative.</i></p>
1029:
1030: <p>With multicore CPUs becoming prevalent, one way to obtain better
1.81 ihickson 1031: performance is to split computationally expensive tasks amongst
1032: multiple workers. In this example, a computationally expensive task
1033: that is to be performed for every number from 1 to 10,000,000 is
1.327 ihickson 1034: farmed out to ten subworkers.</p>
1035:
1036: <p>The main page is as follows, it just reports the result:</p>
1037:
1038: <pre><!DOCTYPE HTML>
1.81 ihickson 1039: <html>
1040: <head>
1.203 ihickson 1041: <title>Worker example: Multicore computation</title>
1.81 ihickson 1042: </head>
1043: <body>
1.203 ihickson 1044: <p>Result: <output id="result"></output></p>
1.81 ihickson 1045: <script>
1.50 ihickson 1046: var worker = new Worker('worker.js');
1047: worker.onmessage = function (event) {
1.54 ihickson 1048: document.getElementById('result').textContent = event.data;
1.40 ihickson 1049: };
1.81 ihickson 1050: </script>
1051: </body>
1.327 ihickson 1052: </html></pre>
1053:
1054: <p>The worker itself is as follows:</p>
1055:
1056: <pre>// settings
1.40 ihickson 1057: var num_workers = 10;
1058: var items_per_worker = 1000000;
1059:
1060: // start the workers
1061: var result = 0;
1062: var pending_workers = num_workers;
1063: for (var i = 0; i < num_workers; i += 1) {
1.50 ihickson 1064: var worker = new Worker('core.js');
1065: worker.postMessage(i * items_per_worker);
1066: worker.postMessage((i+1) * items_per_worker);
1067: worker.onmessage = storeResult;
1.40 ihickson 1068: }
1069:
1070: // handle the results
1071: function storeResult(event) {
1.54 ihickson 1072: result += 1*event.data;
1.40 ihickson 1073: pending_workers -= 1;
1074: if (pending_workers <= 0)
1.50 ihickson 1075: postMessage(result); // finished!
1.327 ihickson 1076: }</pre>
1077:
1078: <p>It consists of a loop to start the subworkers, and then a handler
1079: that waits for all the subworkers to respond.</p>
1080:
1081: <p>The subworkers are implemented as follows:</p>
1082:
1083: <pre>var start;
1.41 ihickson 1084: onmessage = getStart;
1.40 ihickson 1085: function getStart(event) {
1.54 ihickson 1086: start = 1*event.data;
1.40 ihickson 1087: onmessage = getEnd;
1088: }
1089:
1090: var end;
1091: function getEnd(event) {
1.54 ihickson 1092: end = 1*event.data;
1.40 ihickson 1093: onmessage = null;
1.66 ihickson 1094: work();
1.40 ihickson 1095: }
1096:
1.66 ihickson 1097: function work() {
1.40 ihickson 1098: var result = 0;
1099: for (var i = start; i < end; i += 1) {
1100: // perform some complex calculation here
1101: result += 1;
1102: }
1.50 ihickson 1103: postMessage(result);
1104: close();
1.327 ihickson 1105: }</pre>
1106:
1107: <p>They receive two numbers in two events, perform the computation
1.81 ihickson 1108: for the range of numbers thus specified, and then report the result
1.327 ihickson 1109: back to the parent.</p>
1110:
1111: <p><a href="http://www.whatwg.org/demos/workers/multicore/page.html">View this example online</a>.</p>
1112:
1113:
1114:
1115:
1116: <h3 id="tutorials"><span class="secno">1.3 </span>Tutorials</h3>
1117:
1118: <h4 id="creating-a-dedicated-worker"><span class="secno">1.3.1 </span>Creating a dedicated worker</h4>
1119:
1120: <p><i>This section is non-normative.</i></p>
1121:
1122: <p>Creating a worker requires a URL to a JavaScript file. The <code title="dom-Worker"><a href="#dom-worker">Worker()</a></code> constructor is invoked with the
1.303 ihickson 1123: URL to that file as its only argument; a worker is then created and
1.327 ihickson 1124: returned:</p>
1125:
1126: <pre>var worker = new Worker('helper.js');</pre>
1127:
1128:
1129: <h4 id="communicating-with-a-dedicated-worker"><span class="secno">1.3.2 </span>Communicating with a dedicated worker</h4>
1130:
1131: <p><i>This section is non-normative.</i></p>
1132:
1133: <p>Dedicated workers use <code><a href="#messageport">MessagePort</a></code> objects behind the
1.303 ihickson 1134: scenes, and thus support all the same features, such as sending
1135: structured data, transferring binary data, and transferring other
1.327 ihickson 1136: ports.</p>
1137:
1138: <p>To receive messages from a dedicated worker, use the <code title="handler-worker-onmessage"><a href="#handler-worker-onmessage">onmessage</a></code> <span title="event
1.303 ihickson 1139: handler IDL attributes">event handler IDL attribute</span> on the
1.327 ihickson 1140: <code><a href="#worker">Worker</a></code> object:</p>
1141:
1142: <pre>worker.onmessage = function (event) { ... };</pre>
1143:
1144: <p>You can also use the <code title="dom-EventTarget-addEventListener">addEventListener()</code> method.</p>
1145:
1146: <p class="note">The implicit <code><a href="#messageport">MessagePort</a></code> used by
1.303 ihickson 1147: dedicated workers has its <span>port message queue</span> implicitly
1.336 ihickson 1148: enabled when it is created, so there is no equivalent to the
1.303 ihickson 1149: <code><a href="#messageport">MessagePort</a></code> interface's <code title="dom-MessagePort-start">start()</code> method on the
1.327 ihickson 1150: <code><a href="#worker">Worker</a></code> interface.</p>
1151:
1152: <p>To <em>send</em> data to a worker, use the <code title="dom-Worker-postMessage"><a href="#dom-worker-postmessage">postMessage()</a></code> method.
1.303 ihickson 1153: Structured data can be sent over this communication channel. To send
1154: <code>ArrayBuffer</code> objects efficiently (by transferring them
1155: rather than cloning them), list them in an array in the second
1.327 ihickson 1156: argument.</p>
1157:
1158: <pre>worker.postMessage({
1.303 ihickson 1159: operation: 'find-edges',
1160: input: buffer, // an ArrayBuffer object
1161: threshold: 0.6,
1.327 ihickson 1162: }, [buffer]);</pre>
1163:
1164: <p>To receive a message inside the worker, the <code title="handler-DedicatedWorkerGlobalScope-onmessage"><a href="#handler-dedicatedworkerglobalscope-onmessage">onmessage</a></code>
1.303 ihickson 1165: <span title="event handler IDL attributes">event handler IDL
1.327 ihickson 1166: attribute</span> is used.</p>
1167:
1168: <pre>onmessage = function (event) { ... };</pre>
1169:
1170: <p>You can again also use the <code title="dom-EventTarget-addEventListener">addEventListener()</code>
1171: method.</p>
1172:
1173: <p>In either case, the data is provided in the event object's <code title="dom-MessageEvent-data">data</code> attribute.</p>
1174:
1175: <p>To send messages back, you again use <code title="dom-DedicatedWorkerGlobalScope-postMessage"><a href="#dom-dedicatedworkerglobalscope-postmessage">postMessage()</a></code>.
1176: It supports the structured data in the same manner.</p>
1177:
1178: <pre>postMessage(event.data.input, [event.data.input]); // transfer the buffer back</pre>
1179:
1180:
1181: <h4 id="shared-workers"><span class="secno">1.3.3 </span>Shared workers</h4>
1182:
1183: <p><i>This section is non-normative.</i></p>
1184:
1185: <p>Shared workers are identified in one of two ways: either by the
1.303 ihickson 1186: URL of the script used to create it, or by explicit name. When
1187: created by name, the URL used by the first page to create the worker
1188: with that name is the URL of the script that will be used for that
1189: worker. This allows multiple applications on a domain to all use a
1190: single shared worker to provide a common service, without the
1191: applications having to keep track of a common URL for the script
1.327 ihickson 1192: used to provide the service.</p>
1193:
1194: <p class="note">In either case, shared workers are scoped by
1.303 ihickson 1195: <span>origin</span>. Two different sites using the same names will
1.327 ihickson 1196: not collide.</p>
1197:
1198: <p>Creating shared workers is done using the <code title="dom-SharedWorker"><a href="#dom-sharedworker">SharedWorker()</a></code> constructor. This
1.303 ihickson 1199: constructor takes the URL to the script to use for its first
1200: argument, and the name of the worker, if any, as the second
1.327 ihickson 1201: argument.</p>
1202:
1203: <pre>var worker = new SharedWorker('service.js');</pre>
1204:
1205: <p>Communicating with shared workers is done with explicit
1.303 ihickson 1206: <code><a href="#messageport">MessagePort</a></code> objects. The object returned by the <code title="dom-SharedWorker"><a href="#dom-sharedworker">SharedWorker()</a></code> constructor holds a
1.327 ihickson 1207: reference to the port on its <code title="dom-SharedWorker-port"><a href="#dom-sharedworker-port">port</a></code> attribute.</p>
1208:
1209: <pre>worker.port.onmessage = function (event) { ... };
1.303 ihickson 1210: worker.port.postMessage('some message');
1.327 ihickson 1211: worker.port.postMessage({ foo: 'structured', bar: ['data', 'also', 'possible']});</pre>
1212:
1213: <p>Inside the shared worker, new clients of the worker are announced
1.303 ihickson 1214: using the <code title="event-connect">connect</code> event. The port
1.330 ihickson 1215: for the new client is given by the event object's <code title="dom-messageevent-source">source</code> attribute.</p>
1.327 ihickson 1216:
1217: <pre>onconnect = function (event) {
1.330 ihickson 1218: var newPort = event.source;
1.303 ihickson 1219: // set up a listener
1220: newPort.onmessage = function (event) { ... };
1221: // send a message back to the port
1222: newPort.postMessage('ready!'); // can also send structured data, of course
1.327 ihickson 1223: };</pre>
1224:
1225:
1226:
1227:
1228:
1229:
1230: <h2 id="conformance-requirements"><span class="secno">2 </span>Conformance requirements</h2>
1231:
1232: <p>All diagrams, examples, and notes in this specification are
1.81 ihickson 1233: non-normative, as are all sections explicitly marked non-normative.
1.327 ihickson 1234: Everything else in this specification is normative.</p>
1235:
1236: <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
1.81 ihickson 1237: "OPTIONAL" in the normative parts of this document are to be
1238: interpreted as described in RFC2119. For readability, these words do
1.327 ihickson 1239: not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
1240:
1241: <p>Requirements phrased in the imperative as part of algorithms
1.81 ihickson 1242: (such as "strip any leading space characters" or "return false and
1243: abort these steps") are to be interpreted with the meaning of the
1244: key word ("must", "should", "may", etc) used in introducing the
1.327 ihickson 1245: algorithm.</p>
1246:
1247: <p>Some conformance requirements are phrased as requirements on
1.81 ihickson 1248: attributes, methods or objects. Such requirements are to be
1.327 ihickson 1249: interpreted as requirements on user agents.</p>
1250:
1251: <p>Conformance requirements phrased as algorithms or specific steps
1.81 ihickson 1252: may be implemented in any manner, so long as the end result is
1253: equivalent. (In particular, the algorithms defined in this
1254: specification are intended to be easy to follow, and not intended to
1.327 ihickson 1255: be performant.)</p>
1256:
1257: <p>The only conformance class defined by this specification is user
1258: agents.</p>
1259:
1260: <p>User agents may impose implementation-specific limits on
1.81 ihickson 1261: otherwise unconstrained inputs, e.g. to prevent denial of service
1262: attacks, to guard against running out of memory, or to work around
1.327 ihickson 1263: platform-specific limitations.</p>
1264:
1265: <p>When support for a feature is disabled (e.g. as an emergency
1.229 ihickson 1266: measure to mitigate a security problem, or to aid in development, or
1267: for performance reasons), user agents must act as if they had no
1268: support for the feature whatsoever, and as if the feature was not
1269: mentioned in this specification. For example, if a particular
1270: feature is accessed via an attribute in a Web IDL interface, the
1271: attribute itself would be omitted from the objects that implement
1272: that interface — leaving the attribute on the object but
1.327 ihickson 1273: making it return null or throw an exception is insufficient.</p>
1274:
1275:
1276: <h3 id="dependencies"><span class="secno">2.1 </span>Dependencies</h3>
1277:
1278: <p>This specification relies on several other underlying
1279: specifications.</p>
1280:
1281: <dl><dt>HTML</dt>
1.49 ihickson 1282:
1.81 ihickson 1283: <dd>
1.49 ihickson 1284:
1.226 ihickson 1285: <p>Many fundamental concepts from HTML are used by this
1286: specification. <a href="#refsHTML">[HTML]</a></p>
1.49 ihickson 1287:
1.81 ihickson 1288: </dd>
1.1 ihickson 1289:
1.81 ihickson 1290: <dt>WebIDL</dt>
1.1 ihickson 1291:
1292: <dd>
1293:
1.81 ihickson 1294: <p>The IDL blocks in this specification use the semantics of the
1.153 ihickson 1295: WebIDL specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
1.1 ihickson 1296:
1.81 ihickson 1297: </dd>
1.1 ihickson 1298:
1.327 ihickson 1299: </dl><h2 id="terminology"><span class="secno">3 </span>Terminology</h2>
1300:
1301: <p>The construction "a <code title="">Foo</code> object", where
1.81 ihickson 1302: <code title="">Foo</code> is actually an interface, is sometimes
1303: used instead of the more accurate "an object implementing the
1.327 ihickson 1304: interface <code title="">Foo</code>".</p>
1305:
1306: <p>The term DOM is used to refer to the API set made available to
1.81 ihickson 1307: scripts in Web applications, and does not necessarily imply the
1308: existence of an actual <code>Document</code> object or of any other
1309: <code>Node</code> objects as defined in the DOM Core
1.327 ihickson 1310: specifications. <a href="#refsDOMCORE">[DOMCORE]</a></p>
1311:
1312: <p>An IDL attribute is said to be <em>getting</em> when its value is
1.81 ihickson 1313: being retrieved (e.g. by author script), and is said to be
1.327 ihickson 1314: <em>setting</em> when a new value is assigned to it.</p>
1315:
1316:
1317: <p>The term "JavaScript" is used to refer to ECMA262, rather than
1.103 ihickson 1318: the official term ECMAScript, since the term JavaScript is more
1.327 ihickson 1319: widely known. <a href="#refsECMA262">[ECMA262]</a></p>
1320:
1321:
1322:
1323: <h2 id="infrastructure"><span class="secno">4 </span>Infrastructure</h2>
1324:
1325: <p>There are two kinds of workers; dedicated workers, and shared
1.81 ihickson 1326: workers. Dedicated workers, once created, and are linked to their
1327: creator; but message ports can be used to communicate from a
1328: dedicated worker to multiple other browsing contexts or
1329: workers. Shared workers, on the other hand, are named, and once
1330: created any script running in the same <span>origin</span> can
1.327 ihickson 1331: obtain a reference to that worker and communicate with it.</p>
1332:
1333:
1334: <h3 id="dependencies-0"><span class="secno">4.1 </span>Dependencies</h3>
1335: <p>The <dfn id="messageport"><code>MessagePort</code></dfn> interface is defined in
1336: the HTML specification. <a href="#refsHTML">[HTML]</a></p>
1337:
1338:
1339:
1340: <h3 id="the-global-scope"><span class="secno">4.2 </span>The global scope</h3>
1341:
1342: <p>The global scope is the "inside" of a worker.</p>
1343:
1344: <h4 id="the-workerglobalscope-common-interface"><span class="secno">4.2.1 </span>The <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> common interface</h4>
1345:
1346: <pre class="idl">interface <dfn id="workerglobalscope">WorkerGlobalScope</dfn> : <span>EventTarget</span> {
1.115 ihickson 1347: readonly attribute <a href="#workerglobalscope">WorkerGlobalScope</a> <a href="#dom-workerglobalscope-self" title="dom-WorkerGlobalScope-self">self</a>;
1348: readonly attribute <a href="#workerlocation">WorkerLocation</a> <a href="#dom-workerglobalscope-location" title="dom-WorkerGlobalScope-location">location</a>;
1349:
1350: void <a href="#dom-workerglobalscope-close" title="dom-WorkerGlobalScope-close">close</a>();
1.332 ihickson 1351: attribute <span>EventHandler</span> <a href="#handler-workerglobalscope-onerror" title="handler-WorkerGlobalScope-onerror">onerror</a>;
1352: attribute <span>EventHandler</span> <a href="#handler-workerglobalscope-onoffline" title="handler-WorkerGlobalScope-onoffline">onoffline</a>;
1353: attribute <span>EventHandler</span> <a href="#handler-workerglobalscope-ononline" title="handler-WorkerGlobalScope-ononline">ononline</a>;
1.150 ihickson 1354: };
1.327 ihickson 1355: <a href="#workerglobalscope">WorkerGlobalScope</a> implements <a href="#workerutils">WorkerUtils</a>;</pre>
1356:
1357: <p>The <dfn id="dom-workerglobalscope-self" title="dom-WorkerGlobalScope-self"><code>self</code></dfn> attribute
1358: must return the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object itself.</p>
1359:
1360: <p>The <dfn id="dom-workerglobalscope-location" title="dom-WorkerGlobalScope-location"><code>location</code></dfn>
1.115 ihickson 1361: attribute must return the <code><a href="#workerlocation">WorkerLocation</a></code> object created
1362: for the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object when the worker was
1.81 ihickson 1363: created. It represents the <span>absolute URL</span> of the script
1.327 ihickson 1364: that was used to initialize the worker, after any redirects.</p>
1365:
1366: <hr><p>When a script invokes the <dfn id="dom-workerglobalscope-close" title="dom-WorkerGlobalScope-close"><code>close()</code></dfn>
1.123 ihickson 1367: method on a <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object, the user agent
1.327 ihickson 1368: must run the following steps (atomically):</p>
1369:
1370: <ol><li><p>Discard any <span title="concept-task">tasks</span> that
1.123 ihickson 1371: have been added to the <span>event loop</span>'s <span title="task
1372: queue">task queues</span>.</p>
1373:
1.81 ihickson 1374:
1.318 ihickson 1375:
1.115 ihickson 1376: <li><p>Set the worker's <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object's
1377: <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag to
1.123 ihickson 1378: true. (This prevents any further tasks from being queued.)</li>
1.81 ihickson 1379:
1.339 ihickson 1380: </ol><hr><p>The following are the <span>event handlers</span> (and their
1.177 ihickson 1381: corresponding <span title="event handler event type">event handler
1382: event types</span>) that must be supported, as IDL attributes, by
1383: objects implementing the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
1.327 ihickson 1384: interface:</p>
1385:
1386: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.281 ihickson 1387: <tbody><tr><td><dfn id="handler-workerglobalscope-onerror" title="handler-WorkerGlobalScope-onerror"><code>onerror</code></dfn> <td> <code title="event-error">error</code>
1.289 ihickson 1388: <tr><td><dfn id="handler-workerglobalscope-onoffline" title="handler-WorkerGlobalScope-onoffline"><code>onoffline</code></dfn> <td> <code title="event-offline">offline</code>
1389: <tr><td><dfn id="handler-workerglobalscope-ononline" title="handler-WorkerGlobalScope-ononline"><code>ononline</code></dfn> <td> <code title="event-online">online</code>
1.339 ihickson 1390: </table><hr><p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object has a <dfn id="worker-origin">worker
1391: origin</dfn> that is set when the object is created.</p>
1392:
1393: <p class="note">For <span title="data protocol"><code title="">data:</code> URLs</span>, this is the <span>origin</span>
1394: of the <span>entry script</span> that called the constructor. For
1395: other <span title="URL">URLs</span>, this is the <span>origin</span>
1396: of the value of the <span>absolute URL</span> given in the worker's
1397: <code title="dom-WorkerGlobalScope-location"><a href="#dom-workerglobalscope-location"></a></code> attribute.</p>
1398:
1399:
1400:
1401: <h4 id="dedicated-workers-and-the-dedicatedworkerglobalscope-interface"><span class="secno">4.2.2 </span>Dedicated workers and the <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> interface</h4>
1.327 ihickson 1402:
1403: <pre class="idl">interface <dfn id="dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</dfn> : <a href="#workerglobalscope">WorkerGlobalScope</a> {
1.318 ihickson 1404: void <a href="#dom-dedicatedworkerglobalscope-postmessage" title="dom-DedicatedWorkerGlobalScope-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer);
1.332 ihickson 1405: attribute <span>EventHandler</span> <a href="#handler-dedicatedworkerglobalscope-onmessage" title="handler-DedicatedWorkerGlobalScope-onmessage">onmessage</a>;
1.327 ihickson 1406: };</pre>
1407:
1.338 ihickson 1408: <p>The <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> interface must only
1409: be <span title="expose">exposed</span> if the <span>JavaScript
1410: global environment</span> is a <span>dedicated worker
1411: environment</span>.</p>
1.327 ihickson 1412:
1413: <p><code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> objects act as if they
1.301 ihickson 1414: had an implicit <code><a href="#messageport">MessagePort</a></code> associated with them. This
1.81 ihickson 1415: port is part of a channel that is set up when the worker is created,
1416: but it is not exposed. This object must never be garbage collected
1.327 ihickson 1417: before the <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> object.</p>
1418:
1419: <p>All messages received by that port must immediately be retargeted
1420: at the <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> object.</p>
1421:
1422: <p>The <dfn id="dom-dedicatedworkerglobalscope-postmessage" title="dom-DedicatedWorkerGlobalScope-postMessage"><code>postMessage()</code></dfn>
1.318 ihickson 1423: method on
1.115 ihickson 1424: <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> objects must act as if, when
1.281 ihickson 1425: invoked, it immediately invoked the
1.81 ihickson 1426: method of the same name on the port, with the same arguments, and
1.327 ihickson 1427: returned the same return value.</p>
1428:
1429: <p>The following are the <span>event handlers</span> (and their
1.177 ihickson 1430: corresponding <span title="event handler event type">event handler
1431: event types</span>) that must be supported, as IDL attributes, by
1432: objects implementing the <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code>
1.327 ihickson 1433: interface:</p>
1434:
1435: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.155 ihickson 1436: <tbody><tr><td><dfn id="handler-dedicatedworkerglobalscope-onmessage" title="handler-DedicatedWorkerGlobalScope-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message">message</code>
1.191 ihickson 1437: </table><p>For the purposes of the <span>application cache</span> networking
1438: model, a dedicated worker is an extension of the <span>cache
1.327 ihickson 1439: host</span> from which it was created.</p>
1440:
1441:
1442:
1443: <h4 id="shared-workers-and-the-sharedworkerglobalscope-interface"><span class="secno">4.2.3 </span>Shared workers and the <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> interface</h4>
1444:
1445: <pre class="idl">interface <dfn id="sharedworkerglobalscope">SharedWorkerGlobalScope</dfn> : <a href="#workerglobalscope">WorkerGlobalScope</a> {
1.115 ihickson 1446: readonly attribute DOMString <a href="#dom-sharedworkerglobalscope-name" title="dom-SharedWorkerGlobalScope-name">name</a>;
1.181 ihickson 1447: readonly attribute <span>ApplicationCache</span> <span title="dom-SharedWorkerGlobalScope-applicationCache">applicationCache</span>;
1.332 ihickson 1448: attribute <span>EventHandler</span> <a href="#handler-sharedworkerglobalscope-onconnect" title="handler-SharedWorkerGlobalScope-onconnect">onconnect</a>;
1.327 ihickson 1449: };</pre>
1450:
1.338 ihickson 1451: <p>The <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> interface must only be
1452: <span title="expose">exposed</span> if the <span>JavaScript global
1453: environment</span> is a <span>shared worker environment</span>.</p>
1.327 ihickson 1454:
1455: <p>Shared workers receive message ports through <code title="event-WorkerGlobalScope-connect">connect</code> events on
1456: their global object for each connection.</p>
1457:
1458: <p>The <dfn id="dom-sharedworkerglobalscope-name" title="dom-SharedWorkerGlobalScope-name"><code>name</code></dfn>
1.81 ihickson 1459: attribute must return the value it was assigned when the
1.115 ihickson 1460: <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object was created by the
1461: "<a href="#run-a-worker">run a worker</a>" algorithm. Its value represents the name
1.81 ihickson 1462: that can be used to obtain a reference to the worker using the
1.327 ihickson 1463: <code><a href="#sharedworker">SharedWorker</a></code> constructor.</p>
1464:
1465: <p>The following are the <span>event handlers</span> (and their
1.177 ihickson 1466: corresponding <span title="event handler event type">event handler
1467: event types</span>) that must be supported, as IDL attributes, by
1468: objects implementing the <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code>
1.327 ihickson 1469: interface:</p>
1470:
1471: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.155 ihickson 1472: <tbody><tr><td><dfn id="handler-sharedworkerglobalscope-onconnect" title="handler-SharedWorkerGlobalScope-onconnect"><code>onconnect</code></dfn> <td> <code title="event-connect">connect</code>
1.191 ihickson 1473: </table><p>For the purposes of the <span>application cache</span> networking
1474: model, a shared worker is its own <span>cache host</span>. The
1475: <a href="#run-a-worker">run a worker</a> algorithm takes care of associating the
1.327 ihickson 1476: worker with an <span>application cache</span>.</p>
1477:
1478: <p class="note">The <code title="dom-SharedWorkerGlobalScope-applicationCache">applicationCache</code>
1.123 ihickson 1479: attribute returns the <code>ApplicationCache</code> object for the
1.327 ihickson 1480: worker.</p>
1481:
1482:
1.334 ihickson 1483:
1.339 ihickson 1484: <h3 id="the-event-loop"><span class="secno">4.3 </span>The event loop</h3>
1.327 ihickson 1485:
1486: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object has an <span>event
1.128 ihickson 1487: loop</span> distinct from those defined for <span title="unit of
1488: related similar-origin browsing contexts">units of related
1489: similar-origin browsing contexts</span>. This <span>event
1490: loop</span> has no associated <span>browsing context</span>, and its
1491: <span title="task queue">task queues</span> only have events,
1492: callbacks, and networking activity as <span title="concept-task">tasks</span>. The processing model of these
1493: <span title="event loop">event loops</span> is defined below in the
1.327 ihickson 1494: <a href="#run-a-worker">run a worker</a> algorithm.</p>
1495:
1496: <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 1497: initially be false, but which can get set to true by the algorithms
1.327 ihickson 1498: in the processing model section below.</p>
1499:
1500: <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 1501: true, the <span>event loop</span>'s <span title="task queue">task
1.115 ihickson 1502: queues</span> must discard any further <span title="concept-task">tasks</span> that would be added to them (tasks
1.175 ihickson 1503: already on the queue are unaffected except where otherwise
1.115 ihickson 1504: specified). Effectively, once the <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag is true,
1.81 ihickson 1505: timers stop firing, notifications for all pending asynchronous
1.327 ihickson 1506: operations are dropped, etc.</p>
1507:
1508:
1509:
1.339 ihickson 1510: <h3 id="the-worker-s-lifetime"><span class="secno">4.4 </span>The worker's lifetime</h3>
1.327 ihickson 1511:
1512: <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
1513: <code><a href="#messageport">MessagePort</a></code> objects.</p>
1514:
1515: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> <var title="">worker global
1.124 ihickson 1516: scope</var> has a list of <dfn id="the-worker-s-ports">the worker's ports</dfn>, which
1.301 ihickson 1517: consists of all the <code><a href="#messageport">MessagePort</a></code> objects that are
1.81 ihickson 1518: entangled with another port and that have one (but only one) port
1519: owned by <var title="">worker global scope</var>. This list includes
1.281 ihickson 1520: the implicit
1.327 ihickson 1521: <code><a href="#messageport">MessagePort</a></code> in the case of <a href="#dedicatedworkerglobalscope" title="DedicatedWorkerGlobalScope">dedicated workers</a>.</p>
1522:
1523: <p>Each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> also has a list of <dfn id="the-worker-s-workers">the
1.124 ihickson 1524: worker's workers</dfn>. Initially this list is empty; it is
1.327 ihickson 1525: populated when the worker creates or obtains further workers.</p>
1526:
1527: <p>Finally, each <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> also has a list of
1.124 ihickson 1528: <dfn id="the-worker-s-documents">the worker's <code>Document</code>s</dfn>. Initially this list
1.327 ihickson 1529: is empty; it is populated when the worker is created.</p>
1530:
1531: <p>Whenever a <code>Document</code> <var title="">d</var> is <dfn id="add-a-document-to-the-worker-s-documents" title="add a document to the worker's documents">added to the
1.123 ihickson 1532: worker's <code>Document</code>s</dfn>, the user agent must, for each
1.325 ihickson 1533: worker <var title="">q</var> in the list of <a href="#the-worker-s-workers">the worker's
1534: workers</a> whose list of <a href="#the-worker-s-documents">the worker's
1535: <code>Document</code>s</a> does not contain <var title="">d</var>, <a href="#add-a-document-to-the-worker-s-documents" title="add a document to the worker's
1.123 ihickson 1536: documents">add <var title="">d</var> to <var title="">q</var>'s
1537: <code>WorkerGlobalScope</code> owner's list of <span>the worker's
1.327 ihickson 1538: <code>Document</code>s</span></a>.</p>
1539:
1540: <p>Whenever a <code>Document</code> object is <span title="discard a
1.123 ihickson 1541: Document">discarded</span>, it must be removed from the list of
1542: <a href="#the-worker-s-documents">the worker's <code>Document</code>s</a> of each worker
1.327 ihickson 1543: whose list contains that <code>Document</code>.</p>
1544:
1545: <p>Given a <span>script's global object</span> <var title="">o</var>
1.123 ihickson 1546: when creating or obtaining a worker, the <dfn id="list-of-relevant-document-objects-to-add">list of relevant
1547: <code>Document</code> objects to add</dfn> depends on the type of
1548: <var title="">o</var>. If <var title="">o</var> is a
1549: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object (i.e. if we are creating a
1550: nested worker), then the relevant <code>Document</code>s are the
1551: <code>Document</code>s that are in <var title="">o</var>'s own list
1552: of <a href="#the-worker-s-documents">the worker's <code>Document</code>s</a>. Otherwise, <var title="">o</var> is a <code>Window</code> object, and the relevant
1553: <code>Document</code> is just the <code>Document</code> that is the
1.327 ihickson 1554: <span>active document</span> of the <code>Window</code> object <var title="">o</var>.</p>
1555:
1556: <hr><p>A worker is said to be a <dfn id="permissible-worker">permissible worker</dfn> if its
1.123 ihickson 1557: list of <a href="#the-worker-s-documents">the worker's <code>Document</code>s</a> is not
1.327 ihickson 1558: empty.</p>
1559:
1560: <p>A worker is said to be a <dfn id="protected-worker">protected worker</dfn> if it is a
1.123 ihickson 1561: <a href="#permissible-worker">permissible worker</a> and either it has outstanding
1562: timers, database transactions, or network connections, or its list
1.124 ihickson 1563: of <a href="#the-worker-s-ports">the worker's ports</a> is not empty, or its
1.123 ihickson 1564: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> is actually a
1565: <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object (i.e. the worker is a
1.327 ihickson 1566: shared worker).</p>
1567:
1568: <p>A worker is said to be an <dfn id="active-needed-worker">active needed worker</dfn> if any
1.123 ihickson 1569: of the <code>Document</code> objects in <a href="#the-worker-s-documents">the worker's
1.327 ihickson 1570: <code>Document</code>s</a> are <span>fully active</span>.</p>
1571:
1572: <p>A worker is said to be a <dfn id="suspendable-worker">suspendable worker</dfn> if it is
1.123 ihickson 1573: not an <a href="#active-needed-worker">active needed worker</a> but it is a
1.327 ihickson 1574: <a href="#permissible-worker">permissible worker</a>.</p>
1575:
1576:
1.339 ihickson 1577: <h3 id="processing-model"><span class="secno">4.5 </span>Processing model</h3>
1.327 ihickson 1578:
1579: <p>When a user agent is to <dfn id="run-a-worker">run a worker</dfn> for a script with
1.232 ihickson 1580: <span>URL</span> <var title="">url</var>, a <span>browsing
1581: context</span> <var title="">owner browsing context</var>, a
1582: <code>Document</code> <var title="">owner document</var>, an
1583: <span>origin</span> <var title="">owner origin</var>, and with
1584: global scope <var title="">worker global scope</var>, it must run
1.327 ihickson 1585: the following steps:</p>
1586:
1587: <ol><li>
1.81 ihickson 1588:
1.274 ihickson 1589: <p>Create a separate parallel execution environment (i.e. a
1590: separate thread or process or equivalent construct), and run the
1591: rest of these steps asynchronously in that context.</p>
1.81 ihickson 1592:
1593: </li>
1.4 ihickson 1594:
1.101 ihickson 1595: <li><p>If <var title="">worker global scope</var> is actually a
1.115 ihickson 1596: <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object (i.e. the worker is a
1.101 ihickson 1597: shared worker), and there are any <span title="relevant application
1598: cache">relevant application caches</span> that are identified by a
1599: 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 1600: their entries, <em>not</em> excluding entries marked as <span title="concept-appcache-foreign">foreign</span>, then associate the
1601: <var title="">worker global scope</var> with the <span title="concept-appcache-selection">most appropriate application
1.101 ihickson 1602: cache</span> of those that match.</li>
1603:
1.4 ihickson 1604: <li>
1.52 ihickson 1605:
1.256 ihickson 1606: <p>Attempt to <span>fetch</span> the resource identified by <var title="">url</var>, from the <var title="">owner origin</var>,
1607: with the <i>synchronous flag</i> set and the <i>force same-origin
1.281 ihickson 1608: flag</i> set.</p>
1.318 ihickson 1609:
1.256 ihickson 1610: <p>If the attempt fails, then for each <code><a href="#worker">Worker</a></code> or
1611: <code><a href="#sharedworker">SharedWorker</a></code> object associated with <var title="">worker global scope</var>, <span>queue a task</span> to
1612: <span>fire a simple event</span> named <code title="event-error">error</code> at that object. Abort these
1613: steps.</p>
1.7 ihickson 1614:
1.264 ihickson 1615: <p>If the attempt succeeds, then let <var title="">source</var> be
1616: the script resource <span>decoded as UTF-8, with error
1617: handling</span>.
1618:
1619: <a href="#refsHTML">[HTML]</a>
1620:
1621: </p>
1.81 ihickson 1622:
1.68 ihickson 1623: <p>Let <var title="">language</var> be JavaScript.</p>
1.7 ihickson 1624:
1.115 ihickson 1625: <p class="note">As with <code>script</code> elements, the MIME
1.81 ihickson 1626: type of the script is ignored. Unlike with <code>script</code>
1627: elements, there is no way to override the type. It's always
1.170 ihickson 1628: assumed to be JavaScript.</p>
1.81 ihickson 1629:
1630: </li>
1.7 ihickson 1631:
1.338 ihickson 1632: <li><p>In the newly created execution environment, create a
1633: <span>JavaScript global environment</span> whose <i>global
1634: object</i> is <var title="">worker global scope</var>. If <var title="">worker global scope</var> is a
1635: <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> object, then this is a
1636: <span>dedicated worker environment</span>. Otherwise, <var title="">worker global scope</var> is a
1637: <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object, and this is a
1638: <span>shared worker environment</span>. (In either case, by
1639: definition, it is a <span>worker environment</span>.)</li>
1640:
1.7 ihickson 1641: <li>
1.68 ihickson 1642:
1.115 ihickson 1643: <p>A new <span title="concept-script">script</span> is now
1.81 ihickson 1644: created, as follows.</p>
1645:
1646: <p>Create a new <span>script execution environment</span>
1647: set up as appropriate for the scripting language <var title="">language</var>.</p>
1.34 ihickson 1648:
1.68 ihickson 1649: <p>Parse/compile/initialize <var title="">source</var> using that
1.81 ihickson 1650: <span>script execution environment</span>, as appropriate for <var title="">language</var>, and thus obtain a <span>list of code
1651: entry-points</span>; set the <i>initial code entry-point</i> to
1652: the entry-point for any executable code to be immediately run.</p>
1653:
1654: <p>Set the <span>script's global object</span> to <var title="">worker global scope</var>.</p>
1655:
1656: <p>Set the <span>script's browsing context</span> to <var title="">owner browsing context</var>.</p>
1657:
1.232 ihickson 1658: <p>Set the <span>script's document</span> to <var title="">owner
1659: document</var>.</p>
1660:
1.83 ihickson 1661: <p>Set the <span>script's URL character encoding</span> to
1.81 ihickson 1662: UTF-8. (This is just used for encoding non-ASCII characters in the
1663: query component of URLs.)</p>
1.68 ihickson 1664:
1665: <p>Set the <span>script's base URL</span> to <var title="">url</var>.</p>
1.4 ihickson 1666:
1.81 ihickson 1667: </li>
1.4 ihickson 1668:
1669: <li>
1.81 ihickson 1670:
1671: <p><strong>Closing orphan workers</strong>: Start monitoring the
1.125 ihickson 1672: worker such that no sooner than it stops being either a
1673: <a href="#protected-worker">protected worker</a> or a <a href="#suspendable-worker">suspendable
1.123 ihickson 1674: worker</a>, and no later than it stops being a
1675: <a href="#permissible-worker">permissible worker</a>, <var title="">worker global
1676: scope</var>'s <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag is set
1.281 ihickson 1677: to true.</p>
1.81 ihickson 1678:
1679: </li>
1.9 ihickson 1680:
1681: <li>
1.7 ihickson 1682:
1.81 ihickson 1683: <p><strong>Suspending workers</strong>: Start monitoring the
1684: worker, such that whenever <var title="">worker global
1.115 ihickson 1685: scope</var>'s <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag is false
1686: and the worker is a <a href="#suspendable-worker">suspendable worker</a>, the user
1.81 ihickson 1687: agent suspends execution of script in that worker until such time
1.115 ihickson 1688: as either the <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag switches
1689: to true or the worker stops being a <a href="#suspendable-worker">suspendable
1.81 ihickson 1690: worker</a>.</p>
1.4 ihickson 1691:
1.81 ihickson 1692: </li>
1.68 ihickson 1693:
1694: <li>
1.4 ihickson 1695:
1.81 ihickson 1696: <p><span title="jump to a code entry-point">Jump</span> to the
1.115 ihickson 1697: <span title="concept-script">script</span>'s <i>initial code
1.81 ihickson 1698: entry-point</i>, and let that run until it either returns, fails
1699: to catch an exception, or gets prematurely aborted by the
1.115 ihickson 1700: "<a href="#kill-a-worker">kill a worker</a>" or "<a href="#terminate-a-worker">terminate a worker</a>"
1.81 ihickson 1701: algorithms defined below.</p>
1702:
1.4 ihickson 1703:
1.318 ihickson 1704:
1.81 ihickson 1705: </li>
1.4 ihickson 1706:
1.95 ihickson 1707: <li><p>If <var title="">worker global scope</var> is actually a
1.115 ihickson 1708: <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> object (i.e. the worker is
1.126 ihickson 1709: a dedicated worker), then enable the <span>port message
1710: queue</span> of the worker's implicit port.</li>
1.95 ihickson 1711:
1.4 ihickson 1712: <li>
1.68 ihickson 1713:
1.115 ihickson 1714: <p><i title="">Event loop</i>: Wait until either there is a <span title="concept-task">task</span> in one of the <span>event
1715: 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 1716: to true.</p>
1.43 ihickson 1717:
1.81 ihickson 1718: </li>
1.4 ihickson 1719:
1720: <li>
1721:
1.81 ihickson 1722: <p>Run the oldest task on one of the <span>event loop</span>'s
1723: <span title="task queue">task queues</span>, if any. The user
1724: agent may pick any <span>task queue</span>.</p>
1725:
1.115 ihickson 1726: <p class="note">The handling of events or the execution of
1727: callbacks might get prematurely aborted by the "<a href="#kill-a-worker">kill a
1728: worker</a>" or "<a href="#terminate-a-worker">terminate a worker</a>" algorithms
1.81 ihickson 1729: defined below.</p>
1.8 ihickson 1730:
1.81 ihickson 1731: </li>
1.4 ihickson 1732:
1733: <li>
1734:
1.248 ihickson 1735: <p>If the <span>storage mutex</span> is now owned by the worker's
1736: <span>event loop</span>, release it so that it is once again
1737: free.</p>
1738:
1739: </li>
1740:
1741: <li>
1742:
1743: <p>Remove the task just run in the earlier step, if any, from its
1.81 ihickson 1744: <span>task queue</span>.</p>
1.4 ihickson 1745:
1.81 ihickson 1746: </li>
1.4 ihickson 1747:
1748: <li>
1.8 ihickson 1749:
1.81 ihickson 1750: <p>If there are any more events in the <span>event loop</span>'s
1.115 ihickson 1751: <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 1752: to false, then jump back to the step above labeled <i>event
1753: loop</i>.</p>
1.8 ihickson 1754:
1.81 ihickson 1755: </li>
1.8 ihickson 1756:
1757: <li>
1.71 ihickson 1758:
1.123 ihickson 1759: <p>Empty the <var title="">worker global scope</var>'s <span>list
1.333 ihickson 1760: of active timers</span>.</p>
1.50 ihickson 1761:
1.81 ihickson 1762: </li>
1.50 ihickson 1763:
1.247 ihickson 1764: <li>
1765:
1766: <p>Disentangle all the ports in the list of <a href="#the-worker-s-ports">the worker's
1767: ports</a>.</p>
1768:
1769: </li>
1770:
1.318 ihickson 1771:
1.155 ihickson 1772: </ol><hr><p>When a user agent is to <dfn id="kill-a-worker">kill a worker</dfn> it must
1.81 ihickson 1773: run the following steps in parallel with the worker's main loop (the
1.327 ihickson 1774: "<a href="#run-a-worker">run a worker</a>" processing model defined above):</p>
1775:
1776: <ol><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 1777: true.</li>
1778:
1779:
1.318 ihickson 1780:
1.115 ihickson 1781: <li><p>If there are any <span title="concept-task">tasks</span>
1.81 ihickson 1782: queued in the <span>event loop</span>'s <span title="task
1.281 ihickson 1783: queue">task queues</span>, discard them without processing them.</li>
1784:
1.81 ihickson 1785:
1.318 ihickson 1786:
1.81 ihickson 1787: <li><p>Wait a user-agent-defined amount of time.</li>
1788:
1.281 ihickson 1789: <li><p>Abort the script currently running in the worker.</li>
1.81 ihickson 1790:
1.155 ihickson 1791: </ol><p>User agents may invoke the "<a href="#kill-a-worker">kill a worker</a>"
1.81 ihickson 1792: processing model on a worker at any time, e.g. in response to user
1793: requests, in response to CPU quota management, or when a worker
1.115 ihickson 1794: stops being an <a href="#active-needed-worker">active needed worker</a> if the worker
1795: continues executing even after its <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag was
1.327 ihickson 1796: set to true.</p>
1797:
1798: <hr><p>When a user agent is to <dfn id="terminate-a-worker">terminate a worker</dfn> it must run
1.81 ihickson 1799: the following steps in parallel with the worker's main loop (the
1.327 ihickson 1800: "<a href="#run-a-worker">run a worker</a>" processing model defined above):</p>
1801:
1802: <ol><li><p>Set the worker's <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object's
1.115 ihickson 1803: <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag to
1.81 ihickson 1804: true.</li>
1805:
1.115 ihickson 1806: <li><p>If there are any <span title="concept-task">tasks</span>
1.81 ihickson 1807: queued in the <span>event loop</span>'s <span title="task
1808: queue">task queues</span>, discard them without processing
1809: them.</li>
1810:
1811: <li><p>Abort the script currently running in the worker.</li>
1812:
1.115 ihickson 1813: <li><p>If the worker's <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object is
1814: actually a <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> object (i.e. the
1.81 ihickson 1815: worker is a dedicated worker), then empty the <span>port message
1816: queue</span> of the port that the worker's implicit port is
1817: entangled with.</li>
1818:
1.155 ihickson 1819: </ol><hr><p>The <span>task source</span> for the tasks mentioned above is the
1.327 ihickson 1820: <span>DOM manipulation task source</span>.</p>
1821:
1822:
1.339 ihickson 1823: <h3 id="runtime-script-errors"><span class="secno">4.6 </span>Runtime script errors</h3>
1.327 ihickson 1824:
1825: <p>Whenever an uncaught runtime script error occurs in one of the
1.143 ihickson 1826: worker's scripts, if the error did not occur while handling a
1827: previous script error, the user agent must <span>report the
1.314 ihickson 1828: error</span> at the <span>URL</span> of the resource that contained
1.324 ihickson 1829: the script, with the position (line number and column number) where
1830: the error occurred, in the <span>origin</span> of the scripts
1831: running in the worker, using the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
1832: object's <code title="handler-WorkerGlobalScope-onerror"><a href="#handler-workerglobalscope-onerror">onerror</a></code> attribute.
1.205 ihickson 1833:
1.226 ihickson 1834: <a href="#refsHTML">[HTML]</a>
1.205 ihickson 1835:
1.327 ihickson 1836: </p>
1837:
1.205 ihickson 1838: <p>For shared workers, if the error is still <i title="concept-error-nothandled">not handled</i> afterwards, or if
1.132 ihickson 1839: the error occurred while handling a previous script error, the error
1.215 ihickson 1840: may be reported to the user.
1.205 ihickson 1841:
1.226 ihickson 1842: <a href="#refsHTML">[HTML]</a>
1.205 ihickson 1843:
1.327 ihickson 1844: </p>
1845:
1.205 ihickson 1846: <p>For dedicated workers, if the error is still <i title="concept-error-nothandled">not handled</i> afterwards, or if
1.132 ihickson 1847: the error occurred while handling a previous script error, the user
1.292 ihickson 1848: agent must <span>queue a task</span> to fire an event that uses the
1849: <code><a href="#errorevent">ErrorEvent</a></code> interface, with the name <code title="event-error">error</code>, that doesn't bubble and is
1.307 ihickson 1850: 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 initialized
1.292 ihickson 1851: appropriately, at the <code><a href="#worker">Worker</a></code> object associated with the
1.307 ihickson 1852: worker. If the event is not canceled, the user agent must act as if
1853: the uncaught runtime script error had occurred in the global scope
1854: that the <code><a href="#worker">Worker</a></code> object is in, thus repeating the entire
1.327 ihickson 1855: runtime script error reporting process one level up.</p>
1856:
1857: <p>If the implicit port connecting the worker to its
1.292 ihickson 1858: <code><a href="#worker">Worker</a></code> object has been disentangled (i.e. if the parent
1859: worker has been terminated), then the user agent must act as if the
1860: <code><a href="#worker">Worker</a></code> object had no <code title="event-error">error</code> event handler and as if that
1861: worker's <code title="handler-WorkerGlobalScope-onerror"><a href="#handler-workerglobalscope-onerror">onerror</a></code> attribute
1.327 ihickson 1862: was null, but must otherwise act as described above.</p>
1863:
1.331 ihickson 1864: <p class="note">Thus, error reports propagate up to the chain of
1.292 ihickson 1865: dedicated workers up to the original <code>Document</code>, even if
1866: some of the workers along this chain have been terminated and
1.327 ihickson 1867: garbage collected.</p>
1868:
1869: <p>The <span>task source</span> for the task mentioned above is the
1870: <span>DOM manipulation task source</span>.</p>
1871:
1872: <hr><pre class="idl">[Constructor(DOMString type, optional <a href="#erroreventinit">ErrorEventInit</a> eventInitDict)]
1.307 ihickson 1873: interface <dfn id="errorevent">ErrorEvent</dfn> : <span>Event</span> {
1.147 ihickson 1874: readonly attribute DOMString <a href="#dom-errorevent-message" title="dom-ErrorEvent-message">message</a>;
1875: readonly attribute DOMString <a href="#dom-errorevent-filename" title="dom-ErrorEvent-filename">filename</a>;
1.115 ihickson 1876: readonly attribute unsigned long <a href="#dom-errorevent-lineno" title="dom-ErrorEvent-lineno">lineno</a>;
1.307 ihickson 1877: };
1878:
1879: dictionary <dfn id="erroreventinit">ErrorEventInit</dfn> : <span>EventInit</span> {
1880: DOMString message;
1881: DOMString filename;
1882: unsigned long lineno;
1.327 ihickson 1883: };</pre>
1884:
1885: <p>The <dfn id="dom-errorevent-message" title="dom-ErrorEvent-message"><code>message</code></dfn> attribute
1.307 ihickson 1886: must return the value it was initialized to. When the object is
1887: created, this attribute must be initialized to the empty string. It
1.327 ihickson 1888: represents the error message.</p>
1889:
1890: <p>The <dfn id="dom-errorevent-filename" title="dom-ErrorEvent-filename"><code>filename</code></dfn>
1.307 ihickson 1891: attribute must return the value it was initialized to. When the
1892: object is created, this attribute must be initialized to the empty
1893: string. It represents the <span>absolute URL</span> of the script in
1.327 ihickson 1894: which the error originally occurred.</p>
1895:
1896: <p>The <dfn id="dom-errorevent-lineno" title="dom-ErrorEvent-lineno"><code>lineno</code></dfn>
1.307 ihickson 1897: attribute must return the value it was initialized to. When the
1898: object is created, this attribute must be initialized to zero. It
1899: represents the line number where the error occurred in the
1.327 ihickson 1900: script.</p>
1901:
1902:
1903:
1.339 ihickson 1904: <h3 id="creating-workers"><span class="secno">4.7 </span>Creating workers</h3>
1.327 ihickson 1905:
1.339 ihickson 1906: <h4 id="the-abstractworker-abstract-interface"><span class="secno">4.7.1 </span>The <code><a href="#abstractworker">AbstractWorker</a></code> abstract interface</h4>
1.327 ihickson 1907:
1908: <pre class="idl">[NoInterfaceObject]
1.317 ihickson 1909: interface <dfn id="abstractworker">AbstractWorker</dfn> {
1.332 ihickson 1910: attribute <span>EventHandler</span> <a href="#handler-abstractworker-onerror" title="handler-AbstractWorker-onerror">onerror</a>;
1.318 ihickson 1911:
1.327 ihickson 1912: };</pre>
1913:
1914: <p>The following are the <span>event handlers</span> (and their
1.177 ihickson 1915: corresponding <span title="event handler event type">event handler
1916: event types</span>) that must be supported, as IDL attributes, by
1.327 ihickson 1917: objects implementing the <code><a href="#abstractworker">AbstractWorker</a></code> interface:</p>
1918:
1919: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.155 ihickson 1920: <tbody><tr><td><dfn id="handler-abstractworker-onerror" title="handler-AbstractWorker-onerror"><code>onerror</code></dfn> <td> <code title="event-error">error</code>
1.318 ihickson 1921:
1.339 ihickson 1922: </table><h4 id="dedicated-workers-and-the-worker-interface"><span class="secno">4.7.2 </span>Dedicated workers and the <code><a href="#worker">Worker</a></code> interface</h4>
1.327 ihickson 1923:
1924: <pre class="idl">[<a href="#dom-worker" title="dom-Worker">Constructor</a>(DOMString scriptURL)]
1.317 ihickson 1925: interface <dfn id="worker">Worker</dfn> : <span>EventTarget</span> {
1.115 ihickson 1926: void <a href="#dom-worker-terminate" title="dom-Worker-terminate">terminate</a>();
1.50 ihickson 1927:
1.318 ihickson 1928: void <a href="#dom-worker-postmessage" title="dom-Worker-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer);
1.332 ihickson 1929: attribute <span>EventHandler</span> <a href="#handler-worker-onmessage" title="handler-Worker-onmessage">onmessage</a>;
1.317 ihickson 1930: };
1.327 ihickson 1931: <a href="#worker">Worker</a> implements <a href="#abstractworker">AbstractWorker</a>;</pre>
1932:
1933: <p>The <dfn id="dom-worker-terminate" title="dom-Worker-terminate"><code>terminate()</code></dfn> method,
1.115 ihickson 1934: when invoked, must cause the "<a href="#terminate-a-worker">terminate a worker</a>"
1.81 ihickson 1935: algorithm to be run on the worker with with the object is
1.327 ihickson 1936: associated.</p>
1937:
1938: <p><code><a href="#worker">Worker</a></code> objects act as if they had an implicit
1.301 ihickson 1939: <code><a href="#messageport">MessagePort</a></code> associated with them. This port is part of
1.81 ihickson 1940: a channel that is set up when the worker is created, but it is not
1941: exposed. This object must never be garbage collected before the
1.327 ihickson 1942: <code><a href="#worker">Worker</a></code> object.</p>
1943:
1944: <p>All messages received by that port must immediately be retargeted
1945: at the <code><a href="#worker">Worker</a></code> object.</p>
1946:
1947: <p>The <dfn id="dom-worker-postmessage" title="dom-Worker-postMessage"><code>postMessage()</code></dfn>
1.318 ihickson 1948: method on <code><a href="#worker">Worker</a></code> objects
1.281 ihickson 1949: must act as if, when invoked, it
1.81 ihickson 1950: immediately invoked the method of the same name on the port, with
1.327 ihickson 1951: the same arguments, and returned the same return value.</p>
1952:
1953: <div class="example">
1.319 ihickson 1954:
1955: <p>The <code title="dom-Worker-postMessage"><a href="#dom-worker-postmessage">postMessage()</a></code>
1956: method's first argument can be structured data:</p>
1957:
1958: <pre>worker.postMessage({opcode: 'activate', device: 1938, parameters: [23, 102]});</pre>
1959:
1.327 ihickson 1960: </div>
1961:
1962: <p>The following are the <span>event handlers</span> (and their
1.177 ihickson 1963: corresponding <span title="event handler event type">event handler
1964: event types</span>) that must be supported, as IDL attributes, by
1.327 ihickson 1965: objects implementing the <code><a href="#worker">Worker</a></code> interface:</p>
1966:
1967: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.155 ihickson 1968: <tbody><tr><td><dfn id="handler-worker-onmessage" title="handler-Worker-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message">message</code>
1969: </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.327 ihickson 1970: user agent must run the following steps:</p>
1971:
1972: <ol><li><p><span title="resolve a url">Resolve</span> the <var title="">scriptURL</var> argument relative to the <span>entry
1.133 ihickson 1973: script</span>'s <span title="script's base URL">base URL</span>,
1974: when the method is invoked.</li>
1.9 ihickson 1975:
1.309 ihickson 1976: <li><p>If this fails, throw a <code>SyntaxError</code>
1.81 ihickson 1977: exception.</li>
1.9 ihickson 1978:
1.167 ihickson 1979: <li>
1980:
1.339 ihickson 1981: <p>If the <span title="url-scheme"><scheme></span> component of
1982: the resulting <span>absolute URL</span> is not "<code title="data-protocol">data</code>", and the <span>origin</span> of
1983: the resulting <span>absolute URL</span> is not the <span title="same origin">same</span> as the origin of the <span>entry
1984: script</span>, then throw a <code>SecurityError</code> exception
1985: and abort these steps.</p>
1.167 ihickson 1986:
1.334 ihickson 1987: <p class="note">Thus, scripts must either be external files with
1.339 ihickson 1988: the same scheme, host, and port as the original page, or <span title="data protocol"><code title="">data:</code> URLs</span>. For
1989: example, you can't load a script from a <span title="javascript
1990: protocol"><code title="">javascript:</code> URL</span>, and an
1991: <code>http:</code> page couldn't start workers using scripts with
1992: <code>http:</code> URLs.</p>
1.167 ihickson 1993:
1994: </li>
1.9 ihickson 1995:
1.339 ihickson 1996: <li><p>Create a new <code><a href="#dedicatedworkerglobalscope">DedicatedWorkerGlobalScope</a></code> object
1997: whose <a href="#worker-origin">worker origin</a> is the origin of the <span>entry
1998: script</span>. Let <var title="">worker global scope</var> be this
1999: new object.</li>
1.9 ihickson 2000:
1.115 ihickson 2001: <li><p>Create a new <code><a href="#worker">Worker</a></code> object, associated with
1.81 ihickson 2002: <var title="">worker global scope</var>. Let <var title="">worker</var> be this new object.</li>
1.50 ihickson 2003:
1.301 ihickson 2004: <li><p><span>Create a new <code><a href="#messageport">MessagePort</a></code> object</span>
1.192 ihickson 2005: owned by the <span title="script's global object">global
2006: object</span> of the <span title="concept-script">script</span> that
1.185 ihickson 2007: invoked the constructor. Let this be the <var title="">outside
1.81 ihickson 2008: port</var>.</li>
1.9 ihickson 2009:
1.81 ihickson 2010: <li><p>Associate the <var title="">outside port</var> with <var title="">worker</var>.</li>
1.50 ihickson 2011:
1.301 ihickson 2012: <li><p><span>Create a new <code><a href="#messageport">MessagePort</a></code> object</span>
1.185 ihickson 2013: owned by <var title="">worker global scope</var>. Let <var title="">inside port</var> be this new object.</li>
1.50 ihickson 2014:
1.81 ihickson 2015: <li><p>Associate <var title="">inside port</var> with <var title="">worker global scope</var>.</li>
1.50 ihickson 2016:
1.81 ihickson 2017: <li><p><span>Entangle</span> <var title="">outside port</var> and
2018: <var title="">inside port</var>.</li>
1.50 ihickson 2019:
1.81 ihickson 2020: <li><p>Return <var title="">worker</var>, and run the following
2021: steps asynchronously.</li>
1.50 ihickson 2022:
2023:
1.318 ihickson 2024:
1.126 ihickson 2025: <li><p>Enable <var title="">outside port</var>'s <span>port message
1.81 ihickson 2026: queue</span>.</li>
1.50 ihickson 2027:
2028: <li>
1.51 ihickson 2029:
1.123 ihickson 2030: <p>Let <var title="">docs</var> be the <a href="#list-of-relevant-document-objects-to-add">list of relevant
1.192 ihickson 2031: <code>Document</code> objects to add</a> given the <span title="script's global object">global object</span> of the <span title="concept-script">script</span> that invoked the
1.123 ihickson 2032: constructor.</p>
2033:
2034: </li>
2035:
2036: <li>
2037:
2038: <p><a href="#add-a-document-to-the-worker-s-documents" title="add a document to the worker's documents">Add to
2039: <var title="">worker global scope</var>'s list of <span>the
2040: worker's <code>Document</code>s</span></a> the
2041: <code>Document</code> objects in <var title="">docs</var>.</p>
2042:
2043: </li>
2044:
2045: <li>
2046:
1.192 ihickson 2047: <p>If the <span title="script's global object">global object</span>
1.124 ihickson 2048: of the <span title="concept-script">script</span> that invoked the
2049: constructor is a <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object (i.e. we
2050: are creating a nested worker), add <var title="">worker global
2051: scope</var> to the list of <a href="#the-worker-s-workers">the worker's workers</a> of the
1.192 ihickson 2052: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object that is the <span title="script's global object">global object</span> of the <span title="concept-script">script</span> that invoked the
1.124 ihickson 2053: constructor.</p>
2054:
2055: </li>
2056:
2057: <li>
2058:
1.115 ihickson 2059: <p><a href="#run-a-worker">Run a worker</a> for the resulting <span>absolute
1.193 ihickson 2060: URL</span>, with the <span>script's browsing context</span> of the
1.81 ihickson 2061: script that invoked the method as the <var title="">owner browsing
1.232 ihickson 2062: context</var>, with the <span>script's document</span> of the
2063: script that invoked the method as the <var title="">owner
2064: document</var>, with the <span>origin</span> of the <span>entry
1.176 ihickson 2065: script</span> as the <var title="">owner origin</var>, and with
2066: <var title="">worker global scope</var> as the global scope.</p>
1.9 ihickson 2067:
1.81 ihickson 2068: </li>
1.4 ihickson 2069:
1.155 ihickson 2070: </ol><p>This constructor must be visible when the <span>script's global
1.192 ihickson 2071: object</span> is either a <code>Window</code> object or an object
1.327 ihickson 2072: implementing the <code><a href="#workerutils">WorkerUtils</a></code> interface.</p>
2073:
2074:
1.339 ihickson 2075: <h4 id="shared-workers-and-the-sharedworker-interface"><span class="secno">4.7.3 </span>Shared workers and the <code><a href="#sharedworker">SharedWorker</a></code> interface</h4>
1.327 ihickson 2076:
2077: <pre class="idl">[<a href="#dom-sharedworker" title="dom-SharedWorker">Constructor</a>(DOMString scriptURL, optional DOMString name)]
1.317 ihickson 2078: interface <dfn id="sharedworker">SharedWorker</dfn> : <span>EventTarget</span> {
1.301 ihickson 2079: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-sharedworker-port" title="dom-SharedWorker-port">port</a>;
1.317 ihickson 2080: };
1.327 ihickson 2081: <a href="#sharedworker">SharedWorker</a> implements <a href="#abstractworker">AbstractWorker</a>;</pre>
2082:
2083: <p>The <dfn id="dom-sharedworker-port" title="dom-SharedWorker-port"><code>port</code></dfn>
1.81 ihickson 2084: attribute must return the value it was assigned by the object's
1.301 ihickson 2085: constructor. It represents the <code><a href="#messageport">MessagePort</a></code> for
1.327 ihickson 2086: communicating with the shared worker.</p>
2087:
2088: <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 2089: constructor is invoked, the user agent must run the following
1.327 ihickson 2090: steps:</p>
2091:
2092: <ol><li><p><span title="resolve a url">Resolve</span> the <var title="">scriptURL</var> argument.</li>
1.81 ihickson 2093:
1.309 ihickson 2094: <li><p>If this fails, throw a <code>SyntaxError</code>
1.81 ihickson 2095: exception.</li>
2096:
1.159 ihickson 2097: <li><p>Otherwise, let <var title="">scriptURL</var> be the
2098: resulting <span>absolute URL</span>.</li>
2099:
2100: <li><p>Let <var title="">name</var> be the value of the second
1.164 ihickson 2101: argument, or the empty string if the second argument was
2102: omitted.</li>
1.159 ihickson 2103:
1.167 ihickson 2104: <li>
2105:
1.339 ihickson 2106: <p>If the <span title="url-scheme"><scheme></span> component of
2107: <var title="">scriptURL</var> is not "<code title="data-protocol">data</code>", and the <span>origin</span> of
2108: <var title="">scriptURL</var> is not the <span title="same
2109: origin">same</span> as the origin of the <span>entry
2110: script</span>, then throw a <code>SecurityError</code> exception
2111: and abort these steps.</p>
1.167 ihickson 2112:
1.334 ihickson 2113: <p class="note">Thus, scripts must either be external files with
1.339 ihickson 2114: the same scheme, host, and port as the original page, or <span title="data protocol"><code title="">data:</code> URLs</span>. For
2115: example, you can't load a script from a <span title="javascript
2116: protocol"><code title="">javascript:</code> URL</span>, and an
2117: <code>http:</code> page couldn't start workers using scripts with
2118: <code>http:</code> URLs.</p>
1.167 ihickson 2119:
2120: </li>
1.9 ihickson 2121:
2122: <li>
2123:
1.123 ihickson 2124: <p>Let <var title="">docs</var> be the <a href="#list-of-relevant-document-objects-to-add">list of relevant
1.192 ihickson 2125: <code>Document</code> objects to add</a> given the <span title="script's global object">global object</span> of the <span title="concept-script">script</span> that invoked the
1.123 ihickson 2126: constructor.</p>
2127:
2128: </li>
2129:
2130: <li>
2131:
1.50 ihickson 2132: <p>Execute the following substeps atomically:</p>
1.9 ihickson 2133:
1.155 ihickson 2134: <ol><li><p>Create a new <code><a href="#sharedworker">SharedWorker</a></code> object, which will
1.115 ihickson 2135: shortly be associated with a <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code>
2136: object. Let this <code><a href="#sharedworker">SharedWorker</a></code> object be <var title="">worker</var>.</li>
1.81 ihickson 2137:
1.301 ihickson 2138: <li><p><span>Create a new <code><a href="#messageport">MessagePort</a></code> object</span>
1.192 ihickson 2139: owned by the <span title="script's global object">global
2140: object</span> of the script that invoked the method. Let this be
1.123 ihickson 2141: the <var title="">outside port</var>.</li>
1.81 ihickson 2142:
1.115 ihickson 2143: <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 2144:
1.164 ihickson 2145: <li><p>Let <var title="">worker global scope</var> be
2146: null.</li>
2147:
1.312 ihickson 2148: <li>
2149:
2150: <p>If <var title="">name</var> is not the empty string and there
2151: exists a <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object whose <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a> flag is
2152: false, whose <code title="dom-WorkerGlobalScope-name">name</code> attribute is
1.339 ihickson 2153: exactly equal to <var title="">name</var>, and whose
2154: <a href="#worker-origin">worker origin</a> is the <span>same origin</span> as
2155: <var title="">scriptURL</var>, then let <var title="">worker
2156: global scope</var> be that <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code>
2157: object.</p>
1.312 ihickson 2158:
2159: <p>Otherwise, if <var title="">name</var> is the empty string
2160: and there exists a <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object
2161: whose <a href="#dom-workerglobalscope-closing" title="dom-WorkerGlobalScope-closing">closing</a>
2162: flag is false, whose <code title="dom-WorkerGlobalScope-name">name</code> attribute is the
2163: empty string, and whose <code title="dom-WorkerGlobalScope-location"><a href="#dom-workerglobalscope-location">location</a></code> attribute
2164: represents an <span>absolute URL</span> that is exactly equal to
2165: <var title="">scriptURL</var>, then let <var title="">worker
2166: global scope</var> be that <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code>
2167: object.</p>
2168:
2169: </li>
2170:
2171: <li>
2172:
2173: <p>If <var title="">worker global scope</var> is not null, but
2174: the user agent has been configured to disallow communication
2175: between the <span title="concept-script">script</span> that
2176: invoked the constructor and the worker represented by the <var title="">worker global scope</var>, then set <var title="">worker global scope</var> to null.</p>
2177:
2178: <p class="note">For example, a user agent could have a
2179: development mode that isolates a particular <span>top-level
2180: browsing context</span> from all other pages, and scripts in
2181: that development mode could be blocked from connecting to shared
2182: workers running in the normal browser mode.</p>
2183:
2184: </li>
1.164 ihickson 2185:
1.9 ihickson 2186: <li>
2187:
1.164 ihickson 2188: <p>If <var title="">worker global scope</var> is not null, then
2189: run these steps:</p>
1.81 ihickson 2190:
1.164 ihickson 2191: <ol><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 2192: attribute represents an <span>absolute URL</span> that is not
1.159 ihickson 2193: exactly equal to <var title="">scriptURL</var>, then throw a
1.309 ihickson 2194: <code>URLMismatchError</code> exception and abort all these
1.159 ihickson 2195: steps.</li>
1.81 ihickson 2196:
2197: <li><p>Associate <var title="">worker</var> with <var title="">worker global scope</var>.</li>
2198:
1.301 ihickson 2199: <li><p><span>Create a new <code><a href="#messageport">MessagePort</a></code>
1.185 ihickson 2200: object</span> owned by <var title="">worker global
2201: scope</var>. Let this be the <var title="">inside
2202: port</var>.</li>
1.81 ihickson 2203:
2204: <li><p><span>Entangle</span> <var title="">outside port</var>
2205: and <var title="">inside port</var>.</li>
2206:
2207: <li><p>Return <var title="">worker</var> and perform the next
2208: step asynchronously.</li>
1.9 ihickson 2209:
1.81 ihickson 2210: <li><p>Create an event that uses the <code>MessageEvent</code>
1.115 ihickson 2211: interface, with the name <code title="event-connect">connect</code>, which does not bubble, is
1.118 ihickson 2212: not cancelable, has no default action, has a <code title="dom-MessageEvent-data">data</code> attribute whose value
1.330 ihickson 2213: is initialized to the empty string, has a <code title="dom-MessageEvent-ports">ports</code> attribute whose
1.307 ihickson 2214: value is initialized to a <span title="dfn-read-only-array">read only</span> array containing
1.330 ihickson 2215: only the newly created port, and has a <code title="dom-MessageEvent-source">source</code> attribute whose
2216: value is initialized to the newly created port, and <span>queue
2217: a task</span> to dispatch the event at <var title="">worker
2218: global scope</var>.</li>
1.43 ihickson 2219:
1.123 ihickson 2220: <li>
2221:
2222: <p><a href="#add-a-document-to-the-worker-s-documents" title="add a document to the worker's documents">Add to
2223: <var title="">worker global scope</var>'s list of <span>the
2224: worker's <code>Document</code>s</span></a> the
2225: <code>Document</code> objects in <var title="">docs</var>.</p>
2226:
2227: </li>
2228:
1.124 ihickson 2229: <li>
2230:
1.192 ihickson 2231: <p>If the <span title="script's global object">global
2232: object</span> of the <span title="concept-script">script</span>
1.124 ihickson 2233: that invoked the constructor is a
2234: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object, add <var title="">worker global scope</var> to the list of <a href="#the-worker-s-workers">the
2235: worker's workers</a> of the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
1.192 ihickson 2236: object that is the <span title="script's global object">global
2237: object</span> of the <span title="concept-script">script</span>
1.124 ihickson 2238: that invoked the constructor.</p>
2239:
2240: </li>
2241:
1.81 ihickson 2242: <li><p>Abort all these steps.</li>
1.9 ihickson 2243:
1.155 ihickson 2244: </ol></li>
1.9 ihickson 2245:
1.339 ihickson 2246: <li><p>Create a new <code><a href="#sharedworkerglobalscope">SharedWorkerGlobalScope</a></code> object
2247: whose <a href="#worker-origin">worker origin</a> is the origin of the <span>entry
2248: script</span>. Let <var title="">worker global scope</var> be
2249: this new object.</li>
1.9 ihickson 2250:
1.81 ihickson 2251: <li><p>Associate <var title="">worker</var> with <var title="">worker global scope</var>.</li>
1.9 ihickson 2252:
1.115 ihickson 2253: <li><p>Set the <code title="dom-SharedWorkerGlobalScope-name"><a href="#dom-sharedworkerglobalscope-name">name</a></code> attribute of
1.81 ihickson 2254: <var title="">worker global scope</var> to <var title="">name</var>.</li>
1.9 ihickson 2255:
1.301 ihickson 2256: <li><p><span>Create a new <code><a href="#messageport">MessagePort</a></code> object</span>
1.81 ihickson 2257: owned by <var title="">worker global scope</var>. Let <var title="">inside port</var> be this new object.</li>
1.9 ihickson 2258:
1.81 ihickson 2259: <li><p><span>Entangle</span> <var title="">outside port</var> and
2260: <var title="">inside port</var>.</li>
1.9 ihickson 2261:
1.155 ihickson 2262: </ol></li>
1.28 ihickson 2263:
1.123 ihickson 2264: <li><p>Return <var title="">worker</var> and perform the remaining
2265: steps asynchronously.</li>
1.18 ihickson 2266:
1.81 ihickson 2267: <li><p>Create an event that uses the <code>MessageEvent</code>
1.118 ihickson 2268: interface, with the name <code title="event-connect">connect</code>, which does not bubble, is not
1.115 ihickson 2269: cancelable, has no default action, has a <code title="dom-MessageEvent-data">data</code> attribute whose value is
1.330 ihickson 2270: initialized to the empty string, has a <code title="dom-MessageEvent-ports">ports</code> attribute whose value
1.307 ihickson 2271: is initialized to a <span title="dfn-read-only-array">read
1.330 ihickson 2272: only</span> array containing only the newly created port, and has a
2273: <code title="dom-MessageEvent-source">source</code> attribute whose
2274: value is initialized to the newly created port, and <span>queue a
2275: task</span> to dispatch the event at <var title="">worker global
2276: scope</var>.</li>
1.26 ihickson 2277:
2278: <li>
1.46 ihickson 2279:
1.123 ihickson 2280: <p><a href="#add-a-document-to-the-worker-s-documents" title="add a document to the worker's documents">Add to
2281: <var title="">worker global scope</var>'s list of <span>the
2282: worker's <code>Document</code>s</span></a> the
2283: <code>Document</code> objects in <var title="">docs</var>.</p>
2284:
2285: </li>
2286:
2287: <li>
2288:
1.192 ihickson 2289: <p>If the <span title="script's global object">global object</span>
1.124 ihickson 2290: of the <span title="concept-script">script</span> that invoked the
2291: constructor is a <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object, add <var title="">worker global scope</var> to the list of <a href="#the-worker-s-workers">the
2292: worker's workers</a> of the <code><a href="#workerglobalscope">WorkerGlobalScope</a></code>
1.192 ihickson 2293: object that is the <span title="script's global object">global
2294: object</span> of the <span title="concept-script">script</span>
1.124 ihickson 2295: that invoked the constructor.</p>
2296:
2297: </li>
2298:
2299: <li>
2300:
1.159 ihickson 2301: <p><a href="#run-a-worker">Run a worker</a> for <var title="">scriptURL</var>,
1.193 ihickson 2302: with the <span>script's browsing context</span> of the script that
1.159 ihickson 2303: invoked the method as the <var title="">owner browsing
1.232 ihickson 2304: context</var>, with the <span>script's document</span> of the
2305: script that invoked the method as the <var title="">owner
2306: document</var>, with the <span>origin</span> of the <span>entry
1.176 ihickson 2307: script</span> as the <var title="">owner origin</var>, and with
2308: <var title="">worker global scope</var> as the global scope.</p>
1.26 ihickson 2309:
1.60 ihickson 2310: </li>
1.81 ihickson 2311:
1.155 ihickson 2312: </ol><p>This constructor must be visible when the <span>script's global
1.192 ihickson 2313: object</span> is either a <code>Window</code> object or an object
1.327 ihickson 2314: implementing the <code><a href="#workerutils">WorkerUtils</a></code> interface.</p>
2315:
2316: <p>The <span>task source</span> for the tasks mentioned above is the
2317: <span>DOM manipulation task source</span>.</p>
2318:
2319:
2320:
2321: <h2 id="apis-available-to-workers"><span class="secno">5 </span>APIs available to workers</h2>
2322:
2323: <pre class="idl">[NoInterfaceObject]
1.150 ihickson 2324: interface <dfn id="workerutils">WorkerUtils</dfn> {
1.306 ihickson 2325: void <a href="#dom-workerglobalscope-importscripts" title="dom-WorkerGlobalScope-importScripts">importScripts</a>(DOMString... urls);
1.210 ihickson 2326: readonly attribute <a href="#workernavigator">WorkerNavigator</a> <a href="#dom-worker-navigator" title="dom-worker-navigator">navigator</a>;
1.150 ihickson 2327: };
1.290 ihickson 2328: <a href="#workerutils">WorkerUtils</a> implements <span>WindowTimers</span>;
1.327 ihickson 2329: <a href="#workerutils">WorkerUtils</a> implements <span>WindowBase64</span>;</pre>
2330:
2331:
2332: <p>The <code>WindowTimers</code> and <code>WindowBase64</code>
2333: interfaces are defined in the HTML specification. <a href="#refsHTML">[HTML]</a></p>
2334:
2335:
2336: <p>The DOM APIs (<code>Node</code> objects, <code>Document</code>
1.81 ihickson 2337: objects, etc) are not available to workers in this version of this
1.327 ihickson 2338: specification.</p>
2339:
2340:
2341: <h3 id="importing-scripts-and-libraries"><span class="secno">5.1 </span>Importing scripts and libraries</h3>
2342:
2343: <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
1.115 ihickson 2344: <code><a href="#workerglobalscope">WorkerGlobalScope</a></code> object, the user agent must run the
1.327 ihickson 2345: following steps:</p>
2346:
2347: <ol><li><p>If there are no arguments, return without doing
1.81 ihickson 2348: anything. Abort these steps.</li>
2349:
2350: <li><p><span title="resolve a url">Resolve</span> each
2351: argument.</li>
2352:
1.309 ihickson 2353: <li><p>If any fail, throw a <code>SyntaxError</code>
1.81 ihickson 2354: exception.</li>
2355:
1.26 ihickson 2356: <li>
1.81 ihickson 2357:
1.45 ihickson 2358: <p>Attempt to <span>fetch</span> each resource identified by the
1.194 ihickson 2359: resulting <span title="absolute URL">absolute URLs</span>, from
1.256 ihickson 2360: the <span>entry script</span>'s <span>origin</span>, with the
1.281 ihickson 2361: <i>synchronous flag</i> set.</p>
1.318 ihickson 2362:
1.81 ihickson 2363: </li>
1.26 ihickson 2364:
2365: <li>
2366:
1.81 ihickson 2367: <p>For each argument in turn, in the order given, starting with
2368: the first one, run these substeps:</p>
1.26 ihickson 2369:
1.155 ihickson 2370: <ol><li>
1.26 ihickson 2371:
1.81 ihickson 2372: <p>Wait for the fetching attempt for the corresponding resource
2373: to complete.</p>
1.60 ihickson 2374:
1.81 ihickson 2375: <p>If the fetching attempt failed, throw a
1.309 ihickson 2376: <code>NetworkError</code> exception and abort all these
1.81 ihickson 2377: steps.</p>
1.45 ihickson 2378:
1.264 ihickson 2379: <p>If the attempt succeeds, then let <var title="">source</var> be
2380: the script resource <span>decoded as UTF-8, with error
2381: handling</span>.
2382:
2383: <a href="#refsHTML">[HTML]</a>
2384:
2385: </p>
1.85 ihickson 2386:
2387: <p>Let <var title="">language</var> be JavaScript.</p>
1.61 ihickson 2388:
1.115 ihickson 2389: <p class="note">As with the worker's script, the script here is
1.81 ihickson 2390: always assumed to be JavaScript, regardless of the MIME
1.170 ihickson 2391: type.</p>
1.61 ihickson 2392:
1.81 ihickson 2393: </li>
1.26 ihickson 2394:
1.81 ihickson 2395: <li>
1.26 ihickson 2396:
1.314 ihickson 2397: <p><span>Create a script</span>, using <var title="">source</var> as the script source, the <span>URL</span>
2398: from which <var title="">source</var> was obtained, and <var title="">language</var> as the scripting language, using the
1.189 ihickson 2399: same global object, browsing context, URL character encoding,
2400: base URL, and script group as the <span title="concept-script">script</span> that was created by the
1.115 ihickson 2401: worker's <a href="#run-a-worker">run a worker</a> algorithm.</p>
1.81 ihickson 2402:
1.115 ihickson 2403: <p>Let the newly created <span title="concept-script">script</span> run until it either
1.81 ihickson 2404: returns, fails to parse, fails to catch an exception, or gets
1.115 ihickson 2405: prematurely aborted by the "<a href="#kill-a-worker">kill a worker</a>" or
2406: "<a href="#terminate-a-worker">terminate a worker</a>" algorithms defined above.</p>
1.26 ihickson 2407:
1.199 ihickson 2408: <p>If it failed to parse, then throw an ECMAScript
2409: <code>SyntaxError</code> exception and abort all these
2410: steps. <a href="#refsECMA262">[ECMA262]</a></p>
1.63 ihickson 2411:
1.320 ihickson 2412: <p>If an exception was thrown or if the script was prematurely
1.81 ihickson 2413: aborted, then abort all these steps, letting the exception or
2414: aborting continue to be processed by the script that called the
1.115 ihickson 2415: <code title="dom-WorkerGlobalScope-importScripts"><a href="#dom-workerglobalscope-importscripts">importScripts()</a></code>
1.81 ihickson 2416: method.</p>
2417:
1.115 ihickson 2418: <p>If the "<a href="#kill-a-worker">kill a worker</a>" or "<a href="#terminate-a-worker">terminate a
1.81 ihickson 2419: worker</a>" algorithms abort the script then abort all these
2420: steps.</p>
2421:
2422: </li>
2423:
1.155 ihickson 2424: </ol></li>
1.152 ihickson 2425:
1.327 ihickson 2426: </ol><h3 id="the-workernavigator-object"><span class="secno">5.2 </span>The <code><a href="#workernavigator">WorkerNavigator</a></code> object</h3>
2427:
2428: <p>The <dfn id="dom-worker-navigator" title="dom-worker-navigator"><code>navigator</code></dfn> attribute
1.115 ihickson 2429: of the <code><a href="#workerutils">WorkerUtils</a></code> interface must return an instance of
1.210 ihickson 2430: the <code><a href="#workernavigator">WorkerNavigator</a></code> interface, which represents the
1.327 ihickson 2431: identity and state of the user agent (the client):</p>
2432:
2433: <pre class="idl">interface <dfn id="workernavigator">WorkerNavigator</dfn> {};
1.210 ihickson 2434: <a href="#workernavigator">WorkerNavigator</a> implements <span>NavigatorID</span>;
1.327 ihickson 2435: <a href="#workernavigator">WorkerNavigator</a> implements <span>NavigatorOnLine</span>;</pre>
2436:
2437: <p>Objects implementing the <code><a href="#workernavigator">WorkerNavigator</a></code> interface
1.210 ihickson 2438: also implement the <code>NavigatorID</code> and
2439: <code>NavigatorOnLine</code> interfaces.
1.205 ihickson 2440:
1.226 ihickson 2441: <a href="#refsHTML">[HTML]</a>
1.205 ihickson 2442:
1.327 ihickson 2443: </p>
2444:
1.338 ihickson 2445: <p>The <code><a href="#workernavigator">WorkerNavigator</a></code> interface must only be <span title="expose">exposed</span> if the <span>JavaScript global
2446: environment</span> is a <span>worker environment</span>.</p>
1.327 ihickson 2447:
2448:
2449:
2450:
2451: <h3 id="interface-objects-and-constructors"><span class="secno">5.3 </span>Interface objects and constructors</h3>
2452:
1.338 ihickson 2453: <p>Nothing must be <span title="expose">exposed</span> when the
2454: <span>JavaScript global environment</span> is a <span>worker
2455: environment</span> except for the following:</p>
1.327 ihickson 2456:
2457: <ul><li><p><code>XMLHttpRequest</code> and all interface objects and
1.81 ihickson 2458: constructors defined by the XMLHttpRequest specifications, except
2459: that the <span>document response entity body</span> must always be
1.160 ihickson 2460: null. The <span><code>XMLHttpRequest</code> base URL</span> is the
2461: <span>script's base URL</span>; the
2462: <span><code>XMLHttpRequest</code> origin</span> is the script's
2463: <span>origin</span>. <a href="#refsXHR">[XHR]</a></li>
1.81 ihickson 2464:
1.205 ihickson 2465: <li><p>The interface objects and constructors defined by this
1.338 ihickson 2466: specification, except where is further restricted by explicit
2467: requirements in this specification.</li>
1.119 ihickson 2468:
1.338 ihickson 2469: <li><p>The interface objects of any objects made accessible through
2470: interfaces implemented by any objects that are themselves <span title="expose">exposed</span> (i.e. this requirement is
2471: transitive).</li>
1.205 ihickson 2472:
2473: </ul><p class="note">These requirements do not override the requirements
2474: defined by the Web IDL specification, in particular concerning the
1.327 ihickson 2475: visibility of interfaces annotated with the <code title="">[NoInterfaceObject]</code> extended attribute.</p>
2476:
2477:
2478: <h3 id="worker-locations"><span class="secno">5.4 </span>Worker locations</h3>
2479:
2480: <pre class="idl">interface <dfn id="workerlocation">WorkerLocation</dfn> {
1.263 ihickson 2481: // <span>URL decomposition IDL attributes</span>
1.294 ihickson 2482: stringifier readonly attribute DOMString <a href="#dom-workerlocation-href" title="dom-WorkerLocation-href">href</a>;
1.115 ihickson 2483: readonly attribute DOMString <a href="#dom-workerlocation-protocol" title="dom-WorkerLocation-protocol">protocol</a>;
2484: readonly attribute DOMString <a href="#dom-workerlocation-host" title="dom-WorkerLocation-host">host</a>;
2485: readonly attribute DOMString <a href="#dom-workerlocation-hostname" title="dom-WorkerLocation-hostname">hostname</a>;
2486: readonly attribute DOMString <a href="#dom-workerlocation-port" title="dom-WorkerLocation-port">port</a>;
2487: readonly attribute DOMString <a href="#dom-workerlocation-pathname" title="dom-WorkerLocation-pathname">pathname</a>;
2488: readonly attribute DOMString <a href="#dom-workerlocation-search" title="dom-WorkerLocation-search">search</a>;
2489: readonly attribute DOMString <a href="#dom-workerlocation-hash" title="dom-WorkerLocation-hash">hash</a>;
1.327 ihickson 2490: };</pre>
2491:
2492: <p>A <code><a href="#workerlocation">WorkerLocation</a></code> object represents an <span>absolute
2493: URL</span> set at its creation.</p>
2494:
2495: <p>The <dfn id="dom-workerlocation-href" title="dom-WorkerLocation-href"><code>href</code></dfn>
1.81 ihickson 2496: attribute must return the <span>absolute URL</span> that the object
1.327 ihickson 2497: represents.</p>
2498:
2499: <p>The <code><a href="#workerlocation">WorkerLocation</a></code> interface also has the complement
1.163 ihickson 2500: of <span>URL decomposition IDL attributes</span>, <dfn id="dom-workerlocation-protocol" title="dom-WorkerLocation-protocol"><code>protocol</code></dfn>,
1.115 ihickson 2501: <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>,
2502: <dfn id="dom-workerlocation-pathname" title="dom-WorkerLocation-pathname"><code>pathname</code></dfn>,
2503: <dfn id="dom-workerlocation-search" title="dom-WorkerLocation-search"><code>search</code></dfn>,
1.263 ihickson 2504: and <dfn id="dom-workerlocation-hash" title="dom-WorkerLocation-hash"><code>hash</code></dfn>.
2505: These must follow the rules given for <span>URL decomposition IDL
2506: attributes</span>, with the <span title="concept-uda-input">input</span> being the <span>absolute
2507: URL</span> that the object represents (same as the <code title="dom-WorkerLocation-href"><a href="#dom-workerlocation-href">href</a></code> attribute), and the
2508: <span title="concept-uda-setter">common setter action</span> being a
2509: no-op, since the attributes are defined to be readonly.
1.205 ihickson 2510:
1.226 ihickson 2511: <a href="#refsHTML">[HTML]</a>
1.205 ihickson 2512:
1.327 ihickson 2513: </p>
2514:
1.338 ihickson 2515: <p>The <code><a href="#workerlocation">WorkerLocation</a></code> interface must only be <span title="expose">exposed</span> if the <span>JavaScript global
2516: environment</span> is a <span>worker environment</span>.</p>
1.327 ihickson 2517:
2518:
2519:
2520:
2521:
2522:
2523: <h2 class="no-num" id="references">References</h2>
2524:
2525: <p>All references are normative unless marked "Non-normative".</p>
2526:
2527:
2528:
2529: <dl><dt id="refsDOMCORE">[DOMCORE]</dt>
1.276 ihickson 2530: <dd><cite><a href="http://dvcs.w3.org/hg/domcore/raw-file/tip/Overview.html">Web DOM Core</a></cite>, A. van Kesteren. W3C.</dd>
1.153 ihickson 2531:
1.152 ihickson 2532: <dt id="refsECMA262">[ECMA262]</dt>
1.335 ihickson 2533: <dd><cite><a href="http://www.ecma-international.org/publications/standards/Ecma-262.htm">ECMAScript Language Specification</a></cite>. ECMA.</dd>
1.152 ihickson 2534:
1.226 ihickson 2535: <dt id="refsHTML">[HTML]</dt>
2536: <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a></cite>,
2537: I. Hickson. WHATWG.</dd>
1.152 ihickson 2538:
1.315 ihickson 2539:
1.154 ihickson 2540: <dt id="refsRFC2119">[RFC2119]</dt>
1.265 ihickson 2541: <dd><cite><a href="http://tools.ietf.org/html/rfc2119">Key words for use in
1.226 ihickson 2542: RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF.</dd>
1.154 ihickson 2543:
2544: <dt id="refsWEBIDL">[WEBIDL]</dt>
1.318 ihickson 2545:
2546: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web
1.226 ihickson 2547: IDL</a></cite>, C. McCormack. W3C.</dd>
1.154 ihickson 2548:
1.152 ihickson 2549: <dt id="refsXHR">[XHR]</dt>
1.318 ihickson 2550:
2551: <dd><cite><a href="http://dev.w3.org/2006/webapi/XMLHttpRequest-2/"><code>XMLHttpRequest</code></a></cite>,
1.226 ihickson 2552: A. van Kesteren. W3C.</dd>
1.152 ihickson 2553:
1.327 ihickson 2554: </dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2> <!-- ACKS -->
2555:
2556: <p>Thanks to
1.81 ihickson 2557:
2558: Aaron Boodman,
1.155 ihickson 2559: Алексей Проскуряков (Alexey Proskuryakov),
1.81 ihickson 2560: Anne van Kesteren,
2561: Ben Turner,
2562: Dmitry Titov,
1.96 ihickson 2563: Drew Wilson,
1.97 ihickson 2564: Jeremy Orlow,
1.81 ihickson 2565: Jonas Sicking,
2566: Justin James,
2567: Kevin Hakanson,
2568: Maciej Stachowiak,
2569: Michael Nordman,
2570: Mike Smith,
2571:
2572: and
2573:
2574: Philip Taylor
2575:
1.327 ihickson 2576: for their useful and substantial comments.</p>
2577:
2578: <p>Huge thanks to the whole Gears team, who pioneered this
1.81 ihickson 2579: technology and whose experience has been a huge influence on this
1.327 ihickson 2580: specification.</p>
2581:
2582:
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