[html5] r7171 - [e] (0) Explain start() with an example. Fixing https://www.w3.org/Bugs/Public/s [...]

whatwg at whatwg.org whatwg at whatwg.org
Tue Jul 10 14:19:29 PDT 2012


Author: ianh
Date: 2012-07-10 14:19:27 -0700 (Tue, 10 Jul 2012)
New Revision: 7171

Modified:
   complete.html
   index
   source
Log:
[e] (0) Explain start() with an example.
Fixing https://www.w3.org/Bugs/Public/show_bug.cgi?id=13686
Affected topics: DOM APIs

Modified: complete.html
===================================================================
--- complete.html	2012-07-10 20:06:40 UTC (rev 7170)
+++ complete.html	2012-07-10 21:19:27 UTC (rev 7171)
@@ -1076,8 +1076,9 @@
     <ol>
      <li><a href=#introduction-11><span class=secno>10.5.1 </span>Introduction</a>
       <ol>
-       <li><a href=#ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.1 </span>Ports as the basis of an object-capability model on the Web</a></li>
-       <li><a href=#ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.2 </span>Ports as the basis of abstracting out service implementations</a></ol></li>
+       <li><a href=#examples-5><span class=secno>10.5.1.1 </span>Examples</a></li>
+       <li><a href=#ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.2 </span>Ports as the basis of an object-capability model on the Web</a></li>
+       <li><a href=#ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.3 </span>Ports as the basis of abstracting out service implementations</a></ol></li>
      <li><a href=#message-channels><span class=secno>10.5.2 </span>Message channels</a></li>
      <li><a href=#message-ports><span class=secno>10.5.3 </span>Message ports</a>
       <ol>
@@ -83647,10 +83648,76 @@
   <pre>port1.postMessage(['hello', 'world'], 'http://example.com');</pre>
 
 
-  <h5 id=ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.1 </span>Ports as the basis of an object-capability model on the Web</h5>
+  <h5 id=examples-5><span class=secno>10.5.1.1 </span>Examples</h5>
 
   <p><i>This section is non-normative.</i></p>
 
+  <div class=example>
+
+   <p>In this example, two JavaScript libraries are connected to each
+   other using <code><a href=#messageport>MessagePort</a></code>s. This allows the libraries to
+   later be hosted in different frames, or in <code><a href=#worker>Worker</a></code>
+   objects, without any change to the APIs.</p>
+
+   <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
+<script src="compose-mail.js"></script> <!-- exposes a composer object -->
+<script>
+ var channel = new MessageChannel();
+ composer.addContactsProvider(channel.port1);
+ contacts.registerConsumer(channel.port2);
+</script></pre>
+
+   <p>Here's what the "addContactsProvider()" function's
+   implementation could look like:</p>
+
+   <pre>function addContactsProvider(port) {
+  port.onmessage = function (event) {
+    switch (event.data.messageType) {
+      'search-result': handleSearchResult(event.data.results); break;
+      'search-done': handleSearchDone(); break;
+      'search-error': handleSearchError(event.data.message); break;
+      // ...
+    }
+  };
+};</pre>
+
+   <p>Alternatively, it could be implemented as follows:</p>
+
+   <pre>function addContactsProvider(port) {
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-result')
+      handleSearchResult(event.data.results);
+  });
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-done')
+      handleSearchDone();
+  });
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-error')
+      handleSearchError(event.data.message);
+  });
+  // ...
+  port.start();
+};</pre>
+
+   <p>The key difference is that when using <code title=dom-EventTarget-addEventListener>addEventListener()</code>,
+   the <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> method must
+   also be invoked. When using <code title=handler-MessagePort-onmessage><a href=#handler-messageport-onmessage>onmessage</a></code>, the call to
+   <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> is implied.</p>
+
+   <p>The <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> method,
+   whether called explicitly or implicitly (by setting <code title=handler-MessagePort-onmessage><a href=#handler-messageport-onmessage>onmessage</a></code>), starts the
+   flow of messages: messages posted on message ports are initially
+   paused, so that they don't get dropped on the floor before the
+   script has had a chance to set up its handlers.</p>
+
+  </div>
+
+
+  <h5 id=ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.2 </span>Ports as the basis of an object-capability model on the Web</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
   <p>Ports can be viewed as a way to expose limited capabilities (in
   the object-capability model sense) to other actors in the system.
   This can either be a weak capability system, where the ports are
@@ -83720,7 +83787,7 @@
   capability to add a single contact.</p>
 
 
-  <h5 id=ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.2 </span>Ports as the basis of abstracting out service implementations</h5>
+  <h5 id=ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.3 </span>Ports as the basis of abstracting out service implementations</h5>
 
   <p><i>This section is non-normative.</i></p>
 

Modified: index
===================================================================
--- index	2012-07-10 20:06:40 UTC (rev 7170)
+++ index	2012-07-10 21:19:27 UTC (rev 7171)
@@ -1076,8 +1076,9 @@
     <ol>
      <li><a href=#introduction-11><span class=secno>10.5.1 </span>Introduction</a>
       <ol>
-       <li><a href=#ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.1 </span>Ports as the basis of an object-capability model on the Web</a></li>
-       <li><a href=#ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.2 </span>Ports as the basis of abstracting out service implementations</a></ol></li>
+       <li><a href=#examples-5><span class=secno>10.5.1.1 </span>Examples</a></li>
+       <li><a href=#ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.2 </span>Ports as the basis of an object-capability model on the Web</a></li>
+       <li><a href=#ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.3 </span>Ports as the basis of abstracting out service implementations</a></ol></li>
      <li><a href=#message-channels><span class=secno>10.5.2 </span>Message channels</a></li>
      <li><a href=#message-ports><span class=secno>10.5.3 </span>Message ports</a>
       <ol>
@@ -83647,10 +83648,76 @@
   <pre>port1.postMessage(['hello', 'world'], 'http://example.com');</pre>
 
 
-  <h5 id=ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.1 </span>Ports as the basis of an object-capability model on the Web</h5>
+  <h5 id=examples-5><span class=secno>10.5.1.1 </span>Examples</h5>
 
   <p><i>This section is non-normative.</i></p>
 
+  <div class=example>
+
+   <p>In this example, two JavaScript libraries are connected to each
+   other using <code><a href=#messageport>MessagePort</a></code>s. This allows the libraries to
+   later be hosted in different frames, or in <code><a href=#worker>Worker</a></code>
+   objects, without any change to the APIs.</p>
+
+   <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
+<script src="compose-mail.js"></script> <!-- exposes a composer object -->
+<script>
+ var channel = new MessageChannel();
+ composer.addContactsProvider(channel.port1);
+ contacts.registerConsumer(channel.port2);
+</script></pre>
+
+   <p>Here's what the "addContactsProvider()" function's
+   implementation could look like:</p>
+
+   <pre>function addContactsProvider(port) {
+  port.onmessage = function (event) {
+    switch (event.data.messageType) {
+      'search-result': handleSearchResult(event.data.results); break;
+      'search-done': handleSearchDone(); break;
+      'search-error': handleSearchError(event.data.message); break;
+      // ...
+    }
+  };
+};</pre>
+
+   <p>Alternatively, it could be implemented as follows:</p>
+
+   <pre>function addContactsProvider(port) {
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-result')
+      handleSearchResult(event.data.results);
+  });
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-done')
+      handleSearchDone();
+  });
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-error')
+      handleSearchError(event.data.message);
+  });
+  // ...
+  port.start();
+};</pre>
+
+   <p>The key difference is that when using <code title=dom-EventTarget-addEventListener>addEventListener()</code>,
+   the <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> method must
+   also be invoked. When using <code title=handler-MessagePort-onmessage><a href=#handler-messageport-onmessage>onmessage</a></code>, the call to
+   <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> is implied.</p>
+
+   <p>The <code title=dom-MessagePort-start><a href=#dom-messageport-start>start()</a></code> method,
+   whether called explicitly or implicitly (by setting <code title=handler-MessagePort-onmessage><a href=#handler-messageport-onmessage>onmessage</a></code>), starts the
+   flow of messages: messages posted on message ports are initially
+   paused, so that they don't get dropped on the floor before the
+   script has had a chance to set up its handlers.</p>
+
+  </div>
+
+
+  <h5 id=ports-as-the-basis-of-an-object-capability-model-on-the-web><span class=secno>10.5.1.2 </span>Ports as the basis of an object-capability model on the Web</h5>
+
+  <p><i>This section is non-normative.</i></p>
+
   <p>Ports can be viewed as a way to expose limited capabilities (in
   the object-capability model sense) to other actors in the system.
   This can either be a weak capability system, where the ports are
@@ -83720,7 +83787,7 @@
   capability to add a single contact.</p>
 
 
-  <h5 id=ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.2 </span>Ports as the basis of abstracting out service implementations</h5>
+  <h5 id=ports-as-the-basis-of-abstracting-out-service-implementations><span class=secno>10.5.1.3 </span>Ports as the basis of abstracting out service implementations</h5>
 
   <p><i>This section is non-normative.</i></p>
 

Modified: source
===================================================================
--- source	2012-07-10 20:06:40 UTC (rev 7170)
+++ source	2012-07-10 21:19:27 UTC (rev 7171)
@@ -97287,6 +97287,75 @@
   <pre>port1.postMessage(['hello', 'world'], 'http://example.com');</pre>
 
 
+  <h5>Examples</h5>
+
+  <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->
+
+  <div class="example">
+
+   <p>In this example, two JavaScript libraries are connected to each
+   other using <code>MessagePort</code>s. This allows the libraries to
+   later be hosted in different frames, or in <code>Worker</code>
+   objects, without any change to the APIs.</p>
+
+   <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
+<script src="compose-mail.js"></script> <!-- exposes a composer object -->
+<script>
+ var channel = new MessageChannel();
+ composer.addContactsProvider(channel.port1);
+ contacts.registerConsumer(channel.port2);
+</script></pre>
+
+   <p>Here's what the "addContactsProvider()" function's
+   implementation could look like:</p>
+
+   <pre>function addContactsProvider(port) {
+  port.onmessage = function (event) {
+    switch (event.data.messageType) {
+      'search-result': handleSearchResult(event.data.results); break;
+      'search-done': handleSearchDone(); break;
+      'search-error': handleSearchError(event.data.message); break;
+      // ...
+    }
+  };
+};</pre>
+
+   <p>Alternatively, it could be implemented as follows:</p>
+
+   <pre>function addContactsProvider(port) {
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-result')
+      handleSearchResult(event.data.results);
+  });
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-done')
+      handleSearchDone();
+  });
+  port.addEventListener('message', function (event) {
+    if (event.data.messageType == 'search-error')
+      handleSearchError(event.data.message);
+  });
+  // ...
+  port.start();
+};</pre>
+
+   <p>The key difference is that when using <code
+   title="dom-EventTarget-addEventListener">addEventListener()</code>,
+   the <code title="dom-MessagePort-start">start()</code> method must
+   also be invoked. When using <code
+   title="handler-MessagePort-onmessage">onmessage</code>, the call to
+   <code title="dom-MessagePort-start">start()</code> is implied.</p>
+
+   <p>The <code title="dom-MessagePort-start">start()</code> method,
+   whether called explicitly or implicitly (by setting <code
+   title="handler-MessagePort-onmessage">onmessage</code>), starts the
+   flow of messages: messages posted on message ports are initially
+   paused, so that they don't get dropped on the floor before the
+   script has had a chance to set up its handlers.</p>
+
+  </div>
+
+
   <h5>Ports as the basis of an object-capability model on the Web</h5>
 
   <!--END dev-html--><p><i>This section is non-normative.</i></p><!--START dev-html-->




More information about the Commit-Watchers mailing list