[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