SharedArrayBuffer

The SharedArrayBuffer object is used to represent a generic, fixed-length raw binary data buffer, similar to the ArrayBuffer object, but in a way that they can be used to create views on shared memory. Unlike an ArrayBuffer, a SharedArrayBuffer cannot become detached.

Syntax

new SharedArrayBuffer(length)

Parameters

length

The size, in bytes, of the array buffer to create.

Return value

A new SharedArrayBuffer object of the specified size. Its contents are initialized to 0.

Description

Allocating and sharing memory

To share memory using SharedArrayBuffer objects from one agent in the cluster to another (an agent is either the web page’s main program or one of its web workers), postMessage and structured cloning is used.

The structured clone algorithm accepts SharedArrayBuffers and TypedArrays mapped onto SharedArrayBuffers. In both cases, the SharedArrayBuffer object is transmitted to the receiver resulting in a new, private SharedArrayBuffer object in the receiving agent (just as for ArrayBuffer). However, the shared data block referenced by the two SharedArrayBuffer objects is the same data block, and a side effect to the block in one agent will eventually become visible in the other agent.

var sab = new SharedArrayBuffer(1024);
worker.postMessage(sab);

In earlier versions of the specification, SharedArrayBuffers needed to be explicitly transferred during structured cloning. However, a SharedArrayBuffer is not a Transferable object in the sense of HTML. Thus if a SharedArrayBuffer object is present in the transfer list, then postMessage will throw a DataCloneError or at least a warning:

var sab = new SharedArrayBuffer(1024);
worker.postMessage(sab, [sab]); 
// SharedArrayBuffer must not be in the transfer list

Updating and synchronizing shared memory with Atomic operations

Shared memory can be created and updated simultaneously in workers or the main thread. Depending on the system (the CPU, the OS, the Browser) it can take a while until the change is propagated to all contexts. To synchronize, atomic operations are needed.

APIs accepting SharedArrayBuffer objects

• WebGLRenderingContext.bufferData()
• WebGLRenderingContext.bufferSubData()
• WebGL2RenderingContext.getBufferSubData()

Constructing is required with new operator

SharedArrayBuffer constructors require to be constructed with a new operator. Calling a SharedArrayBuffer constructor as a function without new, will throw a TypeError.

var sab = SharedArrayBuffer(1024);
// TypeError: calling a builtin SharedArrayBuffer constructor 
// without new is forbidden

var sab = new SharedArrayBuffer(1024);

Properties

SharedArrayBuffer.length

The SharedArrayBuffer constructor's length property whose value is 1.

SharedArrayBuffer.prototype

Allows the addition of properties to all SharedArrayBuffer objects.

SharedArrayBuffer prototype object

All SharedArrayBuffer instances inherit from SharedArrayBuffer.prototype.

Properties

SharedArrayBuffer.prototype.constructor

Specifies the function that creates an object's prototype. The initial value is the standard built-in SharedArrayBuffer constructor.

SharedArrayBuffer.prototype.byteLength Read only

The size, in bytes, of the array. This is established when the array is constructed and cannot be changed. Read only.

Methods

SharedArrayBuffer.prototype.slice(begin, end)

Returns a new SharedArrayBuffer whose contents are a copy of this SharedArrayBuffer's bytes from 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.

Specifications

Specification	Status	Comment
ECMAScript Shared Memory and Atomics The definition of 'SharedArrayBuffer' in that specification.	Draft	Initial definition.
ECMAScript 2017 Draft (ECMA-262)	Draft

Browser compatibility

[1] In Firefox version 46 until version 51, this feature was disabled by a preference setting. In about:config, set javascript.options.shared_memory to true.

[2] The implementation is under development and needs these runtime flags: --js-flags=--harmony-sharedarraybuffer --enable-blink-feature=SharedArrayBuffer

See also

• Atomics
• ArrayBuffer
• JavaScript typed arrays
• Web Workers
• parlib-simple – a simple library providing synchronization and work distribution abstractions.
• Shared Memory – a brief tutorial

• A Taste of JavaScript’s New Parallel Primitives – Mozilla Hacks