SharedArrayBuffer

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

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

JavaScript
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

ArrayBuffers vs. SharedArrayBuffers

JavaScript offers ArrayBuffer and SharedArrayBuffer objects. They are constructed like this:

JavaScript
var ab = new ArrayBuffer(1024);
var sab = new SharedArrayBuffer(1024);

Web content uses Web Workers to run scripts in background threads. Data gets sent to and from the worker by using the postMessage() method and certain types are so-called transferable objects, that are transferred from one context to another with a zero-copy operation, resulting in high performance.

When transferring an ArrayBuffer from your main app to a worker script, the original ArrayBuffer is cleared and no longer usable. Its content is (quite literally) transferred to the worker context.

JavaScript
var ab = new ArrayBuffer(1024);
var uInt8Array = new Uint8Array(ab);
for (var i = 0; i < uInt8Array.length; ++i) {
  uInt8Array[i] = i;
}

var worker = new Worker("worker.js");

// before transferring
console.log(uInt8Array.byteLength); // 1024

worker.postMessage(uInt8Array.buffer, [uInt8Array.buffer]);

// after transferring
console.log(uInt8Array.byteLength); // 0

Now with a SharedArrayBuffer, you can share this memory with the worker by transferring it using the same postMessage() call.

JavaScript
var sab = new SharedArrayBuffer(1024);

// before transferring
console.log(sab.byteLength); // 1024

worker.postMessage(sab, [sab]);

// after transferring
console.log(sab.byteLength); // 1024

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

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.

JavaScript
var sab = SharedArrayBuffer(1024);
// TypeError: calling a builtin SharedArrayBuffer constructor 
// without new is forbidden
JavaScript
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.

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari
Basic support No support [2] No support 46 (46) [1]
47 (47)
No support No support No support
slice() No support No support No support No support No support No support
Feature Android Chrome for Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support No support No support 46.0 (46) [1] No support No support No support
slice() No support No support No support No support No support No support

[1] This feature is 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

License

© 2016 Mozilla Contributors
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-us/docs/web/javascript/reference/global_objects/sharedarraybuffer

Constructor Experimental JavaScript Shared Memory SharedArrayBuffer TypedArrays