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
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:
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.
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, 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 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.
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
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
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