Integrate with JavaScript WeakRefs

The role of HTML here is strictly limited to being a task scheduling service for JavaScript and tracking incumbent globals.

Co-authored-by: Ms2ger <[email protected]>
Co-authored-by: Shu-yu Guo <[email protected]>

Author: 3 people

source

@@ -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>
@@ -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>
@@ -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>
@@ -90002,16 +90008,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>
 
   <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>
@@ -90049,6 +90059,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>,
@@ -90123,11 +90189,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>
@@ -90187,6 +90250,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
@@ -91067,6 +91131,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>