JavaScript Reference ยท Typed Arrays and Binary Data
SharedArrayBuffer and Atomics
Reference for SharedArrayBuffer and the Atomics object: shared memory between workers, atomic add, load, store, compareExchange, wait and notify, with examples.
A SharedArrayBuffer is like an ArrayBuffer, but when you send it to a Web Worker with postMessage() the worker receives a view of the same memory instead of a copy. Several threads can then read and write the same bytes.
Plain reads and writes from different threads can interleave and lose updates. The Atomics object provides operations on integer typed arrays that happen indivisibly, plus wait() and notify() to let threads sleep and wake each other.
const shared = new SharedArrayBuffer(16); const counters = new Int32Array(shared); Atomics.add(counters, 0, 1);
Try it
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
new SharedArrayBuffer(byteLength) new SharedArrayBuffer(byteLength, { maxByteLength }) Atomics.add(typedArray, index, value) Atomics.load(typedArray, index) Atomics.wait(int32Array, index, expected, timeout) Atomics.notify(int32Array, index, count)
Atomics operations (all take an integer typed array and an index):
| Method | Description |
|---|---|
add, sub, and, or, xor |
Apply the operation and return the previous value. |
load(ta, i) / store(ta, i, v) |
Read or write; store() returns the value written. |
exchange(ta, i, v) |
Write v, return the previous value. |
compareExchange(ta, i, expected, v) |
Write v only if the current value equals expected; always returns the previous value. |
isLockFree(size) |
Whether operations on that many bytes avoid a lock. |
wait(ta, i, expected, timeout) |
Sleep while ta[i] === expected. Returns "ok", "not-equal" or "timed-out". Only on Int32Array or BigInt64Array over shared memory. |
notify(ta, i, count) |
Wake up to count waiting threads; returns how many woke. |
waitAsync(...) |
Non-blocking variant of wait() that returns a promise (newer). |
Exceptions: Atomics methods throw TypeError for non-integer arrays (and for Uint8ClampedArray) and RangeError for a bad index. Atomics.wait() throws on the browser main thread because it would block the page.
Usage notes
- Cross-origin isolation. Browsers expose
SharedArrayBufferonly on pages served with theCross-Origin-Opener-Policy: same-originandCross-Origin-Embedder-Policy: require-corp(orcredentialless) headers. Test withcrossOriginIsolated. Embedded sandboxes, like the editor on this page, usually are not isolated. - Atomics work on normal buffers too, but only shared memory makes them useful across threads.
- Never block the main thread. Use
Atomics.wait()inside workers andwaitAsync()orpostMessage()elsewhere. - Races are subtle. Reading with
counters[0], adding one and writing back is not atomic; useAtomics.add()instead. - Plain accesses to shared data that other threads may change are data races. Prefer
Atomics.load()andstore()for flags that other threads read. - Typical uses: work queues, ring buffers, locks and parallel number crunching or WebAssembly threads.
- Security. The isolation headers exist because shared memory can build precise timers used by side-channel attacks.
Browser support
Shared memory is supported by current browsers but only in cross-origin isolated pages. Atomics.waitAsync() is newer than the rest; check a compatibility table.