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. A SharedArrayBuffer
is not a Transferable Object, unlike an ArrayBuffer
which is transferable.
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 SharedArrayBuffer
objects and typed arrays mapped onto SharedArrayBuffer
objects. 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);
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 which use SharedArrayBuffer objects
Security requirements
Shared memory and high-resolution timers were effectively disabled at the start of 2018 in light of Spectre. In 2020, a new, secure approach has been standardized to re-enable shared memory. With a few security measures, postMessage()
will no longer throw for SharedArrayBuffer
objects and shared memory across threads will be available:
As a baseline requirement, your document needs to be in a secure context.
For top-level documents, two headers will need to be set to cross-origin isolate your site:
Cross-Origin-Opener-Policy
withsame-origin
as value (protects your origin from attackers)Cross-Origin-Embedder-Policy
withrequire-corp
as value (protects victims from your origin)
Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp
To check if cross origin isolation has been successful, you can test against the crossOriginIsolated
property available to window and worker contexts:
if (crossOriginIsolated) {
// Post SharedArrayBuffer
} else {
// Do something else
}
See also Planned changes to shared memory which is starting to roll out to browsers (Firefox 79, for example.)
Always use the new operator to create a SharedArrayBuffer
SharedArrayBuffer
objects must be constructed with the new
operator. Calling SharedArrayBuffer()
as a function without using new
will throw a TypeError
.
var sab = SharedArrayBuffer(1024);
// TypeError: calling a builtin SharedArrayBuffer constructor
// without new is forbidden
var sab = new SharedArrayBuffer(1024);
Constructor
-
Creates a new
SharedArrayBuffer
object.
Instance properties
-
The size, in bytes, of the array. This is established when the array is constructed and cannot be changed. Read only.
Instance methods
-
Returns a new
SharedArrayBuffer
whose contents are a copy of thisSharedArrayBuffer
's bytes frombegin
, inclusive, up toend
, exclusive. If eitherbegin
orend
is negative, it refers to an index from the end of the array, as opposed to from the beginning.
Examples
Creating a new SharedArrayBuffer
var sab = new SharedArrayBuffer(1024);
Slicing the SharedArrayBuffer
sab.slice(); // SharedArrayBuffer { byteLength: 1024 }
sab.slice(2); // SharedArrayBuffer { byteLength: 1022 }
sab.slice(-2); // SharedArrayBuffer { byteLength: 2 }
sab.slice(0, 1); // SharedArrayBuffer { byteLength: 1 }
Using it in a WebGL buffer
const canvas = document.querySelector('canvas');
const gl = canvas.getContext('webgl');
const buffer = gl.createBuffer();
gl.bindBuffer(gl.ARRAY_BUFFER, buffer);
gl.bufferData(gl.ARRAY_BUFFER, sab, gl.STATIC_DRAW);
Specifications
Specification |
---|
ECMAScript Language Specification # sec-sharedarraybuffer-objects |
Browser compatibility
BCD tables only load in the browser
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