[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