mirror of
https://github.com/bendtherules/ask262.git
synced 2026-08-18 13:21:55 +00:00
216 lines
27 KiB
HTML
216 lines
27 KiB
HTML
<!DOCTYPE html><html lang="en-GB-oxendict"><head><meta name="viewport" content="width=device-width, initial-scale=1"><meta charset="utf-8"><meta property="og:image" content="https://tc39.es/ecmarkup/ecma-logo.png"><meta property="og:title" content="ECMAScript® 2026 Language Specification"><meta property="og:description" content="Introduction
|
|
This Ecma Standard defines the ECMAScript 2026 Language. It is the seventeenth edition of the ECMAScript Language Specification. ECMAScript is based on several originating technologies, the most well-known being JavaScript (Netscape) and JScript (Microsoft). The language was invent">
|
|
<link rel="icon" href="../img/favicon.ico">
|
|
<link rel="stylesheet" href="../assets/css/ecmarkup.css"><link rel="stylesheet" href="../assets/css/print.css" media="print">
|
|
|
|
<title>ECMAScript® 2026 Language Specification</title><script src="../assets/js/multipage.js?cache=Wu2V1pj2" defer=""></script><script src="../assets/js/ecmarkup.js?cache=BPFBckdu" defer=""></script><link rel="canonical" href="../#sec-managing-memory"></head>
|
|
<body><div id="spec-container"><emu-clause id="sec-managing-memory">
|
|
<h1><span class="secnum">26</span> Managing Memory</h1>
|
|
|
|
<emu-clause id="sec-weak-ref-objects">
|
|
<h1><span class="secnum">26.1</span> WeakRef Objects</h1>
|
|
<p>A <emu-xref href="#sec-weak-ref-constructor" id="_ref_15530"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRef</a></emu-xref> is an object that is used to refer to a target object or symbol without preserving it from garbage collection. <emu-xref href="#sec-weak-ref-constructor" id="_ref_15531"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRefs</a></emu-xref> can be dereferenced to allow access to the target value, if the target hasn't been reclaimed by garbage collection.</p>
|
|
|
|
<emu-clause id="sec-weak-ref-constructor">
|
|
<h1><span class="secnum">26.1.1</span> The WeakRef Constructor</h1>
|
|
<p>The <dfn variants="WeakRefs" tabindex="-1">WeakRef</dfn> <emu-xref href="#constructor" id="_ref_15532"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
|
<ul>
|
|
<li>is <dfn tabindex="-1">%WeakRef%</dfn>.</li>
|
|
<li>
|
|
is the initial value of the <emu-val>"WeakRef"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_15533"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.
|
|
</li>
|
|
<li>
|
|
creates and initializes a new WeakRef when called as a <emu-xref href="#constructor" id="_ref_15534"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.
|
|
</li>
|
|
<li>
|
|
is not intended to be called as a function and will throw an exception when called in that manner.
|
|
</li>
|
|
<li>
|
|
may be used as the value in an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_15535"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified <code>WeakRef</code> behaviour must include a <code>super</code> call to the <code>WeakRef</code> <emu-xref href="#constructor" id="_ref_15536"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize the subclass instance with the internal state necessary to support the <code>WeakRef.prototype</code> built-in methods.
|
|
</li>
|
|
</ul>
|
|
|
|
<emu-clause id="sec-weak-ref-target" type="built-in function">
|
|
<h1><span class="secnum">26.1.1.1</span> WeakRef ( <var>target</var> )</h1>
|
|
<p>This function performs the following steps when called:</p>
|
|
<emu-alg><ol><li>If NewTarget is <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="CanBeHeldWeakly" id="_ref_15537"><a href="executable-code-and-execution-contexts.html#sec-canbeheldweakly">CanBeHeldWeakly</a></emu-xref>(<var>target</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>weakRef</var> be ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_15538"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(NewTarget, <emu-val>"%WeakRef.prototype%"</emu-val>, « <var class="field">[[WeakRefTarget]]</var> »).</li><li>Perform <emu-xref aoid="AddToKeptObjects" id="_ref_15539"><a href="executable-code-and-execution-contexts.html#sec-addtokeptobjects">AddToKeptObjects</a></emu-xref>(<var>target</var>).</li><li>Set <var>weakRef</var>.<var class="field">[[WeakRefTarget]]</var> to <var>target</var>.</li><li>Return <var>weakRef</var>.</li></ol></emu-alg>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-properties-of-the-weak-ref-constructor">
|
|
<h1><span class="secnum">26.1.2</span> Properties of the WeakRef Constructor</h1>
|
|
<p>The <emu-xref href="#sec-weak-ref-constructor" id="_ref_15540"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRef</a></emu-xref> <emu-xref href="#constructor" id="_ref_15541"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
|
<ul>
|
|
<li>
|
|
has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_15542"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.
|
|
</li>
|
|
<li>has the following properties:</li>
|
|
</ul>
|
|
|
|
<emu-clause id="sec-weak-ref.prototype">
|
|
<h1><span class="secnum">26.1.2.1</span> WeakRef.prototype</h1>
|
|
<p>The initial value of <code>WeakRef.prototype</code> is the <emu-xref href="#sec-properties-of-the-weak-ref-prototype-object" id="_ref_15543"><a href="managing-memory.html#sec-properties-of-the-weak-ref-prototype-object">WeakRef prototype object</a></emu-xref>.</p>
|
|
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-properties-of-the-weak-ref-prototype-object">
|
|
<h1><span class="secnum">26.1.3</span> Properties of the WeakRef Prototype Object</h1>
|
|
<p>The <dfn tabindex="-1">WeakRef prototype object</dfn>:</p>
|
|
<ul>
|
|
<li>is <dfn tabindex="-1">%WeakRef.prototype%</dfn>.</li>
|
|
<li>
|
|
has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15544"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.
|
|
</li>
|
|
<li>is an <emu-xref href="#ordinary-object" id="_ref_15545"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
|
<li>does not have a <var class="field">[[WeakRefTarget]]</var> internal slot.</li>
|
|
</ul>
|
|
|
|
<emu-clause id="sec-weak-ref.prototype.constructor" normative-optional=""><div class="attributes-tag"><emu-xref href="#sec-conformance" id="_ref_15547"><a href="conformance.html#sec-conformance">Normative Optional</a></emu-xref></div>
|
|
<h1><span class="secnum">26.1.3.1</span> WeakRef.prototype.constructor</h1>
|
|
|
|
<p>The initial value of <code>WeakRef.prototype.constructor</code> is <emu-xref href="#sec-weak-ref-constructor" id="_ref_15546"><a href="managing-memory.html#sec-weak-ref-constructor">%WeakRef%</a></emu-xref>.</p>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-weak-ref.prototype.deref" type="built-in function">
|
|
<h1><span class="secnum">26.1.3.2</span> WeakRef.prototype.deref ( )</h1>
|
|
<p>This method performs the following steps when called:</p>
|
|
<emu-alg><ol><li>Let <var>weakRef</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_15548"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>weakRef</var>, <var class="field">[[WeakRefTarget]]</var>).</li><li>Return <emu-xref aoid="WeakRefDeref" id="_ref_15549"><a href="managing-memory.html#sec-weakrefderef">WeakRefDeref</a></emu-xref>(<var>weakRef</var>).</li></ol></emu-alg>
|
|
|
|
<emu-note><span class="note">Note</span><div class="note-contents">
|
|
<p>If the <emu-xref href="#sec-weak-ref-constructor" id="_ref_15550"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRef</a></emu-xref> returns a <var>target</var> value that is not <emu-val>undefined</emu-val>, then this <var>target</var> value should not be garbage collected until the current execution of ECMAScript code has completed. The <emu-xref aoid="AddToKeptObjects" id="_ref_15551"><a href="executable-code-and-execution-contexts.html#sec-addtokeptobjects">AddToKeptObjects</a></emu-xref> operation makes sure read consistency is maintained.</p>
|
|
|
|
<pre><code class="javascript hljs"><span class="hljs-keyword">let</span> target = { <span class="hljs-title function_">foo</span>(<span class="hljs-params"></span>) {} };
|
|
<span class="hljs-keyword">let</span> weakRef = <span class="hljs-keyword">new</span> <span class="hljs-title class_">WeakRef</span>(target);
|
|
|
|
<span class="hljs-comment">// ... later ...</span>
|
|
|
|
<span class="hljs-keyword">if</span> (weakRef.<span class="hljs-title function_">deref</span>()) {
|
|
weakRef.<span class="hljs-title function_">deref</span>().<span class="hljs-title function_">foo</span>();
|
|
}</code></pre>
|
|
|
|
<p>In the above example, if the first deref does not evaluate to <emu-val>undefined</emu-val> then the second deref cannot either.</p>
|
|
</div></emu-note>
|
|
</emu-clause>
|
|
|
|
<emu-clause oldids="sec-weak-ref.prototype-@@tostringtag" id="sec-weak-ref.prototype-%symbol.tostringtag%"><span id="sec-weak-ref.prototype-@@tostringtag"></span>
|
|
<h1><span class="secnum">26.1.3.3</span> WeakRef.prototype [ %Symbol.toStringTag% ]</h1>
|
|
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_15552"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"WeakRef"</emu-val>.</p>
|
|
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-weakref-abstract-operations">
|
|
<h1><span class="secnum">26.1.4</span> WeakRef Abstract Operations</h1>
|
|
|
|
<emu-clause id="sec-weakrefderef" type="abstract operation" aoid="WeakRefDeref">
|
|
<h1><span class="secnum">26.1.4.1</span> WeakRefDeref ( <var>weakRef</var> )</h1>
|
|
<p>The abstract operation WeakRefDeref takes argument <var>weakRef</var> (a <emu-xref href="#sec-weak-ref-constructor" id="_ref_15553"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRef</a></emu-xref>) and returns an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15554"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>. It performs the following steps when called:</p>
|
|
<emu-alg><ol><li>Let <var>target</var> be <var>weakRef</var>.<var class="field">[[WeakRefTarget]]</var>.</li><li>If <var>target</var> is not <emu-const>empty</emu-const>, then<ol><li>Perform <emu-xref aoid="AddToKeptObjects" id="_ref_15555"><a href="executable-code-and-execution-contexts.html#sec-addtokeptobjects">AddToKeptObjects</a></emu-xref>(<var>target</var>).</li><li>Return <var>target</var>.</li></ol></li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
|
<emu-note><span class="note">Note</span><div class="note-contents">
|
|
<p>This abstract operation is defined separately from WeakRef.prototype.deref strictly to make it possible to succinctly define liveness.</p>
|
|
</div></emu-note>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-properties-of-weak-ref-instances">
|
|
<h1><span class="secnum">26.1.5</span> Properties of WeakRef Instances</h1>
|
|
<p><emu-xref href="#sec-weak-ref-constructor" id="_ref_15556"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRef</a></emu-xref> instances are <emu-xref href="#ordinary-object" id="_ref_15557"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary objects</a></emu-xref> that inherit properties from the <emu-xref href="#sec-properties-of-the-weak-ref-prototype-object" id="_ref_15558"><a href="managing-memory.html#sec-properties-of-the-weak-ref-prototype-object">WeakRef prototype object</a></emu-xref>. <emu-xref href="#sec-weak-ref-constructor" id="_ref_15559"><a href="managing-memory.html#sec-weak-ref-constructor">WeakRef</a></emu-xref> instances also have a <var class="field">[[WeakRefTarget]]</var> internal slot.</p>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-finalization-registry-objects">
|
|
<h1><span class="secnum">26.2</span> FinalizationRegistry Objects</h1>
|
|
<p>A <emu-xref href="#sec-finalization-registry-constructor" id="_ref_15560"><a href="managing-memory.html#sec-finalization-registry-constructor">FinalizationRegistry</a></emu-xref> is an object that manages registration and unregistration of cleanup operations that are performed when target objects and symbols are garbage collected.</p>
|
|
|
|
<emu-clause id="sec-finalization-registry-constructor">
|
|
<h1><span class="secnum">26.2.1</span> The FinalizationRegistry Constructor</h1>
|
|
<p>The <dfn variants="FinalizationRegistrys" tabindex="-1">FinalizationRegistry</dfn> <emu-xref href="#constructor" id="_ref_15561"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
|
<ul>
|
|
<li>is <dfn tabindex="-1">%FinalizationRegistry%</dfn>.</li>
|
|
<li>
|
|
is the initial value of the <emu-val>"FinalizationRegistry"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_15562"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.
|
|
</li>
|
|
<li>
|
|
creates and initializes a new FinalizationRegistry when called as a <emu-xref href="#constructor" id="_ref_15563"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.
|
|
</li>
|
|
<li>
|
|
is not intended to be called as a function and will throw an exception when called in that manner.
|
|
</li>
|
|
<li>
|
|
may be used as the value in an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_15564"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified <code>FinalizationRegistry</code> behaviour must include a <code>super</code> call to the <code>FinalizationRegistry</code> <emu-xref href="#constructor" id="_ref_15565"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize the subclass instance with the internal state necessary to support the <code>FinalizationRegistry.prototype</code> built-in methods.
|
|
</li>
|
|
</ul>
|
|
|
|
<emu-clause id="sec-finalization-registry-cleanup-callback" type="built-in function">
|
|
<h1><span class="secnum">26.2.1.1</span> FinalizationRegistry ( <var>cleanupCallback</var> )</h1>
|
|
<p>This function performs the following steps when called:</p>
|
|
<emu-alg><ol><li>If NewTarget is <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsCallable" id="_ref_15566"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>cleanupCallback</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>finalizationRegistry</var> be ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_15567"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(NewTarget, <emu-val>"%FinalizationRegistry.prototype%"</emu-val>, « <var class="field">[[Realm]]</var>, <var class="field">[[CleanupCallback]]</var>, <var class="field">[[Cells]]</var> »).</li><li>Let <var>fn</var> be the <emu-xref href="#active-function-object" id="_ref_15568"><a href="executable-code-and-execution-contexts.html#active-function-object">active function object</a></emu-xref>.</li><li>Set <var>finalizationRegistry</var>.<var class="field">[[Realm]]</var> to <var>fn</var>.<var class="field">[[Realm]]</var>.</li><li>Set <var>finalizationRegistry</var>.<var class="field">[[CleanupCallback]]</var> to <emu-xref aoid="HostMakeJobCallback" id="_ref_15569"><a href="executable-code-and-execution-contexts.html#sec-hostmakejobcallback">HostMakeJobCallback</a></emu-xref>(<var>cleanupCallback</var>).</li><li>Set <var>finalizationRegistry</var>.<var class="field">[[Cells]]</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15570"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Return <var>finalizationRegistry</var>.</li></ol></emu-alg>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-properties-of-the-finalization-registry-constructor">
|
|
<h1><span class="secnum">26.2.2</span> Properties of the FinalizationRegistry Constructor</h1>
|
|
<p>The <emu-xref href="#sec-finalization-registry-constructor" id="_ref_15571"><a href="managing-memory.html#sec-finalization-registry-constructor">FinalizationRegistry</a></emu-xref> <emu-xref href="#constructor" id="_ref_15572"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
|
<ul>
|
|
<li>
|
|
has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-function-prototype-object" id="_ref_15573"><a href="fundamental-objects.html#sec-properties-of-the-function-prototype-object">%Function.prototype%</a></emu-xref>.
|
|
</li>
|
|
<li>has the following properties:</li>
|
|
</ul>
|
|
|
|
<emu-clause id="sec-finalization-registry.prototype">
|
|
<h1><span class="secnum">26.2.2.1</span> FinalizationRegistry.prototype</h1>
|
|
<p>The initial value of <code>FinalizationRegistry.prototype</code> is the <emu-xref href="#sec-properties-of-the-finalization-registry-prototype-object" id="_ref_15574"><a href="managing-memory.html#sec-properties-of-the-finalization-registry-prototype-object">FinalizationRegistry prototype object</a></emu-xref>.</p>
|
|
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>false</emu-val> }.</p>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-properties-of-the-finalization-registry-prototype-object">
|
|
<h1><span class="secnum">26.2.3</span> Properties of the FinalizationRegistry Prototype Object</h1>
|
|
<p>The <dfn tabindex="-1">FinalizationRegistry prototype object</dfn>:</p>
|
|
<ul>
|
|
<li>is <dfn tabindex="-1">%FinalizationRegistry.prototype%</dfn>.</li>
|
|
<li>
|
|
has a <var class="field">[[Prototype]]</var> internal slot whose value is <emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15575"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.
|
|
</li>
|
|
<li>is an <emu-xref href="#ordinary-object" id="_ref_15576"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
|
<li>
|
|
does not have <var class="field">[[Cells]]</var> and <var class="field">[[CleanupCallback]]</var> internal slots.
|
|
</li>
|
|
</ul>
|
|
|
|
<emu-clause id="sec-finalization-registry.prototype.constructor">
|
|
<h1><span class="secnum">26.2.3.1</span> FinalizationRegistry.prototype.constructor</h1>
|
|
<p>The initial value of <code>FinalizationRegistry.prototype.constructor</code> is <emu-xref href="#sec-finalization-registry-constructor" id="_ref_15577"><a href="managing-memory.html#sec-finalization-registry-constructor">%FinalizationRegistry%</a></emu-xref>.</p>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-finalization-registry.prototype.register" type="built-in function">
|
|
<h1><span class="secnum">26.2.3.2</span> FinalizationRegistry.prototype.register ( <var>target</var>, <var>heldValue</var> [ , <var>unregisterToken</var> ] )</h1>
|
|
<p>This method performs the following steps when called:</p>
|
|
<emu-alg><ol><li>Let <var>finalizationRegistry</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_15578"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>finalizationRegistry</var>, <var class="field">[[Cells]]</var>).</li><li>If <emu-xref aoid="CanBeHeldWeakly" id="_ref_15579"><a href="executable-code-and-execution-contexts.html#sec-canbeheldweakly">CanBeHeldWeakly</a></emu-xref>(<var>target</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="SameValue" id="_ref_15580"><a href="abstract-operations.html#sec-samevalue">SameValue</a></emu-xref>(<var>target</var>, <var>heldValue</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="CanBeHeldWeakly" id="_ref_15581"><a href="executable-code-and-execution-contexts.html#sec-canbeheldweakly">CanBeHeldWeakly</a></emu-xref>(<var>unregisterToken</var>) is <emu-val>false</emu-val>, then<ol><li>If <var>unregisterToken</var> is not <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Set <var>unregisterToken</var> to <emu-const>empty</emu-const>.</li></ol></li><li>Let <var>cell</var> be the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15582"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[WeakRefTarget]]</var>: <var>target</var>, <var class="field">[[HeldValue]]</var>: <var>heldValue</var>, <var class="field">[[UnregisterToken]]</var>: <var>unregisterToken</var> }.</li><li>Append <var>cell</var> to <var>finalizationRegistry</var>.<var class="field">[[Cells]]</var>.</li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
|
|
|
<emu-note><span class="note">Note</span><div class="note-contents">
|
|
<p>Based on the algorithms and definitions in this specification, <var>cell</var>.<var class="field">[[HeldValue]]</var> is <emu-xref href="#sec-liveness" id="_ref_15583"><a href="executable-code-and-execution-contexts.html#sec-liveness">live</a></emu-xref> when <var>finalizationRegistry</var>.<var class="field">[[Cells]]</var> contains <var>cell</var>; however, this does not necessarily mean that <var>cell</var>.<var class="field">[[UnregisterToken]]</var> or <var>cell</var>.<var class="field">[[Target]]</var> are <emu-xref href="#sec-liveness" id="_ref_15584"><a href="executable-code-and-execution-contexts.html#sec-liveness">live</a></emu-xref>. For example, registering an object with itself as its unregister token would not keep the object alive forever.</p>
|
|
</div></emu-note>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-finalization-registry.prototype.unregister" type="built-in function">
|
|
<h1><span class="secnum">26.2.3.3</span> FinalizationRegistry.prototype.unregister ( <var>unregisterToken</var> )</h1>
|
|
<p>This method performs the following steps when called:</p>
|
|
<emu-alg><ol><li>Let <var>finalizationRegistry</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_15585"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>finalizationRegistry</var>, <var class="field">[[Cells]]</var>).</li><li>If <emu-xref aoid="CanBeHeldWeakly" id="_ref_15586"><a href="executable-code-and-execution-contexts.html#sec-canbeheldweakly">CanBeHeldWeakly</a></emu-xref>(<var>unregisterToken</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>removed</var> be <emu-val>false</emu-val>.</li><li>For each <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15587"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> { <var class="field">[[WeakRefTarget]]</var>, <var class="field">[[HeldValue]]</var>, <var class="field">[[UnregisterToken]]</var> } <var>cell</var> of <var>finalizationRegistry</var>.<var class="field">[[Cells]]</var>, do<ol><li>If <var>cell</var>.<var class="field">[[UnregisterToken]]</var> is not <emu-const>empty</emu-const> and <emu-xref aoid="SameValue" id="_ref_15588"><a href="abstract-operations.html#sec-samevalue">SameValue</a></emu-xref>(<var>cell</var>.<var class="field">[[UnregisterToken]]</var>, <var>unregisterToken</var>) is <emu-val>true</emu-val>, then<ol><li>Remove <var>cell</var> from <var>finalizationRegistry</var>.<var class="field">[[Cells]]</var>.</li><li>Set <var>removed</var> to <emu-val>true</emu-val>.</li></ol></li></ol></li><li>Return <var>removed</var>.</li></ol></emu-alg>
|
|
</emu-clause>
|
|
|
|
<emu-clause oldids="sec-finalization-registry.prototype-@@tostringtag" id="sec-finalization-registry.prototype-%symbol.tostringtag%"><span id="sec-finalization-registry.prototype-@@tostringtag"></span>
|
|
<h1><span class="secnum">26.2.3.4</span> FinalizationRegistry.prototype [ %Symbol.toStringTag% ]</h1>
|
|
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_15589"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"FinalizationRegistry"</emu-val>.</p>
|
|
<p>This property has the attributes { <var class="field">[[Writable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Enumerable]]</var>: <emu-val>false</emu-val>, <var class="field">[[Configurable]]</var>: <emu-val>true</emu-val> }.</p>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
|
|
<emu-clause id="sec-properties-of-finalization-registry-instances">
|
|
<h1><span class="secnum">26.2.4</span> Properties of FinalizationRegistry Instances</h1>
|
|
<p><emu-xref href="#sec-finalization-registry-constructor" id="_ref_15590"><a href="managing-memory.html#sec-finalization-registry-constructor">FinalizationRegistry</a></emu-xref> instances are <emu-xref href="#ordinary-object" id="_ref_15591"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary objects</a></emu-xref> that inherit properties from the <emu-xref href="#sec-properties-of-the-finalization-registry-prototype-object" id="_ref_15592"><a href="managing-memory.html#sec-properties-of-the-finalization-registry-prototype-object">FinalizationRegistry prototype object</a></emu-xref>. <emu-xref href="#sec-finalization-registry-constructor" id="_ref_15593"><a href="managing-memory.html#sec-finalization-registry-constructor">FinalizationRegistry</a></emu-xref> instances also have <var class="field">[[Cells]]</var> and <var class="field">[[CleanupCallback]]</var> internal slots.</p>
|
|
</emu-clause>
|
|
</emu-clause>
|
|
</emu-clause></div></body></html> |