W3C home > Mailing lists > Public > public-html-diffs@w3.org > June 2011

postmsg; hixie: add infrastructure to postMessage() to support ArrayBuffer cloning (whatwg r6273)

From: poot <cvsmail@w3.org>
Date: Thu, 23 Jun 2011 19:49:27 -0400
To: public-html-diffs@w3.org
Message-Id: <E1QZteJ-0002w6-7O@jay.w3.org>
postmsg; hixie: add infrastructure to postMessage() to support
ArrayBuffer cloning (whatwg r6273)

http://dev.w3.org/cvsweb/html5/postmsg/Overview.html?r1=1.87&r2=1.88&f=h
http://html5.org/tools/web-apps-tracker?from=6272&to=6273

===================================================================
RCS file: /sources/public/html5/postmsg/Overview.html,v
retrieving revision 1.87
retrieving revision 1.88
diff -u -d -r1.87 -r1.88
--- Overview.html	13 Jun 2011 23:39:17 -0000	1.87
+++ Overview.html	23 Jun 2011 23:49:00 -0000	1.88
@@ -211,7 +211,7 @@
 
    <h1>HTML5 Web Messaging</h1>
    
-   <h2 class="no-num no-toc" id="editor-s-draft-13-june-2011">Editor's Draft 13 June 2011</h2>
+   <h2 class="no-num no-toc" id="editor-s-draft-23-june-2011">Editor's Draft 23 June 2011</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>
@@ -311,7 +311,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 13 June 2011 Editor's Draft.
+  This specification is the 23 June 2011 Editor's Draft.
   </p><p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
   February 2004 W3C Patent Policy</a>. W3C maintains a <a href="http://www.w3.org/2004/01/pp-impl/42538/status" rel="disclosure">public list of
   any patent disclosures</a> made in connection with the deliverables
@@ -573,12 +573,12 @@
   disallowed for security reasons. It also requires that UAs be
   careful to allow access to certain properties but not others.</p>
 
-  </div><h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3><dl class="domintro"><dt><var title="">window</var> . <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage</a></code>(<var title="">message</var>, <var title="">targetOrigin</var> [, <var title="">ports</var> ])</dt>
+  </div><h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3><dl class="domintro"><dt><var title="">window</var> . <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage</a></code>(<var title="">message</var>, <var title="">targetOrigin</var> [, <var title="">transfer</var> ])</dt>
 
    <dd>
 
-    <p>Posts a message, optionally with an array of ports, to the
-    given window.</p>
+    <p>Posts a message to the given window. Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning
+    that they are no longer usable on the sending side.</p>
 
     <p>If the origin of the target window doesn't match the given
     origin, the message is discarded, to avoid information leakage. To
@@ -587,7 +587,8 @@
     message to same-origin targets only, without needing to explicitly
     state the origin, set the target origin to "<code title="">/</code>".</p>
 
-    <p>Throws an <code>INVALID_STATE_ERR</code> if the <var title="">ports</var> array contains duplicate ports.</p>
+    <p>Throws a <code>DATA_CLONE_ERR</code> if <var title="">transfer</var> array contains duplicate objects or if
+    <var title="">message</var> could not be cloned.</p>
 
    </dd>
 
@@ -603,9 +604,9 @@
   their readiness to receive messages, and for the parent to wait for
   this message before beginning posting messages.<div class="impl">
 
-  <p>When a script invokes the <dfn id="dom-window-postmessage" title="dom-window-postMessage"><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">ports</var>)</code></dfn> method (with two or three
+  <p>When a script invokes the <dfn id="dom-window-postmessage" title="dom-window-postMessage"><code>postMessage(<var title="">message</var>, <var title="">targetOrigin</var>, <var title="">transfer</var>)</code></dfn> method (with two or three
   arguments) on a <code>Window</code> object, the user agent must
-  follow these steps:
+  follow these steps:</p>
 
   <ol><li>
 
@@ -619,38 +620,47 @@
 
    <li>
 
-    <p>Let <var title="">message clone</var> be the result of
-    obtaining a <span>structured clone</span> of the <var title="">message</var> argument. If this throws an exception, then
-    throw that exception and abort these steps.</p>
+    <p>Let <var title="">new ports</var> be an empty array.</p>
 
    </li>
 
    <li>
 
-    <p>If the <var title="">ports</var> argument is present but any
-    <code><a href="#messageport">MessagePort</a></code> object is listed in <var title="">ports</var> more than once, or any of the
-    <code><a href="#messageport">MessagePort</a></code> objects listed in <var title="">ports</var> have already been cloned once before, then
-    throw an <code>INVALID_STATE_ERR</code> exception and abort these
-    steps.</p>
+    <p>Let <var title="">transfer map</var> be an empty association
+    list of pairs of <code>Transferable</code> objects.</p>
 
    </li>
 
    <li>
 
-    <p>Let <var title="">new ports</var> be an empty array.</p>
+    <p>If the method was invoked with a third argument <var title="">transfer</var>, run these substeps:</p>
 
-    <p>If the <var title="">ports</var> argument is present, then for
-    each port in <var title="">ports</var> in turn, obtain a new port
-    by <a href="#clone-a-port" title="clone a port">cloning</a> the port with the
-    <code>Window</code> object on which the method was invoked as the
-    owner of the clone, and append the clone to the <var title="">new
-    ports</var> array.</p>
+    <ol><li>
 
-    <p class="note">If the original <var title="">ports</var> argument
-    was omitted or empty, then the <var title="">new ports</var> array
-    will be empty.</p>
+      <p>If any object is listed in <var title="">transfer</var> more
+      than once, or any of the <code>Transferable</code> objects
+      listed in <var title="">transfer</var> have already been <span title="transfer a Transferable object">transfered</span> once
+      before, then throw a <code>DATA_CLONE_ERR</code> exception and
+      abort these steps.</p>
 
-   </li>
+     </li>
+
+     <li>
+
+      <p>If the <var title="">transfer</var> argument is present, then
+      for each object in <var title="">transfer</var> in turn, obtain
+      a new object by <span title="transfer a Transferable
+      object">transferring</span> the object to the
+      <code>Window</code> object on which the method was invoked, and
+      add a mapping from the old object to the new transferred object
+      to <var title="">transfer map</var>. If the objects are
+      <code><a href="#messageport">MessagePort</a></code> objects, also append the new
+      transferred object to the <var title="">new ports</var>
+      array.</p>
+
+     </li>
+
+    </ol></li>
 
    <li>
 
@@ -660,6 +670,15 @@
 
    <li>
 
+    <p>Let <var title="">message clone</var> be the result of
+    obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
+    map</var> as the <i>transfer map</i>. If this throws an exception,
+    then throw that exception and abort these steps.</p>
+
+   </li>
+
+   <li>
+
     <p>Return from the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method, but
     asynchronously continue running these steps.</p>
 
@@ -783,21 +802,23 @@
 
   </div><h3 id="message-ports"><span class="secno">5.3 </span>Message ports</h3><p>Each channel has two message ports. Data sent through one port is
   received by the other port, and vice versa.<pre class="idl">interface <dfn id="messageport">MessagePort</dfn> {
-  void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(in any message, in optional sequence&lt;<a href="#messageport">MessagePort</a>&gt; ports);  void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
+  void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(in any message, in optional sequence&lt;<span>Transferable</span>&gt; transfer);  void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
   void <a href="#dom-messageport-close" title="dom-MessagePort-close">close</a>();
 
   // event handlers
            attribute <span>Function</span>? <a href="#handler-messageport-onmessage" title="handler-MessagePort-onmessage">onmessage</a>;
 };
-<a href="#messageport">MessagePort</a> implements <span>EventTarget</span>;</pre><dl class="domintro"><dt><var title="">port</var> . <code title="dom-MessagePort-poseMessage">postMessage</code>(<var title="">message</var> [, <var title="">ports</var>] )</dt>
+<a href="#messageport">MessagePort</a> implements <span>EventTarget</span>;
+<a href="#messageport">MessagePort</a> implements <span>Transferable</span>;</pre><dl class="domintro"><dt><var title="">port</var> . <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage</a></code>(<var title="">message</var> [, <var title="">transfer</var>] )</dt>
 
    <dd>
 
-    <p>Posts a message through the channel, optionally with the given
-    ports.</p>
+    <p>Posts a message through the channel. Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning
+    that they are no longer usable on the sending side.</p>
 
-    <p>Throws an <code>INVALID_STATE_ERR</code> if the <var title="">ports</var> array contains either duplicate ports, or the
-    source or target port.</p>
+    <p>Throws a <code>DATA_CLONE_ERR</code> if <var title="">transfer</var> array contains duplicate objects or the
+    source or target ports, or if <var title="">message</var> could
+    not be cloned.</p>
 
    </dd>
 
@@ -834,7 +855,7 @@
   instantiate a new <code><a href="#messageport">MessagePort</a></code> object, and let its owner
   be <var title="">owner</var>.</p>
 
-  <hr><p>When the user agent is to <dfn id="entangle">entangle</dfn> two
+  <p>When the user agent is to <dfn id="entangle">entangle</dfn> two
   <code><a href="#messageport">MessagePort</a></code> objects, it must run the following
   steps:</p>
 
@@ -855,7 +876,7 @@
    <code><a href="#messagechannel">MessageChannel</a></code> object that represents this
    channel.)</li>
 
-  </ol><hr><p>When the user agent is to <dfn id="clone-a-port">clone a port</dfn> <var title="">original port</var>, with the clone being owned by <var title="">owner</var>, it must run the following steps, which return
+  </ol><p>When the user agent is to <dfn id="clone-a-port">clone a port</dfn> <var title="">original port</var>, with the clone being owned by <var title="">owner</var>, it must run the following steps, which return
   a new <code><a href="#messageport">MessagePort</a></code> object. These steps must be run
   atomically.</p>
 
@@ -886,70 +907,112 @@
    <li><p>Return <var title="">new port</var>. It is the
    clone.</li>
 
-  </ol><hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn>
+  </ol><p id="transferMessagePort">To <span title="transfer a Transferable
+  object">transfer</span> a <code><a href="#messageport">MessagePort</a></code> object <var title="">old</var> to a new owner <var title="">owner</var>, a user
+  agent must <a href="#clone-a-port" title="clone a port">clone</a> the <var title="">old</var> object with the cloned being owned by <var title="">owner</var>, and must return the resulting object.</p>
+
+  <hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn>
   method, when called on a port <var title="">source port</var>, must
   cause the user agent to run the following steps:</p>
 
   <ol><li><p>Let <var title="">target port</var> be the port with which
    <var title="">source port</var> is entangled, if any.</li>
 
-   <li><p>If the method was called with a second argument <var title="">ports</var>, then, if any <code><a href="#messageport">MessagePort</a></code> object
-   is listed in <var title="">ports</var> more than once, if any of the
-   <code><a href="#messageport">MessagePort</a></code> objects listed in <var title="">ports</var>
-   have already been cloned once before, or if any of the entries
-   in <var title="">ports</var> are either the <var title="">source
-   port</var> or the <var title="">target port</var> (if any), then
-   throw an <code>INVALID_STATE_ERR</code> exception.</li>
+   <li><p>Let <var title="">new owner</var> be the owner of <var title="">target port</var>, if there is a <var title="">target
+   port</var>, or else some arbitrary owner. (This <var title="">new
+   owner</var> is used when transfering objects below. If there is no
+   <var title="">target port</var>, the <code>Transferable</code>
+   objects given in the second argument, if any, are still <span title="transfer a Transferable object">transfered</span>, but since
+   they are then discarded, it doesn't matter where they are
+   transfered to.)</li>
 
-   <li><p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code>
-   interface, with the name <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is not
-   cancelable, and has no default action.</li>
+   <li>
 
-   <li><p>Let <var title="">message</var> be the method's first
-   argument.</li>
+    <p>Let <var title="">new ports</var> be an empty array.</p>
 
-   <li><p>Let <var title="">message clone</var> be the result of
-   obtaining a <span>structured clone</span> of <var title="">message</var>. If this throws an exception, then throw
-   that exception and abort these steps.</li>
+   </li>
 
-   <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code>
-   attribute of the event have the value of <var title="">message
-   clone</var>.</li>
+   <li>
 
-   <li><p>If the method was called with a second argument <var title="">ports</var>, then run the following substeps:</p>
+    <p>Let <var title="">transfer map</var> be an empty association
+    list of pairs of <code>Transferable</code> objects.</p>
 
-    <ol><li>
+   </li>
 
-      <p>Let <var title="">new ports</var> be an empty array.</p>
+   <li>
 
-      <p>For each port in <var title="">ports</var> in turn,
-      obtain a new port by <a href="#clone-a-port" title="clone a port">cloning</a>
-      the port with the owner of the <var title="">target port</var>
-      as the owner of the clone, and append the clone to the <var title="">new ports</var> array.</p>
+    <p>If the method was invoked with a second argument <var title="">transfer</var>, run these substeps:</p>
 
-      <p class="note">If the original <var title="">ports</var>
-      array was empty, then the <var title="">new ports</var> array will
-      also be empty.</p>
+    <ol><li>
+
+      <p>If any object is listed in <var title="">transfer</var> more
+      than once, or any of the <code>Transferable</code> objects
+      listed in <var title="">transfer</var> have already been <span title="transfer a Transferable object">transfered</span> once
+      before, then throw a <code>DATA_CLONE_ERR</code> exception and
+      abort these steps.</p>
 
      </li>
 
      <li>
 
-      <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span> array.</p>
+      <p>If any of the objects in <var title="">transfer</var> are
+      either the <var title="">source port</var> or the <var title="">target port</var> (if any), then throw a
+      <code>DATA_CLONE_ERR</code> exception and abort these
+      steps.</li>
+
+     </ol></li>
+
+     <li>
+
+      <p>If the <var title="">transfer</var> argument is present, then
+      for each object in <var title="">transfer</var> in turn, obtain
+      a new object by <span title="transfer a Transferable
+      object">transferring</span> the object to <var title="">new
+      owner</var>, and add a mapping from the old object to the new
+      transferred object to <var title="">transfer map</var>. If the
+      objects are <code><a href="#messageport">MessagePort</a></code> objects, also append the
+      new transferred object to the <var title="">new ports</var>
+      array.</p>
 
      </li>
 
-     <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code>
-     attribute of the event be the <var title="">new ports</var>
-     array.</li>
+    </ol><li>
 
-    </ol></li>
+    <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span> array.</p>
+
+   </li>
+
+   <li><p>Let <var title="">message</var> be the method's first
+   argument.</li>
+
+   <li>
+
+    <p>Let <var title="">message clone</var> be the result of
+    obtaining a <span>structured clone</span> of the <var title="">message</var> argument, with <var title="">transfer
+    map</var> as the <i>transfer map</i>. If this throws an exception,
+    then throw that exception and abort these steps.</p>
+
+   </li>
+
+   <li><p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code>
+   interface, with the name <code title="event-message"><a href="#event-message">message</a></code>, which does not bubble, is not
+   cancelable, and has no default action.</li>
+
+   <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code>
+   attribute of the event have the value of <var title="">message
+   clone</var>.</li>
+
+   <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code>
+   attribute of the event be the <var title="">new ports</var>
+   array.</li>
 
    <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var> is not entangled), then abort these
    steps.</li> 
    <li><p>Add the event to the <a href="#port-message-queue">port message queue</a> of <var title="">target port</var>.</li>
 
-  </ol><hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn>
+  
+
+  <hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn>
   method must enable its port's <a href="#port-message-queue">port message queue</a>, if it
   is not already enabled.</p>
Received on Thursday, 23 June 2011 23:49:30 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Thursday, 23 June 2011 23:49:30 GMT