Annotation of html5/postmsg/Overview.html, revision 1.162
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.162 ! ihickson 219: <h2 class="no-num no-toc" id="editor-s-draft-8-january-2014">Editor's Draft 8 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.162 ! ihickson 351: This specification is the 8 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:
491: <pre class="idl">[Constructor(DOMString type, optional <a href="#messageeventinit">MessageEventInit</a> eventInitDict)]
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.118 ihickson 497: readonly attribute (<span>WindowProxy</span> or <a href="#messageport">MessagePort</a>)? <a href="#dom-messageevent-source" title="dom-MessageEvent-source">source</a>;
1.96 ihickson 498: readonly attribute <a href="#messageport">MessagePort</a>[]? <a href="#dom-messageevent-ports" title="dom-MessageEvent-ports">ports</a>;
499: };
500:
501: dictionary <dfn id="messageeventinit">MessageEventInit</dfn> : <span>EventInit</span> {
502: any data;
503: DOMString origin;
504: DOMString lastEventId;
1.157 ihickson 505: DOMString channel;
1.149 ihickson 506: (<span>WindowProxy</span> or <a href="#messageport">MessagePort</a>)? source;
1.155 ihickson 507: sequence<<a href="#messageport">MessagePort</a>> ports;
1.114 ihickson 508: };</pre>
509:
510: <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 511:
512: <dd>
513:
514: <p>Returns the data of the message.</p>
515:
516: </dd>
517:
518: <dt><var title="">event</var> . <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code></dt>
519:
520: <dd>
521:
1.136 ihickson 522: <p>Returns the origin of the message, for <span>server-sent events</span> and
523: <a href="#web-messaging">cross-document messaging</a>.</p>
1.1 ihickson 524:
525: </dd>
526:
527: <dt><var title="">event</var> . <code title="dom-MessageEvent-lastEventId"><a href="#dom-messageevent-lasteventid">lastEventId</a></code></dt>
528:
529: <dd>
530:
1.136 ihickson 531: <p>Returns the <span title="concept-event-stream-last-event-id">last event ID string</span>, for
532: <span>server-sent events</span>.</p>
1.1 ihickson 533:
534: </dd>
535:
1.157 ihickson 536: <dt><var title="">event</var> . <code title="dom-MessageEvent-channel"><a href="#dom-messageevent-channel">channel</a></code></dt>
537:
538: <dd>
539:
540: <p>Returns the channel ID, for <span>broadcast channels</span>.</p>
541:
542: </dd>
543:
1.1 ihickson 544: <dt><var title="">event</var> . <code title="dom-MessageEvent-source"><a href="#dom-messageevent-source">source</a></code></dt>
545:
546: <dd>
547:
1.162 ! ihickson 548:
1.136 ihickson 549: <p>Returns the <code>WindowProxy</code> of the source window, for <a href="#web-messaging">cross-document
1.162 ! ihickson 550: 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 <code>SharedWorkerGlobalScope</code>
1.136 ihickson 551: objects.</p>
1.1 ihickson 552:
553: </dd>
554:
555: <dt><var title="">event</var> . <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code></dt>
556:
557: <dd>
558:
1.136 ihickson 559: <p>Returns the <code><a href="#messageport">MessagePort</a></code> array sent with the message, for <a href="#web-messaging">cross-document
560: messaging</a> and <a href="#channel-messaging">channel messaging</a>.</p>
1.1 ihickson 561:
562: </dd>
563:
564: </dl><div class="impl">
565:
1.153 ihickson 566: <p>The <dfn id="dom-messageevent-data" title="dom-MessageEvent-data"><code>data</code></dfn> attribute must return the value
567: it was initialized to. When the object is created, this attribute must be initialized to null. It
1.96 ihickson 568: represents the message being sent.</p>
1.1 ihickson 569:
1.153 ihickson 570: <p>The <dfn id="dom-messageevent-origin" title="dom-MessageEvent-origin"><code>origin</code></dfn> attribute must return the
571: value it was initialized to. When the object is created, this attribute must be initialized to the
572: empty string. It represents, in <span>server-sent events</span> and <a href="#web-messaging">cross-document
573: messaging</a>, the <span>origin</span> of the document that sent the message (typically the
574: scheme, hostname, and port of the document, but not its path or fragment identifier).</p>
575:
576: <p>The <dfn id="dom-messageevent-lasteventid" title="dom-MessageEvent-lastEventId"><code>lastEventId</code></dfn> attribute must
577: return the value it was initialized to. When the object is created, this attribute must be
578: 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>
579:
1.157 ihickson 580: <p>The <dfn id="dom-messageevent-channel" title="dom-MessageEvent-channel"><code>channel</code></dfn> attribute must return the
581: value it was initialized to. When the object is created, this attribute must be initialized to the
582: empty string. It represents, in <span>broadcast channels</span>, the channel of the message.</p>
583:
1.153 ihickson 584: <p>The <dfn id="dom-messageevent-source" title="dom-MessageEvent-source"><code>source</code></dfn> attribute must return the
585: value it was initialized to. When the object is created, this attribute must be initialized to
586: null. It represents, in <a href="#web-messaging">cross-document messaging</a>, the <code>WindowProxy</code> of the
587: <span>browsing context</span> of the <code>Window</code> object from which the message came; and
1.162 ! ihickson 588: in the <code title="event-WorkerGlobalScope-connect">connect</code> events used by <span title="SharedWorkerGlobalScope">shared workers</span>, the newly connecting
1.153 ihickson 589: <code><a href="#messageport">MessagePort</a></code>.</p>
590:
591: <p>The <dfn id="dom-messageevent-ports" title="dom-MessageEvent-ports"><code>ports</code></dfn> attribute must return the
592: value it was initialized to. When the object is created, this attribute must be initialized to
593: null. It represents, in
1.155 ihickson 594: <a href="#web-messaging">cross-document messaging</a> and <a href="#channel-messaging">channel messaging</a>, the
1.153 ihickson 595: <code><a href="#messageport">MessagePort</a></code> array being sent, if any.</p>
1.1 ihickson 596:
1.114 ihickson 597: </div>
598:
599:
600: <h2 id="web-messaging"><span class="secno">4 </span><dfn id="crossDocumentMessages">Cross-document messaging</dfn></h2>
601:
1.153 ihickson 602: <p>Web browsers, for security and privacy reasons, prevent documents in different domains from
603: affecting each other; that is, cross-site scripting is disallowed.</p>
604:
605: <p>While this is an important security feature, it prevents pages from different domains from
606: communicating even when those pages are not hostile. This section introduces a messaging system
607: that allows documents to communicate with each other regardless of their source domain, in a way
608: designed to not enable cross-site scripting attacks.</p>
1.114 ihickson 609:
610: <div class="impl">
1.1 ihickson 611:
1.153 ihickson 612: <p>The <span>task source</span> for the <span title="concept-task">tasks</span> in
613: <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 614:
1.114 ihickson 615: </div>
616:
617:
618: <h3 id="introduction"><span class="secno">4.1 </span>Introduction</h3>
619:
620: <p><i>This section is non-normative.</i></p>
621:
622: <div class="example">
1.1 ihickson 623:
1.153 ihickson 624: <p>For example, if document A contains an <code>iframe</code> element that contains document B,
625: and script in document A calls <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> on the
626: <code>Window</code> object of document B, then a message event will be fired on that object,
627: marked as originating from the <code>Window</code> of document A. The script in document A might
1.1 ihickson 628: look like:</p>
629:
630: <pre>var o = document.getElementsByTagName('iframe')[0];
631: o.contentWindow.postMessage('Hello world', 'http://b.example.org/');</pre>
632:
1.153 ihickson 633: <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
634: might look like:</p>
1.1 ihickson 635:
636: <pre>window.addEventListener('message', receiver, false);
637: function receiver(e) {
638: if (e.origin == 'http://example.com') {
639: if (e.data == 'Hello world') {
640: e.source.postMessage('Hello', e.origin);
641: } else {
642: alert(e.data);
643: }
644: }
645: }</pre>
646:
1.153 ihickson 647: <p>This script first checks the domain is the expected domain, and then looks at the message,
648: which it either displays to the user, or responds to by sending a message back to the document
649: which sent the message in the first place.</p>
1.1 ihickson 650:
1.114 ihickson 651: </div>
652:
653:
654:
655: <h3 id="security-postmsg"><span class="secno">4.2 </span>Security</h3>
656:
657: <div class="impl">
1.1 ihickson 658:
1.72 ihickson 659: <h4 id="authors"><span class="secno">4.2.1 </span>Authors</h4>
1.1 ihickson 660:
1.114 ihickson 661: </div>
662:
1.153 ihickson 663: <p id="security-4" class="warning">Use of this API requires extra care to protect users from
664: hostile entities abusing a site for their own purposes.</p>
665:
666: <p>Authors should check the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code> attribute to
667: ensure that messages are only accepted from domains that they expect to receive messages from.
668: Otherwise, bugs in the author's message handling code could be exploited by hostile sites.</p>
669:
670: <p>Furthermore, even after checking the <code title="dom-MessageEvent-origin"><a href="#dom-messageevent-origin">origin</a></code>
671: attribute, authors should also check that the data in question is of the expected format.
672: Otherwise, if the source of the event has been attacked using a cross-site scripting flaw, further
673: 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
674: propagated into the receiver.</p>
675:
676: <p>Authors should not use the wildcard keyword (*) in the <var title="">targetOrigin</var>
677: argument in messages that contain any confidential information, as otherwise there is no way to
678: guarantee that the message is only delivered to the recipient to which it was intended.</p>
679:
680: <hr><p>Authors who accept messages from any origin are encouraged to consider the risks of a
681: denial-of-service attack. An attacker could send a high volume of messages; if the receiving page
682: performs expensive computation or causes network traffic to be sent for each such message, the
683: attacker's message could be multplied into a denial-of-service attack. Authors are encouraged to
684: employ rate limiting (only accepting a certain number of messages per minute) to make such attacks
685: impractical.</p>
1.114 ihickson 686:
687:
688: <div class="impl">
1.1 ihickson 689:
1.72 ihickson 690: <h4 id="user-agents"><span class="secno">4.2.2 </span>User agents</h4>
1.1 ihickson 691:
1.153 ihickson 692: <p>The integrity of this API is based on the inability for scripts of one <span>origin</span> to
693: post arbitrary events (using <code title="">dispatchEvent()</code> or otherwise) to objects in
694: other origins (those that are not the <span title="same origin">same</span>).</p>
695:
696: <p class="note">Implementors are urged to take extra care in the implementation of this feature.
697: It allows authors to transmit information from one domain to another domain, which is normally
698: disallowed for security reasons. It also requires that UAs be careful to allow access to certain
699: properties but not others.</p>
700:
701: <hr><p>User agents are also encouraged to consider rate-limiting message traffic between different
702: <span title="origin">origins</span>, to protect naïve sites from denial-of-service
703: attacks.</p>
1.108 ihickson 704:
1.114 ihickson 705: </div>
706:
707:
708:
709: <h3 id="posting-messages"><span class="secno">4.3 </span>Posting messages</h3>
710:
711: <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 712:
713: <dd>
714:
1.153 ihickson 715: <p>Posts a message to the given window. Messages can be structured objects, e.g. nested objects
716: and arrays, can contain JavaScript values (strings, numbers, <code>Date</code>s, etc), and can
717: contain certain data objects such as <code>File</code> <code>Blob</code>, <code>FileList</code>,
718: and <code>ArrayBuffer</code> objects.</p>
719:
720: <p>Objects listed in <var title="">transfer</var> are transferred, not just cloned, meaning that
721: they are no longer usable on the sending side.</p>
722:
723: <p>If the origin of the target window doesn't match the given origin, the message is discarded,
724: to avoid information leakage. To send the message to the target regardless of origin, set the
725: target origin to "<code title="">*</code>". To restrict the message to same-origin targets only,
726: without needing to explicitly state the origin, set the target origin to "<code title="">/</code>".</p>
1.1 ihickson 727:
1.138 ihickson 728: <p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
729: duplicate objects or if <var title="">message</var> could not be cloned.</p>
1.1 ihickson 730:
731: </dd>
732:
1.153 ihickson 733: </dl><p class="note">When posting a message to a <code>Window</code> of a <span>browsing context</span>
734: that has just been navigated to a new <code>Document</code> is likely to result in the message not
735: receiving its intended recipient: the scripts in the target <span>browsing context</span> have to
736: have had time to set up listeners for the messages. Thus, for instance, in situations where a
737: message is to be sent to the <code>Window</code> of newly created child <code>iframe</code>,
738: authors are advised to have the child <code>Document</code> post a message to their parent
739: announcing their readiness to receive messages, and for the parent to wait for this message before
740: beginning posting messages.</p>
1.114 ihickson 741:
742: <div class="impl">
1.1 ihickson 743:
1.153 ihickson 744: <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
745: <code>Window</code> object, the user agent must follow these steps:</p>
1.1 ihickson 746:
747: <ol><li>
748:
1.153 ihickson 749: <p>If the value of the <var title="">targetOrigin</var> argument is neither a single U+002A
750: ASTERISK character (*), a single U+002F SOLIDUS character (/), nor an <span>absolute URL</span>,
751: then throw a <code>SyntaxError</code> exception and abort the overall set of steps.</p>
1.1 ihickson 752:
753: </li>
754:
755: <li>
756:
1.88 ihickson 757: <p>Let <var title="">new ports</var> be an empty array.</p>
1.1 ihickson 758:
759: </li>
760:
761: <li>
762:
1.153 ihickson 763: <p>Let <var title="">transfer map</var> be an empty association list of
764: <code>Transferable</code> objects to placeholder objects.</p>
1.1 ihickson 765:
766: </li>
767:
768: <li>
769:
1.153 ihickson 770: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
771: substeps:</p>
1.88 ihickson 772:
773: <ol><li>
774:
1.153 ihickson 775: <p>If any object is listed in <var title="">transfer</var> more than once, or any of the
776: <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
777: <code>DataCloneError</code> exception and abort these steps.</p>
1.88 ihickson 778:
779: </li>
780:
781: <li>
782:
1.153 ihickson 783: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
784: 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
785: <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
1.105 ihickson 786: ports</var> array.</p>
1.88 ihickson 787:
788: </li>
789:
790: </ol></li>
791:
792: <li>
1.1 ihickson 793:
1.153 ihickson 794: <p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
795: clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
796: as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
797: these steps.</p>
1.1 ihickson 798:
799: </li>
800:
1.106 ihickson 801: <li>
802:
1.153 ihickson 803: <p>If the method was invoked with a third argument <var title="">transfer</var>, run these
804: substeps:</p>
1.105 ihickson 805:
806: <ol><li>
807:
1.154 ihickson 808: <p>Let <var title="">new owner</var> be the <span>script settings object</span> of the <code>Window</code> object on which the method was
1.153 ihickson 809: invoked.</p>
1.105 ihickson 810:
811: </li>
812:
813: <li>
814:
1.153 ihickson 815: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a new
816: object <var title="">y</var> by <span title="transfer a Transferable
817: object">transferring</span> the object <var title="">x</var> to <var title="">new owner</var>,
818: and replace the placeholder object that was created for the object <var title="">x</var> by
819: the new object <var title="">y</var> wherever the placeholder exists (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
1.105 ihickson 820:
821: </li>
822:
1.106 ihickson 823: </ol></li>
824:
825: <li>
1.1 ihickson 826:
1.153 ihickson 827: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span>
828: array.</p>
1.84 ihickson 829:
830: </li>
831:
832: <li>
833:
1.35 ihickson 834: <p>Return from the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code> method, but
1.1 ihickson 835: asynchronously continue running these steps.</p>
836:
837: </li>
838:
839: <li>
840:
1.154 ihickson 841:
1.153 ihickson 842: <p>If the <var title="">targetOrigin</var> argument is a single literal U+002F SOLIDUS character
843: (/), and the <code>Document</code> of the <code>Window</code> object on which the method was
1.156 ihickson 844: invoked does not have the <span>same origin</span> as the <span>responsible document</span> specified by the <span>entry settings
1.154 ihickson 845: object</span>, then abort these steps silently.</p>
1.153 ihickson 846:
847: <p>Otherwise, if the <var title="">targetOrigin</var> argument is an <span>absolute URL</span>,
848: and the <code>Document</code> of the <code>Window</code> object on which the method was invoked
849: does not have the <span>same origin</span> as <var title="">targetOrigin</var>, then abort these
850: steps silently.</p>
851:
852: <p>Otherwise, the <var title="">targetOrigin</var> argument is a single literal U+002A ASTERISK
853: character (*), and no origin check is made.</p>
1.1 ihickson 854:
855: </li>
856:
857: <li>
858:
1.154 ihickson 859:
1.124 ihickson 860: <p>Create a <span title="concept-events-trusted">trusted</span> event that uses the
1.162 ! ihickson 861: <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
1.124 ihickson 862: default action. The <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute must be
863: 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
1.156 ihickson 864: <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
1.154 ihickson 865: <code>WindowProxy</code> object corresponding to the
866: <span>global object</span> (a <code>Window</code> object) specified by the
1.156 ihickson 867: <span>incumbent settings object</span>,
1.154 ihickson 868: and the <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.
1.109 ihickson 869:
870: <a href="#refsHTML">[HTML]</a>
871:
1.148 ihickson 872: </p>
873:
1.113 ihickson 874:
1.1 ihickson 875: </li>
876:
877: <li>
878:
1.130 ihickson 879: <p><span>Queue a task</span> to <span title="concept-event-dispatch">dispatch</span> the event
880: created in the previous step at the <code>Window</code> object on which the method was invoked.
881: The <span>task source</span> for this <span title="concept-task">task</span> is the <a href="#posted-message-task-source">posted
882: message task source</a>.</p>
1.1 ihickson 883:
884: </li>
885:
1.114 ihickson 886: </ol></div>
887:
888:
889:
890:
891: <h2 id="channel-messaging"><span class="secno">5 </span><dfn>Channel messaging</dfn></h2>
892:
893: <h3 id="introduction-0"><span class="secno">5.1 </span>Introduction</h3>
894:
895: <p><i>This section is non-normative.</i></p>
896:
1.153 ihickson 897: <p>To enable independent pieces of code (e.g. running in different <span title="browsing
898: context">browsing contexts</span>) to communicate directly, authors can use <a href="#channel-messaging">channel
1.114 ihickson 899: messaging</a>.</p>
900:
1.153 ihickson 901: <p>Communication channels in this mechanism are implemented as two-ways pipes, with a port at each
902: end. Messages sent in one port are delivered at the other port, and vice-versa. Messages are
1.114 ihickson 903: asynchronous, and delivered as DOM events.</p>
904:
1.153 ihickson 905: <p>To create a connection (two "entangled" ports), the <code title="">MessageChannel()</code>
906: constructor is called:</p>
1.114 ihickson 907:
908: <pre>var channel = new MessageChannel();</pre>
909:
1.153 ihickson 910: <p>One of the ports is kept as the local port, and the other port is sent to the remote code, e.g.
911: using <code title="dom-window-postMessage"><a href="#dom-window-postmessage">postMessage()</a></code>:</p>
1.114 ihickson 912:
913: <pre>otherWindow.postMessage('hello', 'http://example.com', [channel.port2]);</pre>
914:
915: <p>To send messages, the <code title="dom-MessagePort-postMessage"><a href="#dom-messageport-postmessage">postMessage()</a></code> method on
916: the port is used:</p>
917:
918: <pre>channel.port1.postMessage('hello');</pre>
919:
1.162 ! ihickson 920: <p>To receive messages, one listens to <code title="event-message">message</code> events:</p>
1.114 ihickson 921:
922: <pre>channel.port1.onmessage = handleMessage;
1.1 ihickson 923: function handleMessage(event) {
924: // message is in event.data
925: // ...
1.114 ihickson 926: }</pre>
927:
1.153 ihickson 928: <p>Data sent on a port can be structured data; for example here an array of strings is passed on a
929: <code><a href="#messageport">MessagePort</a></code>:</p>
1.114 ihickson 930:
1.140 ihickson 931: <pre>port1.postMessage(['hello', 'world']);</pre>
1.114 ihickson 932:
933:
1.121 ihickson 934: <h4 id="examples"><span class="secno">5.1.1 </span>Examples</h4>
935:
936: <p><i>This section is non-normative.</i></p>
937:
938: <div class="example">
939:
1.153 ihickson 940: <p>In this example, two JavaScript libraries are connected to each other using
941: <code><a href="#messageport">MessagePort</a></code>s. This allows the libraries to later be hosted in different frames, or
942: in <code>Worker</code> objects, without any change to the APIs.</p>
1.121 ihickson 943:
944: <pre><script src="contacts.js"></script> <!-- exposes a contacts object -->
945: <script src="compose-mail.js"></script> <!-- exposes a composer object -->
946: <script>
947: var channel = new MessageChannel();
948: composer.addContactsProvider(channel.port1);
949: contacts.registerConsumer(channel.port2);
950: </script></pre>
951:
1.153 ihickson 952: <p>Here's what the "addContactsProvider()" function's implementation could look like:</p>
1.121 ihickson 953:
954: <pre>function addContactsProvider(port) {
955: port.onmessage = function (event) {
956: switch (event.data.messageType) {
957: 'search-result': handleSearchResult(event.data.results); break;
958: 'search-done': handleSearchDone(); break;
959: 'search-error': handleSearchError(event.data.message); break;
960: // ...
961: }
962: };
963: };</pre>
964:
965: <p>Alternatively, it could be implemented as follows:</p>
966:
967: <pre>function addContactsProvider(port) {
968: port.addEventListener('message', function (event) {
969: if (event.data.messageType == 'search-result')
970: handleSearchResult(event.data.results);
971: });
972: port.addEventListener('message', function (event) {
973: if (event.data.messageType == 'search-done')
974: handleSearchDone();
975: });
976: port.addEventListener('message', function (event) {
977: if (event.data.messageType == 'search-error')
978: handleSearchError(event.data.message);
979: });
980: // ...
981: port.start();
982: };</pre>
983:
1.153 ihickson 984: <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>
985:
986: <p>The <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code> method, whether called explicitly or
987: implicitly (by setting <code title="handler-MessagePort-onmessage"><a href="#handler-messageport-onmessage">onmessage</a></code>), starts the
988: flow of messages: messages posted on message ports are initially paused, so that they don't get
989: dropped on the floor before the script has had a chance to set up its handlers.</p>
1.121 ihickson 990:
991: </div>
992:
993:
994: <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 995:
996: <p><i>This section is non-normative.</i></p>
997:
1.153 ihickson 998: <p>Ports can be viewed as a way to expose limited capabilities (in the object-capability model
999: sense) to other actors in the system. This can either be a weak capability system, where the ports
1000: are merely used as a convenient model within a particular origin, or as a strong capability model,
1001: where they are provided by one origin <var title="">provider</var> as the only mechanism by which
1002: another origin <var title="">consumer</var> can effect change in or obtain information from <var title="">provider</var>.</p>
1003:
1004: <p>For example, consider a situation in which a social Web site embeds in one <code>iframe</code>
1005: the user's e-mail contacts provider (an address book site, from a second origin), and in a second
1006: <code>iframe</code> a game (from a third origin). The outer social site and the game in the second
1007: <code>iframe</code> cannot access anything inside the first <code>iframe</code>; together they can
1008: only:</p>
1009:
1010: <ul class="brief"><li><span>Navigate</span> the <code>iframe</code> to a new <span>URL</span>, such as the same
1011: <span>URL</span> but with a different fragment identifier, causing the <code>Window</code> in the
1012: <code>iframe</code> to receive a <code title="event-hashchange">hashchange</code> event.</li>
1.100 ihickson 1013:
1.153 ihickson 1014: <li>Resize the <code>iframe</code>, causing the <code>Window</code> in the <code>iframe</code> to
1015: receive a <code title="event-resize">resize</code> event.</li>
1.100 ihickson 1016:
1017:
1018:
1.162 ! ihickson 1019: <li>Send a <code title="event-message">message</code> event to the <code>Window</code> in the
1.153 ihickson 1020: <code>iframe</code> using the <code title="dom-window-postMessage"><a href="#dom-window-postmessage">window.postMessage()</a></code>
1.100 ihickson 1021: API.</li>
1022:
1.153 ihickson 1023: </ul><p>The contacts provider can use these methods, most particularly the third one, to provide an API
1024: that can be accessed by other origins to manipulate the user's address book. For example, it could
1.100 ihickson 1025: respond to a message "<code title="">add-contact Guillaume Tell
1.153 ihickson 1026: <tell@pomme.example.net></code>" by adding the given person and e-mail address to the user's
1027: address book.</p>
1028:
1029: <p>To avoid any site on the Web being able to manipulate the user's contacts, the contacts
1030: provider might only allow certain trusted sites, such as the social site, to do this.</p>
1.114 ihickson 1031:
1.153 ihickson 1032: <p>Now suppose the game wanted to add a contact to the user's address book, and that the social
1033: site was willing to allow it to do so on its behalf, essentially "sharing" the trust that the
1034: contacts provider had with the social site. There are several ways it could do this; most simply,
1035: it could just proxy messages between the game site and the contacts site. However, this solution
1036: has a number of difficulties: it requires the social site to either completely trust the game site
1037: not to abuse the privilege, or it requires that the social site verify each request to make sure
1038: it's not a request that it doesn't want to allow (such as adding multiple contacts, reading the
1039: contacts, or deleting them); it also requires some additional complexity if there's ever the
1040: possibility of multiple games simultaneously trying to interact with the contacts provider.</p>
1041:
1042: <p>Using message channels and <code><a href="#messageport">MessagePort</a></code> objects, however, all of these problems can
1043: go away. When the game tells the social site that it wants to add a contact, the social site can
1044: ask the contacts provider not for it to add a contact, but for the <em>capability</em> to add a
1045: single contact. The contacts provider then creates a pair of <code><a href="#messageport">MessagePort</a></code> objects, and
1046: sends one of them back to the social site, who forwards it on to the game. The game and the
1047: contacts provider then have a direct connection, and the contacts provider knows to only honor a
1048: single "add contact" request, nothing else. In other words, the game has been granted the
1.114 ihickson 1049: capability to add a single contact.</p>
1050:
1051:
1.121 ihickson 1052: <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 1053:
1054: <p><i>This section is non-normative.</i></p>
1055:
1.153 ihickson 1056: <p>Continuing the example from the previous section, consider the contacts provider in particular.
1057: While an initial implementation might have simply used <code>XMLHttpRequest</code> objects in the
1058: 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>
1059:
1060: <p>If the initial design used <code><a href="#messageport">MessagePort</a></code> objects to grant capabilities, or even just
1061: to allow multiple simultaneous independent sessions, the service implementation can switch from
1062: the <code>XMLHttpRequest</code>s-in-each-<code>iframe</code> model to the
1063: shared-<code>WebSocket</code> model without changing the API at all: the ports on the service
1064: provider side can all be forwarded to the shared worker without it affecting the users of the API
1065: in the slightest.</p>
1.114 ihickson 1066:
1067:
1068:
1069: <h3 id="message-channels"><span class="secno">5.2 </span>Message channels</h3>
1070:
1071: <pre class="idl">[<a href="#dom-messagechannel" title="dom-MessageChannel">Constructor</a>]
1.1 ihickson 1072: interface <dfn id="messagechannel">MessageChannel</dfn> {
1073: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port1" title="dom-channel-port1">port1</a>;
1074: readonly attribute <a href="#messageport">MessagePort</a> <a href="#dom-channel-port2" title="dom-channel-port2">port2</a>;
1.114 ihickson 1075: };</pre>
1076:
1077: <dl class="domintro"><dt><var title="">channel</var> = new <code title="dom-MessageChannel"><a href="#dom-messagechannel">MessageChannel</a></code>()</dt>
1.1 ihickson 1078:
1079: <dd>
1080:
1081: <p>Returns a new <code><a href="#messagechannel">MessageChannel</a></code> object with two new <code><a href="#messageport">MessagePort</a></code> objects.</p>
1082:
1083: </dd>
1084:
1085: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port1">port1</code></dt>
1086:
1087: <dd>
1088:
1089: <p>Returns the first <code><a href="#messageport">MessagePort</a></code> object.</p>
1090:
1091: </dd>
1092:
1093: <dt><var title="">channel</var> . <code title="dom-MessageChannel-port2">port2</code></dt>
1094:
1095: <dd>
1096:
1097: <p>Returns the second <code><a href="#messageport">MessagePort</a></code> object.</p>
1098:
1099: </dd>
1100:
1101: </dl><div class="impl">
1102:
1.153 ihickson 1103: <p>When the <dfn id="dom-messagechannel" title="dom-MessageChannel"><code>MessageChannel()</code></dfn> constructor is
1104: called, it must run the following algorithm:</p>
1.1 ihickson 1105:
1.154 ihickson 1106: <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>
1.156 ihickson 1107: is the <span>incumbent settings object</span>, and let <var title="">port1</var> be that object.</li>
1.154 ihickson 1108:
1.1 ihickson 1109:
1.154 ihickson 1110: <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>
1.156 ihickson 1111: is the <span>incumbent settings object</span>, and let <var title="">port2</var> be that object.</li>
1.1 ihickson 1112:
1.153 ihickson 1113: <li><p><a href="#entangle">Entangle</a> the <var title="">port1</var> and <var title="">port2</var>
1114: objects.</li>
1.1 ihickson 1115:
1.153 ihickson 1116: <li><p>Instantiate a new <code><a href="#messagechannel">MessageChannel</a></code> object, and let <var title="">channel</var>
1117: be that object.</li>
1.1 ihickson 1118:
1.153 ihickson 1119: <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 1120:
1.153 ihickson 1121: <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 1122:
1123: <li><p>Return <var title="">channel</var>.</li>
1124:
1.153 ihickson 1125: </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
1126: assigned when the <code><a href="#messagechannel">MessageChannel</a></code> object was created.</p>
1.1 ihickson 1127:
1.114 ihickson 1128: </div>
1129:
1130:
1131:
1132: <h3 id="message-ports"><span class="secno">5.3 </span>Message ports</h3>
1133:
1.153 ihickson 1134: <p>Each channel has two message ports. Data sent through one port is received by the other port,
1135: and vice versa.</p>
1.114 ihickson 1136:
1137: <pre class="idl">interface <dfn id="messageport">MessagePort</dfn> : <span>EventTarget</span> {
1.113 ihickson 1138: void <a href="#dom-messageport-postmessage" title="dom-MessagePort-postMessage">postMessage</a>(any message, optional sequence<<span>Transferable</span>> transfer);
1139: void <a href="#dom-messageport-start" title="dom-MessagePort-start">start</a>();
1.1 ihickson 1140: void <a href="#dom-messageport-close" title="dom-MessagePort-close">close</a>();
1141:
1142: // event handlers
1.120 ihickson 1143: attribute <span>EventHandler</span> <a href="#handler-messageport-onmessage" title="handler-MessagePort-onmessage">onmessage</a>;
1.159 ihickson 1144: attribute <span>EventHandler</span> <a href="#handler-messageport-onerror" title="handler-MessagePort-onerror">onerror</a>;
1.1 ihickson 1145: };
1.146 ihickson 1146: // <a href="#messageport">MessagePort</a> implements <span>Transferable</span>;</pre>
1.114 ihickson 1147:
1148: <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 1149:
1150: <dd>
1151:
1.153 ihickson 1152: <p>Posts a message through the channel. Objects listed in <var title="">transfer</var> are
1153: transferred, not just cloned, meaning that they are no longer usable on the sending side.</p>
1.1 ihickson 1154:
1.138 ihickson 1155: <p>Throws a <code>DataCloneError</code> exception if <var title="">transfer</var> array contains
1156: duplicate objects or the source or target ports, or if <var title="">message</var> could not be
1157: cloned.</p>
1.1 ihickson 1158:
1159: </dd>
1160:
1161: <dt><var title="">port</var> . <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start</a></code>()</dt>
1162:
1163: <dd>
1164:
1165: <p>Begins dispatching messages received on the port.</p>
1166:
1167: </dd>
1168:
1169: <dt><var title="">port</var> . <code title="dom-MessagePort-close"><a href="#dom-messageport-close">close</a></code>()</dt>
1170:
1171: <dd>
1172:
1173: <p>Disconnects the port, so that it is no longer active.</p>
1174:
1175: </dd>
1176:
1177: </dl><div class="impl">
1178:
1.137 ihickson 1179: <p>Each <code><a href="#messageport">MessagePort</a></code> object can be entangled with another (a symmetric relationship).
1180: Each <code><a href="#messageport">MessagePort</a></code> object also has a <span>task source</span> called the <dfn id="port-message-queue">port
1181: message queue</dfn>, initially empty. A <a href="#port-message-queue">port message queue</a> can be enabled or
1182: disabled, and is initially disabled. Once enabled, a port can never be disabled again (though
1183: messages in the queue can get moved to another queue or removed altogether, which has much the
1.154 ihickson 1184: 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
1185: initially be false, and an <dfn id="concept-port-owner" title="concept-port-owner">owner</dfn>, which is a <span>settings
1186: object</span> set when the object is created, as described below.</p>
1187:
1.134 ihickson 1188:
1.151 ihickson 1189: <p>When a port's <a href="#port-message-queue">port message queue</a> is enabled, the <span>event loop</span> must use
1.154 ihickson 1190: it as one of its <span title="task source">task sources</span>. All <span title="concept-task">tasks</span> <span title="queue a task">queued</span> on the <a href="#port-message-queue">port
1191: message queue</a> must be associated with the <span>responsible document</span> specified by
1192: the port's <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</p>
1193:
1.151 ihickson 1194:
1.154 ihickson 1195: <p class="note">If the port's <a href="#concept-port-owner" title="concept-port-owner">owner</a> specifies a <span>responsible document</span> that is <span>fully active</span>,
1196: but the event listeners all have scripts whose <span title="settings object">settings objects</span>
1197: specify <span title="responsible document">responsible documents</span> that are <em>not</em> <span>fully active</span>, then the messages will be
1.151 ihickson 1198: lost.</p>
1199:
1.154 ihickson 1200:
1.134 ihickson 1201: <p>Each <span>event loop</span> has a <span>task source</span> called the <dfn id="unshipped-port-message-queue">unshipped port
1202: message queue</dfn>. This is a virtual <span>task source</span>: it must act as if it contained
1203: the <span title="concept-task">tasks</span> of each <a href="#port-message-queue">port message queue</a> of each
1.154 ihickson 1204: <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
1205: message queue</a> is enabled, and whose <a href="#concept-port-owner" title="concept-port-owner">owner</a>
1206: specifies that <span>event loop</span> as the <span>responsible event loop</span>,
1207: in the order in which they were added to their respective
1.151 ihickson 1208: <span>task source</span>. When a <span title="concept-task">task</span> would be removed from the
1209: <a href="#unshipped-port-message-queue">unshipped port message queue</a>, it must instead be removed from its <a href="#port-message-queue">port message
1210: queue</a>.</p>
1.134 ihickson 1211:
1212: <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
1213: message queue</a> must be ignored for the purposes of the <span>event loop</span>. (The
1214: <a href="#unshipped-port-message-queue">unshipped port message queue</a> is used instead.)</p>
1215:
1216: <p class="note">The <a href="#has-been-shipped">has been shipped</a> flag is set to true when a port, its twin, or
1217: the object it was cloned from, is or has been <span title="transfer a transferable
1218: object">transferred</span>. When a <code><a href="#messageport">MessagePort</a></code>'s <a href="#has-been-shipped">has been shipped</a> flag
1219: is true, its <a href="#port-message-queue">port message queue</a> acts as a first-class <span>task source</span>,
1220: unaffected to any <a href="#unshipped-port-message-queue">unshipped port message queue</a>.</p>
1.1 ihickson 1221:
1.154 ihickson 1222:
1223: <p>When the user agent is to <dfn id="create-a-new-messageport-object">create a new <code>MessagePort</code> object</dfn> with a particular
1224: <span>settings object</span> as its <var title="">owner</var>, it must instantiate a new
1225: <code><a href="#messageport">MessagePort</a></code> object, and let its <a href="#concept-port-owner" title="concept-port-owner">owner</a> be <var title="">owner</var>.</p>
1.137 ihickson 1226:
1227: <p>When the user agent is to <dfn id="entangle">entangle</dfn> two <code><a href="#messageport">MessagePort</a></code> objects, it must run
1228: the following steps:</p>
1.1 ihickson 1229:
1230: <ol><li>
1231:
1.153 ihickson 1232: <p>If one of the ports is already entangled, then disentangle it and the port that it was
1233: entangled with.</p>
1.1 ihickson 1234:
1.153 ihickson 1235: <p class="note">If those two previously entangled ports were the two ports of a
1236: <code><a href="#messagechannel">MessageChannel</a></code> object, then that <code><a href="#messagechannel">MessageChannel</a></code> object no longer
1237: represents an actual channel: the two ports in that object are no longer entangled.</p>
1.1 ihickson 1238:
1239: </li>
1240:
1.143 ihickson 1241: <li>
1242:
1243: <p>Associate the two ports to be entangled, so that they form the two parts of a new channel.
1244: (There is no <code><a href="#messagechannel">MessageChannel</a></code> object that represents this channel.)</p>
1245:
1.144 ihickson 1246: <p>Two ports <var title="">A</var> and <var title="">B</var> that have gone through this step
1247: are now said to be entangled; one is entangled to the other, and vice versa.</p>
1.143 ihickson 1248:
1249: <p class="note">While this specification describes this process as instantaneous,
1250: implementations are more likely to implement it via message passing. As with all algorithms, the
1251: key is "merely" that the end result be indistinguishable, in a black-box sense, from the
1252: specification.</p>
1253:
1254: </li>
1.1 ihickson 1255:
1.153 ihickson 1256: </ol><p>When the user agent is to <dfn id="clone-a-port">clone a port</dfn> <var title="">original port</var>, with the
1257: clone being owned by <var title="">owner</var>, it must run the following steps, which return a
1258: new <code><a href="#messageport">MessagePort</a></code> object. These steps must be run atomically.</p>
1.1 ihickson 1259:
1.134 ihickson 1260: <ol><li><p>Set <var title="">original port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1261: true.</li>
1262:
1.154 ihickson 1263: <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 1264:
1.134 ihickson 1265: <li><p>Set <var title="">new port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to true.</li>
1266:
1.161 ihickson 1267:
1.162 ! ihickson 1268: <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
1.153 ihickson 1269: port</var> to the <a href="#port-message-queue">port message queue</a> of <var title="">new port</var>, if any,
1270: leaving the <var title="">new port</var>'s <a href="#port-message-queue">port message queue</a> in its initial
1.161 ihickson 1271: disabled state, and reassociating the moved <span title="concept-task">tasks</span> with the <span>responsible document</span> specified by <var title="">new
1272: port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</li>
1273:
1274: <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
1275: create a <span title="concept-task">task</span> that <span title="fire a simple event">fires a
1276: simple event</span> named <code title="event-error">error</code> at the <var title="">new
1277: port</var>, and add the <span title="concept-task">task</span> to the <a href="#port-message-queue">port message
1278: queue</a> of <var title="">new port</var>. The <span title="concept-task">task</span> must
1279: be associated with the <span>responsible document</span> specified by <var title="">new
1280: port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</li>
1.1 ihickson 1281:
1282: <li>
1283:
1.153 ihickson 1284: <p>If the <var title="">original port</var> is entangled with another port, then run these
1285: substeps:</p>
1.1 ihickson 1286:
1.153 ihickson 1287: <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 1288:
1.134 ihickson 1289: <li><p>Set <var title="">remote port</var>'s <a href="#has-been-shipped">has been shipped</a> flag to
1290: true.</li>
1291:
1.153 ihickson 1292: <li><p><a href="#entangle">Entangle</a> the <var title="">remote port</var> and <var title="">new
1293: port</var> objects. The <var title="">original port</var> object will be disentangled by this
1.1 ihickson 1294: process.</li>
1295:
1296: </ol></li>
1297:
1.153 ihickson 1298: <li><p>Return <var title="">new port</var>. It is the clone.</li>
1.1 ihickson 1299:
1.153 ihickson 1300: </ol><p id="transferMessagePort">To <span title="transfer a Transferable object">transfer</span> a
1301: <code><a href="#messageport">MessagePort</a></code> object <var title="">old</var> to a new owner <var title="">owner</var>,
1302: a user agent must <a href="#clone-a-port" title="clone a port">clone</a> the <var title="">old</var> object with
1303: the clone being owned by <var title="">owner</var>, thus obtaining <var title="">new</var>, must
1304: <span title="concept-Transferable-neutered">neuter</span> the <var title="">old</var> port, and
1305: must finally return <var title="">new</var>.</p>
1306:
1307: <hr><p>The <dfn id="dom-messageport-postmessage" title="dom-MessagePort-postMessage"><code>postMessage()</code></dfn> method, when
1308: called on a port <var title="">source port</var>, must cause the user agent to run the following
1309: steps:</p>
1.1 ihickson 1310:
1.153 ihickson 1311: <ol><li><p>Let <var title="">target port</var> be the port with which <var title="">source port</var>
1312: is entangled, if any.</li>
1.1 ihickson 1313:
1.88 ihickson 1314: <li>
1315:
1.158 ihickson 1316: <p>Let <var title="">doomed</var> be false. It is set to true if a condition is detected that
1317: 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
1318: object">transferred</span>. (This condition cannot necessarily be detected synchronously.)</p>
1319:
1320: </li>
1321:
1322: <li>
1323:
1.88 ihickson 1324: <p>Let <var title="">new ports</var> be an empty array.</p>
1325:
1326: </li>
1327:
1328: <li>
1.1 ihickson 1329:
1.153 ihickson 1330: <p>Let <var title="">transfer map</var> be an empty association list of
1331: <code>Transferable</code> objects to placeholder objects.</p>
1.1 ihickson 1332:
1.88 ihickson 1333: </li>
1.1 ihickson 1334:
1.88 ihickson 1335: <li>
1.1 ihickson 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.1 ihickson 1339:
1340: <ol><li>
1341:
1.153 ihickson 1342: <p>If any object is listed in <var title="">transfer</var> more than once, or any of the
1343: <code>Transferable</code> objects listed in <var title="">transfer</var> are marked as <span title="concept-Transferable-neutered">neutered</span>, then throw a
1344: <code>DataCloneError</code> exception and abort these steps.</p>
1.1 ihickson 1345:
1.88 ihickson 1346: </li>
1.1 ihickson 1347:
1.88 ihickson 1348: <li>
1349:
1.158 ihickson 1350:
1351: <p>If any of the objects in <var title="">transfer</var> are the <var title="">source
1352: port</var>, then throw a
1.153 ihickson 1353: <code>DataCloneError</code> exception and abort these steps.</p>
1.88 ihickson 1354:
1.89 ihickson 1355: </li>
1.1 ihickson 1356:
1.84 ihickson 1357: <li>
1358:
1.158 ihickson 1359: <p>If any of the objects in <var title="">transfer</var> are the <var title="">target
1360: port</var>, if any, then let <var title="">doomed</var> be true, and optionally report to a
1361: developer console that the target port was posted to itself, causing the communication channel
1362: to be lost.</p>
1363:
1364: </li>
1365:
1366: <li>
1367:
1.153 ihickson 1368: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, add a
1369: 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
1370: <code><a href="#messageport">MessagePort</a></code> object, also append the placeholder object to the <var title="">new
1.105 ihickson 1371: ports</var> array.</p>
1.84 ihickson 1372:
1373: </li>
1374:
1.89 ihickson 1375: </ol></li>
1376:
1377: <li>
1.1 ihickson 1378:
1.153 ihickson 1379: <p>Let <var title="">message clone</var> be the result of obtaining a <span>structured
1380: clone</span> of the <var title="">message</var> argument, with <var title="">transfer map</var>
1381: as the <i>transfer map</i>. If this throws an exception, then throw that exception and abort
1382: these steps.</p>
1.88 ihickson 1383:
1384: </li>
1385:
1.105 ihickson 1386: <li>
1387:
1.153 ihickson 1388: <p>If the method was invoked with a second argument <var title="">transfer</var>, run these
1389: substeps:</p>
1.105 ihickson 1390:
1391: <ol><li>
1392:
1.154 ihickson 1393:
1394: <p>Let <var title="">new owner</var> be the <a href="#concept-port-owner" title="concept-port-owner">owner</a> of <var title="">target port</var>, if there
1.158 ihickson 1395: 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 1396: owner</var> is used when transferring objects below. If there is no <var title="">target
1.158 ihickson 1397: port</var>, or if the <var title="">target port</var> is one of the objects being <span title="transfer a Transferable
1398: object">transferred</span>, the <code>Transferable</code> objects given in the second argument, if any, are
1.153 ihickson 1399: still <span title="transfer a Transferable object">transferred</span>, but since they are then
1400: discarded, it doesn't matter where they are transferred to.)</p>
1.105 ihickson 1401:
1402: </li>
1403:
1404:
1405: <li>
1406:
1.153 ihickson 1407: <p>For each object <var title="">x</var> in <var title="">transfer</var> in turn, obtain a new
1408: object <var title="">y</var> by <span title="transfer a Transferable
1409: object">transferring</span> the object <var title="">x</var> to <var title="">new owner</var>,
1410: and replace the placeholder object that was created for the object <var title="">x</var> by
1411: the new object <var title="">y</var> wherever the placeholder exists (i.e. in <var title="">message clone</var> and in <var title="">new ports</var>).</p>
1.105 ihickson 1412:
1413: </li>
1414:
1415: </ol></li>
1.88 ihickson 1416:
1417: <li>
1418:
1.153 ihickson 1419: <p>Make <var title="">new ports</var> into a <span title="dfn-read-only-array">read only</span>
1420: array.</p>
1.88 ihickson 1421:
1422: </li>
1423:
1.158 ihickson 1424:
1.153 ihickson 1425: <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var> is
1.158 ihickson 1426: not entangled), or if <var title="">doomed</var> is true, then abort these steps.</li>
1.113 ihickson 1427:
1.162 ! ihickson 1428: <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.153 ihickson 1429: default action.
1.109 ihickson 1430:
1431: <a href="#refsHTML">[HTML]</a>
1432:
1433: </li>
1.88 ihickson 1434:
1.153 ihickson 1435: <li><p>Let the <code title="dom-MessageEvent-data"><a href="#dom-messageevent-data">data</a></code> attribute of the event be
1436: initialized to the value of <var title="">message clone</var>.</li>
1.88 ihickson 1437:
1.153 ihickson 1438: <li><p>Let the <code title="dom-MessageEvent-ports"><a href="#dom-messageevent-ports">ports</a></code> attribute of the event be
1439: initialized to the <var title="">new ports</var> array.</li>
1.1 ihickson 1440:
1.153 ihickson 1441: <li><p>Add the event to the <a href="#port-message-queue">port message queue</a> of <var title="">target
1442: port</var>.</li>
1.1 ihickson 1443:
1.137 ihickson 1444: </ol><hr><p>The <dfn id="dom-messageport-start" title="dom-MessagePort-start"><code>start()</code></dfn> method must enable its port's
1445: <a href="#port-message-queue">port message queue</a>, if it is not already enabled.</p>
1446:
1447: <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 1448: <var title="">local port</var> that is entangled with another port, must cause the user agent to
1.137 ihickson 1449: disentangle the two ports. If the method is called on a port that is not entangled, then the
1450: method must do nothing.</p>
1451:
1.159 ihickson 1452: <hr><p>In some circumstances, an entangled <code><a href="#messageport">MessagePort</a></code> <var title="">source port</var>
1453: that is not <a href="#ports-and-garbage-collection">eligible for garbage collection</a> will
1454: nonetheless find itself prematurely destroyed, for example if the user manually terminates the
1455: user agent's host process. Under such circumstances, user agents should attempt to following these
1456: steps:</p>
1457:
1458:
1459:
1460:
1461:
1462: <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>
1463:
1464: <li><p>If there is no <var title="">target port</var> (i.e. if <var title="">source port</var>
1465: 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
1466: steps.</li>
1467:
1.161 ihickson 1468: <li><p>Mark <var title="">target port</var> as being a <dfn id="related-to-an-ill-fated-port">related to an ill-fated
1469: port</dfn>.</li>
1470:
1.160 ihickson 1471:
1.161 ihickson 1472: <li><p>Create a <span title="concept-task">task</span> that <span title="fire a simple 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 <a href="#port-message-queue">port message queue</a> of <var title="">target port</var>. The <span title="concept-task">task</span> must be associated with the <span>responsible document</span>
1.160 ihickson 1473: specified by <var title="">source port</var>'s <a href="#concept-port-owner" title="concept-port-owner">owner</a>.</li>
1.159 ihickson 1474:
1475: <li><p>Disentangle the two ports.</li>
1476:
1477: </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
1478: applications that operate across multiple browser processes (e.g. using workers or communicating
1479: across multiple tabs) to gracefully handle a catastrophic failure in one process. A strictly
1480: conforming user agent would never fail unexpectedly, and thus would never send this event!</p>
1481:
1.137 ihickson 1482: <hr><p>The following are the <span>event handlers</span> (and their corresponding <span title="event
1.153 ihickson 1483: handler event type">event handler event types</span>) that must be supported, as <span>event
1484: handler IDL attributes</span>, by all objects implementing the <code><a href="#messageport">MessagePort</a></code>
1485: interface:</p>
1.1 ihickson 1486:
1487: <table><thead><tr><th><span title="event handlers">Event handler</span> <th><span>Event handler event type</span>
1.162 ! ihickson 1488: <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 1489: <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 1490: </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
1491: message queue</a> must be enabled, as if the <code title="dom-MessagePort-start"><a href="#dom-messageport-start">start()</a></code>
1492: method had been called.</p>
1.1 ihickson 1493:
1.114 ihickson 1494: </div>
1495:
1496:
1.128 ihickson 1497: <h3 id="broadcasting-to-many-ports"><span class="secno">5.4 </span>Broadcasting to many ports</h3>
1498:
1.152 ihickson 1499: <p class="critical">The API described in this section is controversial, as, in an attempt to solve
1500: an architectural memory leak, it instead exposes the details of Garbage Collection. This is a
1501: lose-lose scenario. A better solution is really needed here.</p>
1502:
1.128 ihickson 1503: <p>Broadcasting to many ports is in principle relatively simple: keep an array of
1504: <code><a href="#messageport">MessagePort</a></code> objects to send messages to, and iterate through the array to send a
1.129 ihickson 1505: message. However, this has one rather unfortunate effect: it prevents the ports from being garbage
1.128 ihickson 1506: collected, even if the other side has gone away.</p>
1507:
1508: <p>To avoid this problem, the <code><a href="#portcollection">PortCollection</a></code> object can be used. It acts as an opaque
1509: array of <code><a href="#messageport">MessagePort</a></code> objects, thus allowing the objects to be garbage collected when
1510: they stop being relevant, while still allowing scripts to iterate over the
1511: <code><a href="#messageport">MessagePort</a></code> objects.</p>
1512:
1513: <pre class="idl">[<a href="#dom-portcollection" title="dom-PortCollection">Constructor</a>] interface <dfn id="portcollection">PortCollection</dfn> {
1514: void <a href="#dom-portcollection-add" title="dom-PortCollection-add">add</a>(<a href="#messageport">MessagePort</a> port);
1515: void <a href="#dom-portcollection-remove" title="dom-PortCollection-remove">remove</a>(<a href="#messageport">MessagePort</a> port);
1516: void <a href="#dom-portcollection-clear" title="dom-PortCollection-clear">clear</a>();
1517: void <a href="#dom-portcollection-iterate" title="dom-PortCollection-iterate">iterate</a>(<a href="#portcollectioncallback">PortCollectionCallback</a> callback);
1518: };
1519:
1520: callback <dfn id="portcollectioncallback">PortCollectionCallback</dfn> = void (<a href="#messageport">MessagePort</a> port);</pre>
1521:
1522: <dl class="domintro"><dt><var title="">portCollection</var> = new <code title="dom-PortCollection"><a href="#dom-portcollection">PortCollection</a></code>()</dt>
1523:
1524: <dd>
1525:
1526: <p>Returns a new empty <code><a href="#portcollection">PortCollection</a></code> object.</p>
1527:
1528: </dd>
1529:
1530: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-add"><a href="#dom-portcollection-add">add</a></code>(<var title="">port</var>)</dt>
1531:
1532: <dd>
1533:
1534: <p>Adds <var title="">port</var> to the collection, if it isn't already present.</p>
1535:
1536: </dd>
1537:
1538: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-remove"><a href="#dom-portcollection-remove">remove</a></code>(<var title="">port</var>)</dt>
1539:
1540: <dd>
1541:
1542: <p>Removes <var title="">port</var> from the collection, if it is present.</p>
1543:
1544: </dd>
1545:
1546: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-clear"><a href="#dom-portcollection-clear">clear</a></code>()</dt>
1547:
1548: <dd>
1549:
1550: <p>Removes all ports from the collection.</p>
1551:
1552: </dd>
1553:
1554: <dt><var title="">portCollection</var> . <code title="dom-PortCollection-iterate"><a href="#dom-portcollection-iterate">iterate</a></code>(<var title="">callback</var>)</dt>
1555:
1556: <dd>
1557:
1558: <p>Calls <var title="">callback</var> for each port in the collection.</p>
1559:
1560: </dd>
1561:
1562: </dl><div class="impl">
1563:
1564: <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
1565: a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is garbage collected, it must be
1566: silently removed from that <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>. Objects
1567: in a <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> are ordered chronologically by
1568: the time at which they were most recently added; the least-recently added <code><a href="#messageport">MessagePort</a></code>
1569: object is the first in the list, and the most-recently added <code><a href="#messageport">MessagePort</a></code> is the last
1570: in the list.</p>
1571:
1572: <p>The <dfn id="dom-portcollection" title="dom-PortCollection"><code>PortCollection()</code></dfn> constructor must return
1573: 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>
1574:
1575: <p>The <dfn id="dom-portcollection-add" title="dom-PortCollection-add"><code>add()</code></dfn> method must add the
1576: <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
1577: already in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1578: method does nothing. (Calling this method with a port already in the list does not move the port
1579: to the end of the list.)</p>
1580:
1581: <p>The <dfn id="dom-portcollection-remove" title="dom-PortCollection-remove"><code>remove()</code></dfn> method must remove the
1582: <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
1583: not in the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in which case the
1584: method does nothing.</p>
1585:
1586: <p>The <dfn id="dom-portcollection-clear" title="dom-PortCollection-clear"><code>clear()</code></dfn> method must remove all
1587: <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.
1588: If the <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a> is already empty, the method
1589: does nothing.</p>
1590:
1591: <p>The <dfn id="dom-portcollection-iterate" title="dom-PortCollection-iterate"><code>iterate()</code></dfn> method must invoke its
1592: <code><a href="#portcollectioncallback">PortCollectionCallback</a></code> argument once for each <code><a href="#messageport">MessagePort</a></code> object in the
1593: object's <a href="#concept-portcollection-list" title="concept-PortCollection-list">list of ports</a>, in the order defined
1594: above, with each invocation being passed the corresponding <code><a href="#messageport">MessagePort</a></code> object as the
1595: callback's sole argument.</p>
1596:
1597: </div>
1598:
1599:
1600: <h3 id="ports-and-garbage-collection"><span class="secno">5.5 </span>Ports and garbage collection</h3>
1.114 ihickson 1601:
1602: <div class="impl">
1.1 ihickson 1603:
1.154 ihickson 1604:
1.153 ihickson 1605: <p>When a <code><a href="#messageport">MessagePort</a></code> object <var title="">o</var> is entangled, user agents must
1606: either act as if <var title="">o</var>'s entangled <code><a href="#messageport">MessagePort</a></code> object has a strong
1.154 ihickson 1607: 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
1.153 ihickson 1608: to <var title="">o</var>.</p>
1.1 ihickson 1609:
1610: <div class="note">
1611:
1.153 ihickson 1612: <p>Thus, a message port can be received, given an event listener, and then forgotten, and so long
1613: as that event listener could receive a message, the channel will be maintained.</p>
1614:
1615: <p>Of course, if this was to occur on both sides of the channel, then both ports could be garbage
1616: collected, since they would not be reachable from live code, despite having a strong reference to
1617: each other.</p>
1.1 ihickson 1618:
1619: </div>
1620:
1.159 ihickson 1621:
1.153 ihickson 1622: <p>Furthermore, a <code><a href="#messageport">MessagePort</a></code> object must not be garbage collected while there exists
1.159 ihickson 1623: an event in a <span>task queue</span> that is to be dispatched on that <code><a href="#messageport">MessagePort</a></code>
1624: object, or while the <code><a href="#messageport">MessagePort</a></code> object's <a href="#port-message-queue">port message queue</a> is enabled and
1.162 ! ihickson 1625: there exists a <code title="event-message">message</code> event in that queue.</p>
1.113 ihickson 1626:
1.79 ihickson 1627:
1.113 ihickson 1628:
1.128 ihickson 1629: <p>There are no strong references from a <code><a href="#portcollection">PortCollection</a></code> object to its
1630: <code><a href="#messageport">MessagePort</a></code> objects. (That is in fact the whole point of <code><a href="#portcollection">PortCollection</a></code>
1631: objects: they allow for <code><a href="#messageport">MessagePort</a></code> objects to be referenced without preventing them
1632: from being garbage collected.)</p>
1633:
1.114 ihickson 1634: </div>
1635:
1.128 ihickson 1636: <p class="note">Authors are strongly encouraged to explicitly close <code><a href="#messageport">MessagePort</a></code>
1637: objects to disentangle them, so that their resources can be recollected. Creating many
1638: <code><a href="#messageport">MessagePort</a></code> objects and discarding them without closing them can lead to high
1.159 ihickson 1639: transient memory usage since garbage collection is not necessarily performed promptly, especially
1640: for <code><a href="#messageport">MessagePort</a></code>s where garbage collection can involve cross-process coordination.</p>
1.114 ihickson 1641:
1642:
1643: <h2 class="no-num" id="references">References</h2>
1644:
1645: <p>All references are normative unless marked "Non-normative".</p>
1646:
1647:
1648:
1.132 ihickson 1649: <dl><dt id="refsDOM">[DOM]</dt>
1650: <dd><cite><a href="http://dom.spec.whatwg.org/">DOM</a></cite>, A. van Kesteren, A. Gregor, Ms2ger. WHATWG.</dd>
1.72 ihickson 1651:
1652: <dt id="refsHTML">[HTML]</dt>
1.127 ihickson 1653: <dd><cite><a href="http://www.whatwg.org/specs/web-apps/current-work/">HTML</a></cite>, I. Hickson. WHATWG.</dd>
1.111 ihickson 1654:
1.72 ihickson 1655: <dt id="refsRFC2119">[RFC2119]</dt>
1.133 ihickson 1656: <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 1657:
1.55 ihickson 1658: <dt id="refsWEBIDL">[WEBIDL]</dt>
1.133 ihickson 1659: <dd><cite><a href="http://dev.w3.org/2006/webapi/WebIDL/">Web IDL</a></cite>, C. McCormack. W3C.</dd>
1.1 ihickson 1660:
1.114 ihickson 1661: </dl><h2 class="no-num" id="acknowledgements">Acknowledgements</h2>
1662:
1663: <p>For a full list of acknowledgements, please see the HTML
1664: specification. <a href="#refsHTML">[HTML]</a></p>
1665:
1666:
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