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.

Sign up for GitHub

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

Describe integration with the WeakRefs proposal #4571

Merged
merged 23 commits into from
Mar 18, 2021
Merged

Describe integration with the WeakRefs proposal #4571

Changes from all commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
5aa7783
Describe integration with the WeakRefs proposal
littledan Apr 26, 2019
64762e1
Editorial: Add cross-reference
littledan Apr 26, 2019
979b9fb
Changes from review from Anne and Mathieu
littledan Apr 30, 2019
02d7ca5
Move WeakRef processing logic back to the WeakRef specification
littledan Apr 30, 2019
37de013
ClearKeptObjects in microtask checkpoint algorithm
littledan May 3, 2019
65407e9
Report the exception from CleanupFinalizationGroup
littledan May 6, 2019
531e610
Clean up definition of garbage collection task source
littledan May 20, 2019
8fda8e0
Editorial cleanup in HostCleanupFinalizationGroup
littledan Jun 4, 2019
5bfbfd2
Rename FinalizationGroup to FinalizationRegistry
littledan Apr 24, 2020
ec9b8f1
cleanupSome must be omitted; follow up in issues
littledan Apr 24, 2020
ec24205
Editorial changes.
Ms2ger Apr 27, 2020
78b5ca9
Specify handling of entry and incumbent objects.
Ms2ger Feb 5, 2020
b03f374
fixup! Specify handling of entry and incumbent objects.
Ms2ger Apr 27, 2020
906bc7c
Review comment
Ms2ger Apr 27, 2020
3e6f119
Remove reference to proposal since WeakRefs have been merged into ecm…
syg Feb 19, 2021
7d4e6aa
Depend on https://github.com/tc39/ecma262/pull/2316 for incumbent mac…
syg Feb 19, 2021
e0611bb
Remove cleanupSome reference since that was split out into separate p…
syg Feb 19, 2021
2bbab42
Address review; move FR hook into job-integration section
syg Feb 19, 2021
f06928d
Add notes about ClearKeptObjects
syg Feb 19, 2021
44b79e1
Refine ClearKeptObjects note to not suggest that it dies due to Clear…
syg Feb 19, 2021
f7041ef
Broaden incumbent tracking in Promises to also include FinalizationRe…
syg Feb 22, 2021
cb0f44e
Address domenic review
syg Mar 12, 2021
557bd3d
formatting
annevk Mar 18, 2021
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
88 changes: 80 additions & 8 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2775,6 +2775,8 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute

<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-arraycreate">ArrayCreate</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-call">Call</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-clear-kept-objects">ClearKeptObjects</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-cleanup-finalization-registry">CleanupFinalizationRegistry</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-construct">Construct</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-copydatablockbytes">CopyDataBlockBytes</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-createbytedatablock">CreateByteDataBlock</dfn> abstract operation</li>
Expand All @@ -2788,6 +2790,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-getfunctionrealm">GetFunctionRealm</dfn> abstract operation</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-hasownproperty">HasOwnProperty</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostCallJobCallback" data-x-href="https://tc39.es/ecma262/#sec-hostcalljobcallback">HostCallJobCallback</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnqueueFinalizationRegistryCleanupJob" data-x-href="https://tc39.es/ecma262/#sec-host-cleanup-finalization-registry">HostEnqueueFinalizationRegistryCleanupJob</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnqueuePromiseJob" data-x-href="https://tc39.es/ecma262/#sec-hostenqueuepromisejob">HostEnqueuePromiseJob</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostEnsureCanCompileStrings" data-x-href="https://tc39.es/ecma262/#sec-hostensurecancompilestrings">HostEnsureCanCompileStrings</dfn> abstract operation</li>
<li>The <dfn data-x="js-HostImportModuleDynamically" data-x-href="https://tc39.es/proposal-dynamic-import/#sec-hostimportmoduledynamically">HostImportModuleDynamically</dfn> abstract operation</li>
Expand Down Expand Up @@ -2834,11 +2837,14 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<li>The <dfn data-x="js-strict-equality" data-x-href="https://tc39.es/ecma262/#sec-strict-equality-comparison">Strict Equality Comparison</dfn> algorithm</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-atomics-object"><code>Atomics</code></dfn> object</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-date-objects"><code>Date</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-finalization-registry-objects"><code>FinalizationRegistry</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-regexp-regular-expression-objects"><code>RegExp</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-sharedarraybuffer-objects"><code>SharedArrayBuffer</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-native-error-types-used-in-this-standard-typeerror"><code>TypeError</code></dfn> class</li>
<li>The <dfn data-x="js-RangeError" data-x-href="https://tc39.es/ecma262/#sec-native-error-types-used-in-this-standard-rangeerror"><code>RangeError</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-weak-ref-objects"><code>WeakRef</code></dfn> class</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-eval-x"><code>eval()</code></dfn> function</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-weak-ref.prototype.deref"><code>WeakRef.prototype.deref()</code></dfn> function</li>
<li>The <dfn data-x-href="https://tc39.es/ecma262/#sec-IsHTMLDDA-internal-slot">[[IsHTMLDDA]]</dfn> internal slot</li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-import-calls"><code>import()</code></dfn></li>
<li><dfn data-x-href="https://tc39.es/ecma262/#sec-meta-properties"><code>import.meta</code></dfn></li>
Expand Down Expand Up @@ -90003,16 +90009,20 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
<span data-x="JobCallback Record">JobCallback Records</span> which encapsulate JavaScript
functions that are called as part of jobs. The JavaScript specification contains a number of
<span>implementation-defined</span> abstract operations that lets the host define how jobs are
scheduled and how JobCallbacks are handled. This section defines them for user agent hosts.</p>
scheduled and how JobCallbacks are handled. HTML uses these abstract operations to <span
id="incumbent-settings-object-tracking-in-promises">track the <span>incumbent settings
object</span> in promises and <code>FinalizationRegistry</code> callbacks</span> by saving and
restoring the <span>incumbent settings object</span> and a <span>JavaScript execution
context</span> for the <span>active script</span> in JobCallbacks. This section defines them for
user agent hosts.</p>

<h6 id="hostcalljobcallback"><dfn>HostCallJobCallback</dfn>(<var>callback</var>, <var>V</var>,
<var>argumentsList</var>)</h6>
syg marked this conversation as resolved.
Show resolved Hide resolved

<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostCallJobCallback">HostCallJobCallback</span>(<var>callback</var>, <var>V</var>,
<var>argumentsList</var>) abstract operation to let hosts restore state when invoking JavaScript
callbacks from inside tasks. HTML restores the <span>incumbent settings object</span> and the
<span>active script</span>. User agents must use the following implementation: <ref
callbacks from inside tasks. User agents must use the following implementation: <ref
spec=JAVASCRIPT></p>

<ol>
Expand Down Expand Up @@ -90050,6 +90060,62 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
<li><p>Return <var>result</var>.</p></li>
</ol>

<h6
id="hostenqueuefinalizationregistrycleanupjob"><dfn>HostEnqueueFinalizationRegistryCleanupJob</dfn>(<var>finalizationRegistry</var>)</h6>

<p>JavaScript has the ability to register objects with <code>FinalizationRegistry</code> objects,
in order to schedule a cleanup action if they are found to be garbage collected. The JavaScript
specification contains an <span>implementation-defined</span> <span
data-x="js-HostEnqueueFinalizationRegistryCleanupJob">HostEnqueueFinalizationRegistryCleanupJob</span>(<var>finalizationRegistry</var>)
abstract operation to schedule the cleanup action.</p>

<p class="note">The timing and occurrence of cleanup work is <span>implementation-defined</span>
in the JavaScript specification. User agents might differ in when and whether an object is garbage
collected, affecting both whether the return value of the <code>WeakRef.prototype.deref()</code>
method is undefined, and whether <code>FinalizationRegistry</code> cleanup callbacks occur. There
are well-known cases in popular web browsers where objects are not accessible to JavaScript, but
they remain retained by the garbage collector indefinitely. HTML clears kept-alive
<code>WeakRef</code> objects in the <span>perform a microtask checkpoint</span> algorithm. Authors
would be best off not depending on the timing details of garbage collection implementations.</p>

<p>Cleanup actions do not take place interspersed with synchronous JavaScript execution, but
rather happen in queued <span data-x="concept-task">tasks</span>. User agents must use the
following implementation: <ref spec=JAVASCRIPT></p>

<ol>
<li><p>Let <var>global</var> be <var>finalizationRegistry</var>.[[Realm]]'s <span>global
object</span>.</p></li>

<li>
<p><span>Queue a global task</span> on the <dfn>JavaScript engine task source</dfn> given
<var>global</var> to perform the following steps:</p>

<ol>
<li><p>Let <var>entry</var> be
<var>finalizationRegistry</var>.[[CleanupCallback]].[[Callback]].[[Realm]]'s <span
data-x="concept-realm-settings-object">environment settings object</span>.</p></li>

<li><p><span>Check if we can run script</span> with <var>entry</var>. If this returns "do not
run", then return.</p></li>

<li>
<p><span>Prepare to run script</span> with <var>entry</var>.</p>

<p class="note">This affects the <span data-x="concept-entry-everything">entry</span> concept
while the cleanup callback runs.</p>
</li>

<li><p>Let <var>result</var> be the result of performing
<span>CleanupFinalizationRegistry</span>(<var>finalizationRegistry</var>).</p></li>

<li><p><span>Clean up after running script</span> with <var>entry</var>.</p></li>

<li><p>If <var>result</var> is an <span>abrupt completion</span>, then <span>report the
exception</span> given by <var>result</var>.[[Value]].</p></li>
</ol>
</li>
</ol>

<span id="integration-with-the-javascript-job-queue"></span>
<span id="enqueuejob(queuename,-job,-arguments)"></span>
<h6 id="hostenqueuepromisejob"><dfn>HostEnqueuePromiseJob</dfn>(<var>job</var>,
Expand Down Expand Up @@ -90124,11 +90190,8 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
<p>JavaScript contains an <span>implementation-defined</span> <span
data-x="js-HostMakeJobCallback">HostMakeJobCallback</span>(<var>callable</var>) abstract operation
to let hosts attach state to JavaScript callbacks that are called from inside <span
data-x="concept-task">task</span>s. HTML <span
id="incumbent-settings-object-tracking-in-promises">tracks the <span>incumbent settings
object</span> in promises</span> by saving the <span>incumbent settings object</span> and a
<span>JavaScript execution context</span> for the <span>active script</span>. User agents must use
the following implementation: <ref spec=JAVASCRIPT></p>
data-x="concept-task">task</span>s. User agents must use the following implementation: <ref
spec=JAVASCRIPT></p>

<ol>
<li><p>Let <var>incumbent settings</var> be the <span>incumbent settings object</span>.</p></li>
Expand Down Expand Up @@ -90188,6 +90251,7 @@ dictionary <dfn>PromiseRejectionEventInit</dfn> : <span>EventInit</span> {
<var>script execution context</var> } }.</p></li>
</ol>


<h5 id="integration-with-the-javascript-module-system">Module-related host hooks</h5>

<p>The JavaScript specification defines a syntax for modules, as well as some host-agnostic parts
Expand Down Expand Up @@ -91068,6 +91132,14 @@ import "https://example.com/foo/../module2.mjs";</code></pre>

<li><p><span>Cleanup Indexed Database transactions</span>.</p></li>

<li>
<p>Perform <span>ClearKeptObjects</span>().</p>

<p class="note">When <code>WeakRef.prototype.deref()</code> returns an object, that object is
kept alive until the next invocation of <span>ClearKeptObjects</span>(), after which it is again
subject to garbage collection.</p>
</li>

<li><p>Set the <span>event loop</span>'s <span>performing a microtask checkpoint</span> to
false.</p></li>
</ol>
Expand Down