Skip to content

Commit

Permalink
[e] (0) Give more explanation about how workers work.
Browse files Browse the repository at this point in the history 
Fixing http://www.w3.org/Bugs/Public/show_bug.cgi?id=13232

git-svn-id: http://svn.whatwg.org/webapps@6384 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed Aug 8, 2011
1 parent 1d17d54 commit d70da98
Show file tree
Hide file tree
Showing 3 changed files with 248 additions and 6 deletions.
125 changes: 121 additions & 4 deletions complete.html
View file
Expand Up @@ -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 &mdash; Last Updated 6 August 2011</h2>
<h2 class="no-num no-toc">Living Standard &mdash; 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>
Expand Down Expand Up @@ -1024,14 +1024,19 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
<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>
Expand Down Expand Up @@ -77346,7 +77351,7 @@ <h4 id=scope-0><span class=secno>10.1.1 </span>Scope</h4>
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>

Expand Down Expand Up @@ -78304,6 +78309,118 @@ <h5>Providing libraries</h5>
(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>

Expand Down
2 changes: 1 addition & 1 deletion index
View file
Expand Up @@ -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 &mdash; Last Updated 6 August 2011</h2>
<h2 class="no-num no-toc">Living Standard &mdash; 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>
Expand Down
127 changes: 126 additions & 1 deletion source
View file
Expand Up @@ -88202,7 +88202,7 @@ local.onaddstream = function (event) {
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-->

Expand Down Expand Up @@ -88530,6 +88530,131 @@ local.onaddstream = function (event) {
(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-->
Expand Down

0 comments on commit d70da98

Please sign in to comment.