Skip to content
Browse files

[giow] (0) Provide a way for authors to broadcast to many ports witho…

…ut memory leaks.

Affected topics: DOM APIs, WebSocket API

git-svn-id: http://svn.whatwg.org/webapps@7502 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information...
1 parent 567cc47 commit 65b194ca88abecae8629d2167f911c0c10cfdec8 @Hixie Hixie committed
Showing with 354 additions and 43 deletions.
  1. +116 −15 complete.html
  2. +116 −15 index
  3. +122 −13 source
View
131 complete.html
@@ -248,7 +248,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 1 November 2012</h2>
+ <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 2 November 2012</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>
@@ -1102,9 +1102,9 @@ <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 1 November 2012</
<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>
- <li><a href=#ports-and-garbage-collection><span class=secno>10.5.3.1 </span>Ports and garbage collection</a></ol></ol></ol></li>
+ <li><a href=#message-ports><span class=secno>10.5.3 </span>Message ports</a></li>
+ <li><a href=#broadcasting-to-many-ports><span class=secno>10.5.4 </span>Broadcasting to many ports</a></li>
+ <li><a href=#ports-and-garbage-collection><span class=secno>10.5.5 </span>Ports and garbage collection</a></ol></ol></li>
<li><a href=#webstorage><span class=secno>11 </span>Web storage</a>
<ol>
<li><a href=#introduction-12><span class=secno>11.1 </span>Introduction</a></li>
@@ -85730,13 +85730,12 @@ <h4 id=garbage-collection-1><span class=secno>10.3.7 </span>Garbage collection</
</dl></div><!--data-component-->
-<!--POSTMSG-->
- <div data-component="Web Messaging (editor: Ian Hickson)"><!--TOPIC:DOM APIs-->
+<!--TOPIC:DOM APIs-->
+
-
<h3 id=web-messaging><span class=secno>10.4 </span><dfn id=crossDocumentMessages>Cross-document messaging</dfn></h3>
@@ -86680,7 +86679,106 @@ <h4 id=message-ports><span class=secno>10.5.3 </span>Message ports</h4>
</div>
- <h5 id=ports-and-garbage-collection><span class=secno>10.5.3.1 </span>Ports and garbage collection</h5>
+ <h4 id=broadcasting-to-many-ports><span class=secno>10.5.4 </span>Broadcasting to many ports</h4>
+
+ <p>Broadcasting to many ports is in principle relatively simple: keep an array of
+ <code><a href=#messageport>MessagePort</a></code> objects to send messages to, and iterate through the array to send a
+ message. However, this has one rather unfortuante effect: it prevents the ports from being garbage
+ collected, even if the other side has gone away.</p>
+
+ <p>To avoid this problem, the <code><a href=#portcollection>PortCollection</a></code> object can be used. It acts as an opaque
+ array of <code><a href=#messageport>MessagePort</a></code> objects, thus allowing the objects to be garbage collected when
+ they stop being relevant, while still allowing scripts to iterate over the
+ <code><a href=#messageport>MessagePort</a></code> objects.</p>
+
+ <pre class=idl>[<a href=#dom-portcollection title=dom-PortCollection>Constructor</a>] interface <dfn id=portcollection>PortCollection</dfn> {
+ void <a href=#dom-portcollection-add title=dom-PortCollection-add>add</a>(<a href=#messageport>MessagePort</a> port);
+ void <a href=#dom-portcollection-remove title=dom-PortCollection-remove>remove</a>(<a href=#messageport>MessagePort</a> port);
+ void <a href=#dom-portcollection-clear title=dom-PortCollection-clear>clear</a>();
+ void <a href=#dom-portcollection-iterate title=dom-PortCollection-iterate>iterate</a>(<a href=#portcollectioncallback>PortCollectionCallback</a> callback);
+};
+
+callback <dfn id=portcollectioncallback>PortCollectionCallback</dfn> = void (<a href=#messageport>MessagePort</a> port);</pre>
+
+ <dl class=domintro><dt><var title="">portCollection</var> = new <code title=dom-PortCollection><a href=#dom-portcollection>PortCollection</a></code>()</dt>
+
+ <dd>
+
+ <p>Returns a new empty <code><a href=#portcollection>PortCollection</a></code> object.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-add><a href=#dom-portcollection-add>add</a></code>(<var title="">port</var>)</dt>
+
+ <dd>
+
+ <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-remove><a href=#dom-portcollection-remove>remove</a></code>(<var title="">port</var>)</dt>
+
+ <dd>
+
+ <p>Removes <var title="">port</var> from the collection, if it is present.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-clear><a href=#dom-portcollection-clear>clear</a></code>()</dt>
+
+ <dd>
+
+ <p>Removes all ports from the collection.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-iterate><a href=#dom-portcollection-iterate>iterate</a></code>(<var title="">callback</var>)</dt>
+
+ <dd>
+
+ <p>Calls <var title="">callback</var> for each port in the collection.</p>
+
+ </dd>
+
+ </dl><div class=impl>
+
+ <p>A <code><a href=#portcollection>PortCollection</a></code> object has an initially empty <dfn id=concept-portcollection-list title=concept-PortCollection-list>list of ports</dfn>. When a <code><a href=#messageport>MessagePort</a></code> object in
+ a <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a> is garbage collected, it must be
+ silently removed from that <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>. Objects
+ in a <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a> are ordered chronologically by
+ the time at which they were most recently added; the least-recently added <code><a href=#messageport>MessagePort</a></code>
+ object is the first in the list, and the most-recently added <code><a href=#messageport>MessagePort</a></code> is the last
+ in the list.</p>
+
+ <p>The <dfn id=dom-portcollection title=dom-PortCollection><code>PortCollection()</code></dfn> constructor must return
+ a new <code><a href=#portcollection>PortCollection</a></code> object (with an empty <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>).</p>
+
+ <p>The <dfn id=dom-portcollection-add title=dom-PortCollection-add><code>add()</code></dfn> method must add the
+ <code><a href=#messageport>MessagePort</a></code> given by the argument to the <code><a href=#portcollection>PortCollection</a></code> object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, unless the <code><a href=#messageport>MessagePort</a></code> is
+ already in the <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, in which case the
+ method does nothing. (Calling this method with a port already in the list does not move the port
+ to the end of the list.)</p>
+
+ <p>The <dfn id=dom-portcollection-remove title=dom-PortCollection-remove><code>remove()</code></dfn> method must remove the
+ <code><a href=#messageport>MessagePort</a></code> given by the argument from the <code><a href=#portcollection>PortCollection</a></code> object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, unless the <code><a href=#messageport>MessagePort</a></code> is
+ not in the <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, in which case the
+ method does nothing.</p>
+
+ <p>The <dfn id=dom-portcollection-clear title=dom-PortCollection-clear><code>clear()</code></dfn> method must remove all
+ <code><a href=#messageport>MessagePort</a></code> objects from the <code><a href=#portcollection>PortCollection</a></code> object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, returning it to the initial empty state.
+ If the <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a> is already empty, the method
+ does nothing.</p>
+
+ <p>The <dfn id=dom-portcollection-iterate title=dom-PortCollection-iterate><code>iterate()</code></dfn> method must invoke its
+ <code><a href=#portcollectioncallback>PortCollectionCallback</a></code> argument once for each <code><a href=#messageport>MessagePort</a></code> object in the
+ object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, in the order defined
+ above, with each invocation being passed the corresponding <code><a href=#messageport>MessagePort</a></code> object as the
+ callback's sole argument.</p>
+
+ </div>
+
+
+ <h4 id=ports-and-garbage-collection><span class=secno>10.5.5 </span>Ports and garbage collection</h4>
<div class=impl>
@@ -86716,17 +86814,19 @@ <h5 id=ports-and-garbage-collection><span class=secno>10.5.3.1 </span>Ports and
<!-- ports in the ports attribute of a MessageEvent that isn't
dispatched yet are safe because the MessageEvent is safe -->
- </div>
+ <p>There are no strong references from a <code><a href=#portcollection>PortCollection</a></code> object to its
+ <code><a href=#messageport>MessagePort</a></code> objects. (That is in fact the whole point of <code><a href=#portcollection>PortCollection</a></code>
+ objects: they allow for <code><a href=#messageport>MessagePort</a></code> objects to be referenced without preventing them
+ from being garbage collected.)</p>
- <p class=note>Authors are strongly encouraged to explicitly close
- <code><a href=#messageport>MessagePort</a></code> objects to disentangle them, so that their
- resources can be recollected. Creating many <code><a href=#messageport>MessagePort</a></code>
- objects and discarding them without closing them can lead to high
- memory usage.</p>
+ </div>
+ <p class=note>Authors are strongly encouraged to explicitly close <code><a href=#messageport>MessagePort</a></code>
+ objects to disentangle them, so that their resources can be recollected. Creating many
+ <code><a href=#messageport>MessagePort</a></code> objects and discarding them without closing them can lead to high
+ transient memory usage since garbage collection is not necessarily performed promptly.</p>
- </div><!--data-component-->
@@ -105193,6 +105293,7 @@ <h3 class="no-num">Reflecting IDL attributes</h3>
<li><code><a href=#pagetransitionevent>PageTransitionEvent</a></code>
<li><code><a href=#path>Path</a></code>
<li><code><a href=#popstateevent>PopStateEvent</a></code>
+ <li><code><a href=#portcollection>PortCollection</a></code>
<li><code><a href=#propertynodelist>PropertyNodeList</a></code>
<li><code><a href=#radionodelist>RadioNodeList</a></code>
<li><code><a href=#sharedworker>SharedWorker</a></code>
View
131 index
@@ -248,7 +248,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 1 November 2012</h2>
+ <h2 class="no-num no-toc">Living Standard &mdash; Last Updated 2 November 2012</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>
@@ -1102,9 +1102,9 @@
<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>
- <li><a href=#ports-and-garbage-collection><span class=secno>10.5.3.1 </span>Ports and garbage collection</a></ol></ol></ol></li>
+ <li><a href=#message-ports><span class=secno>10.5.3 </span>Message ports</a></li>
+ <li><a href=#broadcasting-to-many-ports><span class=secno>10.5.4 </span>Broadcasting to many ports</a></li>
+ <li><a href=#ports-and-garbage-collection><span class=secno>10.5.5 </span>Ports and garbage collection</a></ol></ol></li>
<li><a href=#webstorage><span class=secno>11 </span>Web storage</a>
<ol>
<li><a href=#introduction-12><span class=secno>11.1 </span>Introduction</a></li>
@@ -85730,13 +85730,12 @@ dictionary <dfn id=closeeventinit>CloseEventInit</dfn> : <a href=#eventinit>Even
</dl></div><!--data-component-->
-<!--POSTMSG-->
- <div data-component="Web Messaging (editor: Ian Hickson)"><!--TOPIC:DOM APIs-->
+<!--TOPIC:DOM APIs-->
+
-
<h3 id=web-messaging><span class=secno>10.4 </span><dfn id=crossDocumentMessages>Cross-document messaging</dfn></h3>
@@ -86680,7 +86679,106 @@ interface <dfn id=messagechannel>MessageChannel</dfn> {
</div>
- <h5 id=ports-and-garbage-collection><span class=secno>10.5.3.1 </span>Ports and garbage collection</h5>
+ <h4 id=broadcasting-to-many-ports><span class=secno>10.5.4 </span>Broadcasting to many ports</h4>
+
+ <p>Broadcasting to many ports is in principle relatively simple: keep an array of
+ <code><a href=#messageport>MessagePort</a></code> objects to send messages to, and iterate through the array to send a
+ message. However, this has one rather unfortuante effect: it prevents the ports from being garbage
+ collected, even if the other side has gone away.</p>
+
+ <p>To avoid this problem, the <code><a href=#portcollection>PortCollection</a></code> object can be used. It acts as an opaque
+ array of <code><a href=#messageport>MessagePort</a></code> objects, thus allowing the objects to be garbage collected when
+ they stop being relevant, while still allowing scripts to iterate over the
+ <code><a href=#messageport>MessagePort</a></code> objects.</p>
+
+ <pre class=idl>[<a href=#dom-portcollection title=dom-PortCollection>Constructor</a>] interface <dfn id=portcollection>PortCollection</dfn> {
+ void <a href=#dom-portcollection-add title=dom-PortCollection-add>add</a>(<a href=#messageport>MessagePort</a> port);
+ void <a href=#dom-portcollection-remove title=dom-PortCollection-remove>remove</a>(<a href=#messageport>MessagePort</a> port);
+ void <a href=#dom-portcollection-clear title=dom-PortCollection-clear>clear</a>();
+ void <a href=#dom-portcollection-iterate title=dom-PortCollection-iterate>iterate</a>(<a href=#portcollectioncallback>PortCollectionCallback</a> callback);
+};
+
+callback <dfn id=portcollectioncallback>PortCollectionCallback</dfn> = void (<a href=#messageport>MessagePort</a> port);</pre>
+
+ <dl class=domintro><dt><var title="">portCollection</var> = new <code title=dom-PortCollection><a href=#dom-portcollection>PortCollection</a></code>()</dt>
+
+ <dd>
+
+ <p>Returns a new empty <code><a href=#portcollection>PortCollection</a></code> object.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-add><a href=#dom-portcollection-add>add</a></code>(<var title="">port</var>)</dt>
+
+ <dd>
+
+ <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-remove><a href=#dom-portcollection-remove>remove</a></code>(<var title="">port</var>)</dt>
+
+ <dd>
+
+ <p>Removes <var title="">port</var> from the collection, if it is present.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-clear><a href=#dom-portcollection-clear>clear</a></code>()</dt>
+
+ <dd>
+
+ <p>Removes all ports from the collection.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title=dom-PortCollection-iterate><a href=#dom-portcollection-iterate>iterate</a></code>(<var title="">callback</var>)</dt>
+
+ <dd>
+
+ <p>Calls <var title="">callback</var> for each port in the collection.</p>
+
+ </dd>
+
+ </dl><div class=impl>
+
+ <p>A <code><a href=#portcollection>PortCollection</a></code> object has an initially empty <dfn id=concept-portcollection-list title=concept-PortCollection-list>list of ports</dfn>. When a <code><a href=#messageport>MessagePort</a></code> object in
+ a <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a> is garbage collected, it must be
+ silently removed from that <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>. Objects
+ in a <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a> are ordered chronologically by
+ the time at which they were most recently added; the least-recently added <code><a href=#messageport>MessagePort</a></code>
+ object is the first in the list, and the most-recently added <code><a href=#messageport>MessagePort</a></code> is the last
+ in the list.</p>
+
+ <p>The <dfn id=dom-portcollection title=dom-PortCollection><code>PortCollection()</code></dfn> constructor must return
+ a new <code><a href=#portcollection>PortCollection</a></code> object (with an empty <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>).</p>
+
+ <p>The <dfn id=dom-portcollection-add title=dom-PortCollection-add><code>add()</code></dfn> method must add the
+ <code><a href=#messageport>MessagePort</a></code> given by the argument to the <code><a href=#portcollection>PortCollection</a></code> object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, unless the <code><a href=#messageport>MessagePort</a></code> is
+ already in the <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, in which case the
+ method does nothing. (Calling this method with a port already in the list does not move the port
+ to the end of the list.)</p>
+
+ <p>The <dfn id=dom-portcollection-remove title=dom-PortCollection-remove><code>remove()</code></dfn> method must remove the
+ <code><a href=#messageport>MessagePort</a></code> given by the argument from the <code><a href=#portcollection>PortCollection</a></code> object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, unless the <code><a href=#messageport>MessagePort</a></code> is
+ not in the <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, in which case the
+ method does nothing.</p>
+
+ <p>The <dfn id=dom-portcollection-clear title=dom-PortCollection-clear><code>clear()</code></dfn> method must remove all
+ <code><a href=#messageport>MessagePort</a></code> objects from the <code><a href=#portcollection>PortCollection</a></code> object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, returning it to the initial empty state.
+ If the <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a> is already empty, the method
+ does nothing.</p>
+
+ <p>The <dfn id=dom-portcollection-iterate title=dom-PortCollection-iterate><code>iterate()</code></dfn> method must invoke its
+ <code><a href=#portcollectioncallback>PortCollectionCallback</a></code> argument once for each <code><a href=#messageport>MessagePort</a></code> object in the
+ object's <a href=#concept-portcollection-list title=concept-PortCollection-list>list of ports</a>, in the order defined
+ above, with each invocation being passed the corresponding <code><a href=#messageport>MessagePort</a></code> object as the
+ callback's sole argument.</p>
+
+ </div>
+
+
+ <h4 id=ports-and-garbage-collection><span class=secno>10.5.5 </span>Ports and garbage collection</h4>
<div class=impl>
@@ -86716,17 +86814,19 @@ interface <dfn id=messagechannel>MessageChannel</dfn> {
<!-- ports in the ports attribute of a MessageEvent that isn't
dispatched yet are safe because the MessageEvent is safe -->
- </div>
+ <p>There are no strong references from a <code><a href=#portcollection>PortCollection</a></code> object to its
+ <code><a href=#messageport>MessagePort</a></code> objects. (That is in fact the whole point of <code><a href=#portcollection>PortCollection</a></code>
+ objects: they allow for <code><a href=#messageport>MessagePort</a></code> objects to be referenced without preventing them
+ from being garbage collected.)</p>
- <p class=note>Authors are strongly encouraged to explicitly close
- <code><a href=#messageport>MessagePort</a></code> objects to disentangle them, so that their
- resources can be recollected. Creating many <code><a href=#messageport>MessagePort</a></code>
- objects and discarding them without closing them can lead to high
- memory usage.</p>
+ </div>
+ <p class=note>Authors are strongly encouraged to explicitly close <code><a href=#messageport>MessagePort</a></code>
+ objects to disentangle them, so that their resources can be recollected. Creating many
+ <code><a href=#messageport>MessagePort</a></code> objects and discarding them without closing them can lead to high
+ transient memory usage since garbage collection is not necessarily performed promptly.</p>
- </div><!--data-component-->
@@ -105193,6 +105293,7 @@ if (s = prompt('What is your name?')) {
<li><code><a href=#pagetransitionevent>PageTransitionEvent</a></code>
<li><code><a href=#path>Path</a></code>
<li><code><a href=#popstateevent>PopStateEvent</a></code>
+ <li><code><a href=#portcollection>PortCollection</a></code>
<li><code><a href=#propertynodelist>PropertyNodeList</a></code>
<li><code><a href=#radionodelist>RadioNodeList</a></code>
<li><code><a href=#sharedworker>SharedWorker</a></code>
View
135 source
@@ -99711,14 +99711,13 @@ dictionary <dfn>CloseEventInit</dfn> : <span>EventInit</span> {
</div><!--data-component-->
-<!--START dev-html--><!--START w3c-html-->
-<!--END w3c-html--><!--POSTMSG-->
+<!--START dev-html-->
- <div data-component="Web Messaging (editor: Ian Hickson)"><!--TOPIC:DOM APIs-->
+<!--TOPIC:DOM APIs-->
- <!--START postmsg-->
+<!--START postmsg-->
<h3 id="web-messaging"><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h3>
@@ -100820,7 +100819,115 @@ interface <dfn>MessageChannel</dfn> {
</div>
- <h5>Ports and garbage collection</h5>
+ <h4>Broadcasting to many ports</h4>
+
+ <p>Broadcasting to many ports is in principle relatively simple: keep an array of
+ <code>MessagePort</code> objects to send messages to, and iterate through the array to send a
+ message. However, this has one rather unfortuante effect: it prevents the ports from being garbage
+ collected, even if the other side has gone away.</p>
+
+ <p>To avoid this problem, the <code>PortCollection</code> object can be used. It acts as an opaque
+ array of <code>MessagePort</code> objects, thus allowing the objects to be garbage collected when
+ they stop being relevant, while still allowing scripts to iterate over the
+ <code>MessagePort</code> objects.</p>
+
+ <pre class="idl">[<span title="dom-PortCollection">Constructor</span>] interface <dfn>PortCollection</dfn> {
+ void <span title="dom-PortCollection-add">add</span>(<span>MessagePort</span> port);
+ void <span title="dom-PortCollection-remove">remove</span>(<span>MessagePort</span> port);
+ void <span title="dom-PortCollection-clear">clear</span>();
+ void <span title="dom-PortCollection-iterate">iterate</span>(<span>PortCollectionCallback</span> callback);
+};
+
+callback <dfn>PortCollectionCallback</dfn> = void (<span>MessagePort</span> port);</pre>
+
+ <dl class="domintro">
+
+ <dt><var title="">portCollection</var> = new <code title="dom-PortCollection">PortCollection</code>()</dt>
+
+ <dd>
+
+ <p>Returns a new empty <code>PortCollection</code> object.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title="dom-PortCollection-add">add</code>(<var title="">port</var>)</dt>
+
+ <dd>
+
+ <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title="dom-PortCollection-remove">remove</code>(<var title="">port</var>)</dt>
+
+ <dd>
+
+ <p>Removes <var title="">port</var> from the collection, if it is present.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title="dom-PortCollection-clear">clear</code>()</dt>
+
+ <dd>
+
+ <p>Removes all ports from the collection.</p>
+
+ </dd>
+
+ <dt><var title="">portCollection</var> . <code title="dom-PortCollection-iterate">iterate</code>(<var title="">callback</var>)</dt>
+
+ <dd>
+
+ <p>Calls <var title="">callback</var> for each port in the collection.</p>
+
+ </dd>
+
+ </dl>
+
+ <div class="impl">
+
+ <p>A <code>PortCollection</code> object has an initially empty <dfn
+ title="concept-PortCollection-list">list of ports</dfn>. When a <code>MessagePort</code> object in
+ a <span title="concept-PortCollection-list">list of ports</span> is garbage collected, it must be
+ silently removed from that <span title="concept-PortCollection-list">list of ports</span>. Objects
+ in a <span title="concept-PortCollection-list">list of ports</span> are ordered chronologically by
+ the time at which they were most recently added; the least-recently added <code>MessagePort</code>
+ object is the first in the list, and the most-recently added <code>MessagePort</code> is the last
+ in the list.</p>
+
+ <p>The <dfn title="dom-PortCollection"><code>PortCollection()</code></dfn> constructor must return
+ a new <code>PortCollection</code> object (with an empty <span
+ title="concept-PortCollection-list">list of ports</span>).</p>
+
+ <p>The <dfn title="dom-PortCollection-add"><code>add()</code></dfn> method must add the
+ <code>MessagePort</code> given by the argument to the <code>PortCollection</code> object's <span
+ title="concept-PortCollection-list">list of ports</span>, unless the <code>MessagePort</code> is
+ already in the <span title="concept-PortCollection-list">list of ports</span>, in which case the
+ method does nothing. (Calling this method with a port already in the list does not move the port
+ to the end of the list.)</p>
+
+ <p>The <dfn title="dom-PortCollection-remove"><code>remove()</code></dfn> method must remove the
+ <code>MessagePort</code> given by the argument from the <code>PortCollection</code> object's <span
+ title="concept-PortCollection-list">list of ports</span>, unless the <code>MessagePort</code> is
+ not in the <span title="concept-PortCollection-list">list of ports</span>, in which case the
+ method does nothing.</p>
+
+ <p>The <dfn title="dom-PortCollection-clear"><code>clear()</code></dfn> method must remove all
+ <code>MessagePort</code> objects from the <code>PortCollection</code> object's <span
+ title="concept-PortCollection-list">list of ports</span>, returning it to the initial empty state.
+ If the <span title="concept-PortCollection-list">list of ports</span> is already empty, the method
+ does nothing.</p>
+
+ <p>The <dfn title="dom-PortCollection-iterate"><code>iterate()</code></dfn> method must invoke its
+ <code>PortCollectionCallback</code> argument once for each <code>MessagePort</code> object in the
+ object's <span title="concept-PortCollection-list">list of ports</span>, in the order defined
+ above, with each invocation being passed the corresponding <code>MessagePort</code> object as the
+ callback's sole argument.</p>
+
+ </div>
+
+
+ <h4>Ports and garbage collection</h4>
<div class="impl">
@@ -100856,21 +100963,23 @@ interface <dfn>MessageChannel</dfn> {
<!-- ports in the ports attribute of a MessageEvent that isn't
dispatched yet are safe because the MessageEvent is safe -->
+ <p>There are no strong references from a <code>PortCollection</code> object to its
+ <code>MessagePort</code> objects. (That is in fact the whole point of <code>PortCollection</code>
+ objects: they allow for <code>MessagePort</code> objects to be referenced without preventing them
+ from being garbage collected.)</p>
+
</div>
- <p class="note">Authors are strongly encouraged to explicitly close
- <code>MessagePort</code> objects to disentangle them, so that their
- resources can be recollected. Creating many <code>MessagePort</code>
- objects and discarding them without closing them can lead to high
- memory usage.</p>
+ <p class="note">Authors are strongly encouraged to explicitly close <code>MessagePort</code>
+ objects to disentangle them, so that their resources can be recollected. Creating many
+ <code>MessagePort</code> objects and discarding them without closing them can lead to high
+ transient memory usage since garbage collection is not necessarily performed promptly.</p>
<!--END postmsg-->
- </div><!--data-component-->
-
-<!--END dev-html-->
+<!--END dev-html-->
<!--FIXUP complete -1-->

0 comments on commit 65b194c

Please sign in to comment.
Something went wrong with that request. Please try again.