Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[WIP] Refactor structured clone into serialize/deserialize steps #2421

Merged
merged 40 commits into from
Mar 20, 2017
Merged
Changes from 1 commit
Commits
Show all changes
40 commits
Select commit Hold shift + click to select a range
d580c82
Add StructuredSerialize()
domenic Mar 7, 2017
5c27fd4
Re-do the model for platform objects
domenic Mar 7, 2017
37e5659
Change variable names from (input, output) to (value, serialized)
domenic Mar 7, 2017
e004ea3
Deserialize done now
domenic Mar 7, 2017
e208bce
OK, transfer/receivetransfer done
domenic Mar 8, 2017
eb13657
OK, I finally replaced StructuredClone
domenic Mar 8, 2017
2e2ec4a
Fix link error
domenic Mar 8, 2017
daab858
Use IDL [Serializable] and [Transferable] instead of type strings
domenic Mar 8, 2017
63ef273
Fix nits
domenic Mar 8, 2017
9ae5d5e
Don't use "let" to declare variables inside an "if" scope
domenic Mar 8, 2017
007a22b
OffscreenCanvas transfer updated
domenic Mar 8, 2017
6ab096e
ImageBitmap clone and transfer updated
domenic Mar 8, 2017
fe559d1
Copy ArrayBuffers at serialization time
domenic Mar 9, 2017
f4edf17
Genericize detached-checking
domenic Mar 9, 2017
d11aedf
Move MessagePort's [[Transfer]]() to transfer steps
domenic Mar 9, 2017
200cae6
Update File API monkeypatch; a few normative fixes
domenic Mar 9, 2017
47fb170
Define serialization for File, not just Blob
domenic Mar 9, 2017
e65cb80
Update ImageData [[Clone]]() -> (de)serialization steps
domenic Mar 9, 2017
a861483
Delete most of the old stuff
domenic Mar 9, 2017
ccdd204
Update "using from other specifications" with some usage guidance
domenic Mar 9, 2017
7cd1607
Add missing link
domenic Mar 9, 2017
76b63d6
Fix validation error/bad ID
domenic Mar 9, 2017
f3c2bbc
Update for latest code review
domenic Mar 14, 2017
1dd72af
Fix MessagePort and usage site of StructuredCloneWithTransfer
domenic Mar 14, 2017
8fba594
Make StructuredDeserializeWithTransfer usage a little simpler
domenic Mar 14, 2017
b6a1fe7
Inline IsTransferable
domenic Mar 14, 2017
c4db175
Inline StructuredTransfer
domenic Mar 14, 2017
24d8dd1
Inline StructuredReceiveTransfer; remove out of place note about allo…
domenic Mar 14, 2017
66c146a
Minor tweaks, mostly to notes around _memory_
domenic Mar 14, 2017
1a726a2
Update history.state to use serialize/deserialize
domenic Mar 14, 2017
bbaa65b
Update BroadcastChannel to use serialize/deserialize
domenic Mar 14, 2017
60ecdf8
Add explicit asserts that you can't deserialize a transfer twice
domenic Mar 14, 2017
84f4ddc
Fix link error
domenic Mar 14, 2017
4e8bea0
Remove StructuredClone
domenic Mar 15, 2017
3b89876
Fix IsTransferable inlining
domenic Mar 15, 2017
e3edc1d
Fix portMessage event vs. task reference
domenic Mar 15, 2017
169fdc3
Fix URL StructuredSerialize reference
domenic Mar 15, 2017
0be172f
Remove redundant word
domenic Mar 15, 2017
070631b
Fix nits found
domenic Mar 16, 2017
02c5ca4
Move Serializable annotation to the correct interface
annevk Mar 17, 2017
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Update "using from other specifications" with some usage guidance
domenic committed Mar 20, 2017

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature. The key has expired.
commit ccdd20446317e39d728a1bfcaf9e8d7acb80f6d2
82 changes: 68 additions & 14 deletions source
Original file line number Diff line number Diff line change
@@ -8632,26 +8632,81 @@ interface <dfn>DOMStringList</dfn> {
<li><p>Return false.</p></li>
</ol>

<h4>Performing structured clones from other specifications</h4>
<h4 id="performing-structured-clones-from-other-specifications">Performing serialization and
transferring from other specifications</h4>

<p>TODO: needs updating</p>
<p>Other specifications may use the abstract operations defined here. The following provides
some guidance on when each abstract operation is typically useful, with examples. Roughly
speaking, the earlier abstract operations in this list are more broadly useful than the later
ones.</p>

<p>Other specifications may use the <span>StructuredClone</span>,
<span>StructuredCloneWithTransfer</span>, and <span>IsTransferable</span> abstract operations.</p>
<dl>
<dt><span>StructuredClone</span></dt>
<dd>
<p>Cloning a value into a known target <span>JavaScript Realm</span></p>

<p class="example"><code data-x="dom-history-pushState">history.pushState()</code> and <code
data-x="dom-history-replaceState">history.replaceState()</code> use
<span>StructuredClone</span> as a sort of sanitization step performed on user-supplied data.</p>
</dd>

<dt><span>StructuredCloneWithTransfer</span></dt>
<dd>
<p>Cloning a value into a known target <span>JavaScript Realm</span>, with a transfer list.</p>

<p class="example"><code data-x="dom-window-postMessage">window.postMessage()</code> uses
<span>StructuredCloneWithTransfer</span> to allow cloning and transferring values between
different globals.</p>
</dd>

<dt><span>StructuredSerialize</span></dt>
<dt><span>StructuredDeserialize</span></dt>
<dd>
<p>Creating a <span>JavaScript Realm</span>-independent snapshot of a given value which can be
saved for an indefinite amount of time, and then reified back into a JavaScript value later.</p>

<p class="example">Any API for persisting JavaScript values to the filesystem.</p>
</dd>

<dt><span>StructuredSerializeWithTransfer</span></dt>
<dt><span>StructuredDeserializeWithTransfer</span></dt>
<dd>
<p>Cloning a value to another <span>JavaScript Realm</span>, with a transfer list, but where the
target Realm is not known ahead of time. In this case the serialization step can be performed
immediately, with the deserialization step delayed until the target Realm becomes known.</p>

<p class="example"><code data-x="dom-MessagePort-postMessage">messagePort.postMessage()</code>
uses this pair of abstract operations, as the destination Realm is not known until the
<code>MessagePort</code> <span>has been shipped</span>.</p>
</dd>

<dt><span>IsTransferable</span></dt>
<dt><span>StructuredTransfer</span></dt>
<dt><span>StructuredReceiveTransfer</span></dt>
<dd>
<p>These low-level abstract operations are only used when an API needs to manually transfer
individual objects, instead of handling transfers via a transfer list accepted by one of the
previously-discussed abstract operations.</p>
</dd>
</dl>

<p>In general, call sites may pass in Web IDL values instead of JavaScript values; this is to be
understood to perform an implicit <span data-x="concept-idl-convert">conversion</span> to the
JavaScript value before invoking these algorithms.</p>

<hr>

<p>Call sites that are not invoked as a result of author code synchronously calling into a user
agent method must take care to properly <span>prepare to run script</span> and <span>prepare to
run a callback</span> before invoking these abstract operations, if they are being performed on
arbitrary objects. This is necessary because the <span>StructuredClone</span> operation can invoke
author-defined accessors as part of its final deep-cloning steps, and these accessors could call
into operations that rely on the <span data-x="concept-entry-everything">entry</span> and <span
run a callback</span> before invoking <span>StructuredClone</span>,
<span>StructuredCloneWithTransfer</span>, <span>StructuredSerialize</span>, or
<span>StructuredSerializeWithTransfer</span> abstract operations, if they are being performed on
arbitrary objects. This is necessary because the serialization process can invoke author-defined
accessors as part of its final deep-serialization steps, and these accessors could call into
operations that rely on the <span data-x="concept-entry-everything">entry</span> and <span
data-x="concept-incumbent-everything">incumbent</span> concepts being properly set up.</p>

<p class="example"><code data-x="dom-window-postMessage">postMessage</code> performs
<p class="example"><code data-x="dom-window-postMessage">window.postMessage()</code> performs
<span>StructuredCloneWithTransfer</span> on its arguments, but is careful to do so immediately,
inside the synchronous portion of its algorithm. Thus it is able to use the structured cloning
algorithms without needing to <span>prepare to run script</span> and <span>prepare to run a
@@ -8664,13 +8719,12 @@ interface <dfn>DOMStringList</dfn> {
data-x="concept-incumbent-everything">incumbent</span> values, and thus it too does not need to
perform these preparation steps.</p>

<p class="example">In contrast, a hypothetical API that used <span>StructuredClone</span> to
<p class="example">In contrast, a hypothetical API that used <span>StructuredSerialize</span> to
serialize some author-supplied object periodically, directly from a <span
data-x="concept-task">task</span> on the <span>event loop</span>, would need to ensure it performs
the appropriate preparations before calling into the structured clone algorithms. As of this time,
we know of no such APIs on the platform; usually it is simpler to perform the clone ahead of time,
as a synchronous consequence of author code, like <code
data-x="dom-window-postMessage">postMessage</code>.</p>
the appropriate preparations beforehand. As of this time, we know of no such APIs on the platform;
usually it is simpler to perform the serialization ahead of time, as a synchronous consequence of
author code.</p>

<h4>Monkey patch for <code>Blob</code> and <code>FileList</code> objects</h4>