?
u
/
We extend the ArrayBuffer
and SharedArrayBuffer
constructors to take an additional maximum byte length, which would construct dynamically resizable and growable array buffers, respectively. In addition, a transfer
method is added to the ArrayBuffer
prototype.
The abstract operation DetachArrayBuffer takes argument arrayBuffer (an ArrayBuffer) and optional argument key. It performs the following steps when called:
Detaching an ArrayBuffer instance disassociates the Data Block used as its backing store from the instance and sets the byte length of the buffer to 0. No operations defined by this specification use the DetachArrayBuffer abstract operation. However, an ECMAScript host or implementation may define such operations.
The abstract operation AllocateArrayBuffer takes arguments constructor and byteLength (a non-negative integer) and optional argument maxByteLength (a non-negative integer or
The abstract operation ArrayBufferByteLength takes arguments arrayBuffer (an ArrayBuffer) and order (
The abstract operation MakeIdempotentArrayBufferByteLengthGetter takes argument order (
The abstract operation IsResizableArrayBuffer takes argument arrayBuffer (an ArrayBuffer). It performs the following steps when called:
The abstract operation GetArrayBufferMaxByteLengthOption takes argument options. It performs the following steps when called:
"maxByteLength"
).The host-defined abstract operation HostResizeArrayBuffer takes arguments buffer (an ArrayBuffer) and newByteLength (a non-negative integer). The host-defined abstract operation HostResizeArrayBuffer takes arguments buffer (an ArrayBuffer object) and newByteLength. It gives the host an opportunity to perform implementation-defined resizing of buffer. If the host chooses not to handle resizing of buffer, it may return
The implementation of HostResizeArrayBuffer must conform to the following requirements:
The default implementation of HostResizeArrayBuffer is to return
When the ArrayBuffer
function is called with argument length and optional argument options, the following steps are taken:
ArrayBuffer[@@species]
is an accessor property whose set accessor function is
The value of the
ArrayBuffer prototype methods normally use their
ArrayBuffer.prototype.maxByteLength
is an accessor property whose set accessor function is
ArrayBuffer.prototype.resizable
is an accessor property whose set accessor function is
The following steps are taken:
The following steps are taken:
The following steps are taken:
realloc
.The transfer
method intentionally does not honor the @@species property when creating derived objects.
The abstract operation AllocateSharedArrayBuffer takes arguments constructor and byteLength (a non-negative integer) and optional argument maxByteLength (a non-negative integer or
The host-defined abstract operation HostGrowSharedArrayBuffer takes arguments buffer and newByteLength. It gives the host an opportunity to perform implementation-defined growing of buffer. If the host chooses not to handle resizing of buffer, it may return
The implementation of HostGrowSharedArrayBuffer must conform to the following requirements:
SharedArrayBuffer.prototype.grow
are not "lost", i.e. silently do nothing.The default implementation of HostGrowSharedArrayBuffer is to return
The second requirement above is intentionally vague about how or when the current byte length of buffer 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, SharedArrayBuffer.prototype.grow itself does not perform bounds checking on newByteLength before calling HostGrowSharedArrayBuffer, nor is there a requirement on when the current byte length is read.
This is in contrast with
When the SharedArrayBuffer
function is called with argument length and optional argument options, the following steps are taken:
SharedArrayBuffer.prototype.byteLength
is an accessor property whose set accessor function is
SharedArrayBuffer.prototype.growable
is an accessor property whose set accessor function is
SharedArrayBuffer.prototype.maxByteLength
is an accessor property whose set accessor function is
The following steps are taken:
sab.grow(10)
and sab.grow(20)
. One of the two calls is guaranteed to win the race. The call to sab.grow(10)
will never shrink sab
even if sab.grow(20)
happened first.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 ReadModifyWriteSharedMemory event (i.e. a successful compare-exchange) is always added into the candidate execution.
Many of the above steps are shared with the algorithm steps of Atomics.compareExchange and should be refactored when merged into the full specification.
The following steps are taken:
The [[OwnPropertyKeys]] internal method of an Integer-Indexed exotic object O takes no arguments. It performs the following steps when called:
The abstract operation IsValidIntegerIndex takes arguments O (an Integer-Indexed exotic object) and index (a Number). It performs the following steps when called:
The abstract operation IntegerIndexedObjectByteLength takes arguments O (an Integer-Indexed exotic object) and getBufferByteLength (an Abstract Closure). It performs the following steps when called:
The abstract operation IntegerIndexedObjectLength takes arguments O (an Integer-Indexed exotic object) and getBufferByteLength (an Abstract Closure). It performs the following steps when called:
The abstract operation IsIntegerIndexedObjectOutOfBounds takes arguments O (an Integer-Indexed exotic object) and getBufferByteLength (an Abstract Closure). It checks if any of the object's numeric properties reference a value at an index not contained within the underlying data block's bounds. It performs the following steps when called:
The abstract operation ValidateTypedArray takes argument O. It performs the following steps when called:
%TypedArray%.prototype.byteLength
is an accessor property whose set accessor function is
%TypedArray%.prototype.byteOffset
is an accessor property whose set accessor function is
%TypedArray%.prototype.length
is an accessor property whose set accessor function is
This function is not generic. The
The interpretation and use of the arguments of %TypedArray%.prototype.copyWithin
are the same as for Array.prototype.copyWithin
as defined in
When the copyWithin
method is called, the following steps are taken:
The interpretation and use of the arguments of %TypedArray%.prototype.fill
are the same as for Array.prototype.fill
as defined in
When the fill
method is called, the following steps are taken:
The interpretation and use of the arguments of %TypedArray%.prototype.slice
are the same as for Array.prototype.slice
as defined in
When the slice
method is called, the following steps are taken:
This function is not generic. The
%TypedArray%.prototype.sort
is a distinct function that, except as described below, implements the same requirements as those of Array.prototype.sort
as defined in .prototype.sort
specification may be optimized with the knowledge that the
This function is not generic. The
Upon entry, the following steps are performed to initialize evaluation of the sort
function. These steps are used instead of steps
The following version of SortCompare is used by %TypedArray%.prototype.sort
. It performs a numeric comparison rather than the string comparison used in
The abstract operation TypedArraySortCompare takes arguments x and y. It also has access to the obj, comparefn, and buffer values of the current invocation of the sort
method. It performs the following steps when called:
Because
Returns a new TypedArray whose element type is the same as this TypedArray and whose ArrayBuffer is the same as the ArrayBuffer of this TypedArray, referencing the elements at begin, inclusive, up to end, exclusive. If either begin or end is negative, it refers to an index from the end of the array, as opposed to from the beginning.
When the subarray
method is called, the following steps are taken:
This function is not generic. The
The abstract operation SetTypedArrayFromTypedArray takes arguments target (a TypedArray), targetOffset (a non-negative integer or +∞), and source (a TypedArray). It sets multiple values in target, starting at index targetOffset, reading the values from source. It performs the following steps when called:
The abstract operation InitializeTypedArrayFromTypedArray takes arguments O (a TypedArray) and srcArray (a TypedArray). It performs the following steps when called:
The abstract operation InitializeTypedArrayFromArrayBuffer takes arguments O (a TypedArray), buffer (an ArrayBuffer or a SharedArrayBuffer), byteOffset (an ECMAScript language value), and length (an ECMAScript language value). It performs the following steps when called:
The abstract operation GetViewByteLength takes arguments view (a DataView) and getBufferByteLength (an Abstract Closure). It performs the following steps when called:
The abstract operation IsViewOutOfBounds takes arguments view (a DataView) and getBufferByteLength (an Abstract Closure). It performs the following steps when called:
The abstract operation GetViewValue takes arguments view, requestIndex, isLittleEndian, and type. It is used by functions on DataView instances to retrieve values from the view's buffer. It performs the following steps when called:
The abstract operation SetViewValue takes arguments view, requestIndex, isLittleEndian, type, and value. It is used by functions on DataView instances to store values into the view's buffer. It performs the following steps when called:
When the DataView
function is called with at least one argument buffer, the following steps are taken:
DataView.prototype.byteLength
is an accessor property whose set accessor function is
DataView.prototype.byteOffset
is an accessor property whose set accessor function is
The abstract operation ValidateAtomicAccess takes arguments typedArray (a TypedArray) and requestIndex. It performs the following steps when called:
The following are guidelines for ECMAScript programmers working with resizable ArrayBuffer and growable SharedArrayBuffer.
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.
When choosing a value for the "maxByteLength"
option for resizable ArrayBuffer and growable SharedArrayBuffer, we recommend that the smallest possible size for the application be chosen. We recommend that "maxByteLength"
does not exceed 1073741824, or 1GiB.
Please note that successfully constructing a ResizableArrayBuffer or a growable SharedArrayBuffer for a particular maximum size does not guarantee that future resizes and grows will succeed.
The following are guidelines for ECMAScript implementers implementing resizable ArrayBuffer.
Resizable ArrayBuffer 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 constructor's "maxByteLength"
option.
If a host is multi-tenanted (i.e. it runs many JavaScript 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 "maxByteLength"
≥ 1GiB to 1.5GiB. This is to reduce the likelihood a single application can exhaust the virtual memory address space and to reduce interoperability risks.
If a host does not have virtual memory, such as those running on embedded devices without an MMU, or if a host only implements resizing by copying, it may accept any Number value for the "maxByteLength"
option. However, we recommend a
The following are guidelines for ECMAScript implementers implementing growable SharedArrayBuffer.
We recommend growable SharedArrayBuffer be implemented as in-place growth via reserving virtual memory up front.
Because grow operations can be concurrent with memory accesses on a growable SharedArrayBuffer, the constraints of the memory model 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 growable SharedArrayBuffer 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.
Grown memory must appear zeroed from the moment of its creation, including to any racy concurrent accesses. This can be accomplished via zero-filled-on-demand virtual memory pages, or careful synchronization if manually zeroing memory.
In practice it is difficult to implement growable SharedArrayBuffer by copying on hosts that do not have virtual memory, such as those running on embedded devices without an MMU. Memory usage behaviour of growable SharedArrayBuffers on such hosts may significantly differ from that of hosts with virtual memory. Such hosts should clearly communicate memory usage expectations to users.
Uses of [[ArrayLength]] on Integer-Indexed exotic objects are replaced with calls to
Uses of [[ByteLength]] on Integer-Indexed exotic objects are replaced with calls to IntegerIndexedByteLength.
Uses of [[ArrayBufferByteLength]] on buffer objects that may be growable SharedArrayBuffers are replaced with calls to