Repository files navigation

A TC39 proposal for immutable ArrayBuffers.

The TC39 Process

Stage: 2.7

Champions:

• Mark S. Miller (@erights)
• Peter Hoddie (@phoddie)
• Richard Gibson (@gibson042)
• Jack-Works (@Jack-Works)

Specification:https://tc39.es/proposal-immutable-arraybuffer/

• for stage 1 - October 2024 tc39 plenary (slides.key,slides.pdf,video)
• for stage 2 - December 2024 tc39 plenary (slides.key,slides.pdf,docs slides,video)
• for stage 2.7 - February 2025 plenary (slides.key,slides.pdf)
• for stage 3, take 1 - April 2025 Plenary (slides.key,slides.pdf,incomplete video)

Prior proposalsIn-Place Resizable and GrowableArrayBuffers andArrayBuffer.prototype.transfer and friends have both reached stage 4, and so are now an official part of JavaScript. Altogether,ArrayBuffer.prototype now has the following methods:

• transfer(newByteLength?: number) :ArrayBuffer -- move the contents of the original buffer to a new buffer, detach the original buffer, and return the new buffer. The new buffer will be as resizable as the original was.
• transferToFixedLength(newByteLength?: number) :ArrayBuffer -- liketransfer but the new buffer is not resizable.
• resize(newByteLength: number) :void -- change the size of this buffer if possible, or throw otherwise.
• slice(start?: number, end?: number) :ArrayBuffer -- Return a new buffer whose initial contents are a copy of that region of the original buffer. The original buffer is unmodified.

and the following read-only accessor properties

• detached: boolean -- is this buffer detached, or are its contents still available from this buffer object?
• resizable: boolean -- can this buffer be resized, or is it fixed-length?
• byteLength: number -- how big are the current contents of this buffer?
• maxByteLength: number -- how big could this buffer be resized to be?

None of the operations above enable the creation of an immutable buffer, i.e., a non-detached buffer whose contents cannot be changed, resized, or detached.

Both aDataView object and aTypedArray object are views into a buffer backing store. For aTypedArray object, the contents of the backing store appear as indexed data properties of theTypeArray object that reflect the current contents of this backing store. Currently, because there is no way to prevent the contents of the backing store from being changed,TypedArrays cannot be frozen.

Some JavaScript implementations, like Moddable XS, bring JavaScript to embedded systems, like device controllers, where ROM is much more plentiful and cheaper than RAM. These systems need to place voluminous fixed data into ROM, and currently do so using semantics outside the official JavaScript standard.

APIs that accept ArrayBuffers and/or objects backed by them could also benefit from performance improvement by avoiding defensive copies when the input buffers are immutable (seeGeneric zero-copy ArrayBuffer usage for a proposed alternative solution to this problem in the Web Platform).

TheOCapN network protocol treats strings and byte-arrays as distinct forms of bulk data to be transmitted by copy. At JavaScript endpoints speaking OCapN such as@endo/pass-style +@endo/marshal, JavaScript strings represent OCapN strings. The immutability of strings in the JavaScript language reflects their by-copy nature in the protocol. Likewise, to reflect an OCapN byte-array well into the JavaScript language, an immutable container of bulk binary data is required. There currently are none, but an ImmutableArrayBuffer would provide exactly the necessary low-level machinery.

Limited ArrayBuffer, especiallyissue #16

Readonly Collections, especiallyissue #10

wasm zero copyissue #1162 comment

w3c TPAC talkZero-copy operations on the web

web-bluetoothread-only ArrayBuffer, especiallyissue #300

gpuwebissue #2072,issue #747, andSharedValueTable proposal

• likely should useLimited ArrayBuffer instead of Immutable ArrayBuffer because Immutable ArrayBuffers cannot be detached.
• Note thatWebAssembly.Memory also can't be detached (except via other WebAssembly methods,...).

webidlFrozen Array

webcodecsissue #80,issue #104, andissue #212

web transportissue #131

• unlikely because Chrome (and likely others) copy when crossing address spaces.
• But possible: seeEven when talking between different processes, each with their own address space, for a huge enough buffer ...

whatwg streamsissue #495

• unlikely because, well, they are streams, not buffers.

w3c machine learning workshopissue #93

Deno intends to support

Proposal Import Buffer relies on Immutable ArrayBuffer

This proposal introduces additional methods and read-only accessor properties toArrayBuffer.prototype that fit naturally into those explained above. Just as a buffer can be resizable or not, and detached or not, this proposal enables buffers to be immutable or not. Just astransferToFixedSize moves the contents of a original buffer into a newly created non-resizable buffer, this proposal provides a transfer operation that moves the contents of an original original buffer into a newly created immutable buffer. Altogether, this proposal only adds toArrayBuffer.prototype one read-only accessor

• immutable: boolean -- is this buffer immutable, or can its contents be changed?

and two methods

• transferToImmutable(newByteLength?: number) :ArrayBuffer -- move the contents of the original buffer into a new immutable buffer, detach the original buffer, and return the new buffer.
• sliceToImmutable(start?: number, end?: number) :ArrayBuffer -- create a new immutable buffer from a range of the original buffer's contents in a way that allows implementations to easily minimize and sometimes even eliminate copying them.

An immutable buffer cannot be detached, resized, or further transferred. ItsmaxByteLength is the same as itsbyteLength. ADataView orTypedArray using an immutable buffer as its backing store can be frozen and immutable.ArrayBuffers,DataViews, andTypedArrays that are frozen and immutable could be placed in ROM without going beyond JavaScript's official semantics.

The ArrayBufferslice method and TypedArray methods that create new ArrayBuffers (filter,map,slice,toReversed, etc.) make no effort to preserve immutability, just like they make no effort to preserve resizability (although use of SpeciesConstructor in those methods means thatlack of resizability/immutability in the result cannot be guaranteed for the latter).

Immutable buffers alsointuitively integrate with HTMLstructuredClone—they are not transferable, but cloning preserves both immutability and the underlying data block.

constconsumeIntoNetstring=data=>{// Transfer to a new ArrayBuffer with room for the netstring framing.// https://en.wikipedia.org/wiki/Netstringconstprefix=newTextEncoder().encode(`${data.length}:`);constbuf=data.buffer.transfer(prefix.length+data.length+1);// Frame the data.consttmpArr=newUint8Array(buf);tmpArr.copyWithin(prefix.length,0);tmpArr.set(prefix);tmpArr[tmpArr.length-1]=0x2C;// Transfer to an immutable ArrayBuffer backing a frozen Uint8Array.constfrozenNetstring=Object.freeze(newUint8Array(buf.transferToImmutable()));assert(buf.detached);returnfrozenNetstring;};constinput=newTextEncoder().encode('hello world!');constresult=consumeIntoNetstring(input);assert(Object.isFrozen(result));try{result[0]=0;}catch(_err){}try{newUint8Array(result.buffer)[0]=1;}catch(_err){}try{result.buffer.transferToImmutable();}catch(_err){}assert(String.fromCharCode(...result)==='12:hello world!,');

• endo immutable-arraybuffer

Tracking issues to be added:

• JavaScriptCore
• SpiderMonkey
• XS
• V8

Why can't an immutable ArrayBuffer be detached/transferred?

Because that would result in observable changes to any TypedArray or DataView backed by it.

Should the index properties of a TypedArray backed by an immutable ArrayBuffer be configurable and writable?

No, TypedArray index properties should continue to track the state of the underlying buffer without individual bookkeeping.

Should ArrayBuffers support zero-copy slices (e.g.,arrayBuffer.sliceToImmutable())?#9

Yes. As agreed at the December tc39 plenary, we won't specify that the implementation be zero-copy. But providing this operationenables some implementations to easily implement it as zero-copy.

Should the new getter be namedimmutable ormutable?#10

immutable. As agreed at the December tc39 plenary, by following the defaults-to-false principle, feature tests such asif (buf.immutable) { will be falsy on engines that have not yet implemented this proposal.

Order of operations, when to throw or silently do nothing?#16

We will drive the resolution to this from implementor feedback. But when this by itself is not a deciding factor, we prefer failure to throw rather than be silent. This existing XS implementation follows that principle.