The SharedArrayBuffer
object is used to represent a generic, fixed-length raw binary data buffer, similar to the {{jsxref("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
ArrayBuffers vs. SharedArrayBuffers
JavaScript offers {{jsxref("ArrayBuffer")}} and SharedArrayBuffer
objects. They are constructed like this:
var ab = new ArrayBuffer(1024); var sab = new SharedArrayBuffer(1024);
Web content uses Web Workers to run scripts in background threads. Data gets send from and to the worker by using the {{domxref("Worker.postMessage", "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 {{jsxref("ArrayBuffer")}} from your main app to a worker script, the original {{jsxref("ArrayBuffer")}} is cleared and no longer usable. Its content is (quite literally) transferred to the worker context.
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.
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, {{jsxref("Atomics", "atomic", "", 1)}} operations are needed.
APIs accepting SharedArrayBuffer
objects
- {{domxref("WebGLRenderingContext.bufferData()")}}
- {{domxref("WebGLRenderingContext.bufferSubData()")}}
- {{domxref("WebGL2RenderingContext.getBufferSubData()")}}
Constructing is required with new
operator
SharedArrayBuffer
constructors require to be constructed with a {{jsxref("Operators/new", "new")}} operator. Calling a SharedArrayBuffer
constructor as a function without new
, will throw a {{jsxref("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. - {{jsxref("SharedArrayBuffer.prototype")}}
- Allows the addition of properties to all
SharedArrayBuffer
objects.
SharedArrayBuffer
prototype object
All SharedArrayBuffer
instances inherit from {{jsxref("SharedArrayBuffer.prototype")}}.
Properties
{{page('en-US/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/prototype','Properties')}}
Methods
{{page('en-US/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer/prototype','Methods')}}
Specifications
Specification | Status | Comment |
---|---|---|
{{SpecName('Shared Memory', '#StructuredData.SharedArrayBuffer', 'SharedArrayBuffer')}} | {{Spec2('Shared Memory')}} | Initial definition. |
Browser compatibility
{{CompatibilityTable}}
Feature | Chrome | Edge | Firefox (Gecko) | Internet Explorer | Opera | Safari |
---|---|---|---|---|---|---|
Basic support | {{CompatNo}} [2] | {{CompatNo}} | {{CompatGeckoDesktop("46")}} [1] {{CompatGeckoDesktop("47")}} |
{{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
isView() |
{{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
slice() |
{{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
Feature | Android | Chrome for Android | Firefox Mobile (Gecko) | IE Mobile | Opera Mobile | Safari Mobile |
---|---|---|---|---|---|---|
Basic support | {{CompatNo}} | {{CompatNo}} | {{CompatGeckoMobile("46")}} [1] | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
isView() |
{{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
slice() |
{{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} | {{CompatNo}} |
[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
- {{jsxref("Atomics")}}
- {{jsxref("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