W3C home > Mailing lists > Public > public-html-commits@w3.org > November 2012

html5/postmsg Overview.html,1.127,1.128

From: Ian Hickson via cvs-syncmail <cvsmail@w3.org>
Date: Fri, 02 Nov 2012 22:32:38 +0000
To: public-html-commits@w3.org
Message-Id: <E1TUPn4-0002ve-1D@lionel-hutz.w3.org>
Update of /sources/public/html5/postmsg
In directory hutz:/tmp/cvs-serv11234

Modified Files:
	Overview.html 
Log Message:
Provide a way for authors to broadcast to many ports without memory leaks. (whatwg r7502)

Index: Overview.html
===================================================================
RCS file: /sources/public/html5/postmsg/Overview.html,v
retrieving revision 1.127
retrieving revision 1.128
diff -u -d -r1.127 -r1.128
--- Overview.html	25 Oct 2012 18:10:28 -0000	1.127
+++ Overview.html	2 Nov 2012 22:32:35 -0000	1.128
@@ -216,7 +216,7 @@
 
    <h1>HTML5 Web Messaging</h1>
    
-   <h2 class="no-num no-toc" id="editor-s-draft-25-october-2012">Editor's Draft 25 October 2012</h2>
+   <h2 class="no-num no-toc" id="editor-s-draft-2-november-2012">Editor's Draft 2 November 2012</h2>
    <dl><dt>Latest Published Version:</dt>
     <dd><a href="http://www.w3.org/TR/webmessaging/">http://www.w3.org/TR/webmessaging/</a></dd>
     <dt>Latest Editor's Draft:</dt>
@@ -348,7 +348,7 @@
   </dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
   Working Group</a> is the W3C working group responsible for this
   specification's progress along the W3C Recommendation track.
-  This specification is the 25 October 2012 Editor's Draft.
+  This specification is the 2 November 2012 Editor's Draft.
   </p>
 
   
@@ -388,9 +388,9 @@
      <li><a href="#ports-as-the-basis-of-an-object-capability-model-on-the-web"><span class="secno">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">5.1.3 </span>Ports as the basis of abstracting out service implementations</a></ol></li>
    <li><a href="#message-channels"><span class="secno">5.2 </span>Message channels</a></li>
-   <li><a href="#message-ports"><span class="secno">5.3 </span>Message ports</a>
-    <ol>
-     <li><a href="#ports-and-garbage-collection"><span class="secno">5.3.1 </span>Ports and garbage collection</a></ol></ol></li>
+   <li><a href="#message-ports"><span class="secno">5.3 </span>Message ports</a></li>
+   <li><a href="#broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</a></li>
+   <li><a href="#ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</a></ol></li>
  <li><a class="no-num" href="#references">References</a></li>
  <li><a class="no-num" href="#acknowledgements">Acknowledgements</a></ol>
 
@@ -1464,7 +1464,106 @@
   </div>
 
 
-  <h4 id="ports-and-garbage-collection"><span class="secno">5.3.1 </span>Ports and garbage collection</h4>
+  <h3 id="broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</h3>
+
+  <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>
+
+
+  <h3 id="ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</h3>
 
   <div class="impl">
 
@@ -1498,13 +1597,17 @@
 
   
 
+  <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>
+
   </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
-  memory usage.</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
+  transient memory usage since garbage collection is not necessarily performed promptly.</p>
 
 
 
Received on Friday, 2 November 2012 22:32:43 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Friday, 2 November 2012 22:32:43 GMT