Annotation of html5/postmsg/Overview.html, revision 1.165
1.114 ihickson 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"><html lang="en-US-x-Hixie"><title>HTML5 Web Messaging</title><style type="text/css">
1.1 ihickson 2: pre { margin-left: 2em; white-space: pre-wrap; }
3: h2 { margin: 3em 0 1em 0; }
4: h3 { margin: 2.5em 0 1em 0; }
5: h4 { margin: 2.5em 0 0.75em 0; }
6: h5, h6 { margin: 2.5em 0 1em; }
7: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
8: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
9: p { margin: 1em 0; }
10: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
11: dl, dd { margin-top: 0; margin-bottom: 0; }
12: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
13: dt + dt { margin-top: 0; }
14: dd dt { margin-top: 0.25em; margin-bottom: 0; }
15: dd p { margin-top: 0; }
16: dd dl + p { margin-top: 1em; }
17: dd table + p { margin-top: 1em; }
18: p + * > li, dd li { margin: 1em 0; }
19: dt, dfn { font-weight: bold; font-style: normal; }
1.91 ihickson 20: i, em { font-style: italic; }
1.1 ihickson 21: dt dfn { font-style: italic; }
22: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
23: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
24: pre em { font-weight: bolder; font-style: normal; }
25: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
26: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
27: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
1.39 ihickson 28: table thead, table tbody { border-bottom: solid; }
1.1 ihickson 29: table tbody th:first-child { border-left: solid; }
30: table tbody th { text-align: left; }
31: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
32: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
33:
34: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
35: .matrix, .matrix td { border: none; text-align: right; }
36: .matrix { margin-left: 2em; }
37: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
38: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
39: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
40:
41: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
1.94 ihickson 42: img.extra, p.overview { float: right; }
1.93 ihickson 43: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
1.1 ihickson 44: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
1.93 ihickson 45: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
1.1 ihickson 46: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
47: pre.css:first-line { color: #AAAA50; }
1.15 ihickson 48: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
1.1 ihickson 49: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
50: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
51: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
52: dl.domintro dd p { margin: 0.5em 0; }
1.99 ihickson 53: dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
1.1 ihickson 54: dl.switch { padding-left: 2em; }
55: dl.switch > dt { text-indent: -1.5em; }
56: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
57: dl.triple { padding: 0 0 0 1em; }
58: dl.triple dt, dl.triple dd { margin: 0; display: inline }
59: dl.triple dt:after { content: ':'; }
60: dl.triple dd:after { content: '\A'; white-space: pre; }
61: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
62: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
63: a .diff-new { border-bottom: 1px blue solid; }
64:
65: h2 { page-break-before: always; }
66: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
67: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
68:
1.64 ihickson 69: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
70: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 ihickson 71:
72: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
73: div.head p { margin: 0; }
74: div.head h1 { margin: 0; }
75: div.head .logo { float: right; margin: 0 1em; }
76: div.head .logo img { border: none } /* remove border from top image */
77: div.head dl { margin: 1em 0; }
78: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
79:
80: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
81: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
82: body > .toc > li > * { margin-bottom: 0.5em; }
83: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
84: .toc, .toc li { list-style: none; }
85:
86: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
87: .brief li { margin: 0; padding: 0; }
88: .brief li p { margin: 0; padding: 0; }
89:
90: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
91: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
92: .category-list li { display: inline; }
93: .category-list li:not(:last-child)::after { content: ', '; }
94: .category-list li > span, .category-list li > a { text-transform: lowercase; }
95: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
96:
97: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
98: .XXX > :first-child { margin-top: 0; }
99: p .XXX { line-height: 3em; }
100: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
101: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
102: .annotation :link, .annotation :visited { color: inherit; }
103: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
104: .annotation span { border: none ! important; }
105: .note { color: green; background: transparent; font-family: sans-serif; }
106: .warning { color: red; background: transparent; }
107: .note, .warning { font-weight: bolder; font-style: italic; }
1.91 ihickson 108: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 ihickson 109: p.note, div.note { padding: 0.5em 2em; }
110: span.note { padding: 0 2em; }
111: .note p:first-child, .warning p:first-child { margin-top: 0; }
112: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
113: .warning:before { font-style: normal; }
114: p.note:before { content: 'Note: '; }
115: p.warning:before { content: '\26A0 Warning! '; }
116:
117: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
118: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
119: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.57 ihickson 120: .bookkeeping dt { margin: 0.5em 2em 0; }
121: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 ihickson 122:
123: h4 { position: relative; z-index: 3; }
124: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
125: .element {
126: background: #EEEEFF;
127: color: black;
128: margin: 0 0 1em 0.15em;
129: padding: 0 1em 0.25em 0.75em;
130: border-left: solid #9999FF 0.25em;
131: position: relative;
132: z-index: 1;
133: }
134: .element:before {
135: position: absolute;
136: z-index: 2;
137: top: 0;
138: left: -1.15em;
139: height: 2em;
140: width: 0.9em;
141: background: #EEEEFF;
142: content: ' ';
143: border-style: none none solid solid;
144: border-color: #9999FF;
145: border-width: 0.25em;
146: }
147:
148: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
149: td > .example:only-child { margin: 0 0 0 0.1em; }
150:
151: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
152: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
153: ul.domTree li li { list-style: none; }
154: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
155: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
156: ul.domTree span { font-style: italic; font-family: serif; }
157: ul.domTree .t1 code { color: purple; font-weight: bold; }
158: ul.domTree .t2 { font-style: normal; font-family: monospace; }
159: ul.domTree .t2 .name { color: black; font-weight: bold; }
160: ul.domTree .t2 .value { color: blue; font-weight: normal; }
161: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
162: ul.domTree .t7 code, .domTree .t8 code { color: green; }
163: ul.domTree .t10 code { color: teal; }
164:
1.7 ihickson 165: body.dfnEnabled dfn { cursor: pointer; }
166: .dfnPanel {
167: display: inline;
168: position: absolute;
169: z-index: 10;
170: height: auto;
171: width: auto;
172: padding: 0.5em 0.75em;
173: font: small sans-serif, Droid Sans Fallback;
174: background: #DDDDDD;
175: color: black;
176: border: outset 0.2em;
177: }
178: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
179: .dfnPanel :link, .dfnPanel :visited { color: black; }
180: .dfnPanel p { font-weight: bolder; }
181: .dfnPanel * + p { margin-top: 0.25em; }
182: .dfnPanel li { list-style-position: inside; }
183:
1.1 ihickson 184: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
185: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
186: #configUI p label { display: block; }
187: #configUI #updateUI, #configUI .loginUI { text-align: center; }
188: #configUI input[type=button] { display: block; margin: auto; }
1.56 ihickson 189:
1.66 ihickson 190: fieldset { margin: 1em; padding: 0.5em 1em; }
191: fieldset > legend + * { margin-top: 0; }
1.63 ihickson 192: fieldset > :last-child { margin-bottom: 0; }
1.66 ihickson 193: fieldset p { margin: 0.5em 0; }
1.63 ihickson 194:
1.147 ihickson 195: </style><link rel="stylesheet" href="http://www.w3.org/StyleSheets/TR/W3C-ED" type="text/css"><meta content="noindex" name="robots"><script type="text/javascript">
1.1 ihickson 196: function getCookie(name) {
197: var params = location.search.substr(1).split("&");
198: for (var index = 0; index < params.length; index++) {
199: if (params[index] == name)
200: return "1";
201: var data = params[index].split("=");
202: if (data[0] == name)
203: return unescape(data[1]);
204: }
205: var cookies = document.cookie.split("; ");
206: for (var index = 0; index < cookies.length; index++) {
207: var data = cookies[index].split("=");
208: if (data[0] == name)
209: return unescape(data[1]);
210: }
211: return null;
212: }
1.114 ihickson 213: </script><body>
214: <div class="head" id="head">
1.147 ihickson 215: <p><a href="http://www.w3.org/"><img width="72" src="http://www.w3.org/Icons/w3c_home" alt="W3C" height="48"></a></p>
1.48 ihickson 216:
1.10 ihickson 217: <h1>HTML5 Web Messaging</h1>
1.79 ihickson 218:
1.165 ! ihickson 219: <h2 class="no-num no-toc" id="editor-s-draft-28-january-2014">Editor's Draft 28 January 2014</h2>
1.72 ihickson 220: <dl><dt>Latest Published Version:</dt>
1.70 abarsto 221: <dd><a href="http://www.w3.org/TR/webmessaging/">http://www.w3.org/TR/webmessaging/</a></dd>
1.1 ihickson 222: <dt>Latest Editor's Draft:</dt>
1.147 ihickson 223: <dd><a href="http://dev.w3.org/html5/postmsg/" class="latest-link">http://dev.w3.org/html5/postmsg/</a></dd>
1.82 ihickson 224:
1.113 ihickson 225:
1.1 ihickson 226: <dt>Previous Versions:</dt>
1.72 ihickson 227: <dd><a href="http://www.w3.org/TR/2010/WD-webmessaging-20101118/">http://www.w3.org/TR/2010/WD-webmessaging-20101118/</a></dd>
1.1 ihickson 228: <!-- :ZZZ -->
1.72 ihickson 229: <dt>Editor:</dt>
1.1 ihickson 230: <dd><a href="mailto:ian@hixie.ch">Ian Hickson</a>, Google, Inc.</dd>
1.3 ihickson 231: </dl><p class="copyright"><a href="http://www.w3.org/Consortium/Legal/ipr-notice#Copyright">Copyright</a>
1.115 ihickson 232: © 2012 <a href="http://www.w3.org/"><abbr title="World Wide
1.1 ihickson 233: Web Consortium">W3C</abbr></a><sup>®</sup> (<a href="http://www.csail.mit.edu/"><abbr title="Massachusetts
1.90 ihickson 234: Institute of Technology">MIT</abbr></a>, <a href="http://www.ercim.eu/"><abbr title="European Research
1.1 ihickson 235: Consortium for Informatics and Mathematics">ERCIM</abbr></a>, <a href="http://www.keio.ac.jp/">Keio</a>), All Rights Reserved. W3C
236: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#Legal_Disclaimer">liability</a>,
237: <a href="http://www.w3.org/Consortium/Legal/ipr-notice#W3C_Trademarks">trademark</a>
238: and <a href="http://www.w3.org/Consortium/Legal/copyright-documents">document
239: use</a> rules apply.</p>
1.6 ihickson 240:
1.48 ihickson 241:
1.6 ihickson 242: <!-- UNDER NO CIRCUMSTANCES IS THE FOLLOWING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
1.52 ihickson 243: <p class="alt">The bulk of the text of this specification is also
1.48 ihickson 244: available in the WHATWG <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html#comms">Web Applications 1.0</a> specification, under a license that permits
245: reuse of the specification text.</p>
1.6 ihickson 246: <!-- UNDER NO CIRCUMSTANCES IS THE PRECEDING PARAGRAPH TO BE REMOVED OR EDITED WITHOUT TALKING TO IAN FIRST -->
247:
1.48 ihickson 248:
1.114 ihickson 249: </div>
250:
251: <hr class="top"><h2 class="no-num no-toc" id="abstract">Abstract</h2>
252:
253: <p>This specification defines two mechanisms for communicating
254: between browsing contexts in HTML documents.</p>
255:
256: <h2 class="no-num no-toc" id="status-of-this-document">Status of This document</h2>
257:
258:
259:
260:
261: <p><em>This section describes the status of this document at the
1.1 ihickson 262: time of its publication. Other documents may supersede this
1.90 ihickson 263: document. A list of current W3C publications and the
264:
265: most recently formally published <!-- DO NOT CHANGE THIS BACK TO THE STANDARD BOILERPLATE, AS IT IS INACCURATE -->
266:
267: revision of this technical report can be found in the <a href="http://www.w3.org/TR/">W3C technical reports index</a> at
1.114 ihickson 268: http://www.w3.org/TR/.</em></p>
269:
270:
271:
272:
1.126 ihickson 273: <p>If you wish to make comments regarding this document, you can
1.114 ihickson 274: enter feedback using this form:</p>
275:
276: <form action="http://www.whatwg.org/specs/web-apps/current-work/file-spam.cgi" method="post">
1.63 ihickson 277: <fieldset><legend>Feedback Comments</legend>
1.147 ihickson 278: <input value="top" name="id" type="hidden"><input value="Web Messaging (editor: Ian Hickson)" name="component" type="hidden"><input value="html" name="response" type="hidden"><p><label for="feedbackBox">Please enter your feedback, carefully
1.65 ihickson 279: indicating the title of the section for which you are submitting
280: feedback, quoting the text that's wrong today if appropriate. If
281: you're suggesting a new feature, it's really important to say
282: <em>what</em> the problem you're trying to solve is. That's more
283: important than the solution, in fact.</label></p>
1.147 ihickson 284: <p><textarea name="text" rows="10" id="feedbackBox" cols="79"></textarea></p>
1.66 ihickson 285: <p class="note">Please don't use section numbers as these tend to
286: change rapidly and make your feedback harder to understand.</p>
1.65 ihickson 287: <script type="text/javascript">
1.85 ihickson 288: function checkFeedbackForm(form) {
289: if (form.elements.text.value.match(/^ *</)) {
290: alert('Please don\'t start your feedback with an angle bracket, instead explain what topic your feedback is about first.');
291: return true;
292: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
293: if (form.elements.text.value.match(/^Please enter your feedback, carefully/)) {
294: alert('Please enter your feedback, explaining what is wrong, and without repeating the instructions. Thanks!');
295: return true;
296: } else if (form.elements.text.value.match(/ [^ ]+ [^ ]+ [^ ]+ [^ ]+ /)) {
297: form.action = "http://www.whatwg.org/specs/web-apps/current-work/file-bug.cgi";
298: return true;
299: } else {
300: alert('Please include significantly more detail about exactly what problem you are trying to solve.');
301: return false;
302: }
303: }
304: }
1.66 ihickson 305: </script><p>
1.147 ihickson 306: <input value="Submit feedback" onclick="return checkFeedbackForm(form)" type="submit"><small>(Note: Your IP address and user agent will be publicly recorded for spam prevention purposes.)</small>
1.66 ihickson 307: </p>
1.114 ihickson 308: </fieldset></form>
309:
310:
311: <p>You can also e-mail feedback to <a href="mailto:public-webapps@w3.org">public-webapps@w3.org</a> (<a href="mailto:public-webapps-request@w3.org?subject=subscribe">subscribe</a>,
1.72 ihickson 312: <a href="http://lists.w3.org/Archives/Public/public-webapps/">archives</a>),
313: or <a href="mailto:whatwg@whatwg.org">whatwg@whatwg.org</a> (<a href="http://lists.whatwg.org/listinfo.cgi/whatwg-whatwg.org">subscribe</a>,
1.63 ihickson 314: <a href="http://lists.whatwg.org/pipermail/whatwg-whatwg.org/">archives</a>).
1.114 ihickson 315: All feedback is welcome.</p>
316:
317:
318: <p>Implementors should be aware that this specification is not
1.72 ihickson 319: stable. <strong>Implementors who are not taking part in the
320: discussions are likely to find the specification changing out from
321: under them in incompatible ways.</strong> Vendors interested in
322: implementing this specification before it eventually reaches the
323: Candidate Recommendation stage should join the aforementioned
1.114 ihickson 324: mailing lists and take part in the discussions.</p>
325:
326: <div id="multipage-common">
327: </div>
328:
329: <p>The latest
1.72 ihickson 330: stable version of the editor's draft of this specification is always
331: available on <a href="http://dev.w3.org/html5/postmsg/">the W3C CVS server</a>
332: and in the <a href="http://svn.whatwg.org/webapps/">WHATWG
333: Subversion repository</a>. The <a href="http://www.whatwg.org/specs/web-apps/current-work/complete.html">latest
1.1 ihickson 334: editor's working copy</a> (which may contain unfinished text in the
335: process of being prepared) contains the latest draft text of this
336: specification (amongst others). For more details, please see the <a href="http://wiki.whatwg.org/wiki/FAQ#What_are_the_various_versions_of_the_spec.3F">WHATWG
1.114 ihickson 337: FAQ</a>.</p>
338:
339: <p>Notifications of changes to this specification are sent along
1.72 ihickson 340: with notifications of changes to related specifications using the
1.114 ihickson 341: following mechanisms:</p>
342: <dl><dt>E-mail notifications of changes</dt>
1.1 ihickson 343: <dd>Commit-Watchers mailing list (complete source diffs): <a href="http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org">http://lists.whatwg.org/listinfo.cgi/commit-watchers-whatwg.org</a></dd>
344: <dt>Browsable version-control record of all changes:</dt>
345: <dd>CVSWeb interface with side-by-side diffs: <a href="http://dev.w3.org/cvsweb/html5/">http://dev.w3.org/cvsweb/html5/</a></dd>
346: <dd>Annotated summary with unified diffs: <a href="http://html5.org/tools/web-apps-tracker">http://html5.org/tools/web-apps-tracker</a></dd>
347: <dd>Raw Subversion interface: <code>svn checkout http://svn.whatwg.org/webapps/</code></dd>
1.72 ihickson 348: </dl><p>The W3C <a href="http://www.w3.org/2008/webapps/">Web Applications
349: Working Group</a> is the W3C working group responsible for this
350: specification's progress along the W3C Recommendation track.
1.165 ! ihickson 351: This specification is the 28 January 2014 Editor's Draft.
1.114 ihickson 352: </p>
353:
354:
355:
356: <p>This document was produced by a group operating under the <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/">5
1.147 ihickson 357: February 2004 W3C Patent Policy</a>. W3C maintains a <a rel="disclosure" href="http://www.w3.org/2004/01/pp-impl/42538/status">public list of
1.1 ihickson 358: any patent disclosures</a> made in connection with the deliverables
359: of the group; that page also includes instructions for disclosing a
360: patent. An individual who has actual knowledge of a patent which the
361: individual believes contains <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#def-essential">Essential
362: Claim(s)</a> must disclose the information in accordance with <a href="http://www.w3.org/Consortium/Patent-Policy-20040205/#sec-Disclosure">section
1.114 ihickson 363: 6 of the W3C Patent Policy</a>.</p>
364:
365:
366: <h2 class="no-num no-toc" id="contents">Table of Contents</h2>
367:
1.113 ihickson 368:
1.1 ihickson 369: <ol class="toc">
1.72 ihickson 370: <li><a href="#conformance-requirements"><span class="secno">1 </span>Conformance requirements</a>
1.1 ihickson 371: <ol>
1.72 ihickson 372: <li><a href="#dependencies"><span class="secno">1.1 </span>Dependencies</a></ol></li>
373: <li><a href="#terminology"><span class="secno">2 </span>Terminology</a></li>
1.162 ihickson 374: <li><a href="#the-messageevent-interfaces"><span class="secno">3 </span>The <code>MessageEvent</code> interfaces</a></li>
1.72 ihickson 375: <li><a href="#web-messaging"><span class="secno">4 </span>Cross-document messaging</a>
376: <ol>
377: <li><a href="#introduction"><span class="secno">4.1 </span>Introduction</a></li>
378: <li><a href="#security-postmsg"><span class="secno">4.2 </span>Security</a>
1.1 ihickson 379: <ol>
1.72 ihickson 380: <li><a href="#authors"><span class="secno">4.2.1 </span>Authors</a></li>
381: <li><a href="#user-agents"><span class="secno">4.2.2 </span>User agents</a></ol></li>
382: <li><a href="#posting-messages"><span class="secno">4.3 </span>Posting messages</a></ol></li>
383: <li><a href="#channel-messaging"><span class="secno">5 </span>Channel messaging</a>
1.1 ihickson 384: <ol>
1.100 ihickson 385: <li><a href="#introduction-0"><span class="secno">5.1 </span>Introduction</a>
386: <ol>
1.121 ihickson 387: <li><a href="#examples"><span class="secno">5.1.1 </span>Examples</a></li>
388: <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>
389: <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>
1.72 ihickson 390: <li><a href="#message-channels"><span class="secno">5.2 </span>Message channels</a></li>
1.128 ihickson 391: <li><a href="#message-ports"><span class="secno">5.3 </span>Message ports</a></li>
392: <li><a href="#broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</a></li>
393: <li><a href="#ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</a></ol></li>
1.147 ihickson 394: <li><a href="#references" class="no-num">References</a></li>
395: <li><a href="#acknowledgements" class="no-num">Acknowledgements</a></ol>
1.114 ihickson 396:
397: <hr><h2 id="conformance-requirements"><span class="secno">1 </span>Conformance requirements</h2>
398:
399: <p>All diagrams, examples, and notes in this specification are
1.72 ihickson 400: non-normative, as are all sections explicitly marked non-normative.
1.114 ihickson 401: Everything else in this specification is normative.</p>
402:
403: <p>The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
1.72 ihickson 404: "OPTIONAL" in the normative parts of this document are to be
405: interpreted as described in RFC2119. For readability, these words do
1.114 ihickson 406: not appear in all uppercase letters in this specification. <a href="#refsRFC2119">[RFC2119]</a></p>
407:
408: <p>Requirements phrased in the imperative as part of algorithms
1.72 ihickson 409: (such as "strip any leading space characters" or "return false and
410: abort these steps") are to be interpreted with the meaning of the
411: key word ("must", "should", "may", etc) used in introducing the
1.114 ihickson 412: algorithm.</p>
413:
414: <p>Some conformance requirements are phrased as requirements on
1.72 ihickson 415: attributes, methods or objects. Such requirements are to be
1.114 ihickson 416: interpreted as requirements on user agents.</p>
417:
418: <p>Conformance requirements phrased as algorithms or specific steps
1.72 ihickson 419: may be implemented in any manner, so long as the end result is
420: equivalent. (In particular, the algorithms defined in this
421: specification are intended to be easy to follow, and not intended to
1.114 ihickson 422: be performant.)</p>
423:
424: <p>The only conformance class defined by this specification is user
425: agents.</p>
426:
427: <p>User agents may impose implementation-specific limits on
1.72 ihickson 428: otherwise unconstrained inputs, e.g. to prevent denial of service
429: attacks, to guard against running out of memory, or to work around
1.114 ihickson 430: platform-specific limitations.</p>
431:
432: <p>When support for a feature is disabled (e.g. as an emergency
1.72 ihickson 433: measure to mitigate a security problem, or to aid in development, or
434: for performance reasons), user agents must act as if they had no
435: support for the feature whatsoever, and as if the feature was not
436: mentioned in this specification. For example, if a particular
437: feature is accessed via an attribute in a Web IDL interface, the
438: attribute itself would be omitted from the objects that implement
439: that interface — leaving the attribute on the object but
1.114 ihickson 440: making it return null or throw an exception is insufficient.</p>
441:
442:
443: <h3 id="dependencies"><span class="secno">1.1 </span>Dependencies</h3>
444:
445: <p>This specification relies on several other underlying
446: specifications.</p>
447:
448: <dl><dt>HTML</dt>
1.72 ihickson 449:
450: <dd>
451:
452: <p>Many fundamental concepts from HTML are used by this
453: specification. <a href="#refsHTML">[HTML]</a></p>
454:
455: </dd>
456:
457: <dt>WebIDL</dt>
458:
459: <dd>
460:
461: <p>The IDL blocks in this specification use the semantics of the
462: WebIDL specification. <a href="#refsWEBIDL">[WEBIDL]</a></p>
463:
464: </dd>
465:
1.114 ihickson 466: </dl><h2 id="terminology"><span class="secno">2 </span>Terminology</h2>
467:
468: <p>The construction "a <code title="">Foo</code> object", where
1.72 ihickson 469: <code title="">Foo</code> is actually an interface, is sometimes
470: used instead of the more accurate "an object implementing the
1.114 ihickson 471: interface <code title="">Foo</code>".</p>
472:
473: <p>The term DOM is used to refer to the API set made available to
1.72 ihickson 474: scripts in Web applications, and does not necessarily imply the
475: existence of an actual <code>Document</code> object or of any other
1.132 ihickson 476: <code>Node</code> objects as defined in the DOM specifications. <a href="#refsDOM">[DOM]</a></p>
1.114 ihickson 477:
478: <p>An IDL attribute is said to be <em>getting</em> when its value is
1.72 ihickson 479: being retrieved (e.g. by author script), and is said to be
1.114 ihickson 480: <em>setting</em> when a new value is assigned to it.</p>
481:
482:
483:
1.162 ihickson 484: <h2 id="the-messageevent-interfaces"><span class="secno">3 </span>The <code><a href="#messageevent">MessageEvent</a></code> interfaces</h2>
1.114 ihickson 485:
1.133 ihickson 486: <p>Messages in <span>server-sent events</span>, <span>Web sockets</span>, <a href="#web-messaging">cross-document
1.162 ihickson 487: messaging</a>, <a href="#channel-messaging">channel messaging</a>, and <span>broadcast channels</span> use the
488: <code><a href="#messageevent">MessageEvent</a></code> interface for their <code title="event-message">message</code>
489: events:</p>
1.114 ihickson 490:
1.164 ihickson 491: <pre class="idl">[Constructor(DOMString type, optional <a href="#messageeventinit">MessageEventInit</a> eventInitDict), Exposed=Window,Worker]
1.96 ihickson 492: interface <dfn id="messageevent">MessageEvent</dfn> : <span>Event</span> {
1.1 ihickson 493: readonly attribute any <a href="#dom-messageevent-data" title="dom-MessageEvent-data">data</a>;
494: readonly attribute DOMString <a href="#dom-messageevent-origin" title="dom-MessageEvent-origin">origin</a>;
495: readonly attribute DOMString <a href="#dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId">lastEventId</a>;
1.157 ihickson 496: readonly attribute DOMString <a href="#dom-messageevent-channel" title="dom-MessageEvent-channel">channel</a>;
1.96 ihickson 497: readonly attribute <a href="#messageport">MessagePort</a>[]? <a href="#dom-messageevent-ports" title="dom-MessageEvent-ports">ports</a>;
498: };
499:
1.165 ! ihickson 500: [Exposed=Window]
! 501: partial interface <a href="#messageevent">MessageEvent</a> {
! 502: readonly attribute (<span>WindowProxy</span> or <a href="#messageport">MessagePort</a>)? <a href="#dom-messageevent-source" title="dom-MessageEvent-source">source</a>;
! 503: }
! 504:
! 505: [Exposed=Worker]
! 506: partial interface <a href="#messageevent">MessageEvent</a> {
! 507: readonly attribute <a href="#messageport">MessagePort</a>? <a href="#dom-messageevent-source" title="dom-MessageEvent-source">source</a>;
! 508: }
! 509:
1.96 ihickson 510: dictionary <dfn id="messageeventinit">MessageEventInit</dfn> : <span>EventInit</span> {
511: any data;
512: DOMString origin;
513: DOMString lastEventId;
1.157 ihickson 514: DOMString channel;
1.149 ihickson 515: (<span>WindowProxy</span> or <a href="#messageport">MessagePort</a>)? source;
1.155 ihickson 516: sequence<<a href="#messageport">MessagePort</a>> ports;
1.114 ihickson 517: };</pre>
518:
519: <dl class="domintro"><dt><var title="">event</var> . <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code></dt>
1.1 ihickson 520:
521: <dd>
522:
523: <p>Returns the data of the message.</p>
524:
525: </dd>
526:
527: <dt><var title="">event</var> . <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code></dt>
528:
529: <dd>
530:
1.136 ihickson 531: <p>Returns the origin of the message, for <span>server-sent events</span> and
532: <a href="#web-messaging">cross-document messaging</a>.</p>
1.1 ihickson 533:
534: </dd>
535:
536: <dt><var title="">event</var> . <code title="dom-MessageEvent-lastEventId"><a href="#dom-messageevent-lasteventid">lastEventId</a></code></dt>
537:
538: <dd>
539:
1.136 ihickson 540: <p>Returns the <span title="concept-event-stream-last-event-id">last event ID string</span>, for
541: <span>server-sent events</span>.</p>
1.1 ihickson 542:
543: </dd>
544:
1.157 ihickson 545: <dt><var title="">event</var> . <code title="dom-MessageEvent-channel"><a href="#dom-messageevent-channel">channel</a></code></dt>
546:
547: <dd>
548:
549: <p>Returns the channel ID, for <span>broadcast channels</span>.</p>
550:
551: </dd>
552:
1.1 ihickson 553: <dt><var title="">event</var> . <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code></dt>
554:
555: <dd>
556:
1.136 ihickson 557: <p>Returns the <code>WindowProxy</code> of the source window, for <a href="#web-messaging">cross-document
1.163 ihickson 558: messaging</a>, and the <code><a href="#messageport">MessagePort</a></code> being attached, in the <code title="event-WorkerGlobalScope-connect">connect</code> event fired at
559: <code>SharedWorkerGlobalScope</code> objects.</p>
1.1 ihickson 560:
561: </dd>
562:
563: <dt><var title="">event</var> . <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code></dt>
564:
565: <dd>
566:
1.136 ihickson 567: <p>Returns the <code><a href="#messageport">MessagePort</a></code> array sent with the message, for <a href="#web-messaging">cross-document
568: messaging</a> and <a href="#channel-messaging">channel messaging</a>.</p>
1.1 ihickson 569:
570: </dd>
571:
572: </dl><div class="impl">
573:
1.153 ihickson 574: <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn> attribute must return the value
575: it was initialized to. When the object is created, this attribute must be initialized to null. It
1.96 ihickson 576: represents the message being sent.</p>
1.1 ihickson 577:
1.153 ihickson 578: <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute must return the
579: value it was initialized to. When the object is created, this attribute must be initialized to the
580: empty string. It represents, in <span>server-sent events</span> and <a href="#web-messaging">cross-document
581: messaging</a>, the <span>origin</span> of the document that sent the message (typically the
582: scheme, hostname, and port of the document, but not its path or fragment identifier).</p>
583:
584: <p>The <dfn id="dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId"><code>lastEventId</code></dfn> attribute must
585: return the value it was initialized to. When the object is created, this attribute must be
586: initialized to the empty string. It represents, in <span>server-sent events</span>, the <span title="concept-event-stream-last-event-id">last event ID string</span> of the event source.</p>
587:
1.157 ihickson 588: <p>The <dfn id="dom-messageevent-channel" title="dom-MessageEvent-channel"><code>channel</code></dfn> attribute must return the
589: value it was initialized to. When the object is created, this attribute must be initialized to the
590: empty string. It represents, in <span>broadcast channels</span>, the channel of the message.</p>
591:
1.153 ihickson 592: <p>The <dfn id="dom-messageevent-source" title="dom-MessageEvent-source"><code>source</code></dfn> attribute must return the
593: value it was initialized to. When the object is created, this attribute must be initialized to
594: null. It represents, in <a href="#web-messaging">cross-document messaging</a>, the <code>WindowProxy</code> of the
595: <span>browsing context</span> of the <code>Window</code> object from which the message came; and
1.162 ihickson 596: in the <code title="event-WorkerGlobalScope-connect">connect</code> events used by <span title="SharedWorkerGlobalScope">shared workers</span>, the newly connecting
1.153 ihickson 597: <code><a href="#messageport">MessagePort</a></code>.</p>
598:
599: <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn> attribute must return the
600: value it was initialized to. When the object is created, this attribute must be initialized to
601: null. It represents, in
1.155 ihickson 602: <a href="#web-messaging">cross-document messaging</a> and <a href="#channel-messaging">channel messaging</a>, the
1.153 ihickson 603: <code><a href="#messageport">MessagePort</a></code> array being sent, if any.</p>
1.1 ihickson 604:
1.114 ihickson 605: </div>
606:
607:
608: <h2 id="web-messaging"><span class="secno">4 </span><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h2>
609:
1.153 ihickson 610: <p>Web browsers, for security and privacy reasons, prevent documents in different domains from
611: affecting each other; that is, cross-site scripting is disallowed.</p>
612:
613: <p>While this is an important security feature, it prevents pages from different domains from
614: communicating even when those pages are not hostile. This section introduces a messaging system
615: that allows documents to communicate with each other regardless of their source domain, in a way
616: designed to not enable cross-site scripting attacks.</p>
1.114 ihickson 617:
618: <div class="impl">
1.1 ihickson 619:
1.153 ihickson 620: <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in
621: <a href="#web-messaging">cross-document messaging</a> is the <dfn id="posted-message-task-source">posted message task source</dfn>.</p>
1.1 ihickson 622:
1.114 ihickson 623: </div>
624:
625:
626: <h3 id="introduction"><span class="secno">4.1 </span>Introduction</h3>
627:
628: <p><i>This section is non-normative.</i></p>
629:
630: <div class="example">
1.1 ihickson 631:
1.153 ihickson 632: <p>For example, if document A contains an <code>iframe</code> element that contains document B,
633: and script in document A calls <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
634: <code>Window</code> object of document B, then a message event will be fired on that object,
635: marked as originating from the <code>Window</code> of document A. The script in document A might
1.1 ihickson 636: look like:</p>
637:
638: <pre>var o = document.getElementsByTagName('iframe')[0];
639: o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
640:
1.153 ihickson 641: <p>To register an event handler for incoming events, the script would use <code title="">addEventListener()</code> (or similar mechanisms). For example, the script in document B
642: might look like:</p>
1.1 ihickson 643:
644: <pre>window.addEventListener('message', receiver, false);
645: function receiver(e) {
646: if (e.origin == 'http://example.com') {
647: if (e.data == 'Hello world') {
648: e.source.postMessage('Hello', e.origin);
649: } else {
650: alert(e.data);
651: }
652: }
653: }</pre>
654:
1.153 ihickson 655: <p>This script first checks the domain is the expected domain, and then looks at the message,
656: which it either displays to the user, or responds to by sending a message back to the document
657: which sent the message in the first place.</p>
1.1 ihickson 658:
1.114 ihickson 659: </div>
660:
661:
662:
663: <h3 id="security-postmsg"><span class="secno">4.2 </span>Security</h3>
664:
665: <div class="impl">
1.1 ihickson 666:
1.72 ihickson 667: <h4 id="authors"><span class="secno">4.2.1 </span>Authors</h4>
1.1 ihickson 668:
1.114 ihickson 669: </div>
670:
1.153 ihickson 671: <p id="security-4" class="warning">Use of this API requires extra care to protect users from
672: hostile entities abusing a site for their own purposes.</p>
673:
674: <p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to
675: ensure that messages are only accepted from domains that they expect to receive messages from.
676: Otherwise, bugs in the author's message handling code could be exploited by hostile sites.</p>
677:
678: <p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code>
679: attribute, authors should also check that the data in question is of the expected format.
680: Otherwise, if the source of the event has been attacked using a cross-site scripting flaw, further
681: unchecked processing of information sent using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method could result in the attack being
682: propagated into the receiver.</p>
683:
684: <p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var>
685: argument in messages that contain any confidential information, as otherwise there is no way to
686: guarantee that the message is only delivered to the recipient to which it was intended.</p>
687:
688: <hr><p>Authors who accept messages from any origin are encouraged to consider the risks of a
689: denial-of-service attack. An attacker could send a high volume of messages; if the receiving page
690: performs expensive computation or causes network traffic to be sent for each such message, the
691: attacker's message could be multplied into a denial-of-service attack. Authors are encouraged to
692: employ rate limiting (only accepting a certain number of messages per minute) to make such attacks
693: impractical.</p>
1.114 ihickson 694:
695:
696: <div class="impl">
1.1 ihickson 697:
1.72 ihickson 698: <h4 id="user-agents"><span class="secno">4.2.2 </span>User agents</h4>
1.1 ihickson 699:
1.153 ihickson 700: <p>The integrity of this API is based on the inability for scripts of one <span>origin</span> to
701: post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in
702: other origins (those that are not the <span title="same origin">same</span>).</p>
703:
704: <p class="note">Implementors are urged to take extra care in the implementation of this feature.
705: It allows authors to transmit information from one domain to another domain, which is normally
706: disallowed for security reasons. It also requires that UAs be careful to allow access to certain
707: properties but not others.</p>
708:
709: <hr><p>User agents are also encouraged to consider rate-limiting message traffic between different
710: <span title="origin">origins</span>, to protect naïve sites from denial-of-service
711: attacks.</p>
1.108 ihickson 712:
1.114 ihickson 713: </div>
714:
715:
716:
717: <h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3>
718:
719: <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>
1.1 ihickson 720:
721: <dd>
722:
1.153 ihickson 723: <p>Posts a message to the given window. Messages can be structured objects, e.g. nested objects
724: and arrays, can contain JavaScript values (strings, numbers, <code>Date</code>s, etc), and can
725: contain certain data objects such as <code>File</code> <code>Blob</code>, <code>FileList</code>,
726: and <code>ArrayBuffer</code> objects.</p>
727:
728: <p>Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning that
729: they are no longer usable on the sending side.</p>
730:
731: <p>If the origin of the target window doesn't match the given origin, the message is discarded,
732: to avoid information leakage. To send the message to the target regardless of origin, set the
733: target origin to "<code title="">*</code>". To restrict the message to same-origin targets only,
734: without needing to explicitly state the origin, set the target origin to "<code title="">/</code>".</p>
1.1 ihickson 735:
1.138 ihickson 736: <p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
737: duplicate objects or if <var title="">message</var> could not be cloned.</p>
1.1 ihickson 738:
739: </dd>
740:
1.153 ihickson 741: </dl><p class="note">When posting a message to a <code>Window</code> of a <span>browsing context</span>
742: that has just been navigated to a new <code>Document</code> is likely to result in the message not
743: receiving its intended recipient: the scripts in the target <span>browsing context</span> have to
744: have had time to set up listeners for the messages. Thus, for instance, in situations where a
745: message is to be sent to the <code>Window</code> of newly created child <code>iframe</code>,
746: authors are advised to have the child <code>Document</code> post a message to their parent
747: announcing their readiness to receive messages, and for the parent to wait for this message before
748: beginning posting messages.</p>
1.114 ihickson 749:
750: <div class="impl">
1.1 ihickson 751:
1.153 ihickson 752: <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
753: <code>Window</code> object, the user agent must follow these steps:</p>
1.1 ihickson 754:
1.163 ihickson 755: <ol><li><p>If the value of the <var title="">targetOrigin</var> argument is neither a single U+002A
756: ASTERISK character (*), a single U+002F SOLIDUS character (/), nor an <span>absolute URL</span>,
757: then throw a <code>SyntaxError</code> exception and abort the overall set of steps.</li>
1.1 ihickson 758:
1.163 ihickson 759: <li><p>Let <var title="">new ports</var> be an empty array.</li>
1.1 ihickson 760:
1.163 ihickson 761: <li><p>Let <var title="">transfer map</var> be an empty association list of
762: <code>Transferable</code> objects to placeholder objects.</li>
1.1 ihickson 763:
764: <li>
765:
1.153 ihickson 766: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
767: substeps:</p>
1.88 ihickson 768:
1.163 ihickson 769: <ol><li><p>If any object is listed in <var title="">transfer</var> more than once, or any of the
770: <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
771: <code>DataCloneError</code> exception and abort these steps.</li>
772:
773: <li><p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
774: mapping from <var title="">x</var> to a new unique placeholder object created for <var title="">x</var> to <var title="">transfer map</var>, and if <var title="">x</var> is a
775: <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
776: ports</var> array.</li>
1.88 ihickson 777:
778: </ol></li>
779:
1.163 ihickson 780: <li><p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
781: clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
782: as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
783: these steps.</li>
1.1 ihickson 784:
1.106 ihickson 785: <li>
786:
1.153 ihickson 787: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
788: substeps:</p>
1.105 ihickson 789:
1.163 ihickson 790: <ol><li><p>Let <var title="">new owner</var> be the <span>script settings object</span> of the
791: <code>Window</code> object on which the method was invoked.</li>
1.105 ihickson 792:
1.163 ihickson 793: <li><p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain
794: a new object <var title="">y</var> by <span title="transfer a Transferable
795: object">transferring</span> the object <var title="">x</var> to <var title="">new
796: owner</var>, and replace the placeholder object that was created for the object <var title="">x</var> by the new object <var title="">y</var> wherever the placeholder exists
797: (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</li>
1.105 ihickson 798:
1.106 ihickson 799: </ol></li>
800:
1.163 ihickson 801: <li><p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read
802: only</span> array.</li>
1.1 ihickson 803:
1.163 ihickson 804: <li><p>Return from the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method, but
805: asynchronously continue running these steps.</li>
1.1 ihickson 806:
807: <li>
808:
1.163 ihickson 809: <p>If the <var title="">targetOrigin</var> argument is a single literal U+002F SOLIDUS
810: character (/), and the <code>Document</code> of the <code>Window</code> object on which the
811: method was invoked does not have the <span>same origin</span> as the <span>responsible
812: document</span> specified by the <span>entry settings object</span>, then abort these steps
813: silently.</p>
1.153 ihickson 814:
815: <p>Otherwise, if the <var title="">targetOrigin</var> argument is an <span>absolute URL</span>,
816: and the <code>Document</code> of the <code>Window</code> object on which the method was invoked
1.163 ihickson 817: does not have the <span>same origin</span> as <var title="">targetOrigin</var>, then abort
818: these steps silently.</p>
1.153 ihickson 819:
820: <p>Otherwise, the <var title="">targetOrigin</var> argument is a single literal U+002A ASTERISK
821: character (*), and no origin check is made.</p>
1.1 ihickson 822:
823: </li>
824:
1.163 ihickson 825: <li><p>Create a <span title="concept-events-trusted">trusted</span> event that uses the
826: <code><a href="#messageevent">MessageEvent</a></code> interface, with the event type <code title="event-message">message</code>, which does not bubble, is not cancelable, and has no
827: default action. The <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute must be
828: initialized to the value of <var title="">message clone</var>, the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute must be initialized to the <span title="Unicode serialization of an origin">Unicode serialization</span> of the
829: <span>origin</span> specified by the <span>incumbent settings object</span>, the <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code> attribute must be initialized to the
830: <code>WindowProxy</code> object corresponding to the <span>global object</span> (a
831: <code>Window</code> object) specified by the <span>incumbent settings object</span>, and the
832: <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code> attribute must be initialized to the <var title="">new ports</var> array.</li>
833:
1.1 ihickson 834:
1.163 ihickson 835: <li><p><span>Queue a task</span> to <span title="concept-event-dispatch">dispatch</span> the
836: event created in the previous step at the <code>Window</code> object on which the method was
837: invoked. The <span>task source</span> for this <span title="concept-task">task</span> is the
838: <a href="#posted-message-task-source">posted message task source</a>.</li>
1.1 ihickson 839:
1.114 ihickson 840: </ol></div>
841:
842:
843:
844:
845: <h2 id="channel-messaging"><span class="secno">5 </span><dfn>Channel messaging</dfn></h2>
846:
847: <h3 id="introduction-0"><span class="secno">5.1 </span>Introduction</h3>
848:
849: <p><i>This section is non-normative.</i></p>
850:
1.153 ihickson 851: <p>To enable independent pieces of code (e.g. running in different <span title="browsing
852: context">browsing contexts</span>) to communicate directly, authors can use <a href="#channel-messaging">channel
1.114 ihickson 853: messaging</a>.</p>
854:
1.153 ihickson 855: <p>Communication channels in this mechanism are implemented as two-ways pipes, with a port at each
856: end. Messages sent in one port are delivered at the other port, and vice-versa. Messages are
1.114 ihickson 857: asynchronous, and delivered as DOM events.</p>
858:
1.153 ihickson 859: <p>To create a connection (two "entangled" ports), the <code title="">MessageChannel()</code>
860: constructor is called:</p>
1.114 ihickson 861:
862: <pre>var channel = new MessageChannel();</pre>
863:
1.153 ihickson 864: <p>One of the ports is kept as the local port, and the other port is sent to the remote code, e.g.
865: using <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code>:</p>
1.114 ihickson 866:
867: <pre>otherWindow.postMessage('hello', 'http://example.com', [channel.port2]);</pre>
868:
869: <p>To send messages, the <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage()</a></code> method on
870: the port is used:</p>
871:
872: <pre>channel.port1.postMessage('hello');</pre>
873:
1.162 ihickson 874: <p>To receive messages, one listens to <code title="event-message">message</code> events:</p>
1.114 ihickson 875:
876: <pre>channel.port1.onmessage = handleMessage;
1.1 ihickson 877: function handleMessage(event) {
878: // message is in event.data
879: // ...
1.114 ihickson 880: }</pre>
881:
1.153 ihickson 882: <p>Data sent on a port can be structured data; for example here an array of strings is passed on a
883: <code><a href="#messageport">MessagePort</a></code>:</p>
1.114 ihickson 884:
1.140 ihickson 885: <pre>port1.postMessage(['hello', 'world']);</pre>
1.114 ihickson 886:
887:
1.121 ihickson 888: <h4 id="examples"><span class="secno">5.1.1 </span>Examples</h4>
889:
890: <p><i>This section is non-normative.</i></p>
891:
892: <div class="example">
893:
1.153 ihickson 894: <p>In this example, two JavaScript libraries are connected to each other using
895: <code><a href="#messageport">MessagePort</a></code>s. This allows the libraries to later be hosted in different frames, or
896: in <code>Worker</code> objects, without any change to the APIs.</p>
1.121 ihickson 897:
898: <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
899: <script src="compose-mail.js"></script> <!-- exposes a composer object -->
900: <script>
901: var channel = new MessageChannel();
902: composer.addContactsProvider(channel.port1);
903: contacts.registerConsumer(channel.port2);
904: </script></pre>
905:
1.153 ihickson 906: <p>Here's what the "addContactsProvider()" function's implementation could look like:</p>
1.121 ihickson 907:
908: <pre>function addContactsProvider(port) {
909: port.onmessage = function (event) {
910: switch (event.data.messageType) {
911: 'search-result': handleSearchResult(event.data.results); break;
912: 'search-done': handleSearchDone(); break;
913: 'search-error': handleSearchError(event.data.message); break;
914: // ...
915: }
916: };
917: };</pre>
918:
919: <p>Alternatively, it could be implemented as follows:</p>
920:
921: <pre>function addContactsProvider(port) {
922: port.addEventListener('message', function (event) {
923: if (event.data.messageType == 'search-result')
924: handleSearchResult(event.data.results);
925: });
926: port.addEventListener('message', function (event) {
927: if (event.data.messageType == 'search-done')
928: handleSearchDone();
929: });
930: port.addEventListener('message', function (event) {
931: if (event.data.messageType == 'search-error')
932: handleSearchError(event.data.message);
933: });
934: // ...
935: port.start();
936: };</pre>
937:
1.153 ihickson 938: <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>
939:
940: <p>The <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method, whether called explicitly or
941: implicitly (by setting <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code>), starts the
942: flow of messages: messages posted on message ports are initially paused, so that they don't get
943: dropped on the floor before the script has had a chance to set up its handlers.</p>
1.121 ihickson 944:
945: </div>
946:
947:
948: <h4 id="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</h4>
1.114 ihickson 949:
950: <p><i>This section is non-normative.</i></p>
951:
1.153 ihickson 952: <p>Ports can be viewed as a way to expose limited capabilities (in the object-capability model
953: sense) to other actors in the system. This can either be a weak capability system, where the ports
954: are merely used as a convenient model within a particular origin, or as a strong capability model,
955: where they are provided by one origin <var title="">provider</var> as the only mechanism by which
956: another origin <var title="">consumer</var> can effect change in or obtain information from <var title="">provider</var>.</p>
957:
958: <p>For example, consider a situation in which a social Web site embeds in one <code>iframe</code>
959: the user's e-mail contacts provider (an address book site, from a second origin), and in a second
960: <code>iframe</code> a game (from a third origin). The outer social site and the game in the second
961: <code>iframe</code> cannot access anything inside the first <code>iframe</code>; together they can
962: only:</p>
963:
964: <ul class="brief"><li><span>Navigate</span> the <code>iframe</code> to a new <span>URL</span>, such as the same
965: <span>URL</span> but with a different fragment identifier, causing the <code>Window</code> in the
966: <code>iframe</code> to receive a <code title="event-hashchange">hashchange</code> event.</li>
1.100 ihickson 967:
1.153 ihickson 968: <li>Resize the <code>iframe</code>, causing the <code>Window</code> in the <code>iframe</code> to
969: receive a <code title="event-resize">resize</code> event.</li>
1.100 ihickson 970:
971:
972:
1.162 ihickson 973: <li>Send a <code title="event-message">message</code> event to the <code>Window</code> in the
1.153 ihickson 974: <code>iframe</code> using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">window.postMessage()</a></code>
1.100 ihickson 975: API.</li>
976:
1.153 ihickson 977: </ul><p>The contacts provider can use these methods, most particularly the third one, to provide an API
978: that can be accessed by other origins to manipulate the user's address book. For example, it could
1.100 ihickson 979: respond to a message "<code title="">add-contact Guillaume Tell
1.153 ihickson 980: <tell@pomme.example.net></code>" by adding the given person and e-mail address to the user's
981: address book.</p>
982:
983: <p>To avoid any site on the Web being able to manipulate the user's contacts, the contacts
984: provider might only allow certain trusted sites, such as the social site, to do this.</p>
1.114 ihickson 985:
1.153 ihickson 986: <p>Now suppose the game wanted to add a contact to the user's address book, and that the social
987: site was willing to allow it to do so on its behalf, essentially "sharing" the trust that the
988: contacts provider had with the social site. There are several ways it could do this; most simply,
989: it could just proxy messages between the game site and the contacts site. However, this solution
990: has a number of difficulties: it requires the social site to either completely trust the game site
991: not to abuse the privilege, or it requires that the social site verify each request to make sure
992: it's not a request that it doesn't want to allow (such as adding multiple contacts, reading the
993: contacts, or deleting them); it also requires some additional complexity if there's ever the
994: possibility of multiple games simultaneously trying to interact with the contacts provider.</p>
995:
996: <p>Using message channels and <code><a href="#messageport">MessagePort</a></code> objects, however, all of these problems can
997: go away. When the game tells the social site that it wants to add a contact, the social site can
998: ask the contacts provider not for it to add a contact, but for the <em>capability</em> to add a
999: single contact. The contacts provider then creates a pair of <code><a href="#messageport">MessagePort</a></code> objects, and
1000: sends one of them back to the social site, who forwards it on to the game. The game and the
1001: contacts provider then have a direct connection, and the contacts provider knows to only honor a
1002: single "add contact" request, nothing else. In other words, the game has been granted the
1.114 ihickson 1003: capability to add a single contact.</p>
1004:
1005:
1.121 ihickson 1006: <h4 id="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</h4>
1.114 ihickson 1007:
1008: <p><i>This section is non-normative.</i></p>
1009:
1.153 ihickson 1010: <p>Continuing the example from the previous section, consider the contacts provider in particular.
1011: While an initial implementation might have simply used <code>XMLHttpRequest</code> objects in the
1012: service's <code>iframe</code>, an evolution of the service might instead want to use a <span title="SharedWorker">shared worker</span> with a single <code>WebSocket</code> connection.</p>
1013:
1014: <p>If the initial design used <code><a href="#messageport">MessagePort</a></code> objects to grant capabilities, or even just
1015: to allow multiple simultaneous independent sessions, the service implementation can switch from
1016: the <code>XMLHttpRequest</code>s-in-each-<code>iframe</code> model to the
1017: shared-<code>WebSocket</code> model without changing the API at all: the ports on the service
1018: provider side can all be forwarded to the shared worker without it affecting the users of the API
1019: in the slightest.</p>
1.114 ihickson 1020:
1021:
1022:
1023: <h3 id="message-channels"><span class="secno">5.2 </span>Message channels</h3>
1024:
1.164 ihickson 1025: <pre class="idl">[<a href="#dom-messagechannel" title="dom-MessageChannel">Constructor</a>, Exposed=Window,Worker]
1.1 ihickson 1026: interface <dfn id="messagechannel">MessageChannel</dfn> {
1027: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port1" title="dom-channel-port1">port1</a>;
1028: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port2" title="dom-channel-port2">port2</a>;
1.114 ihickson 1029: };</pre>
1030:
1031: <dl class="domintro"><dt><var title="">channel</var> = new <code title="dom-MessageChannel"><a href="#dom-messagechannel">MessageChannel</a></code>()</dt>
1.1 ihickson 1032:
1033: <dd>
1034:
1035: <p>Returns a new <code><a href="#messagechannel">MessageChannel</a></code> object with two new <code><a href="#messageport">MessagePort</a></code> objects.</p>
1036:
1037: </dd>
1038:
1039: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port1">port1</code></dt>
1040:
1041: <dd>
1042:
1043: <p>Returns the first <code><a href="#messageport">MessagePort</a></code> object.</p>
1044:
1045: </dd>
1046:
1047: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port2">port2</code></dt>
1048:
1049: <dd>
1050:
1051: <p>Returns the second <code><a href="#messageport">MessagePort</a></code> object.</p>
1052:
1053: </dd>
1054:
1055: </dl><div class="impl">
1056:
1.153 ihickson 1057: <p>When the <dfn id="dom-messagechannel" title="dom-MessageChannel"><code>MessageChannel()</code></dfn> constructor is
1058: called, it must run the following algorithm:</p>
1.1 ihickson 1059:
1.163 ihickson 1060: <ol><li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a> whose <a href="#concept-port-owner" title="concept-port-owner">owner</a> is the <span>incumbent settings object</span>, and let
1061: <var title="">port1</var> be that object.</li>
1.154 ihickson 1062:
1.163 ihickson 1063: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a> whose <a href="#concept-port-owner" title="concept-port-owner">owner</a> is the <span>incumbent settings object</span>, and let
1064: <var title="">port2</var> be that object.</li>
1.1 ihickson 1065:
1.153 ihickson 1066: <li><p><a href="#entangle">Entangle</a> the <var title="">port1</var> and <var title="">port2</var>
1067: objects.</li>
1.1 ihickson 1068:
1.153 ihickson 1069: <li><p>Instantiate a new <code><a href="#messagechannel">MessageChannel</a></code> object, and let <var title="">channel</var>
1070: be that object.</li>
1.1 ihickson 1071:
1.153 ihickson 1072: <li><p>Let the <code title="dom-channel-port1"><a href="#dom-channel-port1">port1</a></code> attribute of the <var title="">channel</var> object be <var title="">port1</var>.</p>
1.1 ihickson 1073:
1.153 ihickson 1074: <li><p>Let the <code title="dom-channel-port2"><a href="#dom-channel-port2">port2</a></code> attribute of the <var title="">channel</var> object be <var title="">port2</var>.</p>
1.1 ihickson 1075:
1076: <li><p>Return <var title="">channel</var>.</li>
1077:
1.153 ihickson 1078: </ol><p>The <dfn id="dom-channel-port1" title="dom-channel-port1"><code>port1</code></dfn> and <dfn id="dom-channel-port2" title="dom-channel-port2"><code>port2</code></dfn> attributes must return the values they were
1079: assigned when the <code><a href="#messagechannel">MessageChannel</a></code> object was created.</p>
1.1 ihickson 1080:
1.114 ihickson 1081: </div>
1082:
1083:
1084:
1085: <h3 id="message-ports"><span class="secno">5.3 </span>Message ports</h3>
1086:
1.153 ihickson 1087: <p>Each channel has two message ports. Data sent through one port is received by the other port,
1088: and vice versa.</p>
1.114 ihickson 1089:
1.164 ihickson 1090: <pre class="idl">[Exposed=Window,Worker]
1091: interface <dfn id="messageport">MessagePort</dfn> : <span>EventTarget</span> {
1.113 ihickson 1092: void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer);
1093: void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
1.1 ihickson 1094: void <a href="#dom-messageport-close" title="dom-MessagePort-close">close</a>();
1095:
1096: // event handlers
1.120 ihickson 1097: attribute <span>EventHandler</span> <a href="#handler-messageport-onmessage" title="handler-MessagePort-onmessage">onmessage</a>;
1.159 ihickson 1098: attribute <span>EventHandler</span> <a href="#handler-messageport-onerror" title="handler-MessagePort-onerror">onerror</a>;
1.1 ihickson 1099: };
1.146 ihickson 1100: // <a href="#messageport">MessagePort</a> implements <span>Transferable</span>;</pre>
1.114 ihickson 1101:
1102: <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>
1.1 ihickson 1103:
1104: <dd>
1105:
1.153 ihickson 1106: <p>Posts a message through the channel. Objects listed in <var title="">transfer</var> are
1107: transferred, not just cloned, meaning that they are no longer usable on the sending side.</p>
1.1 ihickson 1108:
1.138 ihickson 1109: <p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
1110: duplicate objects or the source or target ports, or if <var title="">message</var> could not be
1111: cloned.</p>
1.1 ihickson 1112:
1113: </dd>
1114:
1115: <dt><var title="">port</var> . <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start</a></code>()</dt>
1116:
1117: <dd>
1118:
1119: <p>Begins dispatching messages received on the port.</p>
1120:
1121: </dd>
1122:
1123: <dt><var title="">port</var> . <code title="dom-MessagePort-close"><a href="#dom-messageport-close">close</a></code>()</dt>
1124:
1125: <dd>
1126:
1127: <p>Disconnects the port, so that it is no longer active.</p>
1128:
1129: </dd>
1130:
1131: </dl><div class="impl">
1132:
1.137 ihickson 1133: <p>Each <code><a href="#messageport">MessagePort</a></code> object can be entangled with another (a symmetric relationship).
1134: Each <code><a href="#messageport">MessagePort</a></code> object also has a <span>task source</span> called the <dfn id="port-message-queue">port
1135: message queue</dfn>, initially empty. A <a href="#port-message-queue">port message queue</a> can be enabled or
1136: disabled, and is initially disabled. Once enabled, a port can never be disabled again (though
1137: messages in the queue can get moved to another queue or removed altogether, which has much the
1.154 ihickson 1138: same effect). A <code><a href="#messageport">MessagePort</a></code> also has a <dfn id="has-been-shipped">has been shipped</dfn> flag, which must
1139: initially be false, and an <dfn id="concept-port-owner" title="concept-port-owner">owner</dfn>, which is a <span>settings
1140: object</span> set when the object is created, as described below.</p>
1141:
1.164 ihickson 1142:
1.151 ihickson 1143: <p>When a port's <a href="#port-message-queue">port message queue</a> is enabled, the <span>event loop</span> must use
1.164 ihickson 1144: it as one of its <span title="task source">task sources</span>. When a port's <a href="#concept-port-owner" title="concept-port-owner">owner</a> specifies a <span>responsible event loop</span> that is a <span>browsing context</span> <span>event loop</span>, all <span title="concept-task">tasks</span> <span title="queue a task">queued</span> on its <a href="#port-message-queue">port
1.154 ihickson 1145: message queue</a> must be associated with the <span>responsible document</span> specified by
1146: the port's <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</p>
1147:
1.163 ihickson 1148: <p class="note">If the port's <a href="#concept-port-owner" title="concept-port-owner">owner</a> specifies a
1149: <span>responsible document</span> that is <span>fully active</span>, but the event listeners all
1150: have scripts whose <span title="settings object">settings objects</span> specify <span title="responsible document">responsible documents</span> that are <em>not</em> <span>fully
1151: active</span>, then the messages will be lost.</p>
1.154 ihickson 1152:
1.134 ihickson 1153: <p>Each <span>event loop</span> has a <span>task source</span> called the <dfn id="unshipped-port-message-queue">unshipped port
1154: message queue</dfn>. This is a virtual <span>task source</span>: it must act as if it contained
1155: the <span title="concept-task">tasks</span> of each <a href="#port-message-queue">port message queue</a> of each
1.154 ihickson 1156: <code><a href="#messageport">MessagePort</a></code> whose <a href="#has-been-shipped">has been shipped</a> flag is false, whose <a href="#port-message-queue">port
1157: message queue</a> is enabled, and whose <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1.163 ihickson 1158: specifies that <span>event loop</span> as the <span>responsible event loop</span>, in the order in
1159: which they were added to their respective <span>task source</span>. When a <span title="concept-task">task</span> would be removed from the <a href="#unshipped-port-message-queue">unshipped port message
1160: queue</a>, it must instead be removed from its <a href="#port-message-queue">port message queue</a>.</p>
1.134 ihickson 1161:
1162: <p>When a <code><a href="#messageport">MessagePort</a></code>'s <a href="#has-been-shipped">has been shipped</a> flag is false, its <a href="#port-message-queue">port
1163: message queue</a> must be ignored for the purposes of the <span>event loop</span>. (The
1164: <a href="#unshipped-port-message-queue">unshipped port message queue</a> is used instead.)</p>
1165:
1166: <p class="note">The <a href="#has-been-shipped">has been shipped</a> flag is set to true when a port, its twin, or
1167: the object it was cloned from, is or has been <span title="transfer a transferable
1168: object">transferred</span>. When a <code><a href="#messageport">MessagePort</a></code>'s <a href="#has-been-shipped">has been shipped</a> flag
1169: is true, its <a href="#port-message-queue">port message queue</a> acts as a first-class <span>task source</span>,
1170: unaffected to any <a href="#unshipped-port-message-queue">unshipped port message queue</a>.</p>
1.1 ihickson 1171:
1.163 ihickson 1172: <p>When the user agent is to <dfn id="create-a-new-messageport-object">create a new <code>MessagePort</code> object</dfn> with a
1173: particular <span>settings object</span> as its <var title="">owner</var>, it must instantiate a
1174: new <code><a href="#messageport">MessagePort</a></code> object, and let its <a href="#concept-port-owner" title="concept-port-owner">owner</a> be
1175: <var title="">owner</var>.</p>
1.137 ihickson 1176:
1177: <p>When the user agent is to <dfn id="entangle">entangle</dfn> two <code><a href="#messageport">MessagePort</a></code> objects, it must run
1178: the following steps:</p>
1.1 ihickson 1179:
1180: <ol><li>
1181:
1.153 ihickson 1182: <p>If one of the ports is already entangled, then disentangle it and the port that it was
1183: entangled with.</p>
1.1 ihickson 1184:
1.153 ihickson 1185: <p class="note">If those two previously entangled ports were the two ports of a
1186: <code><a href="#messagechannel">MessageChannel</a></code> object, then that <code><a href="#messagechannel">MessageChannel</a></code> object no longer
1187: represents an actual channel: the two ports in that object are no longer entangled.</p>
1.1 ihickson 1188:
1189: </li>
1190:
1.143 ihickson 1191: <li>
1192:
1193: <p>Associate the two ports to be entangled, so that they form the two parts of a new channel.
1194: (There is no <code><a href="#messagechannel">MessageChannel</a></code> object that represents this channel.)</p>
1195:
1.144 ihickson 1196: <p>Two ports <var title="">A</var> and <var title="">B</var> that have gone through this step
1197: are now said to be entangled; one is entangled to the other, and vice versa.</p>
1.143 ihickson 1198:
1199: <p class="note">While this specification describes this process as instantaneous,
1200: implementations are more likely to implement it via message passing. As with all algorithms, the
1201: key is "merely" that the end result be indistinguishable, in a black-box sense, from the
1202: specification.</p>
1203:
1204: </li>
1.1 ihickson 1205:
1.153 ihickson 1206: </ol><p>When the user agent is to <dfn id="clone-a-port">clone a port</dfn> <var title="">original port</var>, with the
1207: clone being owned by <var title="">owner</var>, it must run the following steps, which return a
1208: new <code><a href="#messageport">MessagePort</a></code> object. These steps must be run atomically.</p>
1.1 ihickson 1209:
1.134 ihickson 1210: <ol><li><p>Set <var title="">original port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1211: true.</li>
1212:
1.154 ihickson 1213: <li><p><a href="#create-a-new-messageport-object">Create a new <code>MessagePort</code> object</a> whose <a href="#concept-port-owner" title="concept-port-owner">owner</a> is <var title="">owner</var>, and let <var title="">new port</var> be that object.</li>
1.1 ihickson 1214:
1.134 ihickson 1215: <li><p>Set <var title="">new port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to true.</li>
1216:
1.164 ihickson 1217:
1.163 ihickson 1218: <li><p>Move all the <span title="concept-task">tasks</span> that are to fire <code title="event-message">message</code> events in the <a href="#port-message-queue">port message queue</a> of <var title="">original port</var> to the <a href="#port-message-queue">port message queue</a> of <var title="">new
1219: port</var>, if any, leaving the <var title="">new port</var>'s <a href="#port-message-queue">port message queue</a>
1.164 ihickson 1220: in its initial disabled state, and, if the <var title="">new port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1221: specifies a <span>responsible event loop</span> that is a <span>browsing context</span> <span>event loop</span>, associating the moved <span title="concept-task">tasks</span> with the <span>responsible document</span> specified by <var title="">new port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</li>
1222:
1.161 ihickson 1223:
1224: <li><p>If <var title="">original port</var> is <a href="#related-to-an-ill-fated-port">related to an ill-fated port</a>, then
1225: create a <span title="concept-task">task</span> that <span title="fire a simple event">fires a
1226: simple event</span> named <code title="event-error">error</code> at the <var title="">new
1227: port</var>, and add the <span title="concept-task">task</span> to the <a href="#port-message-queue">port message
1.164 ihickson 1228: queue</a> of <var title="">new port</var>. If the <var title="">new port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1229: specifies a <span>responsible event loop</span> that is a <span>browsing context</span> <span>event loop</span>, the <span title="concept-task">task</span> must
1.161 ihickson 1230: be associated with the <span>responsible document</span> specified by <var title="">new
1231: port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</li>
1.1 ihickson 1232:
1233: <li>
1234:
1.153 ihickson 1235: <p>If the <var title="">original port</var> is entangled with another port, then run these
1236: substeps:</p>
1.1 ihickson 1237:
1.153 ihickson 1238: <ol><li><p>Let the <var title="">remote port</var> be the port with which the <var title="">original port</var> is entangled.</li>
1.1 ihickson 1239:
1.134 ihickson 1240: <li><p>Set <var title="">remote port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1241: true.</li>
1242:
1.153 ihickson 1243: <li><p><a href="#entangle">Entangle</a> the <var title="">remote port</var> and <var title="">new
1244: port</var> objects. The <var title="">original port</var> object will be disentangled by this
1.1 ihickson 1245: process.</li>
1246:
1247: </ol></li>
1248:
1.153 ihickson 1249: <li><p>Return <var title="">new port</var>. It is the clone.</li>
1.1 ihickson 1250:
1.153 ihickson 1251: </ol><p id="transferMessagePort">To <span title="transfer a Transferable object">transfer</span> a
1252: <code><a href="#messageport">MessagePort</a></code> object <var title="">old</var> to a new owner <var title="">owner</var>,
1253: a user agent must <a href="#clone-a-port" title="clone a port">clone</a> the <var title="">old</var> object with
1254: the clone being owned by <var title="">owner</var>, thus obtaining <var title="">new</var>, must
1255: <span title="concept-Transferable-neutered">neuter</span> the <var title="">old</var> port, and
1256: must finally return <var title="">new</var>.</p>
1257:
1258: <hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn> method, when
1259: called on a port <var title="">source port</var>, must cause the user agent to run the following
1260: steps:</p>
1.1 ihickson 1261:
1.153 ihickson 1262: <ol><li><p>Let <var title="">target port</var> be the port with which <var title="">source port</var>
1263: is entangled, if any.</li>
1.1 ihickson 1264:
1.88 ihickson 1265: <li>
1266:
1.158 ihickson 1267: <p>Let <var title="">doomed</var> be false. It is set to true if a condition is detected that
1268: will make this message cause the port to be unusable; specifically, if the message contains <var title="">target port</var> as one of the objects being <span title="transfer a Transferable
1269: object">transferred</span>. (This condition cannot necessarily be detected synchronously.)</p>
1270:
1271: </li>
1272:
1273: <li>
1274:
1.88 ihickson 1275: <p>Let <var title="">new ports</var> be an empty array.</p>
1276:
1277: </li>
1278:
1279: <li>
1.1 ihickson 1280:
1.153 ihickson 1281: <p>Let <var title="">transfer map</var> be an empty association list of
1282: <code>Transferable</code> objects to placeholder objects.</p>
1.1 ihickson 1283:
1.88 ihickson 1284: </li>
1.1 ihickson 1285:
1.88 ihickson 1286: <li>
1.1 ihickson 1287:
1.153 ihickson 1288: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these
1289: substeps:</p>
1.1 ihickson 1290:
1291: <ol><li>
1292:
1.153 ihickson 1293: <p>If any object is listed in <var title="">transfer</var> more than once, or any of the
1294: <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
1295: <code>DataCloneError</code> exception and abort these steps.</p>
1.1 ihickson 1296:
1.88 ihickson 1297: </li>
1.1 ihickson 1298:
1.88 ihickson 1299: <li>
1300:
1.158 ihickson 1301: <p>If any of the objects in <var title="">transfer</var> are the <var title="">source
1.163 ihickson 1302: port</var>, then throw a <code>DataCloneError</code> exception and abort these steps.</p>
1.88 ihickson 1303:
1.89 ihickson 1304: </li>
1.1 ihickson 1305:
1.84 ihickson 1306: <li>
1307:
1.158 ihickson 1308: <p>If any of the objects in <var title="">transfer</var> are the <var title="">target
1309: port</var>, if any, then let <var title="">doomed</var> be true, and optionally report to a
1310: developer console that the target port was posted to itself, causing the communication channel
1311: to be lost.</p>
1312:
1313: </li>
1314:
1315: <li>
1316:
1.153 ihickson 1317: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
1318: mapping from <var title="">x</var> to a new unique placeholder object created for <var title="">x</var> to <var title="">transfer map</var>, and if <var title="">x</var> is a
1319: <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
1.105 ihickson 1320: ports</var> array.</p>
1.84 ihickson 1321:
1322: </li>
1323:
1.89 ihickson 1324: </ol></li>
1325:
1326: <li>
1.1 ihickson 1327:
1.153 ihickson 1328: <p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
1329: clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
1330: as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
1331: these steps.</p>
1.88 ihickson 1332:
1333: </li>
1334:
1.105 ihickson 1335: <li>
1336:
1.153 ihickson 1337: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these
1338: substeps:</p>
1.105 ihickson 1339:
1340: <ol><li>
1341:
1.163 ihickson 1342: <p>Let <var title="">new owner</var> be the <a href="#concept-port-owner" title="concept-port-owner">owner</a> of
1343: <var title="">target port</var>, if there is a <var title="">target port</var> and <var title="">doomed</var> is false, or else some arbitrary owner. (This <var title="">new
1.153 ihickson 1344: owner</var> is used when transferring objects below. If there is no <var title="">target
1.163 ihickson 1345: port</var>, or if the <var title="">target port</var> is one of the objects being <span title="transfer a Transferable object">transferred</span>, the <code>Transferable</code>
1346: objects given in the second argument, if any, are still <span title="transfer a Transferable
1347: object">transferred</span>, but since they are then discarded, it doesn't matter where they
1348: are transferred to.)</p>
1.105 ihickson 1349:
1350: </li>
1351:
1352:
1353: <li>
1354:
1.163 ihickson 1355: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a
1356: new object <var title="">y</var> by <span title="transfer a Transferable
1357: object">transferring</span> the object <var title="">x</var> to <var title="">new
1358: owner</var>, and replace the placeholder object that was created for the object <var title="">x</var> by the new object <var title="">y</var> wherever the placeholder exists
1359: (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
1.105 ihickson 1360:
1361: </li>
1362:
1363: </ol></li>
1.88 ihickson 1364:
1365: <li>
1366:
1.153 ihickson 1367: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span>
1368: array.</p>
1.88 ihickson 1369:
1370: </li>
1371:
1.163 ihickson 1372: <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var>
1373: is not entangled), or if <var title="">doomed</var> is true, then abort these steps.</li>
1374:
1.113 ihickson 1375:
1.162 ihickson 1376: <li><p>Create an event that uses the <code><a href="#messageevent">MessageEvent</a></code> interface, with the name <code title="event-message">message</code>, which does not bubble, is not cancelable, and has no
1.163 ihickson 1377: default action.</li>
1.88 ihickson 1378:
1.153 ihickson 1379: <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute of the event be
1380: initialized to the value of <var title="">message clone</var>.</li>
1.88 ihickson 1381:
1.153 ihickson 1382: <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code> attribute of the event be
1383: initialized to the <var title="">new ports</var> array.</li>
1.1 ihickson 1384:
1.153 ihickson 1385: <li><p>Add the event to the <a href="#port-message-queue">port message queue</a> of <var title="">target
1386: port</var>.</li>
1.1 ihickson 1387:
1.137 ihickson 1388: </ol><hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn> method must enable its port's
1389: <a href="#port-message-queue">port message queue</a>, if it is not already enabled.</p>
1390:
1391: <hr><p>The <dfn id="dom-messageport-close" title="dom-MessagePort-close"><code>close()</code></dfn> method, when called on a port
1.139 ihickson 1392: <var title="">local port</var> that is entangled with another port, must cause the user agent to
1.137 ihickson 1393: disentangle the two ports. If the method is called on a port that is not entangled, then the
1394: method must do nothing.</p>
1395:
1.159 ihickson 1396: <hr><p>In some circumstances, an entangled <code><a href="#messageport">MessagePort</a></code> <var title="">source port</var>
1397: that is not <a href="#ports-and-garbage-collection">eligible for garbage collection</a> will
1398: nonetheless find itself prematurely destroyed, for example if the user manually terminates the
1399: user agent's host process. Under such circumstances, user agents should attempt to following these
1400: steps:</p>
1401:
1402:
1403:
1404:
1405:
1406: <ol><li><p>Let <var title="">target port</var> be the port with which the ill-fated <var title="">source port</var> is entangled.</li>
1407:
1408: <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var>
1409: is not entangled), or if <var title="">target port</var> is suffering the same fate as <var title="">source port</var> (e.g. if both ports are in the same host process), then abort these
1410: steps.</li>
1411:
1.161 ihickson 1412: <li><p>Mark <var title="">target port</var> as being a <dfn id="related-to-an-ill-fated-port">related to an ill-fated
1413: port</dfn>.</li>
1414:
1.164 ihickson 1415:
1.163 ihickson 1416: <li><p>Create a <span title="concept-task">task</span> that <span title="fire a simple
1417: event">fires a simple event</span> named <code title="event-error">error</code> at <var title="">target port</var>, and add the <span title="concept-task">task</span> to the
1.164 ihickson 1418: <a href="#port-message-queue">port message queue</a> of <var title="">target port</var>. If the <var title="">new port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1419: specifies a <span>responsible event loop</span> that is a <span>browsing context</span> <span>event loop</span>, the <span title="concept-task">task</span> must be associated with the <span>responsible document</span>
1.160 ihickson 1420: specified by <var title="">source port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</li>
1.159 ihickson 1421:
1422: <li><p>Disentangle the two ports.</li>
1423:
1424: </ol><p class="note">This does not happen if the port is garbage collected or closed using the <code title="dom-messageport-close"><a href="#dom-messageport-close">close()</a></code> method. It is intended only as a way for Web
1425: applications that operate across multiple browser processes (e.g. using workers or communicating
1426: across multiple tabs) to gracefully handle a catastrophic failure in one process. A strictly
1427: conforming user agent would never fail unexpectedly, and thus would never send this event!</p>
1428:
1.137 ihickson 1429: <hr><p>The following are the <span>event handlers</span> (and their corresponding <span title="event
1.153 ihickson 1430: handler event type">event handler event types</span>) that must be supported, as <span>event
1431: handler IDL attributes</span>, by all objects implementing the <code><a href="#messageport">MessagePort</a></code>
1432: interface:</p>
1.1 ihickson 1433:
1434: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.162 ihickson 1435: <tbody><tr><td><dfn id="handler-messageport-onmessage" title="handler-MessagePort-onmessage"><code>onmessage</code></dfn> <td> <code title="event-message">message</code>
1.159 ihickson 1436: <tr><td><dfn id="handler-messageport-onerror" title="handler-MessagePort-onerror"><code>onerror</code></dfn> <td> <code title="event-error">error</code>
1.153 ihickson 1437: </table><p>The first time a <code><a href="#messageport">MessagePort</a></code> object's <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code> IDL attribute is set, the port's <a href="#port-message-queue">port
1438: message queue</a> must be enabled, as if the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code>
1439: method had been called.</p>
1.1 ihickson 1440:
1.114 ihickson 1441: </div>
1442:
1443:
1.128 ihickson 1444: <h3 id="broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</h3>
1445:
1.152 ihickson 1446: <p class="critical">The API described in this section is controversial, as, in an attempt to solve
1447: an architectural memory leak, it instead exposes the details of Garbage Collection. This is a
1448: lose-lose scenario. A better solution is really needed here.</p>
1449:
1.128 ihickson 1450: <p>Broadcasting to many ports is in principle relatively simple: keep an array of
1451: <code><a href="#messageport">MessagePort</a></code> objects to send messages to, and iterate through the array to send a
1.129 ihickson 1452: message. However, this has one rather unfortunate effect: it prevents the ports from being garbage
1.128 ihickson 1453: collected, even if the other side has gone away.</p>
1454:
1455: <p>To avoid this problem, the <code><a href="#portcollection">PortCollection</a></code> object can be used. It acts as an opaque
1456: array of <code><a href="#messageport">MessagePort</a></code> objects, thus allowing the objects to be garbage collected when
1457: they stop being relevant, while still allowing scripts to iterate over the
1458: <code><a href="#messageport">MessagePort</a></code> objects.</p>
1459:
1.164 ihickson 1460: <pre class="idl">[<a href="#dom-portcollection" title="dom-PortCollection">Constructor</a>, Exposed=Window,Worker]
1461: interface <dfn id="portcollection">PortCollection</dfn> {
1.128 ihickson 1462: void <a href="#dom-portcollection-add" title="dom-PortCollection-add">add</a>(<a href="#messageport">MessagePort</a> port);
1463: void <a href="#dom-portcollection-remove" title="dom-PortCollection-remove">remove</a>(<a href="#messageport">MessagePort</a> port);
1464: void <a href="#dom-portcollection-clear" title="dom-PortCollection-clear">clear</a>();
1465: void <a href="#dom-portcollection-iterate" title="dom-PortCollection-iterate">iterate</a>(<a href="#portcollectioncallback">PortCollectionCallback</a> callback);
1466: };
1467:
1468: callback <dfn id="portcollectioncallback">PortCollectionCallback</dfn> = void (<a href="#messageport">MessagePort</a> port);</pre>
1469:
1470: <dl class="domintro"><dt><var title="">portCollection</var> = new <code title="dom-PortCollection"><a href="#dom-portcollection">PortCollection</a></code>()</dt>
1471:
1472: <dd>
1473:
1474: <p>Returns a new empty <code><a href="#portcollection">PortCollection</a></code> object.</p>
1475:
1476: </dd>
1477:
1478: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-add"><a href="#dom-portcollection-add">add</a></code>(<var title="">port</var>)</dt>
1479:
1480: <dd>
1481:
1482: <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
1483:
1484: </dd>
1485:
1486: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-remove"><a href="#dom-portcollection-remove">remove</a></code>(<var title="">port</var>)</dt>
1487:
1488: <dd>
1489:
1490: <p>Removes <var title="">port</var> from the collection, if it is present.</p>
1491:
1492: </dd>
1493:
1494: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-clear"><a href="#dom-portcollection-clear">clear</a></code>()</dt>
1495:
1496: <dd>
1497:
1498: <p>Removes all ports from the collection.</p>
1499:
1500: </dd>
1501:
1502: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-iterate"><a href="#dom-portcollection-iterate">iterate</a></code>(<var title="">callback</var>)</dt>
1503:
1504: <dd>
1505:
1506: <p>Calls <var title="">callback</var> for each port in the collection.</p>
1507:
1508: </dd>
1509:
1510: </dl><div class="impl">
1511:
1512: <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
1513: a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is garbage collected, it must be
1514: silently removed from that <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>. Objects
1515: in a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> are ordered chronologically by
1516: the time at which they were most recently added; the least-recently added <code><a href="#messageport">MessagePort</a></code>
1517: object is the first in the list, and the most-recently added <code><a href="#messageport">MessagePort</a></code> is the last
1518: in the list.</p>
1519:
1520: <p>The <dfn id="dom-portcollection" title="dom-PortCollection"><code>PortCollection()</code></dfn> constructor must return
1521: 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>
1522:
1523: <p>The <dfn id="dom-portcollection-add" title="dom-PortCollection-add"><code>add()</code></dfn> method must add the
1524: <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
1525: already in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1526: method does nothing. (Calling this method with a port already in the list does not move the port
1527: to the end of the list.)</p>
1528:
1529: <p>The <dfn id="dom-portcollection-remove" title="dom-PortCollection-remove"><code>remove()</code></dfn> method must remove the
1530: <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
1531: not in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1532: method does nothing.</p>
1533:
1534: <p>The <dfn id="dom-portcollection-clear" title="dom-PortCollection-clear"><code>clear()</code></dfn> method must remove all
1535: <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.
1536: If the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is already empty, the method
1537: does nothing.</p>
1538:
1539: <p>The <dfn id="dom-portcollection-iterate" title="dom-PortCollection-iterate"><code>iterate()</code></dfn> method must invoke its
1540: <code><a href="#portcollectioncallback">PortCollectionCallback</a></code> argument once for each <code><a href="#messageport">MessagePort</a></code> object in the
1541: object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in the order defined
1542: above, with each invocation being passed the corresponding <code><a href="#messageport">MessagePort</a></code> object as the
1543: callback's sole argument.</p>
1544:
1545: </div>
1546:
1547:
1548: <h3 id="ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</h3>
1.114 ihickson 1549:
1550: <div class="impl">
1.1 ihickson 1551:
1.153 ihickson 1552: <p>When a <code><a href="#messageport">MessagePort</a></code> object <var title="">o</var> is entangled, user agents must
1553: either act as if <var title="">o</var>'s entangled <code><a href="#messageport">MessagePort</a></code> object has a strong
1.163 ihickson 1554: reference to <var title="">o</var>, or as if the <span>global object</span> specified by <var title="">o</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a> has a strong reference to <var title="">o</var>.</p>
1.1 ihickson 1555:
1556: <div class="note">
1557:
1.153 ihickson 1558: <p>Thus, a message port can be received, given an event listener, and then forgotten, and so long
1559: as that event listener could receive a message, the channel will be maintained.</p>
1560:
1561: <p>Of course, if this was to occur on both sides of the channel, then both ports could be garbage
1562: collected, since they would not be reachable from live code, despite having a strong reference to
1563: each other.</p>
1.1 ihickson 1564:
1565: </div>
1566:
1.153 ihickson 1567: <p>Furthermore, a <code><a href="#messageport">MessagePort</a></code> object must not be garbage collected while there exists
1.159 ihickson 1568: an event in a <span>task queue</span> that is to be dispatched on that <code><a href="#messageport">MessagePort</a></code>
1.163 ihickson 1569: object, or while the <code><a href="#messageport">MessagePort</a></code> object's <a href="#port-message-queue">port message queue</a> is enabled
1570: and there exists a <code title="event-message">message</code> event in that queue.</p>
1.113 ihickson 1571:
1.79 ihickson 1572:
1.113 ihickson 1573:
1.128 ihickson 1574: <p>There are no strong references from a <code><a href="#portcollection">PortCollection</a></code> object to its
1575: <code><a href="#messageport">MessagePort</a></code> objects. (That is in fact the whole point of <code><a href="#portcollection">PortCollection</a></code>
1576: objects: they allow for <code><a href="#messageport">MessagePort</a></code> objects to be referenced without preventing them
1577: from being garbage collected.)</p>
1578:
1.114 ihickson 1579: </div>
1580:
1.128 ihickson 1581: <p class="note">Authors are strongly encouraged to explicitly close <code><a href="#messageport">MessagePort</a></code>
1582: objects to disentangle them, so that their resources can be recollected. Creating many
1583: <code><a href="#messageport">MessagePort</a></code> objects and discarding them without closing them can lead to high
1.159 ihickson 1584: transient memory usage since garbage collection is not necessarily performed promptly, especially
1585: for <code><a href="#messageport">MessagePort</a></code>s where garbage collection can involve cross-process coordination.</p>
1.114 ihickson 1586:
1587:
1588: <h2 class="no-num" id="references">References</h2>
1589:
1590: <p>All references are normative unless marked "Non-normative".</p>
1591:
1592:
1593:
1.132 ihickson 1594: <dl><dt id="refsDOM">[DOM]</dt>
1595: <dd><cite><a href="http://dom.spec.whatwg.org/">DOM</a></cite>, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.</dd>
1.72 ihickson 1596:
1597: <dt id="refsHTML">[HTML]</dt>
1.127 ihickson 1598: <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a></cite>, I. Hickson. WHATWG.</dd>
1.111 ihickson 1599:
1.72 ihickson 1600: <dt id="refsRFC2119">[RFC2119]</dt>
1.133 ihickson 1601: <dd><cite><a href="http://tools.ietf.org/html/rfc2119">Key words for use in RFCs to Indicate Requirement Levels</a></cite>, S. Bradner. IETF.</dd>
1.1 ihickson 1602:
1.55 ihickson 1603: <dt id="refsWEBIDL">[WEBIDL]</dt>
1.133 ihickson 1604: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, C. McCormack. W3C.</dd>
1.1 ihickson 1605:
1.114 ihickson 1606: </dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2>
1607:
1.163 ihickson 1608: <p>For a full list of acknowledgements, please see the <a href="http://whatwg.org/html">WHATWG HTML standard</a>.</p>
1.114 ihickson 1609:
1610:
Webmaster
![[BACK]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/back.gif?vpn-1){kind=icon}
Return to Overview.html CVS log ![[TXT]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/text.gif?vpn-1){kind=icon}
![[DIR]](/http/77726476706e69737468656265737421f4f257d23063265f6c0f/cvsweb/icons/dir.gif?vpn-1){kind=icon}
Up to [Public] / html5 / postmsg