mirror of
https://github.com/bendtherules/ask262.git
synced 2026-08-18 13:21:55 +00:00
1400 lines
349 KiB
HTML
1400 lines
349 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-structured-data"></head>
|
||
<body><div id="spec-container"><emu-clause id="sec-structured-data">
|
||
<h1><span class="secnum">25</span> Structured Data</h1>
|
||
|
||
<emu-clause id="sec-arraybuffer-objects">
|
||
<h1><span class="secnum">25.1</span> ArrayBuffer Objects</h1>
|
||
|
||
<emu-clause id="sec-arraybuffer-notation">
|
||
<h1><span class="secnum">25.1.1</span> Notation</h1>
|
||
<p>The descriptions below in this section, <emu-xref href="#sec-atomics-object" id="_ref_786"><a href="structured-data.html#sec-atomics-object">25.4</a></emu-xref>, and <emu-xref href="#sec-memory-model" id="_ref_787"><a href="memory-model.html#sec-memory-model">29</a></emu-xref> use the read-modify-write modification function internal data structure.</p>
|
||
<p>A <dfn variants="read-modify-write modification functions" tabindex="-1">read-modify-write modification function</dfn> is a mathematical function that is represented as an abstract closure that takes two <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14512"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Lists</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_14513"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref> as arguments and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14514"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_14515"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. These abstract closures satisfy all of the following properties:</p>
|
||
<ul>
|
||
<li>They perform all their algorithm steps atomically.</li>
|
||
<li>Their individual algorithm steps are not observable.</li>
|
||
</ul>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>To aid verifying that a read-modify-write modification function's algorithm steps constitute a pure, mathematical function, the following editorial conventions are recommended:</p>
|
||
<ul>
|
||
<li>They do not access, directly or transitively via invoked <emu-xref href="#sec-algorithm-conventions-abstract-operations" id="_ref_14516"><a href="notational-conventions.html#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> and abstract closures, any language or specification values except their parameters and captured values.</li>
|
||
<li>They do not invoke, directly or transitively, <emu-xref href="#sec-algorithm-conventions-abstract-operations" id="_ref_14517"><a href="notational-conventions.html#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> and abstract closures that return <emu-xref href="#sec-completion-record-specification-type" id="_ref_14518"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Records</a></emu-xref>.</li>
|
||
<li>They do not return <emu-xref href="#sec-completion-record-specification-type" id="_ref_14519"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">Completion Records</a></emu-xref>.</li>
|
||
</ul>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-fixed-length-and-resizable-arraybuffer-objects">
|
||
<h1><span class="secnum">25.1.2</span> Fixed-length and Resizable ArrayBuffer Objects</h1>
|
||
<p>A <dfn tabindex="-1">fixed-length ArrayBuffer</dfn> is an ArrayBuffer whose byte length cannot change after creation.</p>
|
||
<p>A <dfn tabindex="-1">resizable ArrayBuffer</dfn> is an ArrayBuffer whose byte length may change after creation via calls to <emu-xref href="#sec-arraybuffer.prototype.resize" title="" id="_ref_788"><a href="structured-data.html#sec-arraybuffer.prototype.resize">ArrayBuffer.prototype.resize ( <var>newLength</var> )</a></emu-xref>.</p>
|
||
<p>The kind of ArrayBuffer object that is created depends on the arguments passed to <emu-xref href="#sec-arraybuffer-length" title="" id="_ref_789"><a href="structured-data.html#sec-arraybuffer-length">ArrayBuffer ( <var>length</var> [ , <var>options</var> ] )</a></emu-xref>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-abstract-operations-for-arraybuffer-objects">
|
||
<h1><span class="secnum">25.1.3</span> Abstract Operations For ArrayBuffer Objects</h1>
|
||
|
||
<emu-clause id="sec-allocatearraybuffer" type="abstract operation" aoid="AllocateArrayBuffer">
|
||
<h1><span class="secnum">25.1.3.1</span> AllocateArrayBuffer ( <var>constructor</var>, <var>byteLength</var> [ , <var>maxByteLength</var> ] )</h1>
|
||
<p>The abstract operation AllocateArrayBuffer takes arguments <var>constructor</var> (a <emu-xref href="#constructor" id="_ref_14520"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>) and <var>byteLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14521"><a href="notational-conventions.html#integer">integer</a></emu-xref>) and optional argument <var>maxByteLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14522"><a href="notational-conventions.html#integer">integer</a></emu-xref> or <emu-const>empty</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14523"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an ArrayBuffer or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14524"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It is used to create an ArrayBuffer. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>slots</var> be « <var class="field">[[ArrayBufferData]]</var>, <var class="field">[[ArrayBufferByteLength]]</var>, <var class="field">[[ArrayBufferDetachKey]]</var> ».</li><li>If <var>maxByteLength</var> is present and <var>maxByteLength</var> is not <emu-const>empty</emu-const>, let <var>allocatingResizableBuffer</var> be <emu-val>true</emu-val>; else let <var>allocatingResizableBuffer</var> be <emu-val>false</emu-val>.</li><li>If <var>allocatingResizableBuffer</var> is <emu-val>true</emu-val>, then<ol><li>If <var>byteLength</var> > <var>maxByteLength</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Append <var class="field">[[ArrayBufferMaxByteLength]]</var> to <var>slots</var>.</li></ol></li><li>Let <var>obj</var> be ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_14525"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(<var>constructor</var>, <emu-val>"%ArrayBuffer.prototype%"</emu-val>, <var>slots</var>).</li><li>Let <var>block</var> be ? <emu-xref aoid="CreateByteDataBlock" id="_ref_14526"><a href="ecmascript-data-types-and-values.html#sec-createbytedatablock">CreateByteDataBlock</a></emu-xref>(<var>byteLength</var>).</li><li>Set <var>obj</var>.<var class="field">[[ArrayBufferData]]</var> to <var>block</var>.</li><li>Set <var>obj</var>.<var class="field">[[ArrayBufferByteLength]]</var> to <var>byteLength</var>.</li><li>If <var>allocatingResizableBuffer</var> is <emu-val>true</emu-val>, then<ol><li>If it is not possible to create a <emu-xref href="#sec-data-blocks" id="_ref_14527"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Data Block</a></emu-xref> <var>block</var> consisting of <var>maxByteLength</var> bytes, throw a <emu-val>RangeError</emu-val> exception.</li><li>NOTE: Resizable ArrayBuffers are designed to be implementable with in-place growth. Implementations may throw if, for example, virtual memory cannot be reserved up front.</li><li>Set <var>obj</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var> to <var>maxByteLength</var>.</li></ol></li><li>Return <var>obj</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybufferbytelength" type="abstract operation" aoid="ArrayBufferByteLength">
|
||
<h1><span class="secnum">25.1.3.2</span> ArrayBufferByteLength ( <var>arrayBuffer</var>, <var>order</var> )</h1>
|
||
<p>The abstract operation ArrayBufferByteLength takes arguments <var>arrayBuffer</var> (an ArrayBuffer or SharedArrayBuffer) and <var>order</var> (<emu-const>seq-cst</emu-const> or <emu-const>unordered</emu-const>) and returns a non-negative <emu-xref href="#integer" id="_ref_14528"><a href="notational-conventions.html#integer">integer</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <emu-xref aoid="IsGrowableSharedArrayBuffer" id="_ref_14529"><a href="structured-data.html#sec-isgrowablesharedarraybuffer">IsGrowableSharedArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>bufferByteLengthBlock</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferByteLengthData]]</var>.</li><li>Let <var>rawLength</var> be <emu-xref aoid="GetRawBytesFromSharedBlock" id="_ref_14530"><a href="structured-data.html#sec-getrawbytesfromsharedblock">GetRawBytesFromSharedBlock</a></emu-xref>(<var>bufferByteLengthBlock</var>, 0, <emu-const>biguint64</emu-const>, <emu-val>true</emu-val>, <var>order</var>).</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14531"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14532"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li><li>Return <emu-xref aoid="ℝ" id="_ref_14533"><a href="notational-conventions.html#%E2%84%9D">ℝ</a></emu-xref>(<emu-xref aoid="RawBytesToNumeric" id="_ref_14534"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<emu-const>biguint64</emu-const>, <var>rawLength</var>, <var>isLittleEndian</var>)).</li></ol></li><li><emu-xref href="#assert" id="_ref_14535"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsDetachedBuffer" id="_ref_14536"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>false</emu-val>.</li><li>Return <var>arrayBuffer</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffercopyanddetach" type="abstract operation" aoid="ArrayBufferCopyAndDetach">
|
||
<h1><span class="secnum">25.1.3.3</span> ArrayBufferCopyAndDetach ( <var>arrayBuffer</var>, <var>newLength</var>, <var>preserveResizability</var> )</h1>
|
||
<p>The abstract operation ArrayBufferCopyAndDetach takes arguments <var>arrayBuffer</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14537"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>newLength</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14538"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), and <var>preserveResizability</var> (<emu-const>preserve-resizability</emu-const> or <emu-const>fixed-length</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14539"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an ArrayBuffer or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14540"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14541"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>arrayBuffer</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14542"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>newLength</var> is <emu-val>undefined</emu-val>, then<ol><li>Let <var>newByteLength</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li></ol></li><li>Else,<ol><li>Let <var>newByteLength</var> be ? <emu-xref aoid="ToIndex" id="_ref_14543"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>newLength</var>).</li></ol></li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14544"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>preserveResizability</var> is <emu-const>preserve-resizability</emu-const> and <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14545"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>newMaxByteLength</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>.</li></ol></li><li>Else,<ol><li>Let <var>newMaxByteLength</var> be <emu-const>empty</emu-const>.</li></ol></li><li>If <var>arrayBuffer</var>.<var class="field">[[ArrayBufferDetachKey]]</var> is not <emu-val>undefined</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>newBuffer</var> be ? <emu-xref aoid="AllocateArrayBuffer" id="_ref_14546"><a href="structured-data.html#sec-allocatearraybuffer">AllocateArrayBuffer</a></emu-xref>(<emu-xref href="#sec-arraybuffer-constructor" id="_ref_14547"><a href="structured-data.html#sec-arraybuffer-constructor">%ArrayBuffer%</a></emu-xref>, <var>newByteLength</var>, <var>newMaxByteLength</var>).</li><li>Let <var>copyLength</var> be <emu-xref aoid="min" id="_ref_14548"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>newByteLength</var>, <var>arrayBuffer</var>.<var class="field">[[ArrayBufferByteLength]]</var>).</li><li>Let <var>fromBlock</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>toBlock</var> be <var>newBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Perform <emu-xref aoid="CopyDataBlockBytes" id="_ref_14549"><a href="ecmascript-data-types-and-values.html#sec-copydatablockbytes">CopyDataBlockBytes</a></emu-xref>(<var>toBlock</var>, 0, <var>fromBlock</var>, 0, <var>copyLength</var>).</li><li>NOTE: Neither creation of the new <emu-xref href="#sec-data-blocks" id="_ref_14550"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Data Block</a></emu-xref> nor copying from the old <emu-xref href="#sec-data-blocks" id="_ref_14551"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Data Block</a></emu-xref> are observable. Implementations may implement this method as a zero-copy move or a <code>realloc</code>.</li><li>Perform ! <emu-xref aoid="DetachArrayBuffer" id="_ref_14552"><a href="structured-data.html#sec-detacharraybuffer">DetachArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>).</li><li>Return <var>newBuffer</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isdetachedbuffer" type="abstract operation" aoid="IsDetachedBuffer">
|
||
<h1><span class="secnum">25.1.3.4</span> IsDetachedBuffer ( <var>arrayBuffer</var> )</h1>
|
||
<p>The abstract operation IsDetachedBuffer takes argument <var>arrayBuffer</var> (an ArrayBuffer or a SharedArrayBuffer) and returns a Boolean. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>arrayBuffer</var>.<var class="field">[[ArrayBufferData]]</var> is <emu-val>null</emu-val>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-detacharraybuffer" type="abstract operation" aoid="DetachArrayBuffer">
|
||
<h1><span class="secnum">25.1.3.5</span> DetachArrayBuffer ( <var>arrayBuffer</var> [ , <var>key</var> ] )</h1>
|
||
<p>The abstract operation DetachArrayBuffer takes argument <var>arrayBuffer</var> (an ArrayBuffer) and optional argument <var>key</var> (anything) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14553"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> <emu-const>unused</emu-const> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14554"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_14555"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14556"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>false</emu-val>.</li><li>If <var>key</var> is not present, set <var>key</var> to <emu-val>undefined</emu-val>.</li><li>If <var>arrayBuffer</var>.<var class="field">[[ArrayBufferDetachKey]]</var> is not <var>key</var>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Set <var>arrayBuffer</var>.<var class="field">[[ArrayBufferData]]</var> to <emu-val>null</emu-val>.</li><li>Set <var>arrayBuffer</var>.<var class="field">[[ArrayBufferByteLength]]</var> to 0.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Detaching an ArrayBuffer instance disassociates the <emu-xref href="#sec-data-blocks" id="_ref_14557"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Data Block</a></emu-xref> used as its backing store from the instance and sets the byte length of the buffer to 0.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-clonearraybuffer" type="abstract operation" aoid="CloneArrayBuffer">
|
||
<h1><span class="secnum">25.1.3.6</span> CloneArrayBuffer ( <var>srcBuffer</var>, <var>srcByteOffset</var>, <var>srcLength</var> )</h1>
|
||
<p>The abstract operation CloneArrayBuffer takes arguments <var>srcBuffer</var> (an ArrayBuffer or a SharedArrayBuffer), <var>srcByteOffset</var> (a non-negative <emu-xref href="#integer" id="_ref_14558"><a href="notational-conventions.html#integer">integer</a></emu-xref>), and <var>srcLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14559"><a href="notational-conventions.html#integer">integer</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14560"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an ArrayBuffer or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14561"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It creates a new ArrayBuffer whose data is a copy of <var>srcBuffer</var>'s data over the range starting at <var>srcByteOffset</var> and continuing for <var>srcLength</var> bytes. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_14562"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsDetachedBuffer" id="_ref_14563"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>srcBuffer</var>) is <emu-val>false</emu-val>.</li><li>Let <var>targetBuffer</var> be ? <emu-xref aoid="AllocateArrayBuffer" id="_ref_14564"><a href="structured-data.html#sec-allocatearraybuffer">AllocateArrayBuffer</a></emu-xref>(<emu-xref href="#sec-arraybuffer-constructor" id="_ref_14565"><a href="structured-data.html#sec-arraybuffer-constructor">%ArrayBuffer%</a></emu-xref>, <var>srcLength</var>).</li><li>Let <var>srcBlock</var> be <var>srcBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>targetBlock</var> be <var>targetBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Perform <emu-xref aoid="CopyDataBlockBytes" id="_ref_14566"><a href="ecmascript-data-types-and-values.html#sec-copydatablockbytes">CopyDataBlockBytes</a></emu-xref>(<var>targetBlock</var>, 0, <var>srcBlock</var>, <var>srcByteOffset</var>, <var>srcLength</var>).</li><li>Return <var>targetBuffer</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getarraybuffermaxbytelengthoption" type="abstract operation" aoid="GetArrayBufferMaxByteLengthOption">
|
||
<h1><span class="secnum">25.1.3.7</span> GetArrayBufferMaxByteLengthOption ( <var>options</var> )</h1>
|
||
<p>The abstract operation GetArrayBufferMaxByteLengthOption takes argument <var>options</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14567"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14568"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either a non-negative <emu-xref href="#integer" id="_ref_14569"><a href="notational-conventions.html#integer">integer</a></emu-xref> or <emu-const>empty</emu-const>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14570"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>options</var> <emu-xref href="#sec-object-type" id="_ref_14571"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, return <emu-const>empty</emu-const>.</li><li>Let <var>maxByteLength</var> be ? <emu-xref aoid="Get" id="_ref_14572"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>options</var>, <emu-val>"maxByteLength"</emu-val>).</li><li>If <var>maxByteLength</var> is <emu-val>undefined</emu-val>, return <emu-const>empty</emu-const>.</li><li>Return ? <emu-xref aoid="ToIndex" id="_ref_14573"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>maxByteLength</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-hostresizearraybuffer" type="host-defined abstract operation" aoid="HostResizeArrayBuffer">
|
||
<h1><span class="secnum">25.1.3.8</span> HostResizeArrayBuffer ( <var>buffer</var>, <var>newByteLength</var> )</h1>
|
||
<p>The <emu-xref href="#host-defined" id="_ref_14574"><a href="overview.html#host-defined">host-defined</a></emu-xref> abstract operation HostResizeArrayBuffer takes arguments <var>buffer</var> (an ArrayBuffer) and <var>newByteLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14575"><a href="notational-conventions.html#integer">integer</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14576"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either <emu-const>handled</emu-const> or <emu-const>unhandled</emu-const>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14577"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It gives the <emu-xref href="#host" id="_ref_14578"><a href="overview.html#host">host</a></emu-xref> an opportunity to perform <emu-xref href="#implementation-defined" id="_ref_14579"><a href="overview.html#implementation-defined">implementation-defined</a></emu-xref> resizing of <var>buffer</var>. If the <emu-xref href="#host" id="_ref_14580"><a href="overview.html#host">host</a></emu-xref> chooses not to handle resizing of <var>buffer</var>, it may return <emu-const>unhandled</emu-const> for the default behaviour.</p>
|
||
|
||
<p>The implementation of HostResizeArrayBuffer must conform to the following requirements:</p>
|
||
<ul>
|
||
<li>The abstract operation does not detach <var>buffer</var>.</li>
|
||
<li>If the abstract operation completes normally with <emu-const>handled</emu-const>, <var>buffer</var>.<var class="field">[[ArrayBufferByteLength]]</var> is <var>newByteLength</var>.</li>
|
||
</ul>
|
||
|
||
<p>The default implementation of HostResizeArrayBuffer is to return <emu-xref aoid="NormalCompletion" id="_ref_14581"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-const>unhandled</emu-const>).</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isfixedlengtharraybuffer" type="abstract operation" aoid="IsFixedLengthArrayBuffer">
|
||
<h1><span class="secnum">25.1.3.9</span> IsFixedLengthArrayBuffer ( <var>arrayBuffer</var> )</h1>
|
||
<p>The abstract operation IsFixedLengthArrayBuffer takes argument <var>arrayBuffer</var> (an ArrayBuffer or a SharedArrayBuffer) and returns a Boolean. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>arrayBuffer</var> has an <var class="field">[[ArrayBufferMaxByteLength]]</var> internal slot, return <emu-val>false</emu-val>.</li><li>Return <emu-val>true</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isunsignedelementtype" type="abstract operation" aoid="IsUnsignedElementType">
|
||
<h1><span class="secnum">25.1.3.10</span> IsUnsignedElementType ( <var>type</var> )</h1>
|
||
<p>The abstract operation IsUnsignedElementType takes argument <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14582"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>) and returns a Boolean. It verifies if the argument <var>type</var> is an unsigned <emu-xref href="#sec-typedarray-objects" id="_ref_14583"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>type</var> is one of <emu-const>uint8</emu-const>, <emu-const>uint8clamped</emu-const>, <emu-const>uint16</emu-const>, <emu-const>uint32</emu-const>, or <emu-const>biguint64</emu-const>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isunclampedintegerelementtype" type="abstract operation" aoid="IsUnclampedIntegerElementType">
|
||
<h1><span class="secnum">25.1.3.11</span> IsUnclampedIntegerElementType ( <var>type</var> )</h1>
|
||
<p>The abstract operation IsUnclampedIntegerElementType takes argument <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14584"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>) and returns a Boolean. It verifies if the argument <var>type</var> is an <emu-xref href="#integer" id="_ref_14585"><a href="notational-conventions.html#integer">Integer</a></emu-xref> <emu-xref href="#sec-typedarray-objects" id="_ref_14586"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref> not including <emu-const>uint8clamped</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>type</var> is one of <emu-const>int8</emu-const>, <emu-const>uint8</emu-const>, <emu-const>int16</emu-const>, <emu-const>uint16</emu-const>, <emu-const>int32</emu-const>, or <emu-const>uint32</emu-const>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isbigintelementtype" type="abstract operation" aoid="IsBigIntElementType">
|
||
<h1><span class="secnum">25.1.3.12</span> IsBigIntElementType ( <var>type</var> )</h1>
|
||
<p>The abstract operation IsBigIntElementType takes argument <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14587"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>) and returns a Boolean. It verifies if the argument <var>type</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_14588"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref> <emu-xref href="#sec-typedarray-objects" id="_ref_14589"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>type</var> is either <emu-const>biguint64</emu-const> or <emu-const>bigint64</emu-const>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isnotearconfiguration" type="abstract operation" aoid="IsNoTearConfiguration">
|
||
<h1><span class="secnum">25.1.3.13</span> IsNoTearConfiguration ( <var>type</var>, <var>order</var> )</h1>
|
||
<p>The abstract operation IsNoTearConfiguration takes arguments <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14590"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>) and <var>order</var> (<emu-const>seq-cst</emu-const>, <emu-const>unordered</emu-const>, or <emu-const>init</emu-const>) and returns a Boolean. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <emu-xref aoid="IsUnclampedIntegerElementType" id="_ref_14591"><a href="structured-data.html#sec-isunclampedintegerelementtype">IsUnclampedIntegerElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val>, return <emu-val>true</emu-val>.</li><li>If <emu-xref aoid="IsBigIntElementType" id="_ref_14592"><a href="structured-data.html#sec-isbigintelementtype">IsBigIntElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val> and <var>order</var> is neither <emu-const>init</emu-const> nor <emu-const>unordered</emu-const>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-rawbytestonumeric" type="abstract operation" oldids="sec-rawbytestonumber" aoid="RawBytesToNumeric"><span id="sec-rawbytestonumber"></span>
|
||
<h1><span class="secnum">25.1.3.14</span> RawBytesToNumeric ( <var>type</var>, <var>rawBytes</var>, <var>isLittleEndian</var> )</h1>
|
||
<p>The abstract operation RawBytesToNumeric takes arguments <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14593"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), <var>rawBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14594"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_14595"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>), and <var>isLittleEndian</var> (a Boolean) and returns a Number or a BigInt. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_790"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>If <var>isLittleEndian</var> is <emu-val>false</emu-val>, reverse the order of the elements of <var>rawBytes</var>.</li><li>If <var>type</var> is <emu-const>float16</emu-const>, then<ol><li>Let <var>value</var> be the byte elements of <var>rawBytes</var> concatenated and interpreted as a little-endian bit string encoding of an <emu-xref href="#sec-bibliography" id="_ref_14596"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary16 value.</li><li>If <var>value</var> is a NaN, return <emu-val>NaN</emu-val>.</li><li>Return the Number value that corresponds to <var>value</var>.</li></ol></li><li>If <var>type</var> is <emu-const>float32</emu-const>, then<ol><li>Let <var>value</var> be the byte elements of <var>rawBytes</var> concatenated and interpreted as a little-endian bit string encoding of an <emu-xref href="#sec-bibliography" id="_ref_14597"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary32 value.</li><li>If <var>value</var> is a NaN, return <emu-val>NaN</emu-val>.</li><li>Return the Number value that corresponds to <var>value</var>.</li></ol></li><li>If <var>type</var> is <emu-const>float64</emu-const>, then<ol><li>Let <var>value</var> be the byte elements of <var>rawBytes</var> concatenated and interpreted as a little-endian bit string encoding of an <emu-xref href="#sec-bibliography" id="_ref_14598"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary64 value.</li><li>If <var>value</var> is a NaN, return <emu-val>NaN</emu-val>.</li><li>Return the Number value that corresponds to <var>value</var>.</li></ol></li><li>If <emu-xref aoid="IsUnsignedElementType" id="_ref_14599"><a href="structured-data.html#sec-isunsignedelementtype">IsUnsignedElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>intValue</var> be the byte elements of <var>rawBytes</var> concatenated and interpreted as a bit string encoding of an unsigned little-endian binary number.</li></ol></li><li>Else,<ol><li>Let <var>intValue</var> be the byte elements of <var>rawBytes</var> concatenated and interpreted as a bit string encoding of a binary little-endian two's complement number of bit length <var>elementSize</var> × 8.</li></ol></li><li>If <emu-xref aoid="IsBigIntElementType" id="_ref_14600"><a href="structured-data.html#sec-isbigintelementtype">IsBigIntElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val>, return the BigInt value that corresponds to <var>intValue</var>.</li><li>Return the Number value that corresponds to <var>intValue</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getrawbytesfromsharedblock" type="abstract operation" aoid="GetRawBytesFromSharedBlock">
|
||
<h1><span class="secnum">25.1.3.15</span> GetRawBytesFromSharedBlock ( <var>block</var>, <var>byteIndex</var>, <var>type</var>, <var>isTypedArray</var>, <var>order</var> )</h1>
|
||
<p>The abstract operation GetRawBytesFromSharedBlock takes arguments <var>block</var> (a <emu-xref href="#sec-data-blocks" id="_ref_14601"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref>), <var>byteIndex</var> (a non-negative <emu-xref href="#integer" id="_ref_14602"><a href="notational-conventions.html#integer">integer</a></emu-xref>), <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14603"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), <var>isTypedArray</var> (a Boolean), and <var>order</var> (<emu-const>seq-cst</emu-const> or <emu-const>unordered</emu-const>) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14604"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_14605"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_791"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14606"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14607"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>execution</var> be <var>AR</var>.<var class="field">[[CandidateExecution]]</var>.</li><li>Let <var>eventsRecord</var> be the <emu-xref href="#sec-agent-event-records" id="_ref_14608"><a href="memory-model.html#sec-agent-event-records">Agent Events Record</a></emu-xref> of <var>execution</var>.<var class="field">[[EventsRecords]]</var> whose <var class="field">[[AgentSignifier]]</var> is <emu-xref aoid="AgentSignifier" id="_ref_14609"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>If <var>isTypedArray</var> is <emu-val>true</emu-val> and <emu-xref aoid="IsNoTearConfiguration" id="_ref_14610"><a href="structured-data.html#sec-isnotearconfiguration">IsNoTearConfiguration</a></emu-xref>(<var>type</var>, <var>order</var>) is <emu-val>true</emu-val>, let <var>noTear</var> be <emu-val>true</emu-val>; else let <var>noTear</var> be <emu-val>false</emu-val>.</li><li>Let <var>rawValue</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14611"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of length <var>elementSize</var> whose elements are nondeterministically chosen <emu-xref href="#sec-data-blocks" id="_ref_14612"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>.</li><li>NOTE: In implementations, <var>rawValue</var> is the result of a non-atomic or atomic read instruction on the underlying hardware. The nondeterminism is a semantic prescription of the <emu-xref href="#sec-memory-model" id="_ref_14613"><a href="memory-model.html#sec-memory-model">memory model</a></emu-xref> to describe observable behaviour of hardware with weak consistency.</li><li>Let <var>readEvent</var> be <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14614"><a href="memory-model.html#sec-memory-model-fundamentals">ReadSharedMemory</a></emu-xref> { <var class="field">[[Order]]</var>: <var>order</var>, <var class="field">[[NoTear]]</var>: <var>noTear</var>, <var class="field">[[Block]]</var>: <var>block</var>, <var class="field">[[ByteIndex]]</var>: <var>byteIndex</var>, <var class="field">[[ElementSize]]</var>: <var>elementSize</var> }.</li><li>Append <var>readEvent</var> to <var>eventsRecord</var>.<var class="field">[[EventList]]</var>.</li><li>Append <emu-xref href="#sec-chosen-value-records" id="_ref_14615"><a href="memory-model.html#sec-chosen-value-records">Chosen Value Record</a></emu-xref> { <var class="field">[[Event]]</var>: <var>readEvent</var>, <var class="field">[[ChosenValue]]</var>: <var>rawValue</var> } to <var>execution</var>.<var class="field">[[ChosenValues]]</var>.</li><li>Return <var>rawValue</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getvaluefrombuffer" type="abstract operation" aoid="GetValueFromBuffer">
|
||
<h1><span class="secnum">25.1.3.16</span> GetValueFromBuffer ( <var>arrayBuffer</var>, <var>byteIndex</var>, <var>type</var>, <var>isTypedArray</var>, <var>order</var> [ , <var>isLittleEndian</var> ] )</h1>
|
||
<p>The abstract operation GetValueFromBuffer takes arguments <var>arrayBuffer</var> (an ArrayBuffer or SharedArrayBuffer), <var>byteIndex</var> (a non-negative <emu-xref href="#integer" id="_ref_14616"><a href="notational-conventions.html#integer">integer</a></emu-xref>), <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14617"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), <var>isTypedArray</var> (a Boolean), and <var>order</var> (<emu-const>seq-cst</emu-const> or <emu-const>unordered</emu-const>) and optional argument <var>isLittleEndian</var> (a Boolean) and returns a Number or a BigInt. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_14618"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsDetachedBuffer" id="_ref_14619"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>false</emu-val>.</li><li><emu-xref href="#assert" id="_ref_14620"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: There are sufficient bytes in <var>arrayBuffer</var> starting at <var>byteIndex</var> to represent a value of <var>type</var>.</li><li>Let <var>block</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_792"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14621"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>true</emu-val>, then<ol><li><emu-xref href="#assert" id="_ref_14622"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>block</var> is a <emu-xref href="#sec-data-blocks" id="_ref_14623"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref>.</li><li>Let <var>rawValue</var> be <emu-xref aoid="GetRawBytesFromSharedBlock" id="_ref_14624"><a href="structured-data.html#sec-getrawbytesfromsharedblock">GetRawBytesFromSharedBlock</a></emu-xref>(<var>block</var>, <var>byteIndex</var>, <var>type</var>, <var>isTypedArray</var>, <var>order</var>).</li></ol></li><li>Else,<ol><li>Let <var>rawValue</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14625"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are bytes from <var>block</var> at indices in the <emu-xref href="#interval" id="_ref_14626"><a href="notational-conventions.html#interval">interval</a></emu-xref> from <var>byteIndex</var> (inclusive) to <var>byteIndex</var> + <var>elementSize</var> (exclusive).</li></ol></li><li><emu-xref href="#assert" id="_ref_14627"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The number of elements in <var>rawValue</var> is <var>elementSize</var>.</li><li>If <var>isLittleEndian</var> is not present, then<ol><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14628"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14629"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Set <var>isLittleEndian</var> to <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li></ol></li><li>Return <emu-xref aoid="RawBytesToNumeric" id="_ref_14630"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>type</var>, <var>rawValue</var>, <var>isLittleEndian</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-numerictorawbytes" type="abstract operation" oldids="sec-numbertorawbytes" aoid="NumericToRawBytes"><span id="sec-numbertorawbytes"></span>
|
||
<h1><span class="secnum">25.1.3.17</span> NumericToRawBytes ( <var>type</var>, <var>value</var>, <var>isLittleEndian</var> )</h1>
|
||
<p>The abstract operation NumericToRawBytes takes arguments <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14631"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), <var>value</var> (a Number or a BigInt), and <var>isLittleEndian</var> (a Boolean) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14632"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_14633"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>type</var> is <emu-const>float16</emu-const>, then<ol><li>Let <var>rawBytes</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14634"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are the 2 bytes that are the result of converting <var>value</var> to <emu-xref href="#sec-bibliography" id="_ref_14635"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary16 format using roundTiesToEven mode. The bytes are arranged in little endian order. If <var>value</var> is <emu-val>NaN</emu-val>, <var>rawBytes</var> may be set to any implementation chosen <emu-xref href="#sec-bibliography" id="_ref_14636"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary16 format NaN encoding. An implementation must always choose the same encoding for each implementation distinguishable <emu-val>NaN</emu-val> value.</li></ol></li><li>Else if <var>type</var> is <emu-const>float32</emu-const>, then<ol><li>Let <var>rawBytes</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14637"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are the 4 bytes that are the result of converting <var>value</var> to <emu-xref href="#sec-bibliography" id="_ref_14638"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary32 format using roundTiesToEven mode. The bytes are arranged in little endian order. If <var>value</var> is <emu-val>NaN</emu-val>, <var>rawBytes</var> may be set to any implementation chosen <emu-xref href="#sec-bibliography" id="_ref_14639"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary32 format NaN encoding. An implementation must always choose the same encoding for each implementation distinguishable <emu-val>NaN</emu-val> value.</li></ol></li><li>Else if <var>type</var> is <emu-const>float64</emu-const>, then<ol><li>Let <var>rawBytes</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14640"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are the 8 bytes that are the <emu-xref href="#sec-bibliography" id="_ref_14641"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary64 format encoding of <var>value</var>. The bytes are arranged in little endian order. If <var>value</var> is <emu-val>NaN</emu-val>, <var>rawBytes</var> may be set to any implementation chosen <emu-xref href="#sec-bibliography" id="_ref_14642"><a href="bibliography.html#sec-bibliography">IEEE 754-2019</a></emu-xref> binary64 format NaN encoding. An implementation must always choose the same encoding for each implementation distinguishable <emu-val>NaN</emu-val> value.</li></ol></li><li>Else,<ol><li>Let <var>n</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_793"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>Let <var>conversionOperation</var> be the abstract operation named in the “Conversion Operation” column of <emu-xref href="#table-the-typedarray-constructors" id="_ref_794"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>Let <var>intValue</var> be <emu-xref aoid="ℝ" id="_ref_14643"><a href="notational-conventions.html#%E2%84%9D">ℝ</a></emu-xref>(! <var>conversionOperation</var>(<var>value</var>)).</li><li>If <var>intValue</var> ≥ 0, then<ol><li>Let <var>rawBytes</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14644"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are the <var>n</var>-byte binary encoding of <var>intValue</var>. The bytes are ordered in little endian order.</li></ol></li><li>Else,<ol><li>Let <var>rawBytes</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14645"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are the <var>n</var>-byte binary two's complement encoding of <var>intValue</var>. The bytes are ordered in little endian order.</li></ol></li></ol></li><li>If <var>isLittleEndian</var> is <emu-val>false</emu-val>, reverse the order of the elements of <var>rawBytes</var>.</li><li>Return <var>rawBytes</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-setvalueinbuffer" type="abstract operation" aoid="SetValueInBuffer">
|
||
<h1><span class="secnum">25.1.3.18</span> SetValueInBuffer ( <var>arrayBuffer</var>, <var>byteIndex</var>, <var>type</var>, <var>value</var>, <var>isTypedArray</var>, <var>order</var> [ , <var>isLittleEndian</var> ] )</h1>
|
||
<p>The abstract operation SetValueInBuffer takes arguments <var>arrayBuffer</var> (an ArrayBuffer or SharedArrayBuffer), <var>byteIndex</var> (a non-negative <emu-xref href="#integer" id="_ref_14646"><a href="notational-conventions.html#integer">integer</a></emu-xref>), <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14647"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), <var>value</var> (a Number or a BigInt), <var>isTypedArray</var> (a Boolean), and <var>order</var> (<emu-const>seq-cst</emu-const>, <emu-const>unordered</emu-const>, or <emu-const>init</emu-const>) and optional argument <var>isLittleEndian</var> (a Boolean) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_14648"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsDetachedBuffer" id="_ref_14649"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>false</emu-val>.</li><li><emu-xref href="#assert" id="_ref_14650"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: There are sufficient bytes in <var>arrayBuffer</var> starting at <var>byteIndex</var> to represent a value of <var>type</var>.</li><li><emu-xref href="#assert" id="_ref_14651"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>value</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_14652"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref> if <emu-xref aoid="IsBigIntElementType" id="_ref_14653"><a href="structured-data.html#sec-isbigintelementtype">IsBigIntElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val>; else, <var>value</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_14654"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>.</li><li>Let <var>block</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_795"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14655"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14656"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>If <var>isLittleEndian</var> is not present, then<ol><li>Set <var>isLittleEndian</var> to <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li></ol></li><li>Let <var>rawBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_14657"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<var>type</var>, <var>value</var>, <var>isLittleEndian</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14658"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>execution</var> be <var>AR</var>.<var class="field">[[CandidateExecution]]</var>.</li><li>Let <var>eventsRecord</var> be the <emu-xref href="#sec-agent-event-records" id="_ref_14659"><a href="memory-model.html#sec-agent-event-records">Agent Events Record</a></emu-xref> of <var>execution</var>.<var class="field">[[EventsRecords]]</var> whose <var class="field">[[AgentSignifier]]</var> is <emu-xref aoid="AgentSignifier" id="_ref_14660"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>If <var>isTypedArray</var> is <emu-val>true</emu-val> and <emu-xref aoid="IsNoTearConfiguration" id="_ref_14661"><a href="structured-data.html#sec-isnotearconfiguration">IsNoTearConfiguration</a></emu-xref>(<var>type</var>, <var>order</var>) is <emu-val>true</emu-val>, let <var>noTear</var> be <emu-val>true</emu-val>; else let <var>noTear</var> be <emu-val>false</emu-val>.</li><li>Append <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14662"><a href="memory-model.html#sec-memory-model-fundamentals">WriteSharedMemory</a></emu-xref> { <var class="field">[[Order]]</var>: <var>order</var>, <var class="field">[[NoTear]]</var>: <var>noTear</var>, <var class="field">[[Block]]</var>: <var>block</var>, <var class="field">[[ByteIndex]]</var>: <var>byteIndex</var>, <var class="field">[[ElementSize]]</var>: <var>elementSize</var>, <var class="field">[[Payload]]</var>: <var>rawBytes</var> } to <var>eventsRecord</var>.<var class="field">[[EventList]]</var>.</li></ol></li><li>Else,<ol><li>Store the individual bytes of <var>rawBytes</var> into <var>block</var>, starting at <var>block</var>[<var>byteIndex</var>].</li></ol></li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getmodifysetvalueinbuffer" type="abstract operation" aoid="GetModifySetValueInBuffer">
|
||
<h1><span class="secnum">25.1.3.19</span> GetModifySetValueInBuffer ( <var>arrayBuffer</var>, <var>byteIndex</var>, <var>type</var>, <var>value</var>, <var>op</var> )</h1>
|
||
<p>The abstract operation GetModifySetValueInBuffer takes arguments <var>arrayBuffer</var> (an ArrayBuffer or a SharedArrayBuffer), <var>byteIndex</var> (a non-negative <emu-xref href="#integer" id="_ref_14663"><a href="notational-conventions.html#integer">integer</a></emu-xref>), <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14664"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), <var>value</var> (a Number or a BigInt), and <var>op</var> (a <emu-xref href="#sec-arraybuffer-notation" id="_ref_14665"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref>) and returns a Number or a BigInt. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_14666"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsDetachedBuffer" id="_ref_14667"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>false</emu-val>.</li><li><emu-xref href="#assert" id="_ref_14668"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: There are sufficient bytes in <var>arrayBuffer</var> starting at <var>byteIndex</var> to represent a value of <var>type</var>.</li><li><emu-xref href="#assert" id="_ref_14669"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>value</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_14670"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref> if <emu-xref aoid="IsBigIntElementType" id="_ref_14671"><a href="structured-data.html#sec-isbigintelementtype">IsBigIntElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val>; else, <var>value</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_14672"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>.</li><li>Let <var>block</var> be <var>arrayBuffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_796"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14673"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14674"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li><li>Let <var>rawBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_14675"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<var>type</var>, <var>value</var>, <var>isLittleEndian</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14676"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>arrayBuffer</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>execution</var> be <var>AR</var>.<var class="field">[[CandidateExecution]]</var>.</li><li>Let <var>eventsRecord</var> be the <emu-xref href="#sec-agent-event-records" id="_ref_14677"><a href="memory-model.html#sec-agent-event-records">Agent Events Record</a></emu-xref> of <var>execution</var>.<var class="field">[[EventsRecords]]</var> whose <var class="field">[[AgentSignifier]]</var> is <emu-xref aoid="AgentSignifier" id="_ref_14678"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>Let <var>rawBytesRead</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14679"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of length <var>elementSize</var> whose elements are nondeterministically chosen <emu-xref href="#sec-data-blocks" id="_ref_14680"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>.</li><li>NOTE: In implementations, <var>rawBytesRead</var> is the result of a load-link, of a load-exclusive, or of an operand of a read-modify-write instruction on the underlying hardware. The nondeterminism is a semantic prescription of the <emu-xref href="#sec-memory-model" id="_ref_14681"><a href="memory-model.html#sec-memory-model">memory model</a></emu-xref> to describe observable behaviour of hardware with weak consistency.</li><li>Let <var>rmwEvent</var> be <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14682"><a href="memory-model.html#sec-memory-model-fundamentals">ReadModifyWriteSharedMemory</a></emu-xref> { <var class="field">[[Order]]</var>: <emu-const>seq-cst</emu-const>, <var class="field">[[NoTear]]</var>: <emu-val>true</emu-val>, <var class="field">[[Block]]</var>: <var>block</var>, <var class="field">[[ByteIndex]]</var>: <var>byteIndex</var>, <var class="field">[[ElementSize]]</var>: <var>elementSize</var>, <var class="field">[[Payload]]</var>: <var>rawBytes</var>, <var class="field">[[ModifyOp]]</var>: <var>op</var> }.</li><li>Append <var>rmwEvent</var> to <var>eventsRecord</var>.<var class="field">[[EventList]]</var>.</li><li>Append <emu-xref href="#sec-chosen-value-records" id="_ref_14683"><a href="memory-model.html#sec-chosen-value-records">Chosen Value Record</a></emu-xref> { <var class="field">[[Event]]</var>: <var>rmwEvent</var>, <var class="field">[[ChosenValue]]</var>: <var>rawBytesRead</var> } to <var>execution</var>.<var class="field">[[ChosenValues]]</var>.</li></ol></li><li>Else,<ol><li>Let <var>rawBytesRead</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14684"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of length <var>elementSize</var> whose elements are the sequence of <var>elementSize</var> bytes starting with <var>block</var>[<var>byteIndex</var>].</li><li>Let <var>rawBytesModified</var> be <var>op</var>(<var>rawBytesRead</var>, <var>rawBytes</var>).</li><li>Store the individual bytes of <var>rawBytesModified</var> into <var>block</var>, starting at <var>block</var>[<var>byteIndex</var>].</li></ol></li><li>Return <emu-xref aoid="RawBytesToNumeric" id="_ref_14685"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>type</var>, <var>rawBytesRead</var>, <var>isLittleEndian</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer-constructor">
|
||
<h1><span class="secnum">25.1.4</span> The ArrayBuffer Constructor</h1>
|
||
<p>The ArrayBuffer <emu-xref href="#constructor" id="_ref_14686"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%ArrayBuffer%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"ArrayBuffer"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_14687"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</li>
|
||
<li>creates and initializes a new ArrayBuffer when called as a <emu-xref href="#constructor" id="_ref_14688"><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 of an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_14689"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified ArrayBuffer behaviour must include a <code>super</code> call to the ArrayBuffer <emu-xref href="#constructor" id="_ref_14690"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize subclass instances with the internal state necessary to support the <code>ArrayBuffer.prototype</code> built-in methods.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-arraybuffer-length" type="built-in function">
|
||
<h1><span class="secnum">25.1.4.1</span> ArrayBuffer ( <var>length</var> [ , <var>options</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>Let <var>byteLength</var> be ? <emu-xref aoid="ToIndex" id="_ref_14691"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>length</var>).</li><li>Let <var>requestedMaxByteLength</var> be ? <emu-xref aoid="GetArrayBufferMaxByteLengthOption" id="_ref_14692"><a href="structured-data.html#sec-getarraybuffermaxbytelengthoption" class="e-user-code">GetArrayBufferMaxByteLengthOption</a></emu-xref>(<var>options</var>).</li><li>Return ? <emu-xref aoid="AllocateArrayBuffer" id="_ref_14693"><a href="structured-data.html#sec-allocatearraybuffer" class="e-user-code">AllocateArrayBuffer</a></emu-xref>(NewTarget, <var>byteLength</var>, <var>requestedMaxByteLength</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-arraybuffer-constructor">
|
||
<h1><span class="secnum">25.1.5</span> Properties of the ArrayBuffer Constructor</h1>
|
||
<p>The ArrayBuffer <emu-xref href="#constructor" id="_ref_14694"><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_14695"><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-arraybuffer.isview" type="built-in function">
|
||
<h1><span class="secnum">25.1.5.1</span> ArrayBuffer.isView ( <var>arg</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>arg</var> <emu-xref href="#sec-object-type" id="_ref_14696"><a href="ecmascript-data-types-and-values.html#sec-object-type">is not an Object</a></emu-xref>, return <emu-val>false</emu-val>.</li><li>If <var>arg</var> has a <var class="field">[[ViewedArrayBuffer]]</var> internal slot, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer.prototype">
|
||
<h1><span class="secnum">25.1.5.2</span> ArrayBuffer.prototype</h1>
|
||
<p>The initial value of <code>ArrayBuffer.prototype</code> is the <emu-xref href="#sec-properties-of-the-arraybuffer-prototype-object" id="_ref_14697"><a href="structured-data.html#sec-properties-of-the-arraybuffer-prototype-object">ArrayBuffer 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 oldids="sec-get-arraybuffer-@@species" id="sec-get-arraybuffer-%symbol.species%" type="built-in function"><span id="sec-get-arraybuffer-@@species"></span>
|
||
<h1><span class="secnum">25.1.5.3</span> get ArrayBuffer [ %Symbol.species% ]</h1>
|
||
<p><code>ArrayBuffer[%Symbol.species%]</code> is an <emu-xref href="#sec-object-type" id="_ref_14698"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return the <emu-val>this</emu-val> value.</li></ol></emu-alg>
|
||
<p>The value of the <emu-val>"name"</emu-val> property of this function is <emu-val>"get [Symbol.species]"</emu-val>.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p><emu-xref href="#sec-arraybuffer.prototype.slice" title="" id="_ref_797"><a href="structured-data.html#sec-arraybuffer.prototype.slice">ArrayBuffer.prototype.slice ( <var>start</var>, <var>end</var> )</a></emu-xref> normally uses its <emu-val>this</emu-val> value's <emu-xref href="#constructor" id="_ref_14699"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create a derived object. However, a subclass <emu-xref href="#constructor" id="_ref_14700"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> may over-ride that default behaviour for the <emu-xref href="#sec-arraybuffer.prototype.slice" title="" id="_ref_798"><a href="structured-data.html#sec-arraybuffer.prototype.slice">ArrayBuffer.prototype.slice ( <var>start</var>, <var>end</var> )</a></emu-xref> method by redefining its <emu-xref href="#sec-well-known-symbols" id="_ref_14701"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.species%</a></emu-xref> property.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-arraybuffer-prototype-object">
|
||
<h1><span class="secnum">25.1.6</span> Properties of the ArrayBuffer Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">ArrayBuffer prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%ArrayBuffer.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_14702"><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_14703"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>does not have an <var class="field">[[ArrayBufferData]]</var> or <var class="field">[[ArrayBufferByteLength]]</var> internal slot.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-get-arraybuffer.prototype.bytelength" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.1</span> get ArrayBuffer.prototype.byteLength</h1>
|
||
<p><code>ArrayBuffer.prototype.byteLength</code> is an <emu-xref href="#sec-object-type" id="_ref_14704"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14705"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14706"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14707"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, return <emu-val>+0</emu-val><sub>𝔽</sub>.</li><li>Let <var>length</var> be <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li><li>Return <emu-xref aoid="𝔽" id="_ref_14708"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>length</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer.prototype.constructor">
|
||
<h1><span class="secnum">25.1.6.2</span> ArrayBuffer.prototype.constructor</h1>
|
||
<p>The initial value of <code>ArrayBuffer.prototype.constructor</code> is <emu-xref href="#sec-arraybuffer-constructor" id="_ref_14709"><a href="structured-data.html#sec-arraybuffer-constructor">%ArrayBuffer%</a></emu-xref>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-arraybuffer.prototype.detached" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.3</span> get ArrayBuffer.prototype.detached</h1>
|
||
<p><code>ArrayBuffer.prototype.detached</code> is an <emu-xref href="#sec-object-type" id="_ref_14710"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14711"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14712"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Return <emu-xref aoid="IsDetachedBuffer" id="_ref_14713"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>O</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-arraybuffer.prototype.maxbytelength" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.4</span> get ArrayBuffer.prototype.maxByteLength</h1>
|
||
<p><code>ArrayBuffer.prototype.maxByteLength</code> is an <emu-xref href="#sec-object-type" id="_ref_14714"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14715"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14716"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14717"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, return <emu-val>+0</emu-val><sub>𝔽</sub>.</li><li>If <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14718"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>length</var> be <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li></ol></li><li>Else,<ol><li>Let <var>length</var> be <var>O</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>.</li></ol></li><li>Return <emu-xref aoid="𝔽" id="_ref_14719"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>length</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-arraybuffer.prototype.resizable" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.5</span> get ArrayBuffer.prototype.resizable</h1>
|
||
<p><code>ArrayBuffer.prototype.resizable</code> is an <emu-xref href="#sec-object-type" id="_ref_14720"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14721"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14722"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14723"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer.prototype.resize" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.6</span> ArrayBuffer.prototype.resize ( <var>newLength</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14724"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferMaxByteLength]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14725"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>newByteLength</var> be ? <emu-xref aoid="ToIndex" id="_ref_14726"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>newLength</var>).</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14727"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>newByteLength</var> > <var>O</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Let <var>hostHandled</var> be ? <emu-xref aoid="HostResizeArrayBuffer" id="_ref_14728"><a href="structured-data.html#sec-hostresizearraybuffer">HostResizeArrayBuffer</a></emu-xref>(<var>O</var>, <var>newByteLength</var>).</li><li>If <var>hostHandled</var> is <emu-const>handled</emu-const>, return <emu-val>undefined</emu-val>.</li><li>Let <var>oldBlock</var> be <var>O</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>newBlock</var> be ? <emu-xref aoid="CreateByteDataBlock" id="_ref_14729"><a href="ecmascript-data-types-and-values.html#sec-createbytedatablock">CreateByteDataBlock</a></emu-xref>(<var>newByteLength</var>).</li><li>Let <var>copyLength</var> be <emu-xref aoid="min" id="_ref_14730"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>newByteLength</var>, <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var>).</li><li>Perform <emu-xref aoid="CopyDataBlockBytes" id="_ref_14731"><a href="ecmascript-data-types-and-values.html#sec-copydatablockbytes">CopyDataBlockBytes</a></emu-xref>(<var>newBlock</var>, 0, <var>oldBlock</var>, 0, <var>copyLength</var>).</li><li>NOTE: Neither creation of the new <emu-xref href="#sec-data-blocks" id="_ref_14732"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Data Block</a></emu-xref> nor copying from the old <emu-xref href="#sec-data-blocks" id="_ref_14733"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Data Block</a></emu-xref> are observable. Implementations may implement this method as in-place growth or shrinkage.</li><li>Set <var>O</var>.<var class="field">[[ArrayBufferData]]</var> to <var>newBlock</var>.</li><li>Set <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var> to <var>newByteLength</var>.</li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer.prototype.slice" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.7</span> ArrayBuffer.prototype.slice ( <var>start</var>, <var>end</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14734"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14735"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14736"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>len</var> be <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li><li>Let <var>relativeStart</var> be ? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_14737"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>start</var>).</li><li>If <var>relativeStart</var> = -∞, let <var>first</var> be 0.</li><li>Else if <var>relativeStart</var> < 0, let <var>first</var> be <emu-xref aoid="max" id="_ref_14738"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>len</var> + <var>relativeStart</var>, 0).</li><li>Else, let <var>first</var> be <emu-xref aoid="min" id="_ref_14739"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>relativeStart</var>, <var>len</var>).</li><li>If <var>end</var> is <emu-val>undefined</emu-val>, let <var>relativeEnd</var> be <var>len</var>; else let <var>relativeEnd</var> be ? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_14740"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>end</var>).</li><li>If <var>relativeEnd</var> = -∞, let <var>final</var> be 0.</li><li>Else if <var>relativeEnd</var> < 0, let <var>final</var> be <emu-xref aoid="max" id="_ref_14741"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>len</var> + <var>relativeEnd</var>, 0).</li><li>Else, let <var>final</var> be <emu-xref aoid="min" id="_ref_14742"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>relativeEnd</var>, <var>len</var>).</li><li>Let <var>newLen</var> be <emu-xref aoid="max" id="_ref_14743"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>final</var> - <var>first</var>, 0).</li><li>Let <var>ctor</var> be ? <emu-xref aoid="SpeciesConstructor" id="_ref_14744"><a href="abstract-operations.html#sec-speciesconstructor" class="e-user-code">SpeciesConstructor</a></emu-xref>(<var>O</var>, <emu-xref href="#sec-arraybuffer-constructor" id="_ref_14745"><a href="structured-data.html#sec-arraybuffer-constructor">%ArrayBuffer%</a></emu-xref>).</li><li>Let <var>new</var> be ? <emu-xref aoid="Construct" id="_ref_14746"><a href="abstract-operations.html#sec-construct" class="e-user-code">Construct</a></emu-xref>(<var>ctor</var>, « <emu-xref aoid="𝔽" id="_ref_14747"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>newLen</var>) »).</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14748"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>new</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14749"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>new</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14750"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>new</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="SameValue" id="_ref_14751"><a href="abstract-operations.html#sec-samevalue">SameValue</a></emu-xref>(<var>new</var>, <var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>new</var>.<var class="field">[[ArrayBufferByteLength]]</var> < <var>newLen</var>, throw a <emu-val>TypeError</emu-val> exception.</li><li>NOTE: Side-effects of the above steps may have detached or resized <var>O</var>.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14752"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>fromBuf</var> be <var>O</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>toBuf</var> be <var>new</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>currentLen</var> be <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li><li>If <var>first</var> < <var>currentLen</var>, then<ol><li>Let <var>count</var> be <emu-xref aoid="min" id="_ref_14753"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>newLen</var>, <var>currentLen</var> - <var>first</var>).</li><li>Perform <emu-xref aoid="CopyDataBlockBytes" id="_ref_14754"><a href="ecmascript-data-types-and-values.html#sec-copydatablockbytes">CopyDataBlockBytes</a></emu-xref>(<var>toBuf</var>, 0, <var>fromBuf</var>, <var>first</var>, <var>count</var>).</li></ol></li><li>Return <var>new</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer.prototype.transfer" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.8</span> ArrayBuffer.prototype.transfer ( [ <var>newLength</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="ArrayBufferCopyAndDetach" id="_ref_14755"><a href="structured-data.html#sec-arraybuffercopyanddetach" class="e-user-code">ArrayBufferCopyAndDetach</a></emu-xref>(<var>O</var>, <var>newLength</var>, <emu-const>preserve-resizability</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-arraybuffer.prototype.transfertofixedlength" type="built-in function">
|
||
<h1><span class="secnum">25.1.6.9</span> ArrayBuffer.prototype.transferToFixedLength ( [ <var>newLength</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="ArrayBufferCopyAndDetach" id="_ref_14756"><a href="structured-data.html#sec-arraybuffercopyanddetach" class="e-user-code">ArrayBufferCopyAndDetach</a></emu-xref>(<var>O</var>, <var>newLength</var>, <emu-const>fixed-length</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-arraybuffer.prototype-@@tostringtag" id="sec-arraybuffer.prototype-%symbol.tostringtag%"><span id="sec-arraybuffer.prototype-@@tostringtag"></span>
|
||
<h1><span class="secnum">25.1.6.10</span> ArrayBuffer.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_14757"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"ArrayBuffer"</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-the-arraybuffer-instances">
|
||
<h1><span class="secnum">25.1.7</span> Properties of ArrayBuffer Instances</h1>
|
||
<p>ArrayBuffer instances inherit properties from the <emu-xref href="#sec-properties-of-the-arraybuffer-prototype-object" id="_ref_14758"><a href="structured-data.html#sec-properties-of-the-arraybuffer-prototype-object">ArrayBuffer prototype object</a></emu-xref>. ArrayBuffer instances each have an <var class="field">[[ArrayBufferData]]</var> internal slot, an <var class="field">[[ArrayBufferByteLength]]</var> internal slot, and an <var class="field">[[ArrayBufferDetachKey]]</var> internal slot. ArrayBuffer instances which are resizable each have an <var class="field">[[ArrayBufferMaxByteLength]]</var> internal slot.</p>
|
||
<p>ArrayBuffer instances whose <var class="field">[[ArrayBufferData]]</var> is <emu-val>null</emu-val> are considered to be detached and all operators to access or modify data contained in the ArrayBuffer instance will fail.</p>
|
||
<p>ArrayBuffer instances whose <var class="field">[[ArrayBufferDetachKey]]</var> is set to a value other than <emu-val>undefined</emu-val> need to have all <emu-xref aoid="DetachArrayBuffer" id="_ref_14759"><a href="structured-data.html#sec-detacharraybuffer">DetachArrayBuffer</a></emu-xref> calls passing that same "detach key" as an argument, otherwise a TypeError will result. This internal slot is only ever set by certain embedding environments, not by algorithms in this specification.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-resizable-arraybuffer-guidelines">
|
||
<h1><span class="secnum">25.1.8</span> Resizable ArrayBuffer Guidelines</h1>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>The following are guidelines for ECMAScript programmers working with <emu-xref href="#sec-fixed-length-and-resizable-arraybuffer-objects" id="_ref_14760"><a href="structured-data.html#sec-fixed-length-and-resizable-arraybuffer-objects">resizable ArrayBuffer</a></emu-xref>.</p>
|
||
<p>We recommend that programs be tested in their deployment environments where possible. The amount of available physical memory differs greatly between hardware devices. Similarly, virtual memory subsystems also differ greatly between hardware devices as well as operating systems. An application that runs without out-of-memory errors on a 64-bit desktop web browser could run out of memory on a 32-bit mobile web browser.</p>
|
||
<p>When choosing a value for the <emu-val>"maxByteLength"</emu-val> option for <emu-xref href="#sec-fixed-length-and-resizable-arraybuffer-objects" id="_ref_14761"><a href="structured-data.html#sec-fixed-length-and-resizable-arraybuffer-objects">resizable ArrayBuffer</a></emu-xref>, we recommend that the smallest possible size for the application be chosen. We recommend that <emu-val>"maxByteLength"</emu-val> does not exceed 1,073,741,824 (2<sup>30</sup> bytes or 1GiB).</p>
|
||
<p>Please note that successfully constructing a <emu-xref href="#sec-fixed-length-and-resizable-arraybuffer-objects" id="_ref_14762"><a href="structured-data.html#sec-fixed-length-and-resizable-arraybuffer-objects">resizable ArrayBuffer</a></emu-xref> for a particular maximum size does not guarantee that future resizes will succeed.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>The following are guidelines for ECMAScript implementers implementing <emu-xref href="#sec-fixed-length-and-resizable-arraybuffer-objects" id="_ref_14763"><a href="structured-data.html#sec-fixed-length-and-resizable-arraybuffer-objects">resizable ArrayBuffer</a></emu-xref>.</p>
|
||
<p><emu-xref href="#sec-fixed-length-and-resizable-arraybuffer-objects" id="_ref_14764"><a href="structured-data.html#sec-fixed-length-and-resizable-arraybuffer-objects">Resizable ArrayBuffer</a></emu-xref> can be implemented as copying upon resize, as in-place growth via reserving virtual memory up front, or as a combination of both for different values of the <emu-xref href="#constructor" id="_ref_14765"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>'s <emu-val>"maxByteLength"</emu-val> option.</p>
|
||
<p>If a <emu-xref href="#host" id="_ref_14766"><a href="overview.html#host">host</a></emu-xref> is multi-tenanted (i.e. it runs many ECMAScript applications simultaneously), such as a web browser, and its implementations choose to implement in-place growth by reserving virtual memory, we recommend that both 32-bit and 64-bit implementations throw for values of <emu-val>"maxByteLength"</emu-val> ≥ 1GiB to 1.5GiB. This is to reduce the likelihood a single application can exhaust the virtual memory address space and to reduce interoperability risk.</p>
|
||
<p>If a <emu-xref href="#host" id="_ref_14767"><a href="overview.html#host">host</a></emu-xref> does not have virtual memory, such as those running on embedded devices without an MMU, or if a <emu-xref href="#host" id="_ref_14768"><a href="overview.html#host">host</a></emu-xref> only implements resizing by copying, it may accept any <emu-not-ref>Number value for</emu-not-ref> the <emu-val>"maxByteLength"</emu-val> option. However, we recommend a <emu-val>RangeError</emu-val> be thrown if a memory block of the requested size can never be allocated. For example, if the requested size is greater than the maximum amount of usable memory on the device.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-sharedarraybuffer-objects">
|
||
<h1><span class="secnum">25.2</span> SharedArrayBuffer Objects</h1>
|
||
|
||
<emu-clause id="sec-fixed-length-and-growable-sharedarraybuffer-objects">
|
||
<h1><span class="secnum">25.2.1</span> Fixed-length and Growable SharedArrayBuffer Objects</h1>
|
||
<p>A <dfn tabindex="-1">fixed-length SharedArrayBuffer</dfn> is a SharedArrayBuffer whose byte length cannot change after creation.</p>
|
||
<p>A <dfn tabindex="-1">growable SharedArrayBuffer</dfn> is a SharedArrayBuffer whose byte length may increase after creation via calls to <emu-xref href="#sec-sharedarraybuffer.prototype.grow" title="" id="_ref_799"><a href="structured-data.html#sec-sharedarraybuffer.prototype.grow">SharedArrayBuffer.prototype.grow ( <var>newLength</var> )</a></emu-xref>.</p>
|
||
<p>The kind of SharedArrayBuffer object that is created depends on the arguments passed to <emu-xref href="#sec-sharedarraybuffer-length" title="" id="_ref_800"><a href="structured-data.html#sec-sharedarraybuffer-length">SharedArrayBuffer ( <var>length</var> [ , <var>options</var> ] )</a></emu-xref>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-abstract-operations-for-sharedarraybuffer-objects">
|
||
<h1><span class="secnum">25.2.2</span> Abstract Operations for SharedArrayBuffer Objects</h1>
|
||
|
||
<emu-clause id="sec-allocatesharedarraybuffer" type="abstract operation" aoid="AllocateSharedArrayBuffer">
|
||
<h1><span class="secnum">25.2.2.1</span> AllocateSharedArrayBuffer ( <var>constructor</var>, <var>byteLength</var> [ , <var>maxByteLength</var> ] )</h1>
|
||
<p>The abstract operation AllocateSharedArrayBuffer takes arguments <var>constructor</var> (a <emu-xref href="#constructor" id="_ref_14769"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>) and <var>byteLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14770"><a href="notational-conventions.html#integer">integer</a></emu-xref>) and optional argument <var>maxByteLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14771"><a href="notational-conventions.html#integer">integer</a></emu-xref> or <emu-const>empty</emu-const>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14772"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> a SharedArrayBuffer or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14773"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It is used to create a SharedArrayBuffer. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>slots</var> be « <var class="field">[[ArrayBufferData]]</var> ».</li><li>If <var>maxByteLength</var> is present and <var>maxByteLength</var> is not <emu-const>empty</emu-const>, let <var>allocatingGrowableBuffer</var> be <emu-val>true</emu-val>; else let <var>allocatingGrowableBuffer</var> be <emu-val>false</emu-val>.</li><li>If <var>allocatingGrowableBuffer</var> is <emu-val>true</emu-val>, then<ol><li>If <var>byteLength</var> > <var>maxByteLength</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Append <var class="field">[[ArrayBufferByteLengthData]]</var> and <var class="field">[[ArrayBufferMaxByteLength]]</var> to <var>slots</var>.</li></ol></li><li>Else,<ol><li>Append <var class="field">[[ArrayBufferByteLength]]</var> to <var>slots</var>.</li></ol></li><li>Let <var>obj</var> be ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_14774"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(<var>constructor</var>, <emu-val>"%SharedArrayBuffer.prototype%"</emu-val>, <var>slots</var>).</li><li>If <var>allocatingGrowableBuffer</var> is <emu-val>true</emu-val>, let <var>allocLength</var> be <var>maxByteLength</var>; else let <var>allocLength</var> be <var>byteLength</var>.</li><li>Let <var>block</var> be ? <emu-xref aoid="CreateSharedByteDataBlock" id="_ref_14775"><a href="ecmascript-data-types-and-values.html#sec-createsharedbytedatablock">CreateSharedByteDataBlock</a></emu-xref>(<var>allocLength</var>).</li><li>Set <var>obj</var>.<var class="field">[[ArrayBufferData]]</var> to <var>block</var>.</li><li>If <var>allocatingGrowableBuffer</var> is <emu-val>true</emu-val>, then<ol><li><emu-xref href="#assert" id="_ref_14776"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>byteLength</var> ≤ <var>maxByteLength</var>.</li><li>Let <var>byteLengthBlock</var> be ? <emu-xref aoid="CreateSharedByteDataBlock" id="_ref_14777"><a href="ecmascript-data-types-and-values.html#sec-createsharedbytedatablock">CreateSharedByteDataBlock</a></emu-xref>(8).</li><li>Perform <emu-xref aoid="SetValueInBuffer" id="_ref_14778"><a href="structured-data.html#sec-setvalueinbuffer">SetValueInBuffer</a></emu-xref>(<var>byteLengthBlock</var>, 0, <emu-const>biguint64</emu-const>, <emu-xref aoid="ℤ" id="_ref_14779"><a href="notational-conventions.html#%E2%84%A4">ℤ</a></emu-xref>(<var>byteLength</var>), <emu-val>true</emu-val>, <emu-const>seq-cst</emu-const>).</li><li>Set <var>obj</var>.<var class="field">[[ArrayBufferByteLengthData]]</var> to <var>byteLengthBlock</var>.</li><li>Set <var>obj</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var> to <var>maxByteLength</var>.</li></ol></li><li>Else,<ol><li>Set <var>obj</var>.<var class="field">[[ArrayBufferByteLength]]</var> to <var>byteLength</var>.</li></ol></li><li>Return <var>obj</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-issharedarraybuffer" type="abstract operation" aoid="IsSharedArrayBuffer">
|
||
<h1><span class="secnum">25.2.2.2</span> IsSharedArrayBuffer ( <var>obj</var> )</h1>
|
||
<p>The abstract operation IsSharedArrayBuffer takes argument <var>obj</var> (an ArrayBuffer or a SharedArrayBuffer) and returns a Boolean. It tests whether an object is a SharedArrayBuffer. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>obj</var>.<var class="field">[[ArrayBufferData]]</var> is a <emu-xref href="#sec-data-blocks" id="_ref_14780"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isgrowablesharedarraybuffer" type="abstract operation" aoid="IsGrowableSharedArrayBuffer">
|
||
<h1><span class="secnum">25.2.2.3</span> IsGrowableSharedArrayBuffer ( <var>obj</var> )</h1>
|
||
<p>The abstract operation IsGrowableSharedArrayBuffer takes argument <var>obj</var> (an ArrayBuffer or a SharedArrayBuffer) and returns a Boolean. It tests whether an object is a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14781"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14782"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>obj</var>) is <emu-val>true</emu-val> and <var>obj</var> has an <var class="field">[[ArrayBufferByteLengthData]]</var> internal slot, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-hostgrowsharedarraybuffer" type="host-defined abstract operation" aoid="HostGrowSharedArrayBuffer">
|
||
<h1><span class="secnum">25.2.2.4</span> HostGrowSharedArrayBuffer ( <var>buffer</var>, <var>newByteLength</var> )</h1>
|
||
<p>The <emu-xref href="#host-defined" id="_ref_14783"><a href="overview.html#host-defined">host-defined</a></emu-xref> abstract operation HostGrowSharedArrayBuffer takes arguments <var>buffer</var> (a SharedArrayBuffer) and <var>newByteLength</var> (a non-negative <emu-xref href="#integer" id="_ref_14784"><a href="notational-conventions.html#integer">integer</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14785"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either <emu-const>handled</emu-const> or <emu-const>unhandled</emu-const>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14786"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It gives the <emu-xref href="#host" id="_ref_14787"><a href="overview.html#host">host</a></emu-xref> an opportunity to perform <emu-xref href="#implementation-defined" id="_ref_14788"><a href="overview.html#implementation-defined">implementation-defined</a></emu-xref> growing of <var>buffer</var>. If the <emu-xref href="#host" id="_ref_14789"><a href="overview.html#host">host</a></emu-xref> chooses not to handle growing of <var>buffer</var>, it may return <emu-const>unhandled</emu-const> for the default behaviour.</p>
|
||
<p>The implementation of HostGrowSharedArrayBuffer must conform to the following requirements:</p>
|
||
<ul>
|
||
<li>If the abstract operation does not complete normally with <emu-const>unhandled</emu-const>, and <var>newByteLength</var> < the current byte length of the <var>buffer</var> or <var>newByteLength</var> > <var>buffer</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>, throw a <emu-val>RangeError</emu-val> exception.</li>
|
||
<li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14790"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14791"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>. Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>. If the abstract operation completes normally with <emu-const>handled</emu-const>, a <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14792"><a href="memory-model.html#sec-memory-model-fundamentals">WriteSharedMemory</a></emu-xref> or <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14793"><a href="memory-model.html#sec-memory-model-fundamentals">ReadModifyWriteSharedMemory</a></emu-xref> event whose <var class="field">[[Order]]</var> is <emu-const>seq-cst</emu-const>, <var class="field">[[Payload]]</var> is <emu-xref aoid="NumericToRawBytes" id="_ref_14794"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<emu-const>biguint64</emu-const>, <var>newByteLength</var>, <var>isLittleEndian</var>), <var class="field">[[Block]]</var> is <var>buffer</var>.<var class="field">[[ArrayBufferByteLengthData]]</var>, <var class="field">[[ByteIndex]]</var> is 0, and <var class="field">[[ElementSize]]</var> is 8 is added to the <emu-xref href="#surrounding-agent" id="_ref_14795"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>'s <emu-xref href="#sec-candidate-executions" id="_ref_14796"><a href="memory-model.html#sec-candidate-executions">candidate execution</a></emu-xref> such that racing calls to <emu-xref href="#sec-sharedarraybuffer.prototype.grow" title="" id="_ref_801"><a href="structured-data.html#sec-sharedarraybuffer.prototype.grow">SharedArrayBuffer.prototype.grow ( <var>newLength</var> )</a></emu-xref> are not "lost", i.e. silently do nothing.</li>
|
||
</ul>
|
||
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>The second requirement above is intentionally vague about how or when the current byte length of <var>buffer</var> is read. Because the byte length must be updated via an atomic read-modify-write operation on the underlying hardware, architectures that use load-link/store-conditional or load-exclusive/store-exclusive instruction pairs may wish to keep the paired instructions close in the instruction stream. As such, <emu-xref href="#sec-sharedarraybuffer.prototype.grow" title="" id="_ref_802"><a href="structured-data.html#sec-sharedarraybuffer.prototype.grow">SharedArrayBuffer.prototype.grow ( <var>newLength</var> )</a></emu-xref> itself does not perform bounds checking on <var>newByteLength</var> before calling HostGrowSharedArrayBuffer, nor is there a requirement on when the current byte length is read.</p>
|
||
<p>This is in contrast with <emu-xref aoid="HostResizeArrayBuffer" id="_ref_14797"><a href="structured-data.html#sec-hostresizearraybuffer">HostResizeArrayBuffer</a></emu-xref>, which is guaranteed that 0 ≤ <var>newByteLength</var> ≤ <var>buffer</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>.</p>
|
||
</div></emu-note>
|
||
|
||
<p>The default implementation of HostGrowSharedArrayBuffer is to return <emu-xref aoid="NormalCompletion" id="_ref_14798"><a href="ecmascript-data-types-and-values.html#sec-normalcompletion">NormalCompletion</a></emu-xref>(<emu-const>unhandled</emu-const>).</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-sharedarraybuffer-constructor">
|
||
<h1><span class="secnum">25.2.3</span> The SharedArrayBuffer Constructor</h1>
|
||
<p>The SharedArrayBuffer <emu-xref href="#constructor" id="_ref_14799"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%SharedArrayBuffer%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"SharedArrayBuffer"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_14800"><a href="global-object.html#sec-global-object">global object</a></emu-xref>, if that property is present (see below).</li>
|
||
<li>creates and initializes a new SharedArrayBuffer when called as a <emu-xref href="#constructor" id="_ref_14801"><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 of an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_14802"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified SharedArrayBuffer behaviour must include a <code>super</code> call to the SharedArrayBuffer <emu-xref href="#constructor" id="_ref_14803"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize subclass instances with the internal state necessary to support the <code>SharedArrayBuffer.prototype</code> built-in methods.</li>
|
||
</ul>
|
||
|
||
<p>Whenever a <emu-xref href="#host" id="_ref_14804"><a href="overview.html#host">host</a></emu-xref> does not provide concurrent access to SharedArrayBuffers it may omit the <emu-val>"SharedArrayBuffer"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_14805"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</p>
|
||
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Unlike an <code>ArrayBuffer</code>, a <code>SharedArrayBuffer</code> cannot become detached, and its internal <var class="field">[[ArrayBufferData]]</var> slot is never <emu-val>null</emu-val>.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-sharedarraybuffer-length" type="built-in function">
|
||
<h1><span class="secnum">25.2.3.1</span> SharedArrayBuffer ( <var>length</var> [ , <var>options</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>Let <var>byteLength</var> be ? <emu-xref aoid="ToIndex" id="_ref_14806"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>length</var>).</li><li>Let <var>requestedMaxByteLength</var> be ? <emu-xref aoid="GetArrayBufferMaxByteLengthOption" id="_ref_14807"><a href="structured-data.html#sec-getarraybuffermaxbytelengthoption" class="e-user-code">GetArrayBufferMaxByteLengthOption</a></emu-xref>(<var>options</var>).</li><li>Return ? <emu-xref aoid="AllocateSharedArrayBuffer" id="_ref_14808"><a href="structured-data.html#sec-allocatesharedarraybuffer" class="e-user-code">AllocateSharedArrayBuffer</a></emu-xref>(NewTarget, <var>byteLength</var>, <var>requestedMaxByteLength</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-sharedarraybuffer-constructor">
|
||
<h1><span class="secnum">25.2.4</span> Properties of the SharedArrayBuffer Constructor</h1>
|
||
<p>The SharedArrayBuffer <emu-xref href="#constructor" id="_ref_14809"><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_14810"><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-sharedarraybuffer.prototype">
|
||
<h1><span class="secnum">25.2.4.1</span> SharedArrayBuffer.prototype</h1>
|
||
<p>The initial value of <code>SharedArrayBuffer.prototype</code> is the <emu-xref href="#sec-properties-of-the-sharedarraybuffer-prototype-object" id="_ref_14811"><a href="structured-data.html#sec-properties-of-the-sharedarraybuffer-prototype-object">SharedArrayBuffer 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 oldids="sec-sharedarraybuffer-@@species" id="sec-sharedarraybuffer-%symbol.species%" type="built-in function"><span id="sec-sharedarraybuffer-@@species"></span>
|
||
<h1><span class="secnum">25.2.4.2</span> get SharedArrayBuffer [ %Symbol.species% ]</h1>
|
||
<p><code>SharedArrayBuffer[%Symbol.species%]</code> is an <emu-xref href="#sec-object-type" id="_ref_14812"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return the <emu-val>this</emu-val> value.</li></ol></emu-alg>
|
||
<p>The value of the <emu-val>"name"</emu-val> property of this function is <emu-val>"get [Symbol.species]"</emu-val>.</p>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-sharedarraybuffer-prototype-object">
|
||
<h1><span class="secnum">25.2.5</span> Properties of the SharedArrayBuffer Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">SharedArrayBuffer prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%SharedArrayBuffer.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_14813"><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_14814"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>does not have an <var class="field">[[ArrayBufferData]]</var> or <var class="field">[[ArrayBufferByteLength]]</var> internal slot.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-get-sharedarraybuffer.prototype.bytelength" type="built-in function">
|
||
<h1><span class="secnum">25.2.5.1</span> get SharedArrayBuffer.prototype.byteLength</h1>
|
||
<p><code>SharedArrayBuffer.prototype.byteLength</code> is an <emu-xref href="#sec-object-type" id="_ref_14815"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14816"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14817"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>length</var> be <emu-xref aoid="ArrayBufferByteLength" id="_ref_14818"><a href="structured-data.html#sec-arraybufferbytelength">ArrayBufferByteLength</a></emu-xref>(<var>O</var>, <emu-const>seq-cst</emu-const>).</li><li>Return <emu-xref aoid="𝔽" id="_ref_14819"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>length</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-sharedarraybuffer.prototype.constructor">
|
||
<h1><span class="secnum">25.2.5.2</span> SharedArrayBuffer.prototype.constructor</h1>
|
||
<p>The initial value of <code>SharedArrayBuffer.prototype.constructor</code> is <emu-xref href="#sec-sharedarraybuffer-constructor" id="_ref_14820"><a href="structured-data.html#sec-sharedarraybuffer-constructor">%SharedArrayBuffer%</a></emu-xref>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-sharedarraybuffer.prototype.grow" type="built-in function">
|
||
<h1><span class="secnum">25.2.5.3</span> SharedArrayBuffer.prototype.grow ( <var>newLength</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14821"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferMaxByteLength]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14822"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>newByteLength</var> be ? <emu-xref aoid="ToIndex" id="_ref_14823"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>newLength</var>).</li><li>Let <var>hostHandled</var> be ? <emu-xref aoid="HostGrowSharedArrayBuffer" id="_ref_14824"><a href="structured-data.html#sec-hostgrowsharedarraybuffer">HostGrowSharedArrayBuffer</a></emu-xref>(<var>O</var>, <var>newByteLength</var>).</li><li>If <var>hostHandled</var> is <emu-const>handled</emu-const>, return <emu-val>undefined</emu-val>.</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_14825"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_14826"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li><li>Let <var>byteLengthBlock</var> be <var>O</var>.<var class="field">[[ArrayBufferByteLengthData]]</var>.</li><li>Let <var>currentByteLengthRawBytes</var> be <emu-xref aoid="GetRawBytesFromSharedBlock" id="_ref_14827"><a href="structured-data.html#sec-getrawbytesfromsharedblock">GetRawBytesFromSharedBlock</a></emu-xref>(<var>byteLengthBlock</var>, 0, <emu-const>biguint64</emu-const>, <emu-val>true</emu-val>, <emu-const>seq-cst</emu-const>).</li><li>Let <var>newByteLengthRawBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_14828"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<emu-const>biguint64</emu-const>, <emu-xref aoid="ℤ" id="_ref_14829"><a href="notational-conventions.html#%E2%84%A4">ℤ</a></emu-xref>(<var>newByteLength</var>), <var>isLittleEndian</var>).</li><li>Repeat,<ol><li>NOTE: This is a compare-and-exchange loop to ensure that parallel, racing grows of the same buffer are totally ordered, are not lost, and do not silently do nothing. The loop exits if it was able to attempt to grow uncontended.</li><li>Let <var>currentByteLength</var> be <emu-xref aoid="ℝ" id="_ref_14830"><a href="notational-conventions.html#%E2%84%9D">ℝ</a></emu-xref>(<emu-xref aoid="RawBytesToNumeric" id="_ref_14831"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<emu-const>biguint64</emu-const>, <var>currentByteLengthRawBytes</var>, <var>isLittleEndian</var>)).</li><li>If <var>newByteLength</var> = <var>currentByteLength</var>, return <emu-val>undefined</emu-val>.</li><li>If <var>newByteLength</var> < <var>currentByteLength</var> or <var>newByteLength</var> > <var>O</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Let <var>byteLengthDelta</var> be <var>newByteLength</var> - <var>currentByteLength</var>.</li><li>If it is impossible to create a new <emu-xref href="#sec-data-blocks" id="_ref_14832"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref> value consisting of <var>byteLengthDelta</var> bytes, throw a <emu-val>RangeError</emu-val> exception.</li><li>NOTE: No new <emu-xref href="#sec-data-blocks" id="_ref_14833"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref> is constructed and used here. The observable behaviour of growable SharedArrayBuffers is specified by allocating a <emu-xref aoid="max" id="_ref_14834"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>-sized <emu-xref href="#sec-data-blocks" id="_ref_14835"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref> at construction time, and this step captures the requirement that implementations that run out of memory must throw a <emu-val>RangeError</emu-val>.</li><li>Let <var>readByteLengthRawBytes</var> be <emu-xref aoid="AtomicCompareExchangeInSharedBlock" id="_ref_14836"><a href="structured-data.html#sec-atomiccompareexchangeinsharedblock">AtomicCompareExchangeInSharedBlock</a></emu-xref>(<var>byteLengthBlock</var>, 0, 8, <var>currentByteLengthRawBytes</var>, <var>newByteLengthRawBytes</var>).</li><li>If <emu-xref aoid="ByteListEqual" id="_ref_14837"><a href="structured-data.html#sec-bytelistequal">ByteListEqual</a></emu-xref>(<var>readByteLengthRawBytes</var>, <var>currentByteLengthRawBytes</var>) is <emu-val>true</emu-val>, return <emu-val>undefined</emu-val>.</li><li>Set <var>currentByteLengthRawBytes</var> to <var>readByteLengthRawBytes</var>.</li></ol></li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>Spurious failures of the compare-exchange to update the length are prohibited. If the bounds checking for the new length passes and the implementation is not out of memory, a <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14838"><a href="memory-model.html#sec-memory-model-fundamentals">ReadModifyWriteSharedMemory</a></emu-xref> event (i.e. a successful compare-exchange) is always added into the <emu-xref href="#sec-candidate-executions" id="_ref_14839"><a href="memory-model.html#sec-candidate-executions">candidate execution</a></emu-xref>.</p>
|
||
<p>Parallel calls to SharedArrayBuffer.prototype.grow are totally ordered. For example, consider two racing calls: <code>sab.grow(10)</code> and <code>sab.grow(20)</code>. One of the two calls is guaranteed to win the race. The call to <code>sab.grow(10)</code> will never shrink <code>sab</code> even if <code>sab.grow(20)</code> happened first; in that case it will instead throw a RangeError.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-sharedarraybuffer.prototype.growable" type="built-in function">
|
||
<h1><span class="secnum">25.2.5.4</span> get SharedArrayBuffer.prototype.growable</h1>
|
||
<p><code>SharedArrayBuffer.prototype.growable</code> is an <emu-xref href="#sec-object-type" id="_ref_14840"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14841"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14842"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14843"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-sharedarraybuffer.prototype.maxbytelength" type="built-in function">
|
||
<h1><span class="secnum">25.2.5.5</span> get SharedArrayBuffer.prototype.maxByteLength</h1>
|
||
<p><code>SharedArrayBuffer.prototype.maxByteLength</code> is an <emu-xref href="#sec-object-type" id="_ref_14844"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14845"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14846"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14847"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>length</var> be <var>O</var>.<var class="field">[[ArrayBufferByteLength]]</var>.</li></ol></li><li>Else,<ol><li>Let <var>length</var> be <var>O</var>.<var class="field">[[ArrayBufferMaxByteLength]]</var>.</li></ol></li><li>Return <emu-xref aoid="𝔽" id="_ref_14848"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>length</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-sharedarraybuffer.prototype.slice" type="built-in function">
|
||
<h1><span class="secnum">25.2.5.6</span> SharedArrayBuffer.prototype.slice ( <var>start</var>, <var>end</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14849"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14850"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>O</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>len</var> be <emu-xref aoid="ArrayBufferByteLength" id="_ref_14851"><a href="structured-data.html#sec-arraybufferbytelength">ArrayBufferByteLength</a></emu-xref>(<var>O</var>, <emu-const>seq-cst</emu-const>).</li><li>Let <var>relativeStart</var> be ? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_14852"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>start</var>).</li><li>If <var>relativeStart</var> = -∞, let <var>first</var> be 0.</li><li>Else if <var>relativeStart</var> < 0, let <var>first</var> be <emu-xref aoid="max" id="_ref_14853"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>len</var> + <var>relativeStart</var>, 0).</li><li>Else, let <var>first</var> be <emu-xref aoid="min" id="_ref_14854"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>relativeStart</var>, <var>len</var>).</li><li>If <var>end</var> is <emu-val>undefined</emu-val>, let <var>relativeEnd</var> be <var>len</var>; else let <var>relativeEnd</var> be ? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_14855"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>end</var>).</li><li>If <var>relativeEnd</var> = -∞, let <var>final</var> be 0.</li><li>Else if <var>relativeEnd</var> < 0, let <var>final</var> be <emu-xref aoid="max" id="_ref_14856"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>len</var> + <var>relativeEnd</var>, 0).</li><li>Else, let <var>final</var> be <emu-xref aoid="min" id="_ref_14857"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>relativeEnd</var>, <var>len</var>).</li><li>Let <var>newLen</var> be <emu-xref aoid="max" id="_ref_14858"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>final</var> - <var>first</var>, 0).</li><li>Let <var>ctor</var> be ? <emu-xref aoid="SpeciesConstructor" id="_ref_14859"><a href="abstract-operations.html#sec-speciesconstructor" class="e-user-code">SpeciesConstructor</a></emu-xref>(<var>O</var>, <emu-xref href="#sec-sharedarraybuffer-constructor" id="_ref_14860"><a href="structured-data.html#sec-sharedarraybuffer-constructor">%SharedArrayBuffer%</a></emu-xref>).</li><li>Let <var>new</var> be ? <emu-xref aoid="Construct" id="_ref_14861"><a href="abstract-operations.html#sec-construct" class="e-user-code">Construct</a></emu-xref>(<var>ctor</var>, « <emu-xref aoid="𝔽" id="_ref_14862"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>newLen</var>) »).</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14863"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>new</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_14864"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>new</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>new</var>.<var class="field">[[ArrayBufferData]]</var> is <var>O</var>.<var class="field">[[ArrayBufferData]]</var>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <emu-xref aoid="ArrayBufferByteLength" id="_ref_14865"><a href="structured-data.html#sec-arraybufferbytelength">ArrayBufferByteLength</a></emu-xref>(<var>new</var>, <emu-const>seq-cst</emu-const>) < <var>newLen</var>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>fromBuf</var> be <var>O</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>toBuf</var> be <var>new</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Perform <emu-xref aoid="CopyDataBlockBytes" id="_ref_14866"><a href="ecmascript-data-types-and-values.html#sec-copydatablockbytes">CopyDataBlockBytes</a></emu-xref>(<var>toBuf</var>, 0, <var>fromBuf</var>, <var>first</var>, <var>newLen</var>).</li><li>Return <var>new</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-sharedarraybuffer.prototype.toString,sec-sharedarraybuffer.prototype-@@tostringtag" id="sec-sharedarraybuffer.prototype-%symbol.tostringtag%"><span id="sec-sharedarraybuffer.prototype-@@tostringtag"></span><span id="sec-sharedarraybuffer.prototype.toString"></span>
|
||
<h1><span class="secnum">25.2.5.7</span> SharedArrayBuffer.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_14867"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"SharedArrayBuffer"</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-the-sharedarraybuffer-instances">
|
||
<h1><span class="secnum">25.2.6</span> Properties of SharedArrayBuffer Instances</h1>
|
||
<p>SharedArrayBuffer instances inherit properties from the <emu-xref href="#sec-properties-of-the-sharedarraybuffer-prototype-object" id="_ref_14868"><a href="structured-data.html#sec-properties-of-the-sharedarraybuffer-prototype-object">SharedArrayBuffer prototype object</a></emu-xref>. SharedArrayBuffer instances each have an <var class="field">[[ArrayBufferData]]</var> internal slot. SharedArrayBuffer instances which are not growable each have an <var class="field">[[ArrayBufferByteLength]]</var> internal slot. SharedArrayBuffer instances which are growable each have an <var class="field">[[ArrayBufferByteLengthData]]</var> internal slot and an <var class="field">[[ArrayBufferMaxByteLength]]</var> internal slot.</p>
|
||
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>SharedArrayBuffer instances, unlike ArrayBuffer instances, are never detached.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-growable-sharedarraybuffer-guidelines">
|
||
<h1><span class="secnum">25.2.7</span> Growable SharedArrayBuffer Guidelines</h1>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>The following are guidelines for ECMAScript programmers working with <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14869"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</p>
|
||
<p>We recommend that programs be tested in their deployment environments where possible. The amount of available physical memory differ greatly between hardware devices. Similarly, virtual memory subsystems also differ greatly between hardware devices as well as operating systems. An application that runs without out-of-memory errors on a 64-bit desktop web browser could run out of memory on a 32-bit mobile web browser.</p>
|
||
<p>When choosing a value for the <emu-val>"maxByteLength"</emu-val> option for <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14870"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>, we recommend that the smallest possible size for the application be chosen. We recommend that <emu-val>"maxByteLength"</emu-val> does not exceed 1073741824, or 1GiB.</p>
|
||
<p>Please note that successfully constructing a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14871"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref> for a particular maximum size does not guarantee that future grows will succeed.</p>
|
||
<p>Not all loads of a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14872"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>'s length are synchronizing <emu-const>seq-cst</emu-const> loads. Loads of the length that are for bounds-checking of an <emu-xref href="#integer-index" id="_ref_14873"><a href="ecmascript-data-types-and-values.html#integer-index">integer-indexed</a></emu-xref> property access, e.g. <code>u8[idx]</code>, are not synchronizing. In general, in the absence of explicit synchronization, one property access being in-bound does not imply a subsequent property access in the same <emu-xref href="#agent" id="_ref_14874"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> is also in-bound. In contrast, explicit loads of the length via the <code>length</code> and <code>byteLength</code> getters on SharedArrayBuffer, <emu-xref href="#sec-%typedarray%-intrinsic-object" id="_ref_14875"><a href="indexed-collections.html#sec-%typedarray%-intrinsic-object">%TypedArray%</a></emu-xref>.prototype, and DataView.prototype are synchronizing. Loads of the length that are performed by built-in methods to check if a <emu-xref href="#typedarray" id="_ref_14876"><a href="ordinary-and-exotic-objects-behaviours.html#typedarray">TypedArray</a></emu-xref> is entirely out-of-bounds are also synchronizing.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>The following are guidelines for ECMAScript implementers implementing <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14877"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</p>
|
||
<p>We recommend <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14878"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref> be implemented as in-place growth via reserving virtual memory up front.</p>
|
||
<p>Because grow operations can happen in parallel with memory accesses on a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14879"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>, the constraints of the <emu-xref href="#sec-memory-model" id="_ref_14880"><a href="memory-model.html#sec-memory-model">memory model</a></emu-xref> require that even unordered accesses do not "tear" (bits of their values will not be mixed). In practice, this means the underlying data block of a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14881"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref> cannot be grown by being copied without stopping the world. We do not recommend stopping the world as an implementation strategy because it introduces a serialization point and is slow.</p>
|
||
<p>Grown memory must appear zeroed from the moment of its creation, including to any racy accesses in parallel. This can be accomplished via zero-filled-on-demand virtual memory pages, or careful synchronization if manually zeroing memory.</p>
|
||
<p><emu-xref href="#integer-index" id="_ref_14882"><a href="ecmascript-data-types-and-values.html#integer-index">Integer-indexed</a></emu-xref> property access on <emu-xref href="#typedarray" id="_ref_14883"><a href="ordinary-and-exotic-objects-behaviours.html#typedarray">TypedArray</a></emu-xref> views of growable SharedArrayBuffers is intended to be optimizable similarly to access on <emu-xref href="#typedarray" id="_ref_14884"><a href="ordinary-and-exotic-objects-behaviours.html#typedarray">TypedArray</a></emu-xref> views of non-growable SharedArrayBuffers, because <emu-xref href="#integer-index" id="_ref_14885"><a href="ecmascript-data-types-and-values.html#integer-index">integer-indexed</a></emu-xref> property loads on are not synchronizing on the underlying buffer's length (see programmer guidelines above). For example, bounds checks for property accesses may still be hoisted out of loops.</p>
|
||
<p>In practice it is difficult to implement <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14886"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref> by copying on <emu-xref href="#host" id="_ref_14887"><a href="overview.html#host">hosts</a></emu-xref> that do not have virtual memory, such as those running on embedded devices without an MMU. Memory usage behaviour of growable SharedArrayBuffers on such <emu-xref href="#host" id="_ref_14888"><a href="overview.html#host">hosts</a></emu-xref> may significantly differ from that of <emu-xref href="#host" id="_ref_14889"><a href="overview.html#host">hosts</a></emu-xref> with virtual memory. Such <emu-xref href="#host" id="_ref_14890"><a href="overview.html#host">hosts</a></emu-xref> should clearly communicate memory usage expectations to users.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview-objects">
|
||
<h1><span class="secnum">25.3</span> DataView Objects</h1>
|
||
|
||
<emu-clause id="sec-abstract-operations-for-dataview-objects">
|
||
<h1><span class="secnum">25.3.1</span> Abstract Operations For DataView Objects</h1>
|
||
|
||
<emu-clause id="sec-dataview-with-buffer-witness-records">
|
||
<h1><span class="secnum">25.3.1.1</span> DataView With Buffer Witness Records</h1>
|
||
<p>A <dfn variants="DataView With Buffer Witness Records" tabindex="-1">DataView With Buffer Witness Record</dfn> is a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14891"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> value used to encapsulate a DataView along with a cached byte length of the viewed buffer. It is used to help ensure there is a single <emu-xref href="#sec-memory-model-fundamentals" id="_ref_14892"><a href="memory-model.html#sec-memory-model-fundamentals">ReadSharedMemory</a></emu-xref> event of the byte length data block when the viewed buffer is a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14893"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</p>
|
||
<p>DataView With Buffer Witness Records have the fields listed in <emu-xref href="#table-dataview-with-buffer-witness-record-fields" id="_ref_803"><a href="structured-data.html#table-dataview-with-buffer-witness-record-fields">Table 72</a></emu-xref>.</p>
|
||
<emu-table id="table-dataview-with-buffer-witness-record-fields" caption="DataView With Buffer Witness Record Fields"><figure><figcaption>Table 72: <emu-xref href="#sec-dataview-with-buffer-witness-records" id="_ref_14894"><a href="structured-data.html#sec-dataview-with-buffer-witness-records">DataView With Buffer Witness Record</a></emu-xref> Fields</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Field Name
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Meaning
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[Object]]</var>
|
||
</td>
|
||
<td>
|
||
a DataView
|
||
</td>
|
||
<td>
|
||
The DataView object whose buffer's byte length is loaded.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[CachedBufferByteLength]]</var>
|
||
</td>
|
||
<td>
|
||
a non-negative <emu-xref href="#integer" id="_ref_14895"><a href="notational-conventions.html#integer">integer</a></emu-xref> or <emu-const>detached</emu-const>
|
||
</td>
|
||
<td>
|
||
The byte length of the object's <var class="field">[[ViewedArrayBuffer]]</var> when the <emu-xref href="#sec-list-and-record-specification-type" id="_ref_14896"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> was created.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-makedataviewwithbufferwitnessrecord" type="abstract operation" aoid="MakeDataViewWithBufferWitnessRecord">
|
||
<h1><span class="secnum">25.3.1.2</span> MakeDataViewWithBufferWitnessRecord ( <var>obj</var>, <var>order</var> )</h1>
|
||
<p>The abstract operation MakeDataViewWithBufferWitnessRecord takes arguments <var>obj</var> (a DataView) and <var>order</var> (<emu-const>seq-cst</emu-const> or <emu-const>unordered</emu-const>) and returns a <emu-xref href="#sec-dataview-with-buffer-witness-records" id="_ref_14897"><a href="structured-data.html#sec-dataview-with-buffer-witness-records">DataView With Buffer Witness Record</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>buffer</var> be <var>obj</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14898"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>buffer</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>byteLength</var> be <emu-const>detached</emu-const>.</li></ol></li><li>Else,<ol><li>Let <var>byteLength</var> be <emu-xref aoid="ArrayBufferByteLength" id="_ref_14899"><a href="structured-data.html#sec-arraybufferbytelength">ArrayBufferByteLength</a></emu-xref>(<var>buffer</var>, <var>order</var>).</li></ol></li><li>Return the <emu-xref href="#sec-dataview-with-buffer-witness-records" id="_ref_14900"><a href="structured-data.html#sec-dataview-with-buffer-witness-records">DataView With Buffer Witness Record</a></emu-xref> { <var class="field">[[Object]]</var>: <var>obj</var>, <var class="field">[[CachedBufferByteLength]]</var>: <var>byteLength</var> }.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getviewbytelength" type="abstract operation" aoid="GetViewByteLength">
|
||
<h1><span class="secnum">25.3.1.3</span> GetViewByteLength ( <var>viewRecord</var> )</h1>
|
||
<p>The abstract operation GetViewByteLength takes argument <var>viewRecord</var> (a <emu-xref href="#sec-dataview-with-buffer-witness-records" id="_ref_14901"><a href="structured-data.html#sec-dataview-with-buffer-witness-records">DataView With Buffer Witness Record</a></emu-xref>) and returns a non-negative <emu-xref href="#integer" id="_ref_14902"><a href="notational-conventions.html#integer">integer</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_14903"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsViewOutOfBounds" id="_ref_14904"><a href="structured-data.html#sec-isviewoutofbounds">IsViewOutOfBounds</a></emu-xref>(<var>viewRecord</var>) is <emu-val>false</emu-val>.</li><li>Let <var>view</var> be <var>viewRecord</var>.<var class="field">[[Object]]</var>.</li><li>If <var>view</var>.<var class="field">[[ByteLength]]</var> is not <emu-const>auto</emu-const>, return <var>view</var>.<var class="field">[[ByteLength]]</var>.</li><li><emu-xref href="#assert" id="_ref_14905"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14906"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>view</var>.<var class="field">[[ViewedArrayBuffer]]</var>) is <emu-val>false</emu-val>.</li><li>Let <var>byteOffset</var> be <var>view</var>.<var class="field">[[ByteOffset]]</var>.</li><li>Let <var>byteLength</var> be <var>viewRecord</var>.<var class="field">[[CachedBufferByteLength]]</var>.</li><li><emu-xref href="#assert" id="_ref_14907"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>byteLength</var> is not <emu-const>detached</emu-const>.</li><li>Return <var>byteLength</var> - <var>byteOffset</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-isviewoutofbounds" type="abstract operation" aoid="IsViewOutOfBounds">
|
||
<h1><span class="secnum">25.3.1.4</span> IsViewOutOfBounds ( <var>viewRecord</var> )</h1>
|
||
<p>The abstract operation IsViewOutOfBounds takes argument <var>viewRecord</var> (a <emu-xref href="#sec-dataview-with-buffer-witness-records" id="_ref_14908"><a href="structured-data.html#sec-dataview-with-buffer-witness-records">DataView With Buffer Witness Record</a></emu-xref>) and returns a Boolean. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be <var>viewRecord</var>.<var class="field">[[Object]]</var>.</li><li>Let <var>bufferByteLength</var> be <var>viewRecord</var>.<var class="field">[[CachedBufferByteLength]]</var>.</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14909"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>view</var>.<var class="field">[[ViewedArrayBuffer]]</var>) is <emu-val>true</emu-val>, then<ol><li><emu-xref href="#assert" id="_ref_14910"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>bufferByteLength</var> is <emu-const>detached</emu-const>.</li><li>Return <emu-val>true</emu-val>.</li></ol></li><li><emu-xref href="#assert" id="_ref_14911"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>bufferByteLength</var> is a non-negative <emu-xref href="#integer" id="_ref_14912"><a href="notational-conventions.html#integer">integer</a></emu-xref>.</li><li>Let <var>byteOffsetStart</var> be <var>view</var>.<var class="field">[[ByteOffset]]</var>.</li><li>If <var>view</var>.<var class="field">[[ByteLength]]</var> is <emu-const>auto</emu-const>, then<ol><li>Let <var>byteOffsetEnd</var> be <var>bufferByteLength</var>.</li></ol></li><li>Else,<ol><li>Let <var>byteOffsetEnd</var> be <var>byteOffsetStart</var> + <var>view</var>.<var class="field">[[ByteLength]]</var>.</li></ol></li><li>NOTE: A 0-length DataView whose <var class="field">[[ByteOffset]]</var> is <var>bufferByteLength</var> is not considered out-of-bounds.</li><li>If <var>byteOffsetStart</var> > <var>bufferByteLength</var> or <var>byteOffsetEnd</var> > <var>bufferByteLength</var>, return <emu-val>true</emu-val>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getviewvalue" type="abstract operation" aoid="GetViewValue">
|
||
<h1><span class="secnum">25.3.1.5</span> GetViewValue ( <var>view</var>, <var>requestIndex</var>, <var>isLittleEndian</var>, <var>type</var> )</h1>
|
||
<p>The abstract operation GetViewValue takes arguments <var>view</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14913"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>requestIndex</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14914"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>isLittleEndian</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14915"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), and <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14916"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14917"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either a Number or a BigInt, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14918"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It is used by functions on DataView instances to retrieve values from the view's buffer. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14919"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>view</var>, <var class="field">[[DataView]]</var>).</li><li><emu-xref href="#assert" id="_ref_14920"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>view</var> has a <var class="field">[[ViewedArrayBuffer]]</var> internal slot.</li><li>Let <var>getIndex</var> be ? <emu-xref aoid="ToIndex" id="_ref_14921"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>requestIndex</var>).</li><li>Set <var>isLittleEndian</var> to <emu-xref aoid="ToBoolean" id="_ref_14922"><a href="abstract-operations.html#sec-toboolean">ToBoolean</a></emu-xref>(<var>isLittleEndian</var>).</li><li>Let <var>viewOffset</var> be <var>view</var>.<var class="field">[[ByteOffset]]</var>.</li><li>Let <var>viewRecord</var> be <emu-xref aoid="MakeDataViewWithBufferWitnessRecord" id="_ref_14923"><a href="structured-data.html#sec-makedataviewwithbufferwitnessrecord">MakeDataViewWithBufferWitnessRecord</a></emu-xref>(<var>view</var>, <emu-const>unordered</emu-const>).</li><li>NOTE: Bounds checking is not a synchronizing operation when <var>view</var>'s backing buffer is a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14924"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</li><li>If <emu-xref aoid="IsViewOutOfBounds" id="_ref_14925"><a href="structured-data.html#sec-isviewoutofbounds">IsViewOutOfBounds</a></emu-xref>(<var>viewRecord</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>viewSize</var> be <emu-xref aoid="GetViewByteLength" id="_ref_14926"><a href="structured-data.html#sec-getviewbytelength">GetViewByteLength</a></emu-xref>(<var>viewRecord</var>).</li><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_804"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>If <var>getIndex</var> + <var>elementSize</var> > <var>viewSize</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Let <var>bufferIndex</var> be <var>getIndex</var> + <var>viewOffset</var>.</li><li>Return <emu-xref aoid="GetValueFromBuffer" id="_ref_14927"><a href="structured-data.html#sec-getvaluefrombuffer">GetValueFromBuffer</a></emu-xref>(<var>view</var>.<var class="field">[[ViewedArrayBuffer]]</var>, <var>bufferIndex</var>, <var>type</var>, <emu-val>false</emu-val>, <emu-const>unordered</emu-const>, <var>isLittleEndian</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-setviewvalue" type="abstract operation" aoid="SetViewValue">
|
||
<h1><span class="secnum">25.3.1.6</span> SetViewValue ( <var>view</var>, <var>requestIndex</var>, <var>isLittleEndian</var>, <var>type</var>, <var>value</var> )</h1>
|
||
<p>The abstract operation SetViewValue takes arguments <var>view</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14928"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>requestIndex</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14929"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>isLittleEndian</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14930"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>type</var> (a <emu-xref href="#sec-typedarray-objects" id="_ref_14931"><a href="indexed-collections.html#sec-typedarray-objects">TypedArray element type</a></emu-xref>), and <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_14932"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14933"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> <emu-val>undefined</emu-val> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_14934"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It is used by functions on DataView instances to store values into the view's buffer. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14935"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>view</var>, <var class="field">[[DataView]]</var>).</li><li><emu-xref href="#assert" id="_ref_14936"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>view</var> has a <var class="field">[[ViewedArrayBuffer]]</var> internal slot.</li><li>Let <var>getIndex</var> be ? <emu-xref aoid="ToIndex" id="_ref_14937"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>requestIndex</var>).</li><li>If <emu-xref aoid="IsBigIntElementType" id="_ref_14938"><a href="structured-data.html#sec-isbigintelementtype">IsBigIntElementType</a></emu-xref>(<var>type</var>) is <emu-val>true</emu-val>, let <var>numberValue</var> be ? <emu-xref aoid="ToBigInt" id="_ref_14939"><a href="abstract-operations.html#sec-tobigint" class="e-user-code">ToBigInt</a></emu-xref>(<var>value</var>).</li><li>Else, let <var>numberValue</var> be ? <emu-xref aoid="ToNumber" id="_ref_14940"><a href="abstract-operations.html#sec-tonumber" class="e-user-code">ToNumber</a></emu-xref>(<var>value</var>).</li><li>Set <var>isLittleEndian</var> to <emu-xref aoid="ToBoolean" id="_ref_14941"><a href="abstract-operations.html#sec-toboolean">ToBoolean</a></emu-xref>(<var>isLittleEndian</var>).</li><li>Let <var>viewOffset</var> be <var>view</var>.<var class="field">[[ByteOffset]]</var>.</li><li>Let <var>viewRecord</var> be <emu-xref aoid="MakeDataViewWithBufferWitnessRecord" id="_ref_14942"><a href="structured-data.html#sec-makedataviewwithbufferwitnessrecord">MakeDataViewWithBufferWitnessRecord</a></emu-xref>(<var>view</var>, <emu-const>unordered</emu-const>).</li><li>NOTE: Bounds checking is not a synchronizing operation when <var>view</var>'s backing buffer is a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_14943"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</li><li>If <emu-xref aoid="IsViewOutOfBounds" id="_ref_14944"><a href="structured-data.html#sec-isviewoutofbounds">IsViewOutOfBounds</a></emu-xref>(<var>viewRecord</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>viewSize</var> be <emu-xref aoid="GetViewByteLength" id="_ref_14945"><a href="structured-data.html#sec-getviewbytelength">GetViewByteLength</a></emu-xref>(<var>viewRecord</var>).</li><li>Let <var>elementSize</var> be the Element Size value specified in <emu-xref href="#table-the-typedarray-constructors" id="_ref_805"><a href="indexed-collections.html#table-the-typedarray-constructors">Table 70</a></emu-xref> for Element Type <var>type</var>.</li><li>If <var>getIndex</var> + <var>elementSize</var> > <var>viewSize</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Let <var>bufferIndex</var> be <var>getIndex</var> + <var>viewOffset</var>.</li><li>Perform <emu-xref aoid="SetValueInBuffer" id="_ref_14946"><a href="structured-data.html#sec-setvalueinbuffer">SetValueInBuffer</a></emu-xref>(<var>view</var>.<var class="field">[[ViewedArrayBuffer]]</var>, <var>bufferIndex</var>, <var>type</var>, <var>numberValue</var>, <emu-val>false</emu-val>, <emu-const>unordered</emu-const>, <var>isLittleEndian</var>).</li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview-constructor">
|
||
<h1><span class="secnum">25.3.2</span> The DataView Constructor</h1>
|
||
<p>The DataView <emu-xref href="#constructor" id="_ref_14947"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%DataView%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"DataView"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_14948"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</li>
|
||
<li>creates and initializes a new DataView when called as a <emu-xref href="#constructor" id="_ref_14949"><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 of an <code>extends</code> clause of a class definition. Subclass <emu-xref href="#constructor" id="_ref_14950"><a href="ecmascript-data-types-and-values.html#constructor">constructors</a></emu-xref> that intend to inherit the specified DataView behaviour must include a <code>super</code> call to the DataView <emu-xref href="#constructor" id="_ref_14951"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> to create and initialize subclass instances with the internal state necessary to support the <code>DataView.prototype</code> built-in methods.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-dataview-buffer-byteoffset-bytelength" type="built-in function">
|
||
<h1><span class="secnum">25.3.2.1</span> DataView ( <var>buffer</var> [ , <var>byteOffset</var> [ , <var>byteLength</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>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14952"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>buffer</var>, <var class="field">[[ArrayBufferData]]</var>).</li><li>Let <var>offset</var> be ? <emu-xref aoid="ToIndex" id="_ref_14953"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>byteOffset</var>).</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14954"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>buffer</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>bufferByteLength</var> be <emu-xref aoid="ArrayBufferByteLength" id="_ref_14955"><a href="structured-data.html#sec-arraybufferbytelength">ArrayBufferByteLength</a></emu-xref>(<var>buffer</var>, <emu-const>seq-cst</emu-const>).</li><li>If <var>offset</var> > <var>bufferByteLength</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Let <var>bufferIsFixedLength</var> be <emu-xref aoid="IsFixedLengthArrayBuffer" id="_ref_14956"><a href="structured-data.html#sec-isfixedlengtharraybuffer">IsFixedLengthArrayBuffer</a></emu-xref>(<var>buffer</var>).</li><li>If <var>byteLength</var> is <emu-val>undefined</emu-val>, then<ol><li>If <var>bufferIsFixedLength</var> is <emu-val>true</emu-val>, then<ol><li>Let <var>viewByteLength</var> be <var>bufferByteLength</var> - <var>offset</var>.</li></ol></li><li>Else,<ol><li>Let <var>viewByteLength</var> be <emu-const>auto</emu-const>.</li></ol></li></ol></li><li>Else,<ol><li>Let <var>viewByteLength</var> be ? <emu-xref aoid="ToIndex" id="_ref_14957"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>byteLength</var>).</li><li>If <var>offset</var> + <var>viewByteLength</var> > <var>bufferByteLength</var>, throw a <emu-val>RangeError</emu-val> exception.</li></ol></li><li>Let <var>O</var> be ? <emu-xref aoid="OrdinaryCreateFromConstructor" id="_ref_14958"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinarycreatefromconstructor" class="e-user-code">OrdinaryCreateFromConstructor</a></emu-xref>(NewTarget, <emu-val>"%DataView.prototype%"</emu-val>, « <var class="field">[[DataView]]</var>, <var class="field">[[ViewedArrayBuffer]]</var>, <var class="field">[[ByteLength]]</var>, <var class="field">[[ByteOffset]]</var> »).</li><li>If <emu-xref aoid="IsDetachedBuffer" id="_ref_14959"><a href="structured-data.html#sec-isdetachedbuffer">IsDetachedBuffer</a></emu-xref>(<var>buffer</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Set <var>bufferByteLength</var> to <emu-xref aoid="ArrayBufferByteLength" id="_ref_14960"><a href="structured-data.html#sec-arraybufferbytelength">ArrayBufferByteLength</a></emu-xref>(<var>buffer</var>, <emu-const>seq-cst</emu-const>).</li><li>If <var>offset</var> > <var>bufferByteLength</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>If <var>byteLength</var> is not <emu-val>undefined</emu-val>, then<ol><li>If <var>offset</var> + <var>viewByteLength</var> > <var>bufferByteLength</var>, throw a <emu-val>RangeError</emu-val> exception.</li></ol></li><li>Set <var>O</var>.<var class="field">[[ViewedArrayBuffer]]</var> to <var>buffer</var>.</li><li>Set <var>O</var>.<var class="field">[[ByteLength]]</var> to <var>viewByteLength</var>.</li><li>Set <var>O</var>.<var class="field">[[ByteOffset]]</var> to <var>offset</var>.</li><li>Return <var>O</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-properties-of-the-dataview-constructor">
|
||
<h1><span class="secnum">25.3.3</span> Properties of the DataView Constructor</h1>
|
||
<p>The DataView <emu-xref href="#constructor" id="_ref_14961"><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_14962"><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-dataview.prototype">
|
||
<h1><span class="secnum">25.3.3.1</span> DataView.prototype</h1>
|
||
<p>The initial value of <code>DataView.prototype</code> is the <emu-xref href="#sec-properties-of-the-dataview-prototype-object" id="_ref_14963"><a href="structured-data.html#sec-properties-of-the-dataview-prototype-object">DataView 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-dataview-prototype-object">
|
||
<h1><span class="secnum">25.3.4</span> Properties of the DataView Prototype Object</h1>
|
||
<p>The <dfn tabindex="-1">DataView prototype object</dfn>:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%DataView.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_14964"><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_14965"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>does not have a <var class="field">[[DataView]]</var>, <var class="field">[[ViewedArrayBuffer]]</var>, <var class="field">[[ByteLength]]</var>, or <var class="field">[[ByteOffset]]</var> internal slot.</li>
|
||
</ul>
|
||
|
||
<emu-clause id="sec-get-dataview.prototype.buffer" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.1</span> get DataView.prototype.buffer</h1>
|
||
<p><code>DataView.prototype.buffer</code> is an <emu-xref href="#sec-object-type" id="_ref_14966"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14967"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[DataView]]</var>).</li><li><emu-xref href="#assert" id="_ref_14968"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> has a <var class="field">[[ViewedArrayBuffer]]</var> internal slot.</li><li>Let <var>buffer</var> be <var>O</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>Return <var>buffer</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-dataview.prototype.bytelength" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.2</span> get DataView.prototype.byteLength</h1>
|
||
<p><code>DataView.prototype.byteLength</code> is an <emu-xref href="#sec-object-type" id="_ref_14969"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14970"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[DataView]]</var>).</li><li><emu-xref href="#assert" id="_ref_14971"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> has a <var class="field">[[ViewedArrayBuffer]]</var> internal slot.</li><li>Let <var>viewRecord</var> be <emu-xref aoid="MakeDataViewWithBufferWitnessRecord" id="_ref_14972"><a href="structured-data.html#sec-makedataviewwithbufferwitnessrecord">MakeDataViewWithBufferWitnessRecord</a></emu-xref>(<var>O</var>, <emu-const>seq-cst</emu-const>).</li><li>If <emu-xref aoid="IsViewOutOfBounds" id="_ref_14973"><a href="structured-data.html#sec-isviewoutofbounds">IsViewOutOfBounds</a></emu-xref>(<var>viewRecord</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>size</var> be <emu-xref aoid="GetViewByteLength" id="_ref_14974"><a href="structured-data.html#sec-getviewbytelength">GetViewByteLength</a></emu-xref>(<var>viewRecord</var>).</li><li>Return <emu-xref aoid="𝔽" id="_ref_14975"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>size</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-get-dataview.prototype.byteoffset" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.3</span> get DataView.prototype.byteOffset</h1>
|
||
<p><code>DataView.prototype.byteOffset</code> is an <emu-xref href="#sec-object-type" id="_ref_14976"><a href="ecmascript-data-types-and-values.html#sec-object-type">accessor property</a></emu-xref> whose set accessor function is <emu-val>undefined</emu-val>. Its get accessor function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>O</var> be the <emu-val>this</emu-val> value.</li><li>Perform ? <emu-xref aoid="RequireInternalSlot" id="_ref_14977"><a href="ordinary-and-exotic-objects-behaviours.html#sec-requireinternalslot">RequireInternalSlot</a></emu-xref>(<var>O</var>, <var class="field">[[DataView]]</var>).</li><li><emu-xref href="#assert" id="_ref_14978"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>O</var> has a <var class="field">[[ViewedArrayBuffer]]</var> internal slot.</li><li>Let <var>viewRecord</var> be <emu-xref aoid="MakeDataViewWithBufferWitnessRecord" id="_ref_14979"><a href="structured-data.html#sec-makedataviewwithbufferwitnessrecord">MakeDataViewWithBufferWitnessRecord</a></emu-xref>(<var>O</var>, <emu-const>seq-cst</emu-const>).</li><li>If <emu-xref aoid="IsViewOutOfBounds" id="_ref_14980"><a href="structured-data.html#sec-isviewoutofbounds">IsViewOutOfBounds</a></emu-xref>(<var>viewRecord</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>offset</var> be <var>O</var>.<var class="field">[[ByteOffset]]</var>.</li><li>Return <emu-xref aoid="𝔽" id="_ref_14981"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>offset</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.constructor">
|
||
<h1><span class="secnum">25.3.4.4</span> DataView.prototype.constructor</h1>
|
||
<p>The initial value of <code>DataView.prototype.constructor</code> is <emu-xref href="#sec-dataview-constructor" id="_ref_14982"><a href="structured-data.html#sec-dataview-constructor">%DataView%</a></emu-xref>.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getbigint64" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.5</span> DataView.prototype.getBigInt64 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14983"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>bigint64</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getbiguint64" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.6</span> DataView.prototype.getBigUint64 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14984"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>biguint64</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getfloat16" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.7</span> DataView.prototype.getFloat16 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14985"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>float16</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getfloat32" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.8</span> DataView.prototype.getFloat32 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14986"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>float32</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getfloat64" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.9</span> DataView.prototype.getFloat64 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14987"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>float64</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getint8" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.10</span> DataView.prototype.getInt8 ( <var>byteOffset</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14988"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <emu-val>true</emu-val>, <emu-const>int8</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getint16" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.11</span> DataView.prototype.getInt16 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14989"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>int16</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getint32" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.12</span> DataView.prototype.getInt32 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14990"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>int32</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getuint8" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.13</span> DataView.prototype.getUint8 ( <var>byteOffset</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14991"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <emu-val>true</emu-val>, <emu-const>uint8</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getuint16" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.14</span> DataView.prototype.getUint16 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14992"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>uint16</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.getuint32" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.15</span> DataView.prototype.getUint32 ( <var>byteOffset</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="GetViewValue" id="_ref_14993"><a href="structured-data.html#sec-getviewvalue" class="e-user-code">GetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>uint32</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setbigint64" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.16</span> DataView.prototype.setBigInt64 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_14994"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>bigint64</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setbiguint64" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.17</span> DataView.prototype.setBigUint64 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_14995"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>biguint64</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setfloat16" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.18</span> DataView.prototype.setFloat16 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_14996"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>float16</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setfloat32" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.19</span> DataView.prototype.setFloat32 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_14997"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>float32</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setfloat64" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.20</span> DataView.prototype.setFloat64 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_14998"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>float64</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setint8" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.21</span> DataView.prototype.setInt8 ( <var>byteOffset</var>, <var>value</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_14999"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <emu-val>true</emu-val>, <emu-const>int8</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setint16" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.22</span> DataView.prototype.setInt16 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_15000"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>int16</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setint32" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.23</span> DataView.prototype.setInt32 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_15001"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>int32</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setuint8" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.24</span> DataView.prototype.setUint8 ( <var>byteOffset</var>, <var>value</var> )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_15002"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <emu-val>true</emu-val>, <emu-const>uint8</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setuint16" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.25</span> DataView.prototype.setUint16 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_15003"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>uint16</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dataview.prototype.setuint32" type="built-in function">
|
||
<h1><span class="secnum">25.3.4.26</span> DataView.prototype.setUint32 ( <var>byteOffset</var>, <var>value</var> [ , <var>littleEndian</var> ] )</h1>
|
||
<p>This method performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>view</var> be the <emu-val>this</emu-val> value.</li><li>If <var>littleEndian</var> is not present, set <var>littleEndian</var> to <emu-val>false</emu-val>.</li><li>Return ? <emu-xref aoid="SetViewValue" id="_ref_15004"><a href="structured-data.html#sec-setviewvalue" class="e-user-code">SetViewValue</a></emu-xref>(<var>view</var>, <var>byteOffset</var>, <var>littleEndian</var>, <emu-const>uint32</emu-const>, <var>value</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-dataview.prototype-@@tostringtag" id="sec-dataview.prototype-%symbol.tostringtag%"><span id="sec-dataview.prototype-@@tostringtag"></span>
|
||
<h1><span class="secnum">25.3.4.27</span> DataView.prototype [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_15005"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"DataView"</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-dataview-instances">
|
||
<h1><span class="secnum">25.3.5</span> Properties of DataView Instances</h1>
|
||
<p>DataView instances are <emu-xref href="#ordinary-object" id="_ref_15006"><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-dataview-prototype-object" id="_ref_15007"><a href="structured-data.html#sec-properties-of-the-dataview-prototype-object">DataView prototype object</a></emu-xref>. DataView instances each have <var class="field">[[DataView]]</var>, <var class="field">[[ViewedArrayBuffer]]</var>, <var class="field">[[ByteLength]]</var>, and <var class="field">[[ByteOffset]]</var> internal slots.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>The value of the <var class="field">[[DataView]]</var> internal slot is not used within this specification. The simple presence of that internal slot is used within the specification to identify objects created using the DataView <emu-xref href="#constructor" id="_ref_15008"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics-object">
|
||
<h1><span class="secnum">25.4</span> The Atomics Object</h1>
|
||
<p>The Atomics object:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%Atomics%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"Atomics"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_15009"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15010"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</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_15011"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.</li>
|
||
<li>does not have a <var class="field">[[Construct]]</var> internal method; it cannot be used as a <emu-xref href="#constructor" id="_ref_15012"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> with the <code>new</code> operator.</li>
|
||
<li>does not have a <var class="field">[[Call]]</var> internal method; it cannot be invoked as a function.</li>
|
||
</ul>
|
||
<p>The Atomics object provides functions that operate indivisibly (atomically) on shared memory array cells as well as functions that let <emu-xref href="#agent" id="_ref_15013"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref> wait for and dispatch primitive events. When used with discipline, the Atomics functions allow multi-<emu-xref href="#agent" id="_ref_15014"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> programs that communicate through shared memory to execute in a well-understood order even on parallel CPUs. The rules that govern shared-memory communication are provided by the <emu-xref href="#sec-memory-model" id="_ref_15015"><a href="memory-model.html#sec-memory-model">memory model</a></emu-xref>, defined below.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>For informative guidelines for programming and implementing shared memory in ECMAScript, please see the notes at the end of the <emu-xref href="#sec-memory-model" id="_ref_15016"><a href="memory-model.html#sec-memory-model">memory model</a></emu-xref> section.</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-waiter-record">
|
||
<h1><span class="secnum">25.4.1</span> Waiter Record</h1>
|
||
<p>A <dfn variants="Waiter Records" tabindex="-1">Waiter Record</dfn> is a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15017"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> value used to denote a particular call to <code>Atomics.wait</code> or <code>Atomics.waitAsync</code>.</p>
|
||
<p>A Waiter Record has fields listed in <emu-xref href="#table-waiterrecord" id="_ref_806"><a href="structured-data.html#table-waiterrecord">Table 73</a></emu-xref>.</p>
|
||
<emu-table id="table-waiterrecord" caption="Waiter Record Fields"><figure><figcaption>Table 73: <emu-xref href="#sec-waiter-record" id="_ref_15018"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref> Fields</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Field Name
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Meaning
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[AgentSignifier]]</var>
|
||
</td>
|
||
<td>
|
||
an <emu-xref href="#sec-agents" id="_ref_15019"><a href="executable-code-and-execution-contexts.html#sec-agents">agent signifier</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The <emu-xref href="#agent" id="_ref_15020"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> that called <code>Atomics.wait</code> or <code>Atomics.waitAsync</code>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[PromiseCapability]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-promisecapability-records" id="_ref_15021"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref> or <emu-const>blocking</emu-const>
|
||
</td>
|
||
<td>
|
||
If denoting a call to <code>Atomics.waitAsync</code>, the resulting promise, otherwise <emu-const>blocking</emu-const>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[TimeoutTime]]</var>
|
||
</td>
|
||
<td>
|
||
a non-negative <emu-xref href="#extended-mathematical-value" id="_ref_15022"><a href="notational-conventions.html#extended-mathematical-value">extended mathematical value</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The earliest time by which timeout may be triggered; computed using <emu-xref href="#sec-time-values-and-time-range" id="_ref_15023"><a href="numbers-and-dates.html#sec-time-values-and-time-range">time values</a></emu-xref>.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[Result]]</var>
|
||
</td>
|
||
<td>
|
||
<emu-val>"ok"</emu-val> or <emu-val>"timed-out"</emu-val>
|
||
</td>
|
||
<td>
|
||
The return value of the call.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-waiterlist-records" oldids="sec-waiterlist-objects"><span id="sec-waiterlist-objects"></span>
|
||
<h1><span class="secnum">25.4.2</span> WaiterList Records</h1>
|
||
<p>A <dfn variants="WaiterList Records" tabindex="-1">WaiterList Record</dfn> is used to explain waiting and notification of <emu-xref href="#agent" id="_ref_15024"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref> via <code>Atomics.wait</code>, <code>Atomics.waitAsync</code>, and <code>Atomics.notify</code>.</p>
|
||
<p>A WaiterList Record has fields listed in <emu-xref href="#table-waiterlistrecord" id="_ref_807"><a href="structured-data.html#table-waiterlistrecord">Table 74</a></emu-xref>.</p>
|
||
<emu-table id="table-waiterlistrecord" caption="WaiterList Record Fields"><figure><figcaption>Table 74: <emu-xref href="#sec-waiterlist-records" id="_ref_15025"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref> Fields</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Field Name
|
||
</th>
|
||
<th>
|
||
Value
|
||
</th>
|
||
<th>
|
||
Meaning
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
<var class="field">[[Waiters]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15026"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-waiter-record" id="_ref_15027"><a href="structured-data.html#sec-waiter-record">Waiter Records</a></emu-xref>
|
||
</td>
|
||
<td>
|
||
The calls to <code>Atomics.wait</code> or <code>Atomics.waitAsync</code> that are waiting on the location with which this WaiterList is associated.
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
<var class="field">[[MostRecentLeaveEvent]]</var>
|
||
</td>
|
||
<td>
|
||
a <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15028"><a href="memory-model.html#sec-memory-model-fundamentals">Synchronize event</a></emu-xref> or <emu-const>empty</emu-const>
|
||
</td>
|
||
<td>
|
||
The event of the most recent leaving of its <emu-xref href="#sec-waiterlist-records" id="_ref_15029"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref>, or <emu-const>empty</emu-const> if its <emu-xref href="#sec-waiterlist-records" id="_ref_15030"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> has never been entered.
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
<p>There can be multiple <emu-xref href="#sec-waiter-record" id="_ref_15031"><a href="structured-data.html#sec-waiter-record">Waiter Records</a></emu-xref> in a WaiterList with the same <emu-xref href="#sec-agents" id="_ref_15032"><a href="executable-code-and-execution-contexts.html#sec-agents">agent signifier</a></emu-xref>.</p>
|
||
<p>The <emu-xref href="#sec-agent-clusters" id="_ref_15033"><a href="executable-code-and-execution-contexts.html#sec-agent-clusters">agent cluster</a></emu-xref> has a store of WaiterList Records; the store is indexed by (<var>block</var>, <var>i</var>), where <var>block</var> is a <emu-xref href="#sec-data-blocks" id="_ref_15034"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref> and <var>i</var> a byte offset into the memory of <var>block</var>. WaiterList Records are <emu-xref href="#agent" id="_ref_15035"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref>-independent: a lookup in the store of WaiterList Records by (<var>block</var>, <var>i</var>) will result in the same WaiterList Record in any <emu-xref href="#agent" id="_ref_15036"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> in the <emu-xref href="#sec-agent-clusters" id="_ref_15037"><a href="executable-code-and-execution-contexts.html#sec-agent-clusters">agent cluster</a></emu-xref>.</p>
|
||
<p>Each WaiterList Record has a <dfn variants="critical sections" tabindex="-1">critical section</dfn> that controls exclusive access to that WaiterList Record during evaluation. Only a single <emu-xref href="#agent" id="_ref_15038"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> may enter a WaiterList Record's critical section at one time. Entering and leaving a WaiterList Record's critical section is controlled by the <emu-xref href="#sec-algorithm-conventions-abstract-operations" id="_ref_15039"><a href="notational-conventions.html#sec-algorithm-conventions-abstract-operations">abstract operations</a></emu-xref> <emu-xref aoid="EnterCriticalSection" id="_ref_15040"><a href="structured-data.html#sec-entercriticalsection">EnterCriticalSection</a></emu-xref> and <emu-xref aoid="LeaveCriticalSection" id="_ref_15041"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>. Operations on a WaiterList Record—adding and removing waiting <emu-xref href="#agent" id="_ref_15042"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref>, traversing the list of <emu-xref href="#agent" id="_ref_15043"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref>, suspending and notifying <emu-xref href="#agent" id="_ref_15044"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref> on the list, setting and retrieving the <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15045"><a href="memory-model.html#sec-memory-model-fundamentals">Synchronize event</a></emu-xref>—may only be performed by <emu-xref href="#agent" id="_ref_15046"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref> that have entered the WaiterList Record's critical section.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-abstract-operations-for-atomics">
|
||
<h1><span class="secnum">25.4.3</span> Abstract Operations for Atomics</h1>
|
||
|
||
<emu-clause id="sec-validateintegertypedarray" type="abstract operation" oldids="sec-validatesharedintegertypedarray" aoid="ValidateIntegerTypedArray"><span id="sec-validatesharedintegertypedarray"></span>
|
||
<h1><span class="secnum">25.4.3.1</span> ValidateIntegerTypedArray ( <var>typedArray</var>, <var>waitable</var> )</h1>
|
||
<p>The abstract operation ValidateIntegerTypedArray takes arguments <var>typedArray</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15047"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and <var>waitable</var> (a Boolean) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15048"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> a <emu-xref href="#sec-typedarray-with-buffer-witness-records" id="_ref_15049"><a href="ordinary-and-exotic-objects-behaviours.html#sec-typedarray-with-buffer-witness-records">TypedArray With Buffer Witness Record</a></emu-xref>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15050"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>taRecord</var> be ? <emu-xref aoid="ValidateTypedArray" id="_ref_15051"><a href="indexed-collections.html#sec-validatetypedarray">ValidateTypedArray</a></emu-xref>(<var>typedArray</var>, <emu-const>unordered</emu-const>).</li><li>NOTE: Bounds checking is not a synchronizing operation when <var>typedArray</var>'s backing buffer is a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_15052"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</li><li>If <var>waitable</var> is <emu-val>true</emu-val>, then<ol><li>If <var>typedArray</var>.<var class="field">[[TypedArrayName]]</var> is neither <emu-val>"Int32Array"</emu-val> nor <emu-val>"BigInt64Array"</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li></ol></li><li>Else,<ol><li>Let <var>type</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15053"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>If <emu-xref aoid="IsUnclampedIntegerElementType" id="_ref_15054"><a href="structured-data.html#sec-isunclampedintegerelementtype">IsUnclampedIntegerElementType</a></emu-xref>(<var>type</var>) is <emu-val>false</emu-val> and <emu-xref aoid="IsBigIntElementType" id="_ref_15055"><a href="structured-data.html#sec-isbigintelementtype">IsBigIntElementType</a></emu-xref>(<var>type</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li></ol></li><li>Return <var>taRecord</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-validateatomicaccess" type="abstract operation" aoid="ValidateAtomicAccess">
|
||
<h1><span class="secnum">25.4.3.2</span> ValidateAtomicAccess ( <var>taRecord</var>, <var>requestIndex</var> )</h1>
|
||
<p>The abstract operation ValidateAtomicAccess takes arguments <var>taRecord</var> (a <emu-xref href="#sec-typedarray-with-buffer-witness-records" id="_ref_15056"><a href="ordinary-and-exotic-objects-behaviours.html#sec-typedarray-with-buffer-witness-records">TypedArray With Buffer Witness Record</a></emu-xref>) and <var>requestIndex</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15057"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15058"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#integer" id="_ref_15059"><a href="notational-conventions.html#integer">integer</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15060"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>length</var> be <emu-xref aoid="TypedArrayLength" id="_ref_15061"><a href="ordinary-and-exotic-objects-behaviours.html#sec-typedarraylength">TypedArrayLength</a></emu-xref>(<var>taRecord</var>).</li><li>Let <var>accessIndex</var> be ? <emu-xref aoid="ToIndex" id="_ref_15062"><a href="abstract-operations.html#sec-toindex" class="e-user-code">ToIndex</a></emu-xref>(<var>requestIndex</var>).</li><li><emu-xref href="#assert" id="_ref_15063"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>accessIndex</var> ≥ 0.</li><li>If <var>accessIndex</var> ≥ <var>length</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Let <var>typedArray</var> be <var>taRecord</var>.<var class="field">[[Object]]</var>.</li><li>Let <var>elementSize</var> be <emu-xref aoid="TypedArrayElementSize" id="_ref_15064"><a href="indexed-collections.html#sec-typedarrayelementsize">TypedArrayElementSize</a></emu-xref>(<var>typedArray</var>).</li><li>Let <var>offset</var> be <var>typedArray</var>.<var class="field">[[ByteOffset]]</var>.</li><li>Return (<var>accessIndex</var> × <var>elementSize</var>) + <var>offset</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-validateatomicaccessonintegertypedarray" type="abstract operation" aoid="ValidateAtomicAccessOnIntegerTypedArray">
|
||
<h1><span class="secnum">25.4.3.3</span> ValidateAtomicAccessOnIntegerTypedArray ( <var>typedArray</var>, <var>requestIndex</var> )</h1>
|
||
<p>The abstract operation ValidateAtomicAccessOnIntegerTypedArray takes arguments <var>typedArray</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15065"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and <var>requestIndex</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15066"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15067"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#integer" id="_ref_15068"><a href="notational-conventions.html#integer">integer</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15069"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>taRecord</var> be ? <emu-xref aoid="ValidateIntegerTypedArray" id="_ref_15070"><a href="structured-data.html#sec-validateintegertypedarray">ValidateIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <emu-val>false</emu-val>).</li><li>Return ? <emu-xref aoid="ValidateAtomicAccess" id="_ref_15071"><a href="structured-data.html#sec-validateatomicaccess" class="e-user-code">ValidateAtomicAccess</a></emu-xref>(<var>taRecord</var>, <var>requestIndex</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-revalidateatomicaccess" type="abstract operation" aoid="RevalidateAtomicAccess">
|
||
<h1><span class="secnum">25.4.3.4</span> RevalidateAtomicAccess ( <var>typedArray</var>, <var>byteIndexInBuffer</var> )</h1>
|
||
<p>The abstract operation RevalidateAtomicAccess takes arguments <var>typedArray</var> (a <emu-xref href="#typedarray" id="_ref_15072"><a href="ordinary-and-exotic-objects-behaviours.html#typedarray">TypedArray</a></emu-xref>) and <var>byteIndexInBuffer</var> (an <emu-xref href="#integer" id="_ref_15073"><a href="notational-conventions.html#integer">integer</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15074"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> <emu-const>unused</emu-const> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15075"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. This operation revalidates the index within the backing buffer for atomic operations after all argument coercions are performed in Atomics methods, as argument coercions can have arbitrary side effects, which could cause the buffer to become out of bounds. This operation does not throw when <var>typedArray</var>'s backing buffer is a SharedArrayBuffer. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>taRecord</var> be <emu-xref aoid="MakeTypedArrayWithBufferWitnessRecord" id="_ref_15076"><a href="ordinary-and-exotic-objects-behaviours.html#sec-maketypedarraywithbufferwitnessrecord">MakeTypedArrayWithBufferWitnessRecord</a></emu-xref>(<var>typedArray</var>, <emu-const>unordered</emu-const>).</li><li>NOTE: Bounds checking is not a synchronizing operation when <var>typedArray</var>'s backing buffer is a <emu-xref href="#sec-fixed-length-and-growable-sharedarraybuffer-objects" id="_ref_15077"><a href="structured-data.html#sec-fixed-length-and-growable-sharedarraybuffer-objects">growable SharedArrayBuffer</a></emu-xref>.</li><li>If <emu-xref aoid="IsTypedArrayOutOfBounds" id="_ref_15078"><a href="ordinary-and-exotic-objects-behaviours.html#sec-istypedarrayoutofbounds">IsTypedArrayOutOfBounds</a></emu-xref>(<var>taRecord</var>) is <emu-val>true</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li><emu-xref href="#assert" id="_ref_15079"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>byteIndexInBuffer</var> ≥ <var>typedArray</var>.<var class="field">[[ByteOffset]]</var>.</li><li>If <var>byteIndexInBuffer</var> ≥ <var>taRecord</var>.<var class="field">[[CachedBufferByteLength]]</var>, throw a <emu-val>RangeError</emu-val> exception.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-getwaiterlist" type="abstract operation" aoid="GetWaiterList">
|
||
<h1><span class="secnum">25.4.3.5</span> GetWaiterList ( <var>block</var>, <var>i</var> )</h1>
|
||
<p>The abstract operation GetWaiterList takes arguments <var>block</var> (a <emu-xref href="#sec-data-blocks" id="_ref_15080"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref>) and <var>i</var> (a non-negative <emu-xref href="#integer" id="_ref_15081"><a href="notational-conventions.html#integer">integer</a></emu-xref> that is evenly divisible by 4) and returns a <emu-xref href="#sec-waiterlist-records" id="_ref_15082"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15083"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>i</var> and <var>i</var> + 3 are valid byte offsets within the memory of <var>block</var>.</li><li>Return the <emu-xref href="#sec-waiterlist-records" id="_ref_15084"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref> that is referenced by the pair (<var>block</var>, <var>i</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-entercriticalsection" type="abstract operation" aoid="EnterCriticalSection">
|
||
<h1><span class="secnum">25.4.3.6</span> EnterCriticalSection ( <var>WL</var> )</h1>
|
||
<p>The abstract operation EnterCriticalSection takes argument <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15085"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15086"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15087"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is not in the <emu-xref href="#sec-waiterlist-records" id="_ref_15088"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for any <emu-xref href="#sec-waiterlist-records" id="_ref_15089"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>.</li><li>Wait until no <emu-xref href="#agent" id="_ref_15090"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15091"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>, then enter the <emu-xref href="#sec-waiterlist-records" id="_ref_15092"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var> (without allowing any other <emu-xref href="#agent" id="_ref_15093"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> to enter).</li><li>If <var>WL</var>.<var class="field">[[MostRecentLeaveEvent]]</var> is not <emu-const>empty</emu-const>, then<ol><li>NOTE: A <var>WL</var> whose <emu-xref href="#sec-waiterlist-records" id="_ref_15094"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> has been entered at least once has a <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15095"><a href="memory-model.html#sec-memory-model-fundamentals">Synchronize event</a></emu-xref> set by <emu-xref aoid="LeaveCriticalSection" id="_ref_15096"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>.</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15097"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15098"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>execution</var> be <var>AR</var>.<var class="field">[[CandidateExecution]]</var>.</li><li>Let <var>eventsRecord</var> be the <emu-xref href="#sec-agent-event-records" id="_ref_15099"><a href="memory-model.html#sec-agent-event-records">Agent Events Record</a></emu-xref> of <var>execution</var>.<var class="field">[[EventsRecords]]</var> whose <var class="field">[[AgentSignifier]]</var> is <emu-xref aoid="AgentSignifier" id="_ref_15100"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>Let <var>enterEvent</var> be a new <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15101"><a href="memory-model.html#sec-memory-model-fundamentals">Synchronize event</a></emu-xref>.</li><li>Append <var>enterEvent</var> to <var>eventsRecord</var>.<var class="field">[[EventList]]</var>.</li><li>Append (<var>WL</var>.<var class="field">[[MostRecentLeaveEvent]]</var>, <var>enterEvent</var>) to <var>eventsRecord</var>.<var class="field">[[AgentSynchronizesWith]]</var>.</li></ol></li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
<p>EnterCriticalSection has <dfn tabindex="-1">contention</dfn> when an <emu-xref href="#agent" id="_ref_15102"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> attempting to enter the <emu-xref href="#sec-waiterlist-records" id="_ref_15103"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> must wait for another <emu-xref href="#agent" id="_ref_15104"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> to leave it. When there is no contention, FIFO order of EnterCriticalSection calls is observable. When there is contention, an implementation may choose an arbitrary order but may not cause an <emu-xref href="#agent" id="_ref_15105"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> to wait indefinitely.</p>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-leavecriticalsection" type="abstract operation" aoid="LeaveCriticalSection">
|
||
<h1><span class="secnum">25.4.3.7</span> LeaveCriticalSection ( <var>WL</var> )</h1>
|
||
<p>The abstract operation LeaveCriticalSection takes argument <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15106"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15107"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15108"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15109"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15110"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15111"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>execution</var> be <var>AR</var>.<var class="field">[[CandidateExecution]]</var>.</li><li>Let <var>eventsRecord</var> be the <emu-xref href="#sec-agent-event-records" id="_ref_15112"><a href="memory-model.html#sec-agent-event-records">Agent Events Record</a></emu-xref> of <var>execution</var>.<var class="field">[[EventsRecords]]</var> whose <var class="field">[[AgentSignifier]]</var> is <emu-xref aoid="AgentSignifier" id="_ref_15113"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>Let <var>leaveEvent</var> be a new <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15114"><a href="memory-model.html#sec-memory-model-fundamentals">Synchronize event</a></emu-xref>.</li><li>Append <var>leaveEvent</var> to <var>eventsRecord</var>.<var class="field">[[EventList]]</var>.</li><li>Set <var>WL</var>.<var class="field">[[MostRecentLeaveEvent]]</var> to <var>leaveEvent</var>.</li><li>Leave the <emu-xref href="#sec-waiterlist-records" id="_ref_15115"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-addwaiter" type="abstract operation" aoid="AddWaiter">
|
||
<h1><span class="secnum">25.4.3.8</span> AddWaiter ( <var>WL</var>, <var>waiterRecord</var> )</h1>
|
||
<p>The abstract operation AddWaiter takes arguments <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15116"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and <var>waiterRecord</var> (a <emu-xref href="#sec-waiter-record" id="_ref_15117"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15118"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15119"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15120"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li><emu-xref href="#assert" id="_ref_15121"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: There is no <emu-xref href="#sec-waiter-record" id="_ref_15122"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref> in <var>WL</var>.<var class="field">[[Waiters]]</var> whose <var class="field">[[PromiseCapability]]</var> field is <var>waiterRecord</var>.<var class="field">[[PromiseCapability]]</var> and whose <var class="field">[[AgentSignifier]]</var> field is <var>waiterRecord</var>.<var class="field">[[AgentSignifier]]</var>.</li><li>Append <var>waiterRecord</var> to <var>WL</var>.<var class="field">[[Waiters]]</var>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-removewaiter" type="abstract operation" aoid="RemoveWaiter">
|
||
<h1><span class="secnum">25.4.3.9</span> RemoveWaiter ( <var>WL</var>, <var>waiterRecord</var> )</h1>
|
||
<p>The abstract operation RemoveWaiter takes arguments <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15123"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and <var>waiterRecord</var> (a <emu-xref href="#sec-waiter-record" id="_ref_15124"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15125"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15126"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15127"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li><emu-xref href="#assert" id="_ref_15128"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>WL</var>.<var class="field">[[Waiters]]</var> contains <var>waiterRecord</var>.</li><li>Remove <var>waiterRecord</var> from <var>WL</var>.<var class="field">[[Waiters]]</var>.</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-removewaiters" type="abstract operation" aoid="RemoveWaiters">
|
||
<h1><span class="secnum">25.4.3.10</span> RemoveWaiters ( <var>WL</var>, <var>c</var> )</h1>
|
||
<p>The abstract operation RemoveWaiters takes arguments <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15129"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and <var>c</var> (a non-negative <emu-xref href="#integer" id="_ref_15130"><a href="notational-conventions.html#integer">integer</a></emu-xref> or +∞) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15131"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-waiter-record" id="_ref_15132"><a href="structured-data.html#sec-waiter-record">Waiter Records</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15133"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15134"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15135"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li>Let <var>len</var> be the number of elements in <var>WL</var>.<var class="field">[[Waiters]]</var>.</li><li>Let <var>n</var> be <emu-xref aoid="min" id="_ref_15136"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(<var>c</var>, <var>len</var>).</li><li>Let <var>L</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15137"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> whose elements are the first <var>n</var> elements of <var>WL</var>.<var class="field">[[Waiters]]</var>.</li><li>Remove the first <var>n</var> elements of <var>WL</var>.<var class="field">[[Waiters]]</var>.</li><li>Return <var>L</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-suspendthisagent" type="abstract operation" oldids="sec-suspend,sec-suspendagent" aoid="SuspendThisAgent"><span id="sec-suspendagent"></span><span id="sec-suspend"></span>
|
||
<h1><span class="secnum">25.4.3.11</span> SuspendThisAgent ( <var>WL</var>, <var>waiterRecord</var> )</h1>
|
||
<p>The abstract operation SuspendThisAgent takes arguments <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15138"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and <var>waiterRecord</var> (a <emu-xref href="#sec-waiter-record" id="_ref_15139"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15140"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15141"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15142"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li><emu-xref href="#assert" id="_ref_15143"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>WL</var>.<var class="field">[[Waiters]]</var> contains <var>waiterRecord</var>.</li><li>Let <var>thisAgent</var> be <emu-xref aoid="AgentSignifier" id="_ref_15144"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li><emu-xref href="#assert" id="_ref_15145"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>waiterRecord</var>.<var class="field">[[AgentSignifier]]</var> is <var>thisAgent</var>.</li><li><emu-xref href="#assert" id="_ref_15146"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>waiterRecord</var>.<var class="field">[[PromiseCapability]]</var> is <emu-const>blocking</emu-const>.</li><li><emu-xref href="#assert" id="_ref_15147"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="AgentCanSuspend" id="_ref_15148"><a href="executable-code-and-execution-contexts.html#sec-agentcansuspend">AgentCanSuspend</a></emu-xref>() is <emu-val>true</emu-val>.</li><li>Perform <emu-xref aoid="LeaveCriticalSection" id="_ref_15149"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>(<var>WL</var>) and suspend the <emu-xref href="#surrounding-agent" id="_ref_15150"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> until the time is <var>waiterRecord</var>.<var class="field">[[TimeoutTime]]</var>, performing the combined operation in such a way that a notification that arrives after the <emu-xref href="#sec-waiterlist-records" id="_ref_15151"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> is exited but before the suspension takes effect is not lost. The <emu-xref href="#surrounding-agent" id="_ref_15152"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> can only wake from suspension due to a timeout or due to another <emu-xref href="#agent" id="_ref_15153"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> calling <emu-xref aoid="NotifyWaiter" id="_ref_15154"><a href="structured-data.html#sec-notifywaiter">NotifyWaiter</a></emu-xref> with arguments <var>WL</var> and <var>thisAgent</var> (i.e. via a call to <code>Atomics.notify</code>).</li><li>Perform <emu-xref aoid="EnterCriticalSection" id="_ref_15155"><a href="structured-data.html#sec-entercriticalsection">EnterCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-notifywaiter" type="abstract operation" aoid="NotifyWaiter">
|
||
<h1><span class="secnum">25.4.3.12</span> NotifyWaiter ( <var>WL</var>, <var>waiterRecord</var> )</h1>
|
||
<p>The abstract operation NotifyWaiter takes arguments <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15156"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and <var>waiterRecord</var> (a <emu-xref href="#sec-waiter-record" id="_ref_15157"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15158"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: The <emu-xref href="#surrounding-agent" id="_ref_15159"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> is in the <emu-xref href="#sec-waiterlist-records" id="_ref_15160"><a href="structured-data.html#sec-waiterlist-records">critical section</a></emu-xref> for <var>WL</var>.</li><li>If <var>waiterRecord</var>.<var class="field">[[PromiseCapability]]</var> is <emu-const>blocking</emu-const>, then<ol><li>Wake the <emu-xref href="#agent" id="_ref_15161"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> whose signifier is <var>waiterRecord</var>.<var class="field">[[AgentSignifier]]</var> from suspension.</li><li>NOTE: This causes the <emu-xref href="#agent" id="_ref_15162"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> to resume execution in <emu-xref aoid="SuspendThisAgent" id="_ref_15163"><a href="structured-data.html#sec-suspendthisagent">SuspendThisAgent</a></emu-xref>.</li></ol></li><li>Else if <emu-xref aoid="AgentSignifier" id="_ref_15164"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>() is <var>waiterRecord</var>.<var class="field">[[AgentSignifier]]</var>, then<ol><li>Let <var>promiseCapability</var> be <var>waiterRecord</var>.<var class="field">[[PromiseCapability]]</var>.</li><li>Perform ! <emu-xref aoid="Call" id="_ref_15165"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>waiterRecord</var>.<var class="field">[[Result]]</var> »).</li></ol></li><li>Else,<ol><li>Perform <emu-xref aoid="EnqueueResolveInAgentJob" id="_ref_15166"><a href="structured-data.html#sec-enqueueresolveinagentjob">EnqueueResolveInAgentJob</a></emu-xref>(<var>waiterRecord</var>.<var class="field">[[AgentSignifier]]</var>, <var>waiterRecord</var>.<var class="field">[[PromiseCapability]]</var>, <var>waiterRecord</var>.<var class="field">[[Result]]</var>).</li></ol></li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>An <emu-xref href="#agent" id="_ref_15167"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> must not access another <emu-xref href="#agent" id="_ref_15168"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref>'s promise capability in any capacity beyond passing it to the <emu-xref href="#host" id="_ref_15169"><a href="overview.html#host">host</a></emu-xref>.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-enqueueresolveinagentjob" type="abstract operation" aoid="EnqueueResolveInAgentJob">
|
||
<h1><span class="secnum">25.4.3.13</span> EnqueueResolveInAgentJob ( <var>agentSignifier</var>, <var>promiseCapability</var>, <var>resolution</var> )</h1>
|
||
<p>The abstract operation EnqueueResolveInAgentJob takes arguments <var>agentSignifier</var> (an <emu-xref href="#sec-agents" id="_ref_15170"><a href="executable-code-and-execution-contexts.html#sec-agents">agent signifier</a></emu-xref>), <var>promiseCapability</var> (a <emu-xref href="#sec-promisecapability-records" id="_ref_15171"><a href="control-abstraction-objects.html#sec-promisecapability-records">PromiseCapability Record</a></emu-xref>), and <var>resolution</var> (<emu-val>"ok"</emu-val> or <emu-val>"timed-out"</emu-val>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>resolveJob</var> be a new <emu-xref href="#job" id="_ref_15172"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_15173"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>agentSignifier</var>, <var>promiseCapability</var>, and <var>resolution</var> and performs the following steps when called:<ol><li><emu-xref href="#assert" id="_ref_15174"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="AgentSignifier" id="_ref_15175"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>() is <var>agentSignifier</var>.</li><li>Perform ! <emu-xref aoid="Call" id="_ref_15176"><a href="abstract-operations.html#sec-call">Call</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>, <emu-val>undefined</emu-val>, « <var>resolution</var> »).</li><li>Return <emu-const>unused</emu-const>.</li></ol></li><li>Let <var>realmInTargetAgent</var> be ! <emu-xref aoid="GetFunctionRealm" id="_ref_15177"><a href="abstract-operations.html#sec-getfunctionrealm">GetFunctionRealm</a></emu-xref>(<var>promiseCapability</var>.<var class="field">[[Resolve]]</var>).</li><li><emu-xref href="#assert" id="_ref_15178"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>agentSignifier</var> is <var>realmInTargetAgent</var>.<var class="field">[[AgentSignifier]]</var>.</li><li>Perform <emu-xref aoid="HostEnqueueGenericJob" id="_ref_15179"><a href="executable-code-and-execution-contexts.html#sec-hostenqueuegenericjob">HostEnqueueGenericJob</a></emu-xref>(<var>resolveJob</var>, <var>realmInTargetAgent</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-dowait" type="abstract operation" aoid="DoWait">
|
||
<h1><span class="secnum">25.4.3.14</span> DoWait ( <var>mode</var>, <var>typedArray</var>, <var>index</var>, <var>value</var>, <var>timeout</var> )</h1>
|
||
<p>The abstract operation DoWait takes arguments <var>mode</var> (<emu-const>sync</emu-const> or <emu-const>async</emu-const>), <var>typedArray</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15180"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>index</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15181"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15182"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), and <var>timeout</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15183"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15184"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either an Object, <emu-val>"not-equal"</emu-val>, <emu-val>"timed-out"</emu-val>, or <emu-val>"ok"</emu-val>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15185"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>taRecord</var> be ? <emu-xref aoid="ValidateIntegerTypedArray" id="_ref_15186"><a href="structured-data.html#sec-validateintegertypedarray">ValidateIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <emu-val>true</emu-val>).</li><li>Let <var>buffer</var> be <var>taRecord</var>.<var class="field">[[Object]]</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_15187"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>buffer</var>) is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>byteIndexInBuffer</var> be ? <emu-xref aoid="ValidateAtomicAccess" id="_ref_15188"><a href="structured-data.html#sec-validateatomicaccess" class="e-user-code">ValidateAtomicAccess</a></emu-xref>(<var>taRecord</var>, <var>index</var>).</li><li>Let <var>arrayTypeName</var> be <var>typedArray</var>.<var class="field">[[TypedArrayName]]</var>.</li><li>If <var>arrayTypeName</var> is <emu-val>"BigInt64Array"</emu-val>, let <var>v</var> be ? <emu-xref aoid="ToBigInt64" id="_ref_15189"><a href="abstract-operations.html#sec-tobigint64" class="e-user-code">ToBigInt64</a></emu-xref>(<var>value</var>).</li><li>Else, let <var>v</var> be ? <emu-xref aoid="ToInt32" id="_ref_15190"><a href="abstract-operations.html#sec-toint32" class="e-user-code">ToInt32</a></emu-xref>(<var>value</var>).</li><li>Let <var>q</var> be ? <emu-xref aoid="ToNumber" id="_ref_15191"><a href="abstract-operations.html#sec-tonumber" class="e-user-code">ToNumber</a></emu-xref>(<var>timeout</var>).</li><li>If <var>q</var> is either <emu-val>NaN</emu-val> or <emu-val>+∞</emu-val><sub>𝔽</sub>, let <var>t</var> be +∞.</li><li>Else if <var>q</var> is <emu-val>-∞</emu-val><sub>𝔽</sub>, let <var>t</var> be 0.</li><li>Else, let <var>t</var> be <emu-xref aoid="max" id="_ref_15192"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<emu-xref aoid="ℝ" id="_ref_15193"><a href="notational-conventions.html#%E2%84%9D">ℝ</a></emu-xref>(<var>q</var>), 0).</li><li>If <var>mode</var> is <emu-const>sync</emu-const> and <emu-xref aoid="AgentCanSuspend" id="_ref_15194"><a href="executable-code-and-execution-contexts.html#sec-agentcansuspend">AgentCanSuspend</a></emu-xref>() is <emu-val>false</emu-val>, throw a <emu-val>TypeError</emu-val> exception.</li><li>Let <var>block</var> be <var>buffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>Let <var>WL</var> be <emu-xref aoid="GetWaiterList" id="_ref_15195"><a href="structured-data.html#sec-getwaiterlist">GetWaiterList</a></emu-xref>(<var>block</var>, <var>byteIndexInBuffer</var>).</li><li>If <var>mode</var> is <emu-const>sync</emu-const>, then<ol><li>Let <var>promiseCapability</var> be <emu-const>blocking</emu-const>.</li><li>Let <var>resultObject</var> be <emu-val>undefined</emu-val>.</li></ol></li><li>Else,<ol><li>Let <var>promiseCapability</var> be ! <emu-xref aoid="NewPromiseCapability" id="_ref_15196"><a href="control-abstraction-objects.html#sec-newpromisecapability">NewPromiseCapability</a></emu-xref>(<emu-xref href="#sec-promise-constructor" id="_ref_15197"><a href="control-abstraction-objects.html#sec-promise-constructor">%Promise%</a></emu-xref>).</li><li>Let <var>resultObject</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_15198"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15199"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>).</li></ol></li><li>Perform <emu-xref aoid="EnterCriticalSection" id="_ref_15200"><a href="structured-data.html#sec-entercriticalsection">EnterCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>Let <var>elementType</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15201"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Let <var>w</var> be <emu-xref aoid="GetValueFromBuffer" id="_ref_15202"><a href="structured-data.html#sec-getvaluefrombuffer">GetValueFromBuffer</a></emu-xref>(<var>buffer</var>, <var>byteIndexInBuffer</var>, <var>elementType</var>, <emu-val>true</emu-val>, <emu-const>seq-cst</emu-const>).</li><li>If <var>v</var> ≠ <var>w</var>, then<ol><li>Perform <emu-xref aoid="LeaveCriticalSection" id="_ref_15203"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>If <var>mode</var> is <emu-const>sync</emu-const>, return <emu-val>"not-equal"</emu-val>.</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15204"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>resultObject</var>, <emu-val>"async"</emu-val>, <emu-val>false</emu-val>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15205"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>resultObject</var>, <emu-val>"value"</emu-val>, <emu-val>"not-equal"</emu-val>).</li><li>Return <var>resultObject</var>.</li></ol></li><li>If <var>t</var> = 0 and <var>mode</var> is <emu-const>async</emu-const>, then<ol><li>NOTE: There is no special handling of synchronous immediate timeouts. Asynchronous immediate timeouts have special handling in order to fail fast and avoid unnecessary Promise jobs.</li><li>Perform <emu-xref aoid="LeaveCriticalSection" id="_ref_15206"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15207"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>resultObject</var>, <emu-val>"async"</emu-val>, <emu-val>false</emu-val>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15208"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>resultObject</var>, <emu-val>"value"</emu-val>, <emu-val>"timed-out"</emu-val>).</li><li>Return <var>resultObject</var>.</li></ol></li><li>Let <var>thisAgent</var> be <emu-xref aoid="AgentSignifier" id="_ref_15209"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>Let <var>now</var> be the <emu-xref href="#sec-time-values-and-time-range" id="_ref_15210"><a href="numbers-and-dates.html#sec-time-values-and-time-range">time value</a></emu-xref> (UTC) identifying the current time.</li><li>Let <var>additionalTimeout</var> be an <emu-xref href="#implementation-defined" id="_ref_15211"><a href="overview.html#implementation-defined">implementation-defined</a></emu-xref> non-negative <emu-xref href="#mathematical-value" id="_ref_15212"><a href="notational-conventions.html#mathematical-value">mathematical value</a></emu-xref>.</li><li>Let <var>timeoutTime</var> be <emu-xref aoid="ℝ" id="_ref_15213"><a href="notational-conventions.html#%E2%84%9D">ℝ</a></emu-xref>(<var>now</var>) + <var>t</var> + <var>additionalTimeout</var>.</li><li>NOTE: When <var>t</var> is +∞, <var>timeoutTime</var> is also +∞.</li><li>Let <var>waiterRecord</var> be a new <emu-xref href="#sec-waiter-record" id="_ref_15214"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref> { <var class="field">[[AgentSignifier]]</var>: <var>thisAgent</var>, <var class="field">[[PromiseCapability]]</var>: <var>promiseCapability</var>, <var class="field">[[TimeoutTime]]</var>: <var>timeoutTime</var>, <var class="field">[[Result]]</var>: <emu-val>"ok"</emu-val> }.</li><li>Perform <emu-xref aoid="AddWaiter" id="_ref_15215"><a href="structured-data.html#sec-addwaiter">AddWaiter</a></emu-xref>(<var>WL</var>, <var>waiterRecord</var>).</li><li>If <var>mode</var> is <emu-const>sync</emu-const>, then<ol><li>Perform <emu-xref aoid="SuspendThisAgent" id="_ref_15216"><a href="structured-data.html#sec-suspendthisagent">SuspendThisAgent</a></emu-xref>(<var>WL</var>, <var>waiterRecord</var>).</li></ol></li><li>Else if <var>timeoutTime</var> is <emu-xref href="#finite" id="_ref_15217"><a href="ecmascript-data-types-and-values.html#finite">finite</a></emu-xref>, then<ol><li>Perform <emu-xref aoid="EnqueueAtomicsWaitAsyncTimeoutJob" id="_ref_15218"><a href="structured-data.html#sec-enqueueatomicswaitasynctimeoutjob">EnqueueAtomicsWaitAsyncTimeoutJob</a></emu-xref>(<var>WL</var>, <var>waiterRecord</var>).</li></ol></li><li>Perform <emu-xref aoid="LeaveCriticalSection" id="_ref_15219"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>If <var>mode</var> is <emu-const>sync</emu-const>, return <var>waiterRecord</var>.<var class="field">[[Result]]</var>.</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15220"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>resultObject</var>, <emu-val>"async"</emu-val>, <emu-val>true</emu-val>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15221"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>resultObject</var>, <emu-val>"value"</emu-val>, <var>promiseCapability</var>.<var class="field">[[Promise]]</var>).</li><li>Return <var>resultObject</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p><var>additionalTimeout</var> allows implementations to pad timeouts as necessary, such as for reducing power consumption or coarsening timer resolution to mitigate timing attacks. This value may differ from call to call of DoWait.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-enqueueatomicswaitasynctimeoutjob" type="abstract operation" aoid="EnqueueAtomicsWaitAsyncTimeoutJob">
|
||
<h1><span class="secnum">25.4.3.15</span> EnqueueAtomicsWaitAsyncTimeoutJob ( <var>WL</var>, <var>waiterRecord</var> )</h1>
|
||
<p>The abstract operation EnqueueAtomicsWaitAsyncTimeoutJob takes arguments <var>WL</var> (a <emu-xref href="#sec-waiterlist-records" id="_ref_15222"><a href="structured-data.html#sec-waiterlist-records">WaiterList Record</a></emu-xref>) and <var>waiterRecord</var> (a <emu-xref href="#sec-waiter-record" id="_ref_15223"><a href="structured-data.html#sec-waiter-record">Waiter Record</a></emu-xref>) and returns <emu-const>unused</emu-const>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>timeoutJob</var> be a new <emu-xref href="#job" id="_ref_15224"><a href="executable-code-and-execution-contexts.html#job">Job</a></emu-xref> <emu-xref href="#sec-abstract-closure" id="_ref_15225"><a href="ecmascript-data-types-and-values.html#sec-abstract-closure">Abstract Closure</a></emu-xref> with no parameters that captures <var>WL</var> and <var>waiterRecord</var> and performs the following steps when called:<ol><li>Perform <emu-xref aoid="EnterCriticalSection" id="_ref_15226"><a href="structured-data.html#sec-entercriticalsection">EnterCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>If <var>WL</var>.<var class="field">[[Waiters]]</var> contains <var>waiterRecord</var>, then<ol><li>Let <var>timeOfJobExecution</var> be the <emu-xref href="#sec-time-values-and-time-range" id="_ref_15227"><a href="numbers-and-dates.html#sec-time-values-and-time-range">time value</a></emu-xref> (UTC) identifying the current time.</li><li><emu-xref href="#assert" id="_ref_15228"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <emu-xref aoid="ℝ" id="_ref_15229"><a href="notational-conventions.html#%E2%84%9D">ℝ</a></emu-xref>(<var>timeOfJobExecution</var>) ≥ <var>waiterRecord</var>.<var class="field">[[TimeoutTime]]</var> (ignoring potential non-monotonicity of <emu-xref href="#sec-time-values-and-time-range" id="_ref_15230"><a href="numbers-and-dates.html#sec-time-values-and-time-range">time values</a></emu-xref>).</li><li>Set <var>waiterRecord</var>.<var class="field">[[Result]]</var> to <emu-val>"timed-out"</emu-val>.</li><li>Perform <emu-xref aoid="RemoveWaiter" id="_ref_15231"><a href="structured-data.html#sec-removewaiter">RemoveWaiter</a></emu-xref>(<var>WL</var>, <var>waiterRecord</var>).</li><li>Perform <emu-xref aoid="NotifyWaiter" id="_ref_15232"><a href="structured-data.html#sec-notifywaiter">NotifyWaiter</a></emu-xref>(<var>WL</var>, <var>waiterRecord</var>).</li></ol></li><li>Perform <emu-xref aoid="LeaveCriticalSection" id="_ref_15233"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></li><li>Let <var>now</var> be the <emu-xref href="#sec-time-values-and-time-range" id="_ref_15234"><a href="numbers-and-dates.html#sec-time-values-and-time-range">time value</a></emu-xref> (UTC) identifying the current time.</li><li>Let <var>currentRealm</var> be <emu-xref href="#current-realm" id="_ref_15235"><a href="executable-code-and-execution-contexts.html#current-realm">the current Realm Record</a></emu-xref>.</li><li>Perform <emu-xref aoid="HostEnqueueTimeoutJob" id="_ref_15236"><a href="executable-code-and-execution-contexts.html#sec-hostenqueuetimeoutjob">HostEnqueueTimeoutJob</a></emu-xref>(<var>timeoutJob</var>, <var>currentRealm</var>, <emu-xref aoid="𝔽" id="_ref_15237"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>waiterRecord</var>.<var class="field">[[TimeoutTime]]</var>) - <var>now</var>).</li><li>Return <emu-const>unused</emu-const>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomiccompareexchangeinsharedblock" type="abstract operation" aoid="AtomicCompareExchangeInSharedBlock">
|
||
<h1><span class="secnum">25.4.3.16</span> AtomicCompareExchangeInSharedBlock ( <var>block</var>, <var>byteIndexInBuffer</var>, <var>elementSize</var>, <var>expectedBytes</var>, <var>replacementBytes</var> )</h1>
|
||
<p>The abstract operation AtomicCompareExchangeInSharedBlock takes arguments <var>block</var> (a <emu-xref href="#sec-data-blocks" id="_ref_15238"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">Shared Data Block</a></emu-xref>), <var>byteIndexInBuffer</var> (an <emu-xref href="#integer" id="_ref_15239"><a href="notational-conventions.html#integer">integer</a></emu-xref>), <var>elementSize</var> (a non-negative <emu-xref href="#integer" id="_ref_15240"><a href="notational-conventions.html#integer">integer</a></emu-xref>), <var>expectedBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15241"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15242"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>), and <var>replacementBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15243"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15244"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15245"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15246"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15247"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15248"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>execution</var> be <var>AR</var>.<var class="field">[[CandidateExecution]]</var>.</li><li>Let <var>eventsRecord</var> be the <emu-xref href="#sec-agent-event-records" id="_ref_15249"><a href="memory-model.html#sec-agent-event-records">Agent Events Record</a></emu-xref> of <var>execution</var>.<var class="field">[[EventsRecords]]</var> whose <var class="field">[[AgentSignifier]]</var> is <emu-xref aoid="AgentSignifier" id="_ref_15250"><a href="executable-code-and-execution-contexts.html#sec-agentsignifier">AgentSignifier</a></emu-xref>().</li><li>Let <var>rawBytesRead</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15251"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of length <var>elementSize</var> whose elements are nondeterministically chosen <emu-xref href="#sec-data-blocks" id="_ref_15252"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>.</li><li>NOTE: In implementations, <var>rawBytesRead</var> is the result of a load-link, of a load-exclusive, or of an operand of a read-modify-write instruction on the underlying hardware. The nondeterminism is a semantic prescription of the <emu-xref href="#sec-memory-model" id="_ref_15253"><a href="memory-model.html#sec-memory-model">memory model</a></emu-xref> to describe observable behaviour of hardware with weak consistency.</li><li>NOTE: The comparison of the expected value and the read value is performed outside of the <emu-xref href="#sec-arraybuffer-notation" id="_ref_15254"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> to avoid needlessly strong synchronization when the expected value is not equal to the read value.</li><li>If <emu-xref aoid="ByteListEqual" id="_ref_15255"><a href="structured-data.html#sec-bytelistequal">ByteListEqual</a></emu-xref>(<var>rawBytesRead</var>, <var>expectedBytes</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>second</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15256"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>oldBytes</var>, <var>newBytes</var>) that captures nothing and performs the following steps atomically when called:<ol><li>Return <var>newBytes</var>.</li></ol></li><li>Let <var>event</var> be <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15257"><a href="memory-model.html#sec-memory-model-fundamentals">ReadModifyWriteSharedMemory</a></emu-xref> { <var class="field">[[Order]]</var>: <emu-const>seq-cst</emu-const>, <var class="field">[[NoTear]]</var>: <emu-val>true</emu-val>, <var class="field">[[Block]]</var>: <var>block</var>, <var class="field">[[ByteIndex]]</var>: <var>byteIndexInBuffer</var>, <var class="field">[[ElementSize]]</var>: <var>elementSize</var>, <var class="field">[[Payload]]</var>: <var>replacementBytes</var>, <var class="field">[[ModifyOp]]</var>: <var>second</var> }.</li></ol></li><li>Else,<ol><li>Let <var>event</var> be <emu-xref href="#sec-memory-model-fundamentals" id="_ref_15258"><a href="memory-model.html#sec-memory-model-fundamentals">ReadSharedMemory</a></emu-xref> { <var class="field">[[Order]]</var>: <emu-const>seq-cst</emu-const>, <var class="field">[[NoTear]]</var>: <emu-val>true</emu-val>, <var class="field">[[Block]]</var>: <var>block</var>, <var class="field">[[ByteIndex]]</var>: <var>byteIndexInBuffer</var>, <var class="field">[[ElementSize]]</var>: <var>elementSize</var> }.</li></ol></li><li>Append <var>event</var> to <var>eventsRecord</var>.<var class="field">[[EventList]]</var>.</li><li>Append <emu-xref href="#sec-chosen-value-records" id="_ref_15259"><a href="memory-model.html#sec-chosen-value-records">Chosen Value Record</a></emu-xref> { <var class="field">[[Event]]</var>: <var>event</var>, <var class="field">[[ChosenValue]]</var>: <var>rawBytesRead</var> } to <var>execution</var>.<var class="field">[[ChosenValues]]</var>.</li><li>Return <var>rawBytesRead</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomicreadmodifywrite" type="abstract operation" aoid="AtomicReadModifyWrite">
|
||
<h1><span class="secnum">25.4.3.17</span> AtomicReadModifyWrite ( <var>typedArray</var>, <var>index</var>, <var>value</var>, <var>op</var> )</h1>
|
||
<p>The abstract operation AtomicReadModifyWrite takes arguments <var>typedArray</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15260"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>index</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15261"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15262"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>), and <var>op</var> (a <emu-xref href="#sec-arraybuffer-notation" id="_ref_15263"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15264"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either a Number or a BigInt, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15265"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. <var>op</var> takes two <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15266"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15267"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref> arguments and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15268"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15269"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. This operation atomically loads a value, combines it with another value, and stores the combination. It returns the loaded value. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>byteIndexInBuffer</var> be ? <emu-xref aoid="ValidateAtomicAccessOnIntegerTypedArray" id="_ref_15270"><a href="structured-data.html#sec-validateatomicaccessonintegertypedarray" class="e-user-code">ValidateAtomicAccessOnIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <var>index</var>).</li><li>If <var>typedArray</var>.<var class="field">[[ContentType]]</var> is <emu-const>bigint</emu-const>, let <var>v</var> be ? <emu-xref aoid="ToBigInt" id="_ref_15271"><a href="abstract-operations.html#sec-tobigint" class="e-user-code">ToBigInt</a></emu-xref>(<var>value</var>).</li><li>Else, let <var>v</var> be <emu-xref aoid="𝔽" id="_ref_15272"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15273"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>value</var>)).</li><li>Perform ? <emu-xref aoid="RevalidateAtomicAccess" id="_ref_15274"><a href="structured-data.html#sec-revalidateatomicaccess">RevalidateAtomicAccess</a></emu-xref>(<var>typedArray</var>, <var>byteIndexInBuffer</var>).</li><li>Let <var>buffer</var> be <var>typedArray</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>Let <var>elementType</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15275"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Return <emu-xref aoid="GetModifySetValueInBuffer" id="_ref_15276"><a href="structured-data.html#sec-getmodifysetvalueinbuffer">GetModifySetValueInBuffer</a></emu-xref>(<var>buffer</var>, <var>byteIndexInBuffer</var>, <var>elementType</var>, <var>v</var>, <var>op</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-bytelistbitwiseop" type="abstract operation" aoid="ByteListBitwiseOp">
|
||
<h1><span class="secnum">25.4.3.18</span> ByteListBitwiseOp ( <var>op</var>, <var>xBytes</var>, <var>yBytes</var> )</h1>
|
||
<p>The abstract operation ByteListBitwiseOp takes arguments <var>op</var> (<code>&</code>, <code>^</code>, or <code>|</code>), <var>xBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15277"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15278"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>), and <var>yBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15279"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15280"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>) and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15281"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15282"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. The operation atomically performs a bitwise operation on all <emu-xref href="#sec-data-blocks" id="_ref_15283"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref> of the arguments and returns a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15284"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15285"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li><emu-xref href="#assert" id="_ref_15286"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>xBytes</var> and <var>yBytes</var> have the same number of elements.</li><li>Let <var>result</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15287"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Let <var>i</var> be 0.</li><li>For each element <var>xByte</var> of <var>xBytes</var>, do<ol><li>Let <var>yByte</var> be <var>yBytes</var>[<var>i</var>].</li><li>If <var>op</var> is <code>&</code>, then<ol><li>Let <var>resultByte</var> be the result of applying the bitwise AND operation to <var>xByte</var> and <var>yByte</var>.</li></ol></li><li>Else if <var>op</var> is <code>^</code>, then<ol><li>Let <var>resultByte</var> be the result of applying the bitwise exclusive OR (XOR) operation to <var>xByte</var> and <var>yByte</var>.</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_15288"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>op</var> is <code>|</code>.</li><li>Let <var>resultByte</var> be the result of applying the bitwise inclusive OR operation to <var>xByte</var> and <var>yByte</var>.</li></ol></li><li>Set <var>i</var> to <var>i</var> + 1.</li><li>Append <var>resultByte</var> to <var>result</var>.</li></ol></li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-bytelistequal" type="abstract operation" aoid="ByteListEqual">
|
||
<h1><span class="secnum">25.4.3.19</span> ByteListEqual ( <var>xBytes</var>, <var>yBytes</var> )</h1>
|
||
<p>The abstract operation ByteListEqual takes arguments <var>xBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15289"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15290"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>) and <var>yBytes</var> (a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15291"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of <emu-xref href="#sec-data-blocks" id="_ref_15292"><a href="ecmascript-data-types-and-values.html#sec-data-blocks">byte values</a></emu-xref>) and returns a Boolean. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>xBytes</var> and <var>yBytes</var> do not have the same number of elements, return <emu-val>false</emu-val>.</li><li>Let <var>i</var> be 0.</li><li>For each element <var>xByte</var> of <var>xBytes</var>, do<ol><li>Let <var>yByte</var> be <var>yBytes</var>[<var>i</var>].</li><li>If <var>xByte</var> ≠ <var>yByte</var>, return <emu-val>false</emu-val>.</li><li>Set <var>i</var> to <var>i</var> + 1.</li></ol></li><li>Return <emu-val>true</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.add" type="built-in function">
|
||
<h1><span class="secnum">25.4.4</span> Atomics.add ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>add</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15293"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>xBytes</var>, <var>yBytes</var>) that captures <var>typedArray</var> and performs the following steps atomically when called:<ol><li>Let <var>type</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15294"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15295"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15296"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li><li>Let <var>x</var> be <emu-xref aoid="RawBytesToNumeric" id="_ref_15297"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>type</var>, <var>xBytes</var>, <var>isLittleEndian</var>).</li><li>Let <var>y</var> be <emu-xref aoid="RawBytesToNumeric" id="_ref_15298"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>type</var>, <var>yBytes</var>, <var>isLittleEndian</var>).</li><li>If <var>x</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_15299"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>, then<ol><li>Let <var>sum</var> be <emu-xref aoid="Number::add" id="_ref_15300"><a href="ecmascript-data-types-and-values.html#sec-numeric-types-number-add">Number::add</a></emu-xref>(<var>x</var>, <var>y</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_15301"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>x</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_15302"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref>.</li><li>Let <var>sum</var> be <emu-xref aoid="BigInt::add" id="_ref_15303"><a href="ecmascript-data-types-and-values.html#sec-numeric-types-bigint-add">BigInt::add</a></emu-xref>(<var>x</var>, <var>y</var>).</li></ol></li><li>Let <var>sumBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_15304"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<var>type</var>, <var>sum</var>, <var>isLittleEndian</var>).</li><li><emu-xref href="#assert" id="_ref_15305"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>sumBytes</var>, <var>xBytes</var>, and <var>yBytes</var> have the same number of elements.</li><li>Return <var>sumBytes</var>.</li></ol></li><li>Return ? <emu-xref aoid="AtomicReadModifyWrite" id="_ref_15306"><a href="structured-data.html#sec-atomicreadmodifywrite" class="e-user-code">AtomicReadModifyWrite</a></emu-xref>(<var>typedArray</var>, <var>index</var>, <var>value</var>, <var>add</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.and" type="built-in function">
|
||
<h1><span class="secnum">25.4.5</span> Atomics.and ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>and</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15307"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>xBytes</var>, <var>yBytes</var>) that captures nothing and performs the following steps atomically when called:<ol><li>Return <emu-xref aoid="ByteListBitwiseOp" id="_ref_15308"><a href="structured-data.html#sec-bytelistbitwiseop">ByteListBitwiseOp</a></emu-xref>(<code>&</code>, <var>xBytes</var>, <var>yBytes</var>).</li></ol></li><li>Return ? <emu-xref aoid="AtomicReadModifyWrite" id="_ref_15309"><a href="structured-data.html#sec-atomicreadmodifywrite" class="e-user-code">AtomicReadModifyWrite</a></emu-xref>(<var>typedArray</var>, <var>index</var>, <var>value</var>, <var>and</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.compareexchange" type="built-in function">
|
||
<h1><span class="secnum">25.4.6</span> Atomics.compareExchange ( <var>typedArray</var>, <var>index</var>, <var>expectedValue</var>, <var>replacementValue</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>byteIndexInBuffer</var> be ? <emu-xref aoid="ValidateAtomicAccessOnIntegerTypedArray" id="_ref_15310"><a href="structured-data.html#sec-validateatomicaccessonintegertypedarray" class="e-user-code">ValidateAtomicAccessOnIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <var>index</var>).</li><li>Let <var>buffer</var> be <var>typedArray</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>Let <var>block</var> be <var>buffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>If <var>typedArray</var>.<var class="field">[[ContentType]]</var> is <emu-const>bigint</emu-const>, then<ol><li>Let <var>expected</var> be ? <emu-xref aoid="ToBigInt" id="_ref_15311"><a href="abstract-operations.html#sec-tobigint" class="e-user-code">ToBigInt</a></emu-xref>(<var>expectedValue</var>).</li><li>Let <var>replacement</var> be ? <emu-xref aoid="ToBigInt" id="_ref_15312"><a href="abstract-operations.html#sec-tobigint" class="e-user-code">ToBigInt</a></emu-xref>(<var>replacementValue</var>).</li></ol></li><li>Else,<ol><li>Let <var>expected</var> be <emu-xref aoid="𝔽" id="_ref_15313"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15314"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>expectedValue</var>)).</li><li>Let <var>replacement</var> be <emu-xref aoid="𝔽" id="_ref_15315"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15316"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>replacementValue</var>)).</li></ol></li><li>Perform ? <emu-xref aoid="RevalidateAtomicAccess" id="_ref_15317"><a href="structured-data.html#sec-revalidateatomicaccess">RevalidateAtomicAccess</a></emu-xref>(<var>typedArray</var>, <var>byteIndexInBuffer</var>).</li><li>Let <var>elementType</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15318"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Let <var>elementSize</var> be <emu-xref aoid="TypedArrayElementSize" id="_ref_15319"><a href="indexed-collections.html#sec-typedarrayelementsize">TypedArrayElementSize</a></emu-xref>(<var>typedArray</var>).</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15320"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15321"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li><li>Let <var>expectedBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_15322"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<var>elementType</var>, <var>expected</var>, <var>isLittleEndian</var>).</li><li>Let <var>replacementBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_15323"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<var>elementType</var>, <var>replacement</var>, <var>isLittleEndian</var>).</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_15324"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>buffer</var>) is <emu-val>true</emu-val>, then<ol><li>Let <var>rawBytesRead</var> be <emu-xref aoid="AtomicCompareExchangeInSharedBlock" id="_ref_15325"><a href="structured-data.html#sec-atomiccompareexchangeinsharedblock">AtomicCompareExchangeInSharedBlock</a></emu-xref>(<var>block</var>, <var>byteIndexInBuffer</var>, <var>elementSize</var>, <var>expectedBytes</var>, <var>replacementBytes</var>).</li></ol></li><li>Else,<ol><li>Let <var>rawBytesRead</var> be a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15326"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of length <var>elementSize</var> whose elements are the sequence of <var>elementSize</var> bytes starting with <var>block</var>[<var>byteIndexInBuffer</var>].</li><li>If <emu-xref aoid="ByteListEqual" id="_ref_15327"><a href="structured-data.html#sec-bytelistequal">ByteListEqual</a></emu-xref>(<var>rawBytesRead</var>, <var>expectedBytes</var>) is <emu-val>true</emu-val>, then<ol><li>Store the individual bytes of <var>replacementBytes</var> into <var>block</var>, starting at <var>block</var>[<var>byteIndexInBuffer</var>].</li></ol></li></ol></li><li>Return <emu-xref aoid="RawBytesToNumeric" id="_ref_15328"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>elementType</var>, <var>rawBytesRead</var>, <var>isLittleEndian</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.exchange" type="built-in function">
|
||
<h1><span class="secnum">25.4.7</span> Atomics.exchange ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>second</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15329"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>oldBytes</var>, <var>newBytes</var>) that captures nothing and performs the following steps atomically when called:<ol><li>Return <var>newBytes</var>.</li></ol></li><li>Return ? <emu-xref aoid="AtomicReadModifyWrite" id="_ref_15330"><a href="structured-data.html#sec-atomicreadmodifywrite" class="e-user-code">AtomicReadModifyWrite</a></emu-xref>(<var>typedArray</var>, <var>index</var>, <var>value</var>, <var>second</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.islockfree" type="built-in function">
|
||
<h1><span class="secnum">25.4.8</span> Atomics.isLockFree ( <var>size</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>n</var> be ? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15331"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>size</var>).</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15332"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15333"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>If <var>n</var> = 1, return <var>AR</var>.<var class="field">[[IsLockFree1]]</var>.</li><li>If <var>n</var> = 2, return <var>AR</var>.<var class="field">[[IsLockFree2]]</var>.</li><li>If <var>n</var> = 4, return <emu-val>true</emu-val>.</li><li>If <var>n</var> = 8, return <var>AR</var>.<var class="field">[[IsLockFree8]]</var>.</li><li>Return <emu-val>false</emu-val>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This function is an optimization primitive. The intuition is that if the atomic step of an atomic primitive (<code>compareExchange</code>, <code>load</code>, <code>store</code>, <code>add</code>, <code>sub</code>, <code>and</code>, <code>or</code>, <code>xor</code>, or <code>exchange</code>) on a datum of size <var>n</var> bytes will be performed without the <emu-xref href="#surrounding-agent" id="_ref_15334"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> acquiring a lock outside the <var>n</var> bytes comprising the datum, then <code>Atomics.isLockFree</code>(<var>n</var>) will return <emu-val>true</emu-val>. High-performance algorithms will use this function to determine whether to use locks or atomic operations in <emu-xref href="#sec-waiterlist-records" id="_ref_15335"><a href="structured-data.html#sec-waiterlist-records">critical sections</a></emu-xref>. If an atomic primitive is not lock-free then it is often more efficient for an algorithm to provide its own locking.</p>
|
||
<p><code>Atomics.isLockFree</code>(4) always returns <emu-val>true</emu-val> as that can be supported on all known relevant hardware. Being able to assume this will generally simplify programs.</p>
|
||
<p>Regardless of the value returned by this function, all atomic operations are guaranteed to be atomic. For example, they will never have a visible operation take place in the middle of the operation (e.g., "tearing").</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.load" oldids="sec-atomicload" type="built-in function"><span id="sec-atomicload"></span>
|
||
<h1><span class="secnum">25.4.9</span> Atomics.load ( <var>typedArray</var>, <var>index</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>byteIndexInBuffer</var> be ? <emu-xref aoid="ValidateAtomicAccessOnIntegerTypedArray" id="_ref_15336"><a href="structured-data.html#sec-validateatomicaccessonintegertypedarray" class="e-user-code">ValidateAtomicAccessOnIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <var>index</var>).</li><li>Perform ? <emu-xref aoid="RevalidateAtomicAccess" id="_ref_15337"><a href="structured-data.html#sec-revalidateatomicaccess">RevalidateAtomicAccess</a></emu-xref>(<var>typedArray</var>, <var>byteIndexInBuffer</var>).</li><li>Let <var>buffer</var> be <var>typedArray</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>Let <var>elementType</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15338"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Return <emu-xref aoid="GetValueFromBuffer" id="_ref_15339"><a href="structured-data.html#sec-getvaluefrombuffer">GetValueFromBuffer</a></emu-xref>(<var>buffer</var>, <var>byteIndexInBuffer</var>, <var>elementType</var>, <emu-val>true</emu-val>, <emu-const>seq-cst</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.or" type="built-in function">
|
||
<h1><span class="secnum">25.4.10</span> Atomics.or ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>or</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15340"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>xBytes</var>, <var>yBytes</var>) that captures nothing and performs the following steps atomically when called:<ol><li>Return <emu-xref aoid="ByteListBitwiseOp" id="_ref_15341"><a href="structured-data.html#sec-bytelistbitwiseop">ByteListBitwiseOp</a></emu-xref>(<code>|</code>, <var>xBytes</var>, <var>yBytes</var>).</li></ol></li><li>Return ? <emu-xref aoid="AtomicReadModifyWrite" id="_ref_15342"><a href="structured-data.html#sec-atomicreadmodifywrite" class="e-user-code">AtomicReadModifyWrite</a></emu-xref>(<var>typedArray</var>, <var>index</var>, <var>value</var>, <var>or</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.store" type="built-in function">
|
||
<h1><span class="secnum">25.4.11</span> Atomics.store ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>byteIndexInBuffer</var> be ? <emu-xref aoid="ValidateAtomicAccessOnIntegerTypedArray" id="_ref_15343"><a href="structured-data.html#sec-validateatomicaccessonintegertypedarray" class="e-user-code">ValidateAtomicAccessOnIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <var>index</var>).</li><li>If <var>typedArray</var>.<var class="field">[[ContentType]]</var> is <emu-const>bigint</emu-const>, let <var>v</var> be ? <emu-xref aoid="ToBigInt" id="_ref_15344"><a href="abstract-operations.html#sec-tobigint" class="e-user-code">ToBigInt</a></emu-xref>(<var>value</var>).</li><li>Else, let <var>v</var> be <emu-xref aoid="𝔽" id="_ref_15345"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15346"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>value</var>)).</li><li>Perform ? <emu-xref aoid="RevalidateAtomicAccess" id="_ref_15347"><a href="structured-data.html#sec-revalidateatomicaccess">RevalidateAtomicAccess</a></emu-xref>(<var>typedArray</var>, <var>byteIndexInBuffer</var>).</li><li>Let <var>buffer</var> be <var>typedArray</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>Let <var>elementType</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15348"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Perform <emu-xref aoid="SetValueInBuffer" id="_ref_15349"><a href="structured-data.html#sec-setvalueinbuffer">SetValueInBuffer</a></emu-xref>(<var>buffer</var>, <var>byteIndexInBuffer</var>, <var>elementType</var>, <var>v</var>, <emu-val>true</emu-val>, <emu-const>seq-cst</emu-const>).</li><li>Return <var>v</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.sub" type="built-in function">
|
||
<h1><span class="secnum">25.4.12</span> Atomics.sub ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>subtract</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15350"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>xBytes</var>, <var>yBytes</var>) that captures <var>typedArray</var> and performs the following steps atomically when called:<ol><li>Let <var>type</var> be <emu-xref aoid="TypedArrayElementType" id="_ref_15351"><a href="indexed-collections.html#sec-typedarrayelementtype">TypedArrayElementType</a></emu-xref>(<var>typedArray</var>).</li><li>Let <var>AR</var> be the <emu-xref href="#agent-record" id="_ref_15352"><a href="executable-code-and-execution-contexts.html#agent-record">Agent Record</a></emu-xref> of the <emu-xref href="#surrounding-agent" id="_ref_15353"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref>.</li><li>Let <var>isLittleEndian</var> be <var>AR</var>.<var class="field">[[LittleEndian]]</var>.</li><li>Let <var>x</var> be <emu-xref aoid="RawBytesToNumeric" id="_ref_15354"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>type</var>, <var>xBytes</var>, <var>isLittleEndian</var>).</li><li>Let <var>y</var> be <emu-xref aoid="RawBytesToNumeric" id="_ref_15355"><a href="structured-data.html#sec-rawbytestonumeric">RawBytesToNumeric</a></emu-xref>(<var>type</var>, <var>yBytes</var>, <var>isLittleEndian</var>).</li><li>If <var>x</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_15356"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>, then<ol><li>Let <var>difference</var> be <emu-xref aoid="Number::subtract" id="_ref_15357"><a href="ecmascript-data-types-and-values.html#sec-numeric-types-number-subtract">Number::subtract</a></emu-xref>(<var>x</var>, <var>y</var>).</li></ol></li><li>Else,<ol><li><emu-xref href="#assert" id="_ref_15358"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>x</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_15359"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref>.</li><li>Let <var>difference</var> be <emu-xref aoid="BigInt::subtract" id="_ref_15360"><a href="ecmascript-data-types-and-values.html#sec-numeric-types-bigint-subtract">BigInt::subtract</a></emu-xref>(<var>x</var>, <var>y</var>).</li></ol></li><li>Let <var>differenceBytes</var> be <emu-xref aoid="NumericToRawBytes" id="_ref_15361"><a href="structured-data.html#sec-numerictorawbytes">NumericToRawBytes</a></emu-xref>(<var>type</var>, <var>difference</var>, <var>isLittleEndian</var>).</li><li><emu-xref href="#assert" id="_ref_15362"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>differenceBytes</var>, <var>xBytes</var>, and <var>yBytes</var> have the same number of elements.</li><li>Return <var>differenceBytes</var>.</li></ol></li><li>Return ? <emu-xref aoid="AtomicReadModifyWrite" id="_ref_15363"><a href="structured-data.html#sec-atomicreadmodifywrite" class="e-user-code">AtomicReadModifyWrite</a></emu-xref>(<var>typedArray</var>, <var>index</var>, <var>value</var>, <var>subtract</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.wait" type="built-in function">
|
||
<h1><span class="secnum">25.4.13</span> Atomics.wait ( <var>typedArray</var>, <var>index</var>, <var>value</var>, <var>timeout</var> )</h1>
|
||
<p>This function puts the <emu-xref href="#surrounding-agent" id="_ref_15364"><a href="executable-code-and-execution-contexts.html#surrounding-agent">surrounding agent</a></emu-xref> in a wait queue and suspends it until notified or until the wait times out, returning a String differentiating those cases.</p>
|
||
<p>It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return ? <emu-xref aoid="DoWait" id="_ref_15365"><a href="structured-data.html#sec-dowait" class="e-user-code">DoWait</a></emu-xref>(<emu-const>sync</emu-const>, <var>typedArray</var>, <var>index</var>, <var>value</var>, <var>timeout</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.waitasync" type="built-in function">
|
||
<h1><span class="secnum">25.4.14</span> Atomics.waitAsync ( <var>typedArray</var>, <var>index</var>, <var>value</var>, <var>timeout</var> )</h1>
|
||
<p>This function returns a Promise that is resolved when the calling <emu-xref href="#agent" id="_ref_15366"><a href="executable-code-and-execution-contexts.html#agent">agent</a></emu-xref> is notified or the timeout is reached.</p>
|
||
<p>It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Return ? <emu-xref aoid="DoWait" id="_ref_15367"><a href="structured-data.html#sec-dowait" class="e-user-code">DoWait</a></emu-xref>(<emu-const>async</emu-const>, <var>typedArray</var>, <var>index</var>, <var>value</var>, <var>timeout</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.notify" type="built-in function">
|
||
<h1><span class="secnum">25.4.15</span> Atomics.notify ( <var>typedArray</var>, <var>index</var>, <var>count</var> )</h1>
|
||
<p>This function notifies some <emu-xref href="#agent" id="_ref_15368"><a href="executable-code-and-execution-contexts.html#agent">agents</a></emu-xref> that are sleeping in the wait queue.</p>
|
||
<p>It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>taRecord</var> be ? <emu-xref aoid="ValidateIntegerTypedArray" id="_ref_15369"><a href="structured-data.html#sec-validateintegertypedarray">ValidateIntegerTypedArray</a></emu-xref>(<var>typedArray</var>, <emu-val>true</emu-val>).</li><li>Let <var>byteIndexInBuffer</var> be ? <emu-xref aoid="ValidateAtomicAccess" id="_ref_15370"><a href="structured-data.html#sec-validateatomicaccess" class="e-user-code">ValidateAtomicAccess</a></emu-xref>(<var>taRecord</var>, <var>index</var>).</li><li>If <var>count</var> is <emu-val>undefined</emu-val>, then<ol><li>Let <var>c</var> be +∞.</li></ol></li><li>Else,<ol><li>Let <var>intCount</var> be ? <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15371"><a href="abstract-operations.html#sec-tointegerorinfinity" class="e-user-code">ToIntegerOrInfinity</a></emu-xref>(<var>count</var>).</li><li>Let <var>c</var> be <emu-xref aoid="max" id="_ref_15372"><a href="notational-conventions.html#eqn-max">max</a></emu-xref>(<var>intCount</var>, 0).</li></ol></li><li>Let <var>buffer</var> be <var>typedArray</var>.<var class="field">[[ViewedArrayBuffer]]</var>.</li><li>Let <var>block</var> be <var>buffer</var>.<var class="field">[[ArrayBufferData]]</var>.</li><li>If <emu-xref aoid="IsSharedArrayBuffer" id="_ref_15373"><a href="structured-data.html#sec-issharedarraybuffer">IsSharedArrayBuffer</a></emu-xref>(<var>buffer</var>) is <emu-val>false</emu-val>, return <emu-val>+0</emu-val><sub>𝔽</sub>.</li><li>Let <var>WL</var> be <emu-xref aoid="GetWaiterList" id="_ref_15374"><a href="structured-data.html#sec-getwaiterlist">GetWaiterList</a></emu-xref>(<var>block</var>, <var>byteIndexInBuffer</var>).</li><li>Perform <emu-xref aoid="EnterCriticalSection" id="_ref_15375"><a href="structured-data.html#sec-entercriticalsection">EnterCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>Let <var>S</var> be <emu-xref aoid="RemoveWaiters" id="_ref_15376"><a href="structured-data.html#sec-removewaiters">RemoveWaiters</a></emu-xref>(<var>WL</var>, <var>c</var>).</li><li>For each element <var>W</var> of <var>S</var>, do<ol><li>Perform <emu-xref aoid="NotifyWaiter" id="_ref_15377"><a href="structured-data.html#sec-notifywaiter">NotifyWaiter</a></emu-xref>(<var>WL</var>, <var>W</var>).</li></ol></li><li>Perform <emu-xref aoid="LeaveCriticalSection" id="_ref_15378"><a href="structured-data.html#sec-leavecriticalsection">LeaveCriticalSection</a></emu-xref>(<var>WL</var>).</li><li>Let <var>n</var> be the number of elements in <var>S</var>.</li><li>Return <emu-xref aoid="𝔽" id="_ref_15379"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>n</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-atomics.xor" type="built-in function">
|
||
<h1><span class="secnum">25.4.16</span> Atomics.xor ( <var>typedArray</var>, <var>index</var>, <var>value</var> )</h1>
|
||
<p>This function performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>xor</var> be a new <emu-xref href="#sec-arraybuffer-notation" id="_ref_15380"><a href="structured-data.html#sec-arraybuffer-notation">read-modify-write modification function</a></emu-xref> with parameters (<var>xBytes</var>, <var>yBytes</var>) that captures nothing and performs the following steps atomically when called:<ol><li>Return <emu-xref aoid="ByteListBitwiseOp" id="_ref_15381"><a href="structured-data.html#sec-bytelistbitwiseop">ByteListBitwiseOp</a></emu-xref>(<code>^</code>, <var>xBytes</var>, <var>yBytes</var>).</li></ol></li><li>Return ? <emu-xref aoid="AtomicReadModifyWrite" id="_ref_15382"><a href="structured-data.html#sec-atomicreadmodifywrite" class="e-user-code">AtomicReadModifyWrite</a></emu-xref>(<var>typedArray</var>, <var>index</var>, <var>value</var>, <var>xor</var>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-atomics-@@tostringtag" id="sec-atomics-%symbol.tostringtag%"><span id="sec-atomics-@@tostringtag"></span>
|
||
<h1><span class="secnum">25.4.17</span> Atomics [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_15383"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"Atomics"</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-json-object">
|
||
<h1><span class="secnum">25.5</span> The JSON Object</h1>
|
||
<p>The JSON object:</p>
|
||
<ul>
|
||
<li>is <dfn tabindex="-1">%JSON%</dfn>.</li>
|
||
<li>is the initial value of the <emu-val>"JSON"</emu-val> property of the <emu-xref href="#sec-global-object" id="_ref_15384"><a href="global-object.html#sec-global-object">global object</a></emu-xref>.</li>
|
||
<li>is an <emu-xref href="#ordinary-object" id="_ref_15385"><a href="ecmascript-data-types-and-values.html#ordinary-object">ordinary object</a></emu-xref>.</li>
|
||
<li>contains two functions, <code>parse</code> and <code>stringify</code>, that are used to parse and construct JSON texts.</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_15386"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>.</li>
|
||
<li>does not have a <var class="field">[[Construct]]</var> internal method; it cannot be used as a <emu-xref href="#constructor" id="_ref_15387"><a href="ecmascript-data-types-and-values.html#constructor">constructor</a></emu-xref> with the <code>new</code> operator.</li>
|
||
<li>does not have a <var class="field">[[Call]]</var> internal method; it cannot be invoked as a function.</li>
|
||
</ul>
|
||
<p>The JSON Data Interchange Format is defined in ECMA-404. The JSON interchange format used in this specification is exactly that described by ECMA-404. Conforming implementations of <code>JSON.parse</code> and <code>JSON.stringify</code> must support the exact interchange format described in the ECMA-404 specification without any deletions or extensions to the format.</p>
|
||
|
||
<emu-clause id="sec-json.parse" type="built-in function">
|
||
<h1><span class="secnum">25.5.1</span> JSON.parse ( <var>text</var> [ , <var>reviver</var> ] )</h1>
|
||
<p>This function parses a JSON text (a JSON-formatted String) and produces an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15388"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>. The JSON format represents literals, arrays, and objects with a syntax similar to the syntax for ECMAScript literals, Array Initializers, and Object Initializers. After parsing, JSON objects are realized as ECMAScript objects. JSON arrays are realized as ECMAScript Array instances. JSON strings, numbers, booleans, and null are realized as ECMAScript Strings, Numbers, Booleans, and <emu-val>null</emu-val>.</p>
|
||
<p>The optional <var>reviver</var> parameter is a function that takes two parameters, <var>key</var> and <var>value</var>. It can filter and transform the results. It is called with each of the <var>key</var>/<var>value</var> pairs produced by the parse, and its return value is used instead of the original value. If it returns what it received, the structure is not modified. If it returns <emu-val>undefined</emu-val> then the property is deleted from the result.</p>
|
||
<emu-alg><ol><li>Let <var>jsonString</var> be ? <emu-xref aoid="ToString" id="_ref_15389"><a href="abstract-operations.html#sec-tostring" class="e-user-code">ToString</a></emu-xref>(<var>text</var>).</li><li>Let <var>unfiltered</var> be ? <emu-xref aoid="ParseJSON" id="_ref_15390"><a href="structured-data.html#sec-ParseJSON">ParseJSON</a></emu-xref>(<var>jsonString</var>).</li><li>If <emu-xref aoid="IsCallable" id="_ref_15391"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>reviver</var>) is <emu-val>false</emu-val>, return <var>unfiltered</var>.</li><li>Let <var>root</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_15392"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15393"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>).</li><li>Let <var>rootName</var> be the empty String.</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15394"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>root</var>, <var>rootName</var>, <var>unfiltered</var>).</li><li>Return ? <emu-xref aoid="InternalizeJSONProperty" id="_ref_15395"><a href="structured-data.html#sec-internalizejsonproperty" class="e-user-code">InternalizeJSONProperty</a></emu-xref>(<var>root</var>, <var>rootName</var>, <var>reviver</var>).</li></ol></emu-alg>
|
||
<p>The <emu-val>"length"</emu-val> property of this function is <emu-val>2</emu-val><sub>𝔽</sub>.</p>
|
||
|
||
<emu-clause id="sec-ParseJSON" type="abstract operation" aoid="ParseJSON">
|
||
<h1><span class="secnum">25.5.1.1</span> ParseJSON ( <var>text</var> )</h1>
|
||
<p>The abstract operation ParseJSON takes argument <var>text</var> (a String) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15396"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15397"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15398"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li id="step-json-parse-validate">If <emu-xref aoid="StringToCodePoints" id="_ref_15399"><a href="ecmascript-language-source-code.html#sec-stringtocodepoints">StringToCodePoints</a></emu-xref>(<var>text</var>) is not a valid JSON text as specified in ECMA-404, throw a <emu-val>SyntaxError</emu-val> exception.</li><li>Let <var>scriptString</var> be the <emu-xref href="#string-concatenation" id="_ref_15400"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <emu-val>"("</emu-val>, <var>text</var>, and <emu-val>");"</emu-val>.</li><li id="step-json-parse-parse">Let <var>script</var> be <emu-xref aoid="ParseText" id="_ref_15401"><a href="ecmascript-language-source-code.html#sec-parsetext">ParseText</a></emu-xref>(<var>scriptString</var>, <emu-nt id="_ref_24549"><a href="ecmascript-language-scripts-and-modules.html#prod-Script">Script</a></emu-nt>).</li><li>NOTE: The <emu-xref href="#early-error" id="_ref_15402"><a href="error-handling-and-language-extensions.html#early-error">early error</a></emu-xref> rules defined in <emu-xref href="#sec-object-initializer-static-semantics-early-errors" id="_ref_808"><a href="ecmascript-language-expressions.html#sec-object-initializer-static-semantics-early-errors">13.2.5.1</a></emu-xref> have special handling for the above invocation of <emu-xref aoid="ParseText" id="_ref_15403"><a href="ecmascript-language-source-code.html#sec-parsetext">ParseText</a></emu-xref>.</li><li><emu-xref href="#assert" id="_ref_15404"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>script</var> is a <emu-xref href="#sec-syntactic-grammar" id="_ref_15405"><a href="notational-conventions.html#sec-syntactic-grammar">Parse Node</a></emu-xref>.</li><li id="step-json-parse-eval">Let <var>result</var> be ! <emu-xref aoid="Evaluation" id="_ref_15406"><a href="syntax-directed-operations.html#sec-evaluation">Evaluation</a></emu-xref> of <var>script</var>.</li><li>NOTE: The <emu-xref aoid="PropertyDefinitionEvaluation" id="_ref_15407"><a href="ecmascript-language-expressions.html#sec-runtime-semantics-propertydefinitionevaluation">PropertyDefinitionEvaluation</a></emu-xref> semantics defined in <emu-xref href="#sec-runtime-semantics-propertydefinitionevaluation" id="_ref_809"><a href="ecmascript-language-expressions.html#sec-runtime-semantics-propertydefinitionevaluation">13.2.5.5</a></emu-xref> have special handling for the above evaluation.</li><li id="step-json-parse-assert-type"><emu-xref href="#assert" id="_ref_15408"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>result</var> is either a String, a Number, a Boolean, an Object that is defined by either an <emu-nt id="_ref_24550"><a href="ecmascript-language-expressions.html#prod-ArrayLiteral">ArrayLiteral</a></emu-nt> or an <emu-nt id="_ref_24551"><a href="ecmascript-language-expressions.html#prod-ObjectLiteral">ObjectLiteral</a></emu-nt>, or <emu-val>null</emu-val>.</li><li>Return <var>result</var>.</li></ol></emu-alg>
|
||
<p>It is not permitted for a conforming implementation of <code>JSON.parse</code> to extend the JSON grammars. If an implementation wishes to support a modified or extended JSON interchange format it must do so by defining a different parse function.</p>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>Valid JSON text is a subset of the ECMAScript <emu-nt id="_ref_24552"><a href="ecmascript-language-expressions.html#prod-PrimaryExpression">PrimaryExpression</a></emu-nt> syntax. Step <emu-xref href="#step-json-parse-validate" id="_ref_810"><a href="structured-data.html#step-json-parse-validate">1</a></emu-xref> verifies that <var>jsonString</var> conforms to that subset, and step <emu-xref href="#step-json-parse-assert-type" id="_ref_811"><a href="structured-data.html#step-json-parse-assert-type">8</a></emu-xref> asserts that evaluation returns a value of an appropriate type.</p>
|
||
<p>However, because <emu-xref href="#sec-runtime-semantics-propertydefinitionevaluation" id="_ref_812"><a href="ecmascript-language-expressions.html#sec-runtime-semantics-propertydefinitionevaluation">13.2.5.5</a></emu-xref> behaves differently during ParseJSON, the same source text can produce different results when evaluated as a <emu-nt id="_ref_24553"><a href="ecmascript-language-expressions.html#prod-PrimaryExpression">PrimaryExpression</a></emu-nt> rather than as JSON. Furthermore, the Early Error for duplicate <emu-val>"__proto__"</emu-val> properties in object literals, which likewise does not apply during ParseJSON, means that not all texts accepted by ParseJSON are valid as a <emu-nt id="_ref_24554"><a href="ecmascript-language-expressions.html#prod-PrimaryExpression">PrimaryExpression</a></emu-nt>, despite matching the grammar.</p>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>In the case where there are duplicate name Strings within an object, lexically preceding values for the same key shall be overwritten.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-internalizejsonproperty" type="abstract operation" aoid="InternalizeJSONProperty">
|
||
<h1><span class="secnum">25.5.1.2</span> InternalizeJSONProperty ( <var>holder</var>, <var>name</var>, <var>reviver</var> )</h1>
|
||
<p>The abstract operation InternalizeJSONProperty takes arguments <var>holder</var> (an Object), <var>name</var> (a String), and <var>reviver</var> (a <emu-xref href="#function-object" id="_ref_15409"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15410"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15411"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref> or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15412"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>.</p>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>This algorithm intentionally does not throw an exception if either <var class="field">[[Delete]]</var> or <emu-xref aoid="CreateDataProperty" id="_ref_15413"><a href="abstract-operations.html#sec-createdataproperty">CreateDataProperty</a></emu-xref> return <emu-val>false</emu-val>.</p>
|
||
</div></emu-note>
|
||
<p>It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>val</var> be ? <emu-xref aoid="Get" id="_ref_15414"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>holder</var>, <var>name</var>).</li><li>If <var>val</var> <emu-xref href="#sec-object-type" id="_ref_15415"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref>, then<ol><li>Let <var>isArray</var> be ? <emu-xref aoid="IsArray" id="_ref_15416"><a href="abstract-operations.html#sec-isarray">IsArray</a></emu-xref>(<var>val</var>).</li><li>If <var>isArray</var> is <emu-val>true</emu-val>, then<ol><li>Let <var>len</var> be ? <emu-xref aoid="LengthOfArrayLike" id="_ref_15417"><a href="abstract-operations.html#sec-lengthofarraylike" class="e-user-code">LengthOfArrayLike</a></emu-xref>(<var>val</var>).</li><li>Let <var>I</var> be 0.</li><li>Repeat, while <var>I</var> < <var>len</var>,<ol><li>Let <var>prop</var> be ! <emu-xref aoid="ToString" id="_ref_15418"><a href="abstract-operations.html#sec-tostring">ToString</a></emu-xref>(<emu-xref aoid="𝔽" id="_ref_15419"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>I</var>)).</li><li>Let <var>newElement</var> be ? <emu-xref aoid="InternalizeJSONProperty" id="_ref_15420"><a href="structured-data.html#sec-internalizejsonproperty" class="e-user-code">InternalizeJSONProperty</a></emu-xref>(<var>val</var>, <var>prop</var>, <var>reviver</var>).</li><li>If <var>newElement</var> is <emu-val>undefined</emu-val>, then<ol><li>Perform ? <span class="e-user-code"><var>val</var>.<var class="field">[[Delete]]</var>(<var>prop</var>)</span>.</li></ol></li><li>Else,<ol><li>Perform ? <emu-xref aoid="CreateDataProperty" id="_ref_15421"><a href="abstract-operations.html#sec-createdataproperty" class="e-user-code">CreateDataProperty</a></emu-xref>(<var>val</var>, <var>prop</var>, <var>newElement</var>).</li></ol></li><li>Set <var>I</var> to <var>I</var> + 1.</li></ol></li></ol></li><li>Else,<ol><li>Let <var>keys</var> be ? <emu-xref aoid="EnumerableOwnProperties" id="_ref_15422"><a href="abstract-operations.html#sec-enumerableownproperties" class="e-user-code">EnumerableOwnProperties</a></emu-xref>(<var>val</var>, <emu-const>key</emu-const>).</li><li>For each String <var>P</var> of <var>keys</var>, do<ol><li>Let <var>newElement</var> be ? <emu-xref aoid="InternalizeJSONProperty" id="_ref_15423"><a href="structured-data.html#sec-internalizejsonproperty" class="e-user-code">InternalizeJSONProperty</a></emu-xref>(<var>val</var>, <var>P</var>, <var>reviver</var>).</li><li>If <var>newElement</var> is <emu-val>undefined</emu-val>, then<ol><li>Perform ? <span class="e-user-code"><var>val</var>.<var class="field">[[Delete]]</var>(<var>P</var>)</span>.</li></ol></li><li>Else,<ol><li>Perform ? <emu-xref aoid="CreateDataProperty" id="_ref_15424"><a href="abstract-operations.html#sec-createdataproperty" class="e-user-code">CreateDataProperty</a></emu-xref>(<var>val</var>, <var>P</var>, <var>newElement</var>).</li></ol></li></ol></li></ol></li></ol></li><li>Return ? <emu-xref aoid="Call" id="_ref_15425"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>reviver</var>, <var>holder</var>, « <var>name</var>, <var>val</var> »).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-json.stringify" type="built-in function">
|
||
<h1><span class="secnum">25.5.2</span> JSON.stringify ( <var>value</var> [ , <var>replacer</var> [ , <var>space</var> ] ] )</h1>
|
||
<p>This function returns a String in UTF-16 encoded JSON format representing an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15426"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>, or <emu-val>undefined</emu-val>. It can take three parameters. The <var>value</var> parameter is an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15427"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>, which is usually an object or array, although it can also be a String, Boolean, Number or <emu-val>null</emu-val>. The optional <var>replacer</var> parameter is either a function that alters the way objects and arrays are stringified, or an array of Strings and Numbers that acts as an inclusion list for selecting the object properties that will be stringified. The optional <var>space</var> parameter <emu-xref href="#sec-ecmascript-language-types-string-type" id="_ref_15428"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-string-type">is a String</a></emu-xref> or Number that allows the result to have white space injected into it to improve human readability.</p>
|
||
<p>It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>stack</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15429"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Let <var>indent</var> be the empty String.</li><li>Let <var>PropertyList</var> be <emu-val>undefined</emu-val>.</li><li>Let <var>ReplacerFunction</var> be <emu-val>undefined</emu-val>.</li><li>If <var>replacer</var> <emu-xref href="#sec-object-type" id="_ref_15430"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref>, then<ol><li>If <emu-xref aoid="IsCallable" id="_ref_15431"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>replacer</var>) is <emu-val>true</emu-val>, then<ol><li>Set <var>ReplacerFunction</var> to <var>replacer</var>.</li></ol></li><li>Else,<ol><li>Let <var>isArray</var> be ? <emu-xref aoid="IsArray" id="_ref_15432"><a href="abstract-operations.html#sec-isarray">IsArray</a></emu-xref>(<var>replacer</var>).</li><li>If <var>isArray</var> is <emu-val>true</emu-val>, then<ol><li>Set <var>PropertyList</var> to a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15433"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Let <var>len</var> be ? <emu-xref aoid="LengthOfArrayLike" id="_ref_15434"><a href="abstract-operations.html#sec-lengthofarraylike" class="e-user-code">LengthOfArrayLike</a></emu-xref>(<var>replacer</var>).</li><li>Let <var>k</var> be 0.</li><li>Repeat, while <var>k</var> < <var>len</var>,<ol><li>Let <var>prop</var> be ! <emu-xref aoid="ToString" id="_ref_15435"><a href="abstract-operations.html#sec-tostring">ToString</a></emu-xref>(<emu-xref aoid="𝔽" id="_ref_15436"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>k</var>)).</li><li>Let <var>v</var> be ? <emu-xref aoid="Get" id="_ref_15437"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>replacer</var>, <var>prop</var>).</li><li>Let <var>item</var> be <emu-val>undefined</emu-val>.</li><li>If <var>v</var> <emu-xref href="#sec-ecmascript-language-types-string-type" id="_ref_15438"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-string-type">is a String</a></emu-xref>, then<ol><li>Set <var>item</var> to <var>v</var>.</li></ol></li><li>Else if <var>v</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_15439"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>, then<ol><li>Set <var>item</var> to ! <emu-xref aoid="ToString" id="_ref_15440"><a href="abstract-operations.html#sec-tostring">ToString</a></emu-xref>(<var>v</var>).</li></ol></li><li>Else if <var>v</var> <emu-xref href="#sec-object-type" id="_ref_15441"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref>, then<ol><li>If <var>v</var> has a <var class="field">[[StringData]]</var> or <var class="field">[[NumberData]]</var> internal slot, set <var>item</var> to ? <emu-xref aoid="ToString" id="_ref_15442"><a href="abstract-operations.html#sec-tostring" class="e-user-code">ToString</a></emu-xref>(<var>v</var>).</li></ol></li><li>If <var>item</var> is not <emu-val>undefined</emu-val> and <var>PropertyList</var> does not contain <var>item</var>, then<ol><li>Append <var>item</var> to <var>PropertyList</var>.</li></ol></li><li>Set <var>k</var> to <var>k</var> + 1.</li></ol></li></ol></li></ol></li></ol></li><li>If <var>space</var> <emu-xref href="#sec-object-type" id="_ref_15443"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref>, then<ol><li>If <var>space</var> has a <var class="field">[[NumberData]]</var> internal slot, then<ol><li>Set <var>space</var> to ? <emu-xref aoid="ToNumber" id="_ref_15444"><a href="abstract-operations.html#sec-tonumber" class="e-user-code">ToNumber</a></emu-xref>(<var>space</var>).</li></ol></li><li>Else if <var>space</var> has a <var class="field">[[StringData]]</var> internal slot, then<ol><li>Set <var>space</var> to ? <emu-xref aoid="ToString" id="_ref_15445"><a href="abstract-operations.html#sec-tostring" class="e-user-code">ToString</a></emu-xref>(<var>space</var>).</li></ol></li></ol></li><li>If <var>space</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_15446"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>, then<ol><li>Let <var>spaceMV</var> be ! <emu-xref aoid="ToIntegerOrInfinity" id="_ref_15447"><a href="abstract-operations.html#sec-tointegerorinfinity">ToIntegerOrInfinity</a></emu-xref>(<var>space</var>).</li><li>Set <var>spaceMV</var> to <emu-xref aoid="min" id="_ref_15448"><a href="notational-conventions.html#eqn-min">min</a></emu-xref>(10, <var>spaceMV</var>).</li><li>If <var>spaceMV</var> < 1, let <var>gap</var> be the empty String; else let <var>gap</var> be the String value containing <var>spaceMV</var> occurrences of the code unit 0x0020 (SPACE).</li></ol></li><li>Else if <var>space</var> <emu-xref href="#sec-ecmascript-language-types-string-type" id="_ref_15449"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-string-type">is a String</a></emu-xref>, then<ol><li>If the length of <var>space</var> ≤ 10, let <var>gap</var> be <var>space</var>; else let <var>gap</var> be the <emu-xref href="#substring" id="_ref_15450"><a href="ecmascript-data-types-and-values.html#substring">substring</a></emu-xref> of <var>space</var> from 0 to 10.</li></ol></li><li>Else,<ol><li>Let <var>gap</var> be the empty String.</li></ol></li><li>Let <var>wrapper</var> be <emu-xref aoid="OrdinaryObjectCreate" id="_ref_15451"><a href="ordinary-and-exotic-objects-behaviours.html#sec-ordinaryobjectcreate">OrdinaryObjectCreate</a></emu-xref>(<emu-xref href="#sec-properties-of-the-object-prototype-object" id="_ref_15452"><a href="fundamental-objects.html#sec-properties-of-the-object-prototype-object">%Object.prototype%</a></emu-xref>).</li><li>Perform ! <emu-xref aoid="CreateDataPropertyOrThrow" id="_ref_15453"><a href="abstract-operations.html#sec-createdatapropertyorthrow">CreateDataPropertyOrThrow</a></emu-xref>(<var>wrapper</var>, the empty String, <var>value</var>).</li><li>Let <var>state</var> be the <emu-xref href="#sec-json-serialization-record" id="_ref_15454"><a href="structured-data.html#sec-json-serialization-record">JSON Serialization Record</a></emu-xref> { <var class="field">[[ReplacerFunction]]</var>: <var>ReplacerFunction</var>, <var class="field">[[Stack]]</var>: <var>stack</var>, <var class="field">[[Indent]]</var>: <var>indent</var>, <var class="field">[[Gap]]</var>: <var>gap</var>, <var class="field">[[PropertyList]]</var>: <var>PropertyList</var> }.</li><li>Return ? <emu-xref aoid="SerializeJSONProperty" id="_ref_15455"><a href="structured-data.html#sec-serializejsonproperty" class="e-user-code">SerializeJSONProperty</a></emu-xref>(<var>state</var>, the empty String, <var>wrapper</var>).</li></ol></emu-alg>
|
||
<p>The <emu-val>"length"</emu-val> property of this function is <emu-val>3</emu-val><sub>𝔽</sub>.</p>
|
||
<emu-note><span class="note">Note 1</span><div class="note-contents">
|
||
<p>JSON structures are allowed to be nested to any depth, but they must be acyclic. If <var>value</var> is or contains a cyclic structure, then this function must throw a <emu-val>TypeError</emu-val> exception. This is an example of a value that cannot be stringified:</p>
|
||
<pre><code class="javascript hljs">a = [];
|
||
a[<span class="hljs-number">0</span>] = a;
|
||
my_text = <span class="hljs-variable constant_">JSON</span>.<span class="hljs-title function_">stringify</span>(a); <span class="hljs-comment">// This must throw a TypeError.</span></code></pre>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 2</span><div class="note-contents">
|
||
<p>Symbolic primitive values are rendered as follows:</p>
|
||
<ul>
|
||
<li>
|
||
The <emu-val>null</emu-val> value is rendered in JSON text as the String value <emu-val>"null"</emu-val>.
|
||
</li>
|
||
<li>
|
||
The <emu-val>undefined</emu-val> value is not rendered.
|
||
</li>
|
||
<li>
|
||
The <emu-val>true</emu-val> value is rendered in JSON text as the String value <emu-val>"true"</emu-val>.
|
||
</li>
|
||
<li>
|
||
The <emu-val>false</emu-val> value is rendered in JSON text as the String value <emu-val>"false"</emu-val>.
|
||
</li>
|
||
</ul>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 3</span><div class="note-contents">
|
||
<p>String values are wrapped in QUOTATION MARK (<code>"</code>) code units. The code units <code>"</code> and <code>\</code> are escaped with <code>\</code> prefixes. Control characters code units are replaced with escape sequences <code>\u</code>HHHH, or with the shorter forms, <code>\b</code> (BACKSPACE), <code>\f</code> (FORM FEED), <code>\n</code> (LINE FEED), <code>\r</code> (CARRIAGE RETURN), <code>\t</code> (CHARACTER TABULATION).</p>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 4</span><div class="note-contents">
|
||
<p><emu-xref href="#finite" id="_ref_15456"><a href="ecmascript-data-types-and-values.html#finite">Finite</a></emu-xref> numbers are stringified as if by calling <emu-xref aoid="ToString" id="_ref_15457"><a href="abstract-operations.html#sec-tostring">ToString</a></emu-xref>(<var>number</var>). <emu-val>NaN</emu-val> and <emu-val>Infinity</emu-val> regardless of sign are represented as the String value <emu-val>"null"</emu-val>.</p>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 5</span><div class="note-contents">
|
||
<p>Values that do not have a JSON representation (such as <emu-val>undefined</emu-val> and functions) do not produce a String. Instead they produce the <emu-val>undefined</emu-val> value. In arrays these values are represented as the String value <emu-val>"null"</emu-val>. In objects an unrepresentable value causes the property to be excluded from stringification.</p>
|
||
</div></emu-note>
|
||
<emu-note><span class="note">Note 6</span><div class="note-contents">
|
||
<p>An object is rendered as U+007B (LEFT CURLY BRACKET) followed by zero or more properties, separated with a U+002C (COMMA), closed with a U+007D (RIGHT CURLY BRACKET). A property is a quoted String representing the <emu-xref href="#property-name" id="_ref_15458"><a href="ecmascript-data-types-and-values.html#property-name">property name</a></emu-xref>, a U+003A (COLON), and then the stringified property value. An array is rendered as an opening U+005B (LEFT SQUARE BRACKET) followed by zero or more values, separated with a U+002C (COMMA), closed with a U+005D (RIGHT SQUARE BRACKET).</p>
|
||
</div></emu-note>
|
||
|
||
<emu-clause id="sec-json-serialization-record">
|
||
<h1><span class="secnum">25.5.2.1</span> JSON Serialization Record</h1>
|
||
<p>A <dfn variants="JSON Serialization Records" tabindex="-1">JSON Serialization Record</dfn> is a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15459"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">Record</a></emu-xref> value used to enable serialization to the JSON format.</p>
|
||
<p>JSON Serialization Records have the fields listed in <emu-xref href="#table-json-serialization-record" id="_ref_813"><a href="structured-data.html#table-json-serialization-record">Table 75</a></emu-xref>.</p>
|
||
<emu-table id="table-json-serialization-record" caption="JSON Serialization Record Fields"><figure><figcaption>Table 75: <emu-xref href="#sec-json-serialization-record" id="_ref_15460"><a href="structured-data.html#sec-json-serialization-record">JSON Serialization Record</a></emu-xref> Fields</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>Field Name</th>
|
||
<th>Value</th>
|
||
<th>Meaning</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td><var class="field">[[ReplacerFunction]]</var></td>
|
||
<td>a <emu-xref href="#function-object" id="_ref_15461"><a href="ecmascript-data-types-and-values.html#function-object">function object</a></emu-xref> or <emu-val>undefined</emu-val></td>
|
||
<td>A function that can supply replacement values for object properties (from JSON.stringify's <var>replacer</var> parameter).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[PropertyList]]</var></td>
|
||
<td>either a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15462"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of Strings or <emu-val>undefined</emu-val></td>
|
||
<td>The names of properties to include when serializing a non-array object (from JSON.stringify's <var>replacer</var> parameter).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[Gap]]</var></td>
|
||
<td>a String</td>
|
||
<td>The unit of indentation (from JSON.stringify's <var>space</var> parameter).</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[Stack]]</var></td>
|
||
<td>a <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15463"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref> of Objects</td>
|
||
<td>The set of nested objects that are in the process of being serialized. Used to detect cyclic structures.</td>
|
||
</tr>
|
||
<tr>
|
||
<td><var class="field">[[Indent]]</var></td>
|
||
<td>a String</td>
|
||
<td>The current indentation.</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-serializejsonproperty" type="abstract operation" aoid="SerializeJSONProperty">
|
||
<h1><span class="secnum">25.5.2.2</span> SerializeJSONProperty ( <var>state</var>, <var>key</var>, <var>holder</var> )</h1>
|
||
<p>The abstract operation SerializeJSONProperty takes arguments <var>state</var> (a <emu-xref href="#sec-json-serialization-record" id="_ref_15464"><a href="structured-data.html#sec-json-serialization-record">JSON Serialization Record</a></emu-xref>), <var>key</var> (a String), and <var>holder</var> (an Object) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15465"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> either a String or <emu-val>undefined</emu-val>, or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15466"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>value</var> be ? <emu-xref aoid="Get" id="_ref_15467"><a href="abstract-operations.html#sec-get-o-p" class="e-user-code">Get</a></emu-xref>(<var>holder</var>, <var>key</var>).</li><li>If <var>value</var> <emu-xref href="#sec-object-type" id="_ref_15468"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref> or <var>value</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_15469"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref>, then<ol><li>Let <var>toJSON</var> be ? <emu-xref aoid="GetV" id="_ref_15470"><a href="abstract-operations.html#sec-getv" class="e-user-code">GetV</a></emu-xref>(<var>value</var>, <emu-val>"toJSON"</emu-val>).</li><li>If <emu-xref aoid="IsCallable" id="_ref_15471"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>toJSON</var>) is <emu-val>true</emu-val>, then<ol><li>Set <var>value</var> to ? <emu-xref aoid="Call" id="_ref_15472"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>toJSON</var>, <var>value</var>, « <var>key</var> »).</li></ol></li></ol></li><li>If <var>state</var>.<var class="field">[[ReplacerFunction]]</var> is not <emu-val>undefined</emu-val>, then<ol><li>Set <var>value</var> to ? <emu-xref aoid="Call" id="_ref_15473"><a href="abstract-operations.html#sec-call" class="e-user-code">Call</a></emu-xref>(<var>state</var>.<var class="field">[[ReplacerFunction]]</var>, <var>holder</var>, « <var>key</var>, <var>value</var> »).</li></ol></li><li>If <var>value</var> <emu-xref href="#sec-object-type" id="_ref_15474"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref>, then<ol><li>If <var>value</var> has a <var class="field">[[NumberData]]</var> internal slot, then<ol><li>Set <var>value</var> to ? <emu-xref aoid="ToNumber" id="_ref_15475"><a href="abstract-operations.html#sec-tonumber" class="e-user-code">ToNumber</a></emu-xref>(<var>value</var>).</li></ol></li><li>Else if <var>value</var> has a <var class="field">[[StringData]]</var> internal slot, then<ol><li>Set <var>value</var> to ? <emu-xref aoid="ToString" id="_ref_15476"><a href="abstract-operations.html#sec-tostring" class="e-user-code">ToString</a></emu-xref>(<var>value</var>).</li></ol></li><li>Else if <var>value</var> has a <var class="field">[[BooleanData]]</var> internal slot, then<ol><li>Set <var>value</var> to <var>value</var>.<var class="field">[[BooleanData]]</var>.</li></ol></li><li>Else if <var>value</var> has a <var class="field">[[BigIntData]]</var> internal slot, then<ol><li>Set <var>value</var> to <var>value</var>.<var class="field">[[BigIntData]]</var>.</li></ol></li></ol></li><li>If <var>value</var> is <emu-val>null</emu-val>, return <emu-val>"null"</emu-val>.</li><li>If <var>value</var> is <emu-val>true</emu-val>, return <emu-val>"true"</emu-val>.</li><li>If <var>value</var> is <emu-val>false</emu-val>, return <emu-val>"false"</emu-val>.</li><li>If <var>value</var> <emu-xref href="#sec-ecmascript-language-types-string-type" id="_ref_15477"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-string-type">is a String</a></emu-xref>, return <emu-xref aoid="QuoteJSONString" id="_ref_15478"><a href="structured-data.html#sec-quotejsonstring">QuoteJSONString</a></emu-xref>(<var>value</var>).</li><li>If <var>value</var> <emu-xref href="#sec-ecmascript-language-types-number-type" id="_ref_15479"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-number-type">is a Number</a></emu-xref>, then<ol><li>If <var>value</var> is <emu-xref href="#finite" id="_ref_15480"><a href="ecmascript-data-types-and-values.html#finite">finite</a></emu-xref>, return ! <emu-xref aoid="ToString" id="_ref_15481"><a href="abstract-operations.html#sec-tostring">ToString</a></emu-xref>(<var>value</var>).</li><li>Return <emu-val>"null"</emu-val>.</li></ol></li><li>If <var>value</var> <emu-xref href="#sec-ecmascript-language-types-bigint-type" id="_ref_15482"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-bigint-type">is a BigInt</a></emu-xref>, throw a <emu-val>TypeError</emu-val> exception.</li><li>If <var>value</var> <emu-xref href="#sec-object-type" id="_ref_15483"><a href="ecmascript-data-types-and-values.html#sec-object-type">is an Object</a></emu-xref> and <emu-xref aoid="IsCallable" id="_ref_15484"><a href="abstract-operations.html#sec-iscallable">IsCallable</a></emu-xref>(<var>value</var>) is <emu-val>false</emu-val>, then<ol><li>Let <var>isArray</var> be ? <emu-xref aoid="IsArray" id="_ref_15485"><a href="abstract-operations.html#sec-isarray">IsArray</a></emu-xref>(<var>value</var>).</li><li>If <var>isArray</var> is <emu-val>true</emu-val>, return ? <emu-xref aoid="SerializeJSONArray" id="_ref_15486"><a href="structured-data.html#sec-serializejsonarray" class="e-user-code">SerializeJSONArray</a></emu-xref>(<var>state</var>, <var>value</var>).</li><li>Return ? <emu-xref aoid="SerializeJSONObject" id="_ref_15487"><a href="structured-data.html#sec-serializejsonobject" class="e-user-code">SerializeJSONObject</a></emu-xref>(<var>state</var>, <var>value</var>).</li></ol></li><li>Return <emu-val>undefined</emu-val>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-quotejsonstring" type="abstract operation" aoid="QuoteJSONString">
|
||
<h1><span class="secnum">25.5.2.3</span> QuoteJSONString ( <var>value</var> )</h1>
|
||
<p>The abstract operation QuoteJSONString takes argument <var>value</var> (a String) and returns a String. It wraps <var>value</var> in 0x0022 (QUOTATION MARK) code units and escapes certain other code units within it. This operation interprets <var>value</var> as a sequence of UTF-16 encoded code points, as described in <emu-xref href="#sec-ecmascript-language-types-string-type" id="_ref_814"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types-string-type">6.1.4</a></emu-xref>. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>product</var> be the String value consisting solely of the code unit 0x0022 (QUOTATION MARK).</li><li>For each code point <var>C</var> of <emu-xref aoid="StringToCodePoints" id="_ref_15488"><a href="ecmascript-language-source-code.html#sec-stringtocodepoints">StringToCodePoints</a></emu-xref>(<var>value</var>), do<ol><li>If <var>C</var> is listed in the “Code Point” column of <emu-xref href="#table-json-single-character-escapes" id="_ref_815"><a href="structured-data.html#table-json-single-character-escapes">Table 76</a></emu-xref>, then<ol><li>Set <var>product</var> to the <emu-xref href="#string-concatenation" id="_ref_15489"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>product</var> and the escape sequence for <var>C</var> as specified in the “Escape Sequence” column of the corresponding row.</li></ol></li><li>Else if <var>C</var> has a numeric value less than 0x0020 (SPACE) or <var>C</var> has the same numeric value as a <emu-xref href="#leading-surrogate" id="_ref_15490"><a href="ecmascript-data-types-and-values.html#leading-surrogate">leading surrogate</a></emu-xref> or <emu-xref href="#trailing-surrogate" id="_ref_15491"><a href="ecmascript-data-types-and-values.html#trailing-surrogate">trailing surrogate</a></emu-xref>, then<ol><li>Let <var>unit</var> be the code unit whose numeric value is the numeric value of <var>C</var>.</li><li>Set <var>product</var> to the <emu-xref href="#string-concatenation" id="_ref_15492"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>product</var> and <emu-xref aoid="UnicodeEscape" id="_ref_15493"><a href="structured-data.html#sec-unicodeescape">UnicodeEscape</a></emu-xref>(<var>unit</var>).</li></ol></li><li>Else,<ol><li>Set <var>product</var> to the <emu-xref href="#string-concatenation" id="_ref_15494"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>product</var> and <emu-xref aoid="UTF16EncodeCodePoint" id="_ref_15495"><a href="ecmascript-language-source-code.html#sec-utf16encodecodepoint">UTF16EncodeCodePoint</a></emu-xref>(<var>C</var>).</li></ol></li></ol></li><li>Set <var>product</var> to the <emu-xref href="#string-concatenation" id="_ref_15496"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>product</var> and the code unit 0x0022 (QUOTATION MARK).</li><li>Return <var>product</var>.</li></ol></emu-alg>
|
||
<emu-table id="table-json-single-character-escapes" caption="JSON Single Character Escape Sequences"><figure><figcaption>Table 76: JSON Single Character Escape Sequences</figcaption>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th>
|
||
Code Point
|
||
</th>
|
||
<th>
|
||
Unicode Character Name
|
||
</th>
|
||
<th>
|
||
Escape Sequence
|
||
</th>
|
||
</tr>
|
||
</thead>
|
||
<tbody><tr>
|
||
<td>
|
||
U+0008
|
||
</td>
|
||
<td>
|
||
BACKSPACE
|
||
</td>
|
||
<td>
|
||
<code>\b</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
U+0009
|
||
</td>
|
||
<td>
|
||
CHARACTER TABULATION
|
||
</td>
|
||
<td>
|
||
<code>\t</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
U+000A
|
||
</td>
|
||
<td>
|
||
LINE FEED (LF)
|
||
</td>
|
||
<td>
|
||
<code>\n</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
U+000C
|
||
</td>
|
||
<td>
|
||
FORM FEED (FF)
|
||
</td>
|
||
<td>
|
||
<code>\f</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
U+000D
|
||
</td>
|
||
<td>
|
||
CARRIAGE RETURN (CR)
|
||
</td>
|
||
<td>
|
||
<code>\r</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
U+0022
|
||
</td>
|
||
<td>
|
||
QUOTATION MARK
|
||
</td>
|
||
<td>
|
||
<code>\"</code>
|
||
</td>
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
U+005C
|
||
</td>
|
||
<td>
|
||
REVERSE SOLIDUS
|
||
</td>
|
||
<td>
|
||
<code>\\</code>
|
||
</td>
|
||
</tr>
|
||
</tbody></table>
|
||
</figure></emu-table>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-unicodeescape" type="abstract operation" aoid="UnicodeEscape">
|
||
<h1><span class="secnum">25.5.2.4</span> UnicodeEscape ( <var>C</var> )</h1>
|
||
<p>The abstract operation UnicodeEscape takes argument <var>C</var> (a code unit) and returns a String. It represents <var>C</var> as a Unicode escape sequence. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>Let <var>n</var> be the numeric value of <var>C</var>.</li><li><emu-xref href="#assert" id="_ref_15497"><a href="notational-conventions.html#assert">Assert</a></emu-xref>: <var>n</var> ≤ 0xFFFF.</li><li>Let <var>hex</var> be the String representation of <var>n</var>, formatted as a lowercase hexadecimal number.</li><li>Return the <emu-xref href="#string-concatenation" id="_ref_15498"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of the code unit 0x005C (REVERSE SOLIDUS), <emu-val>"u"</emu-val>, and <emu-xref aoid="StringPad" id="_ref_15499"><a href="text-processing.html#sec-stringpad">StringPad</a></emu-xref>(<var>hex</var>, 4, <emu-val>"0"</emu-val>, <emu-const>start</emu-const>).</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-serializejsonobject" type="abstract operation" aoid="SerializeJSONObject">
|
||
<h1><span class="secnum">25.5.2.5</span> SerializeJSONObject ( <var>state</var>, <var>value</var> )</h1>
|
||
<p>The abstract operation SerializeJSONObject takes arguments <var>state</var> (a <emu-xref href="#sec-json-serialization-record" id="_ref_15500"><a href="structured-data.html#sec-json-serialization-record">JSON Serialization Record</a></emu-xref>) and <var>value</var> (an Object) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15501"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> a String or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15502"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It serializes an object. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>state</var>.<var class="field">[[Stack]]</var> contains <var>value</var>, throw a <emu-val>TypeError</emu-val> exception because the structure is cyclical.</li><li>Append <var>value</var> to <var>state</var>.<var class="field">[[Stack]]</var>.</li><li>Let <var>stepBack</var> be <var>state</var>.<var class="field">[[Indent]]</var>.</li><li>Set <var>state</var>.<var class="field">[[Indent]]</var> to the <emu-xref href="#string-concatenation" id="_ref_15503"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>state</var>.<var class="field">[[Indent]]</var> and <var>state</var>.<var class="field">[[Gap]]</var>.</li><li>If <var>state</var>.<var class="field">[[PropertyList]]</var> is not <emu-val>undefined</emu-val>, then<ol><li>Let <var>K</var> be <var>state</var>.<var class="field">[[PropertyList]]</var>.</li></ol></li><li>Else,<ol><li>Let <var>K</var> be ? <emu-xref aoid="EnumerableOwnProperties" id="_ref_15504"><a href="abstract-operations.html#sec-enumerableownproperties" class="e-user-code">EnumerableOwnProperties</a></emu-xref>(<var>value</var>, <emu-const>key</emu-const>).</li></ol></li><li>Let <var>partial</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15505"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>For each element <var>P</var> of <var>K</var>, do<ol><li>Let <var>strP</var> be ? <emu-xref aoid="SerializeJSONProperty" id="_ref_15506"><a href="structured-data.html#sec-serializejsonproperty" class="e-user-code">SerializeJSONProperty</a></emu-xref>(<var>state</var>, <var>P</var>, <var>value</var>).</li><li>If <var>strP</var> is not <emu-val>undefined</emu-val>, then<ol><li>Let <var>member</var> be <emu-xref aoid="QuoteJSONString" id="_ref_15507"><a href="structured-data.html#sec-quotejsonstring">QuoteJSONString</a></emu-xref>(<var>P</var>).</li><li>Set <var>member</var> to the <emu-xref href="#string-concatenation" id="_ref_15508"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>member</var> and <emu-val>":"</emu-val>.</li><li>If <var>state</var>.<var class="field">[[Gap]]</var> is not the empty String, then<ol><li>Set <var>member</var> to the <emu-xref href="#string-concatenation" id="_ref_15509"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>member</var> and the code unit 0x0020 (SPACE).</li></ol></li><li>Set <var>member</var> to the <emu-xref href="#string-concatenation" id="_ref_15510"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>member</var> and <var>strP</var>.</li><li>Append <var>member</var> to <var>partial</var>.</li></ol></li></ol></li><li>If <var>partial</var> is empty, then<ol><li>Let <var>final</var> be <emu-val>"{}"</emu-val>.</li></ol></li><li>Else,<ol><li>If <var>state</var>.<var class="field">[[Gap]]</var> is the empty String, then<ol><li>Let <var>properties</var> be the String value formed by concatenating all the element Strings of <var>partial</var> with each adjacent pair of Strings separated with the code unit 0x002C (COMMA). A comma is not inserted either before the first String or after the last String.</li><li>Let <var>final</var> be the <emu-xref href="#string-concatenation" id="_ref_15511"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <emu-val>"{"</emu-val>, <var>properties</var>, and <emu-val>"}"</emu-val>.</li></ol></li><li>Else,<ol><li>Let <var>separator</var> be the <emu-xref href="#string-concatenation" id="_ref_15512"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of the code unit 0x002C (COMMA), the code unit 0x000A (LINE FEED), and <var>state</var>.<var class="field">[[Indent]]</var>.</li><li>Let <var>properties</var> be the String value formed by concatenating all the element Strings of <var>partial</var> with each adjacent pair of Strings separated with <var>separator</var>. The <var>separator</var> String is not inserted either before the first String or after the last String.</li><li>Let <var>final</var> be the <emu-xref href="#string-concatenation" id="_ref_15513"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <emu-val>"{"</emu-val>, the code unit 0x000A (LINE FEED), <var>state</var>.<var class="field">[[Indent]]</var>, <var>properties</var>, the code unit 0x000A (LINE FEED), <var>stepBack</var>, and <emu-val>"}"</emu-val>.</li></ol></li></ol></li><li>Remove the last element of <var>state</var>.<var class="field">[[Stack]]</var>.</li><li>Set <var>state</var>.<var class="field">[[Indent]]</var> to <var>stepBack</var>.</li><li>Return <var>final</var>.</li></ol></emu-alg>
|
||
</emu-clause>
|
||
|
||
<emu-clause id="sec-serializejsonarray" type="abstract operation" aoid="SerializeJSONArray">
|
||
<h1><span class="secnum">25.5.2.6</span> SerializeJSONArray ( <var>state</var>, <var>value</var> )</h1>
|
||
<p>The abstract operation SerializeJSONArray takes arguments <var>state</var> (a <emu-xref href="#sec-json-serialization-record" id="_ref_15514"><a href="structured-data.html#sec-json-serialization-record">JSON Serialization Record</a></emu-xref>) and <var>value</var> (an <emu-xref href="#sec-ecmascript-language-types" id="_ref_15515"><a href="ecmascript-data-types-and-values.html#sec-ecmascript-language-types">ECMAScript language value</a></emu-xref>) and returns either a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15516"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">normal completion containing</a></emu-xref> a String or a <emu-xref href="#sec-completion-record-specification-type" id="_ref_15517"><a href="ecmascript-data-types-and-values.html#sec-completion-record-specification-type">throw completion</a></emu-xref>. It serializes an array. It performs the following steps when called:</p>
|
||
<emu-alg><ol><li>If <var>state</var>.<var class="field">[[Stack]]</var> contains <var>value</var>, throw a <emu-val>TypeError</emu-val> exception because the structure is cyclical.</li><li>Append <var>value</var> to <var>state</var>.<var class="field">[[Stack]]</var>.</li><li>Let <var>stepBack</var> be <var>state</var>.<var class="field">[[Indent]]</var>.</li><li>Set <var>state</var>.<var class="field">[[Indent]]</var> to the <emu-xref href="#string-concatenation" id="_ref_15518"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <var>state</var>.<var class="field">[[Indent]]</var> and <var>state</var>.<var class="field">[[Gap]]</var>.</li><li>Let <var>partial</var> be a new empty <emu-xref href="#sec-list-and-record-specification-type" id="_ref_15519"><a href="ecmascript-data-types-and-values.html#sec-list-and-record-specification-type">List</a></emu-xref>.</li><li>Let <var>len</var> be ? <emu-xref aoid="LengthOfArrayLike" id="_ref_15520"><a href="abstract-operations.html#sec-lengthofarraylike" class="e-user-code">LengthOfArrayLike</a></emu-xref>(<var>value</var>).</li><li>Let <var>index</var> be 0.</li><li>Repeat, while <var>index</var> < <var>len</var>,<ol><li>Let <var>strP</var> be ? <emu-xref aoid="SerializeJSONProperty" id="_ref_15521"><a href="structured-data.html#sec-serializejsonproperty" class="e-user-code">SerializeJSONProperty</a></emu-xref>(<var>state</var>, ! <emu-xref aoid="ToString" id="_ref_15522"><a href="abstract-operations.html#sec-tostring">ToString</a></emu-xref>(<emu-xref aoid="𝔽" id="_ref_15523"><a href="notational-conventions.html#%F0%9D%94%BD">𝔽</a></emu-xref>(<var>index</var>)), <var>value</var>).</li><li>If <var>strP</var> is <emu-val>undefined</emu-val>, then<ol><li>Append <emu-val>"null"</emu-val> to <var>partial</var>.</li></ol></li><li>Else,<ol><li>Append <var>strP</var> to <var>partial</var>.</li></ol></li><li>Set <var>index</var> to <var>index</var> + 1.</li></ol></li><li>If <var>partial</var> is empty, then<ol><li>Let <var>final</var> be <emu-val>"[]"</emu-val>.</li></ol></li><li>Else,<ol><li>If <var>state</var>.<var class="field">[[Gap]]</var> is the empty String, then<ol><li>Let <var>properties</var> be the String value formed by concatenating all the element Strings of <var>partial</var> with each adjacent pair of Strings separated with the code unit 0x002C (COMMA). A comma is not inserted either before the first String or after the last String.</li><li>Let <var>final</var> be the <emu-xref href="#string-concatenation" id="_ref_15524"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <emu-val>"["</emu-val>, <var>properties</var>, and <emu-val>"]"</emu-val>.</li></ol></li><li>Else,<ol><li>Let <var>separator</var> be the <emu-xref href="#string-concatenation" id="_ref_15525"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of the code unit 0x002C (COMMA), the code unit 0x000A (LINE FEED), and <var>state</var>.<var class="field">[[Indent]]</var>.</li><li>Let <var>properties</var> be the String value formed by concatenating all the element Strings of <var>partial</var> with each adjacent pair of Strings separated with <var>separator</var>. The <var>separator</var> String is not inserted either before the first String or after the last String.</li><li>Let <var>final</var> be the <emu-xref href="#string-concatenation" id="_ref_15526"><a href="ecmascript-data-types-and-values.html#string-concatenation">string-concatenation</a></emu-xref> of <emu-val>"["</emu-val>, the code unit 0x000A (LINE FEED), <var>state</var>.<var class="field">[[Indent]]</var>, <var>properties</var>, the code unit 0x000A (LINE FEED), <var>stepBack</var>, and <emu-val>"]"</emu-val>.</li></ol></li></ol></li><li>Remove the last element of <var>state</var>.<var class="field">[[Stack]]</var>.</li><li>Set <var>state</var>.<var class="field">[[Indent]]</var> to <var>stepBack</var>.</li><li>Return <var>final</var>.</li></ol></emu-alg>
|
||
<emu-note><span class="note">Note</span><div class="note-contents">
|
||
<p>The representation of arrays includes only the elements in the <emu-xref href="#interval" id="_ref_15527"><a href="notational-conventions.html#interval">interval</a></emu-xref> from <emu-val>+0</emu-val><sub>𝔽</sub> (inclusive) to <code>array.length</code> (exclusive). Properties whose keys are not <emu-xref href="#array-index" id="_ref_15528"><a href="ecmascript-data-types-and-values.html#array-index">array indices</a></emu-xref> are excluded from the stringification. An array is stringified as an opening LEFT SQUARE BRACKET, elements separated by COMMA, and a closing RIGHT SQUARE BRACKET.</p>
|
||
</div></emu-note>
|
||
</emu-clause>
|
||
</emu-clause>
|
||
|
||
<emu-clause oldids="sec-json-@@tostringtag" id="sec-json-%symbol.tostringtag%"><span id="sec-json-@@tostringtag"></span>
|
||
<h1><span class="secnum">25.5.3</span> JSON [ %Symbol.toStringTag% ]</h1>
|
||
<p>The initial value of the <emu-xref href="#sec-well-known-symbols" id="_ref_15529"><a href="ecmascript-data-types-and-values.html#sec-well-known-symbols">%Symbol.toStringTag%</a></emu-xref> property is the String value <emu-val>"JSON"</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></div></body></html> |