Skip to content
Tutorials Center
My learning

Topics

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.

JavaScript
const shared = new SharedArrayBuffer(16);
const counters = new Int32Array(shared);
Atomics.add(counters, 0, 1);

Try it

JS Atomic operations

Press Run (or Ctrl + Enter) to see the console output here.

No output.

JS Is shared memory available?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Syntax

JavaScript
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 SharedArrayBuffer only on pages served with the Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp (or credentialless) headers. Test with crossOriginIsolated. 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 and waitAsync() or postMessage() elsewhere.
  • Races are subtle. Reading with counters[0], adding one and writing back is not atomic; use Atomics.add() instead.
  • Plain accesses to shared data that other threads may change are data races. Prefer Atomics.load() and store() 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.