[html5] r6384 - [e] (0) Give more explanation about how workers work. Fixing http://www.w3.org/B [...]
whatwg at whatwg.org
whatwg at whatwg.org
Mon Aug 8 13:10:19 PDT 2011
Author: ianh
Date: 2011-08-08 13:10:17 -0700 (Mon, 08 Aug 2011)
New Revision: 6384
Modified:
complete.html
index
source
Log:
[e] (0) Give more explanation about how workers work.
Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=13232
Modified: complete.html
===================================================================
--- complete.html 2011-08-06 07:13:37 UTC (rev 6383)
+++ complete.html 2011-08-08 20:10:17 UTC (rev 6384)
@@ -239,7 +239,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1>Web Applications 1.0</h1>
- <h2 class="no-num no-toc">Living Standard — Last Updated 6 August 2011</h2>
+ <h2 class="no-num no-toc">Living Standard — Last Updated 8 August 2011</h2>
</hgroup><dl><dt>Multiple-page version:</dt>
<dd><a href=http://www.whatwg.org/specs/web-apps/current-work/complete/>http://www.whatwg.org/specs/web-apps/current-work/complete/</a></dd>
<dt>One-page version:</dt>
@@ -1024,14 +1024,19 @@
<li><a href=#introduction-13><span class=secno>10.1 </span>Introduction</a>
<ol>
<li><a href=#scope-0><span class=secno>10.1.1 </span>Scope</a></li>
- <li><a href=#tutorial><span class=secno>10.1.2 </span>Tutorial</a>
+ <li><a href=#examples-5><span class=secno>10.1.2 </span>Examples</a>
<ol>
<li><a href=#a-background-number-crunching-worker><span class=secno>10.1.2.1 </span>A background number-crunching worker</a></li>
<li><a href=#a-worker-for-updating-a-client-side-database><span class=secno>10.1.2.2 </span>A worker for updating a client-side database</a></li>
<li><a href=#worker-used-for-background-i/o><span class=secno>10.1.2.3 </span>Worker used for background I/O</a></li>
<li><a href=#shared-workers-introduction><span class=secno>10.1.2.4 </span>Shared workers introduction</a></li>
<li><a href=#shared-state-using-a-shared-worker><span class=secno>10.1.2.5 </span>Shared state using a shared worker</a></li>
- <li><a href=#delegation><span class=secno>10.1.2.6 </span>Delegation</a></ol></ol></li>
+ <li><a href=#delegation><span class=secno>10.1.2.6 </span>Delegation</a></ol></li>
+ <li><a href=#tutorials><span class=secno>10.1.3 </span>Tutorials</a>
+ <ol>
+ <li><a href=#creating-a-dedicated-worker><span class=secno>10.1.3.1 </span>Creating a dedicated worker</a></li>
+ <li><a href=#communicating-with-a-dedicated-worker><span class=secno>10.1.3.2 </span>Communicating with a dedicated worker</a></li>
+ <li><a href=#shared-workers><span class=secno>10.1.3.3 </span>Shared workers</a></ol></ol></li>
<li><a href=#infrastructure-0><span class=secno>10.2 </span>Infrastructure</a>
<ol>
<li><a href=#the-global-scope><span class=secno>10.2.1 </span>The global scope</a>
@@ -77346,7 +77351,7 @@
start-up performance cost, and a high per-instance memory cost.</p>
- <h4 id=tutorial><span class=secno>10.1.2 </span>Tutorial</h4>
+ <h4 id=examples-5><span class=secno>10.1.2 </span>Examples</h4>
<p><i>This section is non-normative.</i></p>
@@ -78304,7 +78309,119 @@
(end startConversation block) (beware nested comments)-->
+ <h4 id=tutorials><span class=secno>10.1.3 </span>Tutorials</h4>
+ <h5 id=creating-a-dedicated-worker><span class=secno>10.1.3.1 </span>Creating a dedicated worker</h5>
+
+ <p><i>This section is non-normative.</i></p>
+
+ <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
+ URL to that file as its only argument; a worker is then created and
+ returned:</p>
+
+ <pre>var worker = new Worker('helper.js');</pre>
+
+
+ <h5 id=communicating-with-a-dedicated-worker><span class=secno>10.1.3.2 </span>Communicating with a dedicated worker</h5>
+
+ <p><i>This section is non-normative.</i></p>
+
+ <p>Dedicated workers use <code><a href=#messageport>MessagePort</a></code> objects behind the
+ scenes, and thus support all the same features, such as sending
+ structured data, transferring binary data, and transferring other
+ ports.</p>
+
+ <p>To receive messages from a dedicated worker, use the <code title=handler-worker-onmessage><a href=#handler-worker-onmessage>onmessage</a></code> <a href=#event-handler-idl-attributes title="event
+ handler IDL attributes">event handler IDL attribute</a> on the
+ <code><a href=#worker>Worker</a></code> object:</p>
+
+ <pre>worker.onmessage = function (event) { ... };</pre>
+
+ <p>You can also use the <code title=dom-EventTarget-addEventListener>addEventListener()</code> method.</p>
+
+ <p class=note>The implicit <code><a href=#messageport>MessagePort</a></code> used by
+ dedicated workers has its <a href=#port-message-queue>port message queue</a> implicitly
+ enabled when it is created, so there is no equivanet to the
+ <code><a href=#messageport>MessagePort</a></code> interface's <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> method on the
+ <code><a href=#worker>Worker</a></code> interface.</p>
+
+ <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.
+ Structured data can be sent over this communication channel. To send
+ <code>ArrayBuffer</code> objects efficiently (by transferring them
+ rather than cloning them), list them in an array in the second
+ argument.</p>
+
+ <pre>worker.postMessage({
+ operation: 'find-edges',
+ input: buffer, // an ArrayBuffer object
+ threshold: 0.6,
+}, [buffer]);</pre>
+
+ <p>To receive a message inside the worker, the <code title=handler-DedicatedWorkerGlobalScope-onmessage><a href=#handler-dedicatedworkerglobalscope-onmessage>onmessage</a></code>
+ <a href=#event-handler-idl-attributes title="event handler IDL attributes">event handler IDL
+ attribute</a> is used.</p>
+
+ <pre>onmessage = function (event) { ... };</pre>
+
+ <p>You can again also use the <code title=dom-EventTarget-addEventListener>addEventListener()</code>
+ method.</p>
+
+ <p>In either case, the data is provided in the event object's <code title=dom-MessageEvent-data><a href=#dom-messageevent-data>data</a></code> attribute.</p>
+
+ <p>To send messages back, you again use <code title=dom-DedicatedWorkerGlobalScope-postMessage><a href=#dom-dedicatedworkerglobalscope-postmessage>postMessage()</a></code>.
+ It supports the structured data in the same manner.</p>
+
+ <pre>postMessage(event.data.input, [event.data.input]); // transfer the buffer back</pre>
+
+
+ <h5 id=shared-workers><span class=secno>10.1.3.3 </span>Shared workers</h5>
+
+ <p><i>This section is non-normative.</i></p>
+
+ <p>Shared workers are identified in one of two ways: either by the
+ URL of the script used to create it, or by explicit name. When
+ created by name, the URL used by the first page to create the worker
+ with that name is the URL of the script that will be used for that
+ worker. This allows multiple applications on a domain to all use a
+ single shared worker to provide a common service, without the
+ applications having to keep track of a common URL for the script
+ used to provide the service.</p>
+
+ <p class=note>In either case, shared workers are scoped by
+ <a href=#origin>origin</a>. Two different sites using the same names will
+ not collide.</p>
+
+ <p>Creating shared workers is done using the <code title=dom-SharedWorker><a href=#dom-sharedworker>SharedWorker()</a></code> constructor. This
+ constructor takes the URL to the script to use for its first
+ argument, and the name of the worker, if any, as the second
+ argument.</p>
+
+ <pre>var worker = new SharedWorker('service.js');</pre>
+
+ <p>Communicating with shared workers is done with explicit
+ <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
+ reference to the port on its <code title=dom-SharedWorker-port><a href=#dom-sharedworker-port>port</a></code> attribute.</p>
+
+ <pre>worker.port.onmessage = function (event) { ... };
+worker.port.postMessage('some message');
+worker.port.postMessage({ foo: 'structured'; bar: ['data', 'also', 'possible']});</pre>
+
+ <p>Inside the shared worker, new clients of the worker are announced
+ using the <code title=event-connect>connect</code> event. The port
+ for the new client is given by the event object's <code title=dom-messageevent-ports><a href=#dom-messageevent-ports>ports</a></code> array as its first (and
+ only) value.</p>
+
+ <pre>onconnect = function (event) {
+ var newPort = event.ports[0];
+ // set up a listener
+ newPort.onmessage = function (event) { ... };
+ // send a message back to the port
+ newPort.postMessage('ready!'); // can also send structured data, of course
+};</pre>
+
+
+
+
<h3 id=infrastructure-0><span class=secno>10.2 </span>Infrastructure</h3>
<p>There are two kinds of workers; dedicated workers, and shared
Modified: index
===================================================================
--- index 2011-08-06 07:13:37 UTC (rev 6383)
+++ index 2011-08-08 20:10:17 UTC (rev 6384)
@@ -243,7 +243,7 @@
<header class=head id=head><p><a class=logo href=http://www.whatwg.org/><img alt=WHATWG height=101 src=/images/logo width=101></a></p>
<hgroup><h1 class=allcaps>HTML</h1>
- <h2 class="no-num no-toc">Living Standard — Last Updated 6 August 2011</h2>
+ <h2 class="no-num no-toc">Living Standard — Last Updated 8 August 2011</h2>
</hgroup><dl><dt><strong>Web developer edition</strong></dt>
<dd><strong><a href=http://developers.whatwg.org/>http://developers.whatwg.org/</a></strong></dd>
<dt>Multiple-page version:</dt>
Modified: source
===================================================================
--- source 2011-08-06 07:13:37 UTC (rev 6383)
+++ source 2011-08-08 20:10:17 UTC (rev 6384)
@@ -88202,7 +88202,7 @@
start-up performance cost, and a high per-instance memory cost.</p>
- <h4>Tutorial</h4>
+ <h4>Examples</h4>
<!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
@@ -88530,6 +88530,131 @@
(end startConversation block) (beware nested comments)-->
+ <h4>Tutorials</h4>
+
+ <h5>Creating a dedicated worker</h5>
+
+ <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+ <p>Creating a worker requires a URL to a JavaScript file. The <code
+ title="dom-Worker">Worker()</code> constructor is invoked with the
+ URL to that file as its only argument; a worker is then created and
+ returned:</p>
+
+ <pre>var worker = new Worker('helper.js');</pre>
+
+
+ <h5>Communicating with a dedicated worker</h5>
+
+ <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+ <p>Dedicated workers use <code>MessagePort</code> objects behind the
+ scenes, and thus support all the same features, such as sending
+ structured data, transferring binary data, and transferring other
+ ports.</p>
+
+ <p>To receive messages from a dedicated worker, use the <code
+ title="handler-worker-onmessage">onmessage</code> <span title="event
+ handler IDL attributes">event handler IDL attribute</span> on the
+ <code>Worker</code> object:</p>
+
+ <pre>worker.onmessage = function (event) { ... };</pre>
+
+ <p>You can also use the <code
+ title="dom-EventTarget-addEventListener">addEventListener()</code> method.</p>
+
+ <p class="note">The implicit <code>MessagePort</code> used by
+ dedicated workers has its <span>port message queue</span> implicitly
+ enabled when it is created, so there is no equivanet to the
+ <code>MessagePort</code> interface's <code
+ title="dom-MessagePort-start">start()</code> method on the
+ <code>Worker</code> interface.</p>
+
+ <p>To <em>send</em> data to a worker, use the <code
+ title="dom-Worker-postMessage">postMessage()</code> method.
+ Structured data can be sent over this communication channel. To send
+ <code>ArrayBuffer</code> objects efficiently (by transferring them
+ rather than cloning them), list them in an array in the second
+ argument.</p>
+
+ <pre>worker.postMessage({
+ operation: 'find-edges',
+ input: buffer, // an ArrayBuffer object
+ threshold: 0.6,
+}, [buffer]);</pre>
+
+ <p>To receive a message inside the worker, the <code
+ title="handler-DedicatedWorkerGlobalScope-onmessage">onmessage</code>
+ <span title="event handler IDL attributes">event handler IDL
+ attribute</span> is used.</p>
+
+ <pre>onmessage = function (event) { ... };</pre>
+
+ <p>You can again also use the <code
+ title="dom-EventTarget-addEventListener">addEventListener()</code>
+ method.</p>
+
+ <p>In either case, the data is provided in the event object's <code
+ title="dom-MessageEvent-data">data</code> attribute.</p>
+
+ <p>To send messages back, you again use <code
+ title="dom-DedicatedWorkerGlobalScope-postMessage">postMessage()</code>.
+ It supports the structured data in the same manner.</p>
+
+ <pre>postMessage(event.data.input, [event.data.input]); // transfer the buffer back</pre>
+
+
+ <h5>Shared workers</h5>
+
+ <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+ <p>Shared workers are identified in one of two ways: either by the
+ URL of the script used to create it, or by explicit name. When
+ created by name, the URL used by the first page to create the worker
+ with that name is the URL of the script that will be used for that
+ worker. This allows multiple applications on a domain to all use a
+ single shared worker to provide a common service, without the
+ applications having to keep track of a common URL for the script
+ used to provide the service.</p>
+
+ <p class="note">In either case, shared workers are scoped by
+ <span>origin</span>. Two different sites using the same names will
+ not collide.</p>
+
+ <p>Creating shared workers is done using the <code
+ title="dom-SharedWorker">SharedWorker()</code> constructor. This
+ constructor takes the URL to the script to use for its first
+ argument, and the name of the worker, if any, as the second
+ argument.</p>
+
+ <pre>var worker = new SharedWorker('service.js');</pre>
+
+ <p>Communicating with shared workers is done with explicit
+ <code>MessagePort</code> objects. The object returned by the <code
+ title="dom-SharedWorker">SharedWorker()</code> constructor holds a
+ reference to the port on its <code
+ title="dom-SharedWorker-port">port</code> attribute.</p>
+
+ <pre>worker.port.onmessage = function (event) { ... };
+worker.port.postMessage('some message');
+worker.port.postMessage({ foo: 'structured'; bar: ['data', 'also', 'possible']});</pre>
+
+ <p>Inside the shared worker, new clients of the worker are announced
+ using the <code title="event-connect">connect</code> event. The port
+ for the new client is given by the event object's <code
+ title="dom-messageevent-ports">ports</code> array as its first (and
+ only) value.</p>
+
+ <pre>onconnect = function (event) {
+ var newPort = event.ports[0];
+ // set up a listener
+ newPort.onmessage = function (event) { ... };
+ // send a message back to the port
+ newPort.postMessage('ready!'); // can also send structured data, of course
+};</pre>
+
+
+
<!--END complete--><!--END epub-->
<!--FIXUP whatwg-workers +1-->
<!--FIXUP workers +1-->
More information about the Commit-Watchers
mailing list