Shared counters
Several workers increment a shared counter without lost updates.
JavaScript · Const
Atomics
Atomics is a namespace of static methods for atomic operations on typed-array elements, including shared-memory synchronization. It is commonly used with SharedArrayBuffer to coordinate concurrent agents safely.
How it works
Atomics is a namespace of static methods for indivisible operations on integer typed-array elements, especially when storage is shared between agents. Read-modify-write methods return the value that was present before the operation, while load, store, wait, and notification methods support coordination.
Syntax
Atomics.add(typedArray, index, value)
Atomics.and(typedArray, index, value)
Atomics.compareExchange(typedArray, index, expectedValue, replacementValue)
Atomics.exchange(typedArray, index, value)
Atomics.isLockFree(size)
Atomics.load(typedArray, index)
Atomics.notify(typedArray, index, count)
Atomics.or(typedArray, index, value)
Atomics.store(typedArray, index, value)
Atomics.sub(typedArray, index, value)
Atomics.wait(typedArray, index, value, timeout)
Atomics.waitAsync(typedArray, index, value, timeout)
Atomics.xor(typedArray, index, value)Parameters
| Name | Type | Description |
|---|---|---|
typedArray | integer TypedArray | An integer typed array, such as Int32Array or BigInt64Array, whose element is accessed atomically. |
index | number | The zero-based element position to access. |
value | number or bigint | The operation-specific operand, such as a value to add, store, exchange, or compare. |
expectedValue | number or bigint | For compareExchange, the value that must currently be present before replacement. |
replacementValue | number or bigint | For compareExchange, the value written when the expected value matches. |
value | number or bigint | For wait and waitAsync, the value expected at the location before waiting. |
timeout | number | For wait and waitAsync, the maximum wait duration in milliseconds. |
Returns
The result depends on the static method: read-modify-write methods generally return the old element value; load returns the current value; wait returns a status string; notify returns the number of awakened agents; waitAsync returns an object describing an immediate result or Promise.
Key points
- Atomics is a namespace rather than an instance-based API; all operations are exposed as static methods.
- The methods operate on typed-array views backed by shared or ordinary array buffers.
- Atomic access prevents an operation's read and write phases from being interrupted by another write.
- Atomics.add performs an atomic addition at one typed-array position.
- Read-modify-write methods such as add, sub, and exchange return the element's pre-operation value.
- Atomics.notify wakes agents waiting on a selected shared-memory index.
Common mistakes
- Do not call Atomics with new or invoke it as a function; use its static methods directly.
- Atomic operations require an allowed integer typed array, not an arbitrary typed-array view.
- wait and notify are synchronization primitives; use them for coordination rather than ordinary value updates.
Example: Atomic counter update
const buffer = new SharedArrayBuffer(4);
const counter = new Int32Array(buffer);
Atomics.store(counter, 0, 1);
const previous = Atomics.add(counter, 0, 2);
console.log(previous); // 1
console.log(Atomics.load(counter, 0)); // 3This creates shared integer storage, atomically adds to one element, and reads both the previous and current values.
When to use it
Thread synchronization
Workers coordinate progress through a shared state value.
Lock-free algorithms
A lock implementation needs indivisible compare-and-swap behavior.
Shared flags
A program needs atomic bitwise flags in shared integer storage.
Interview questions
QWhat problem does Atomics solve?
Atomics provides static methods that perform atomic operations on typed-array elements. These operations prevent another write from interleaving during the indivisible operation, which makes shared-memory updates predictable.
Follow-up: Why is Atomics.add useful for a counter? It combines reading the old value, adding, and writing the result into one atomic operation, returning the old value.
QHow is Atomics used?
Atomics is a namespace object, not a constructor, so it cannot be used with new. Its methods are called directly, such as Atomics.load(array, index) or Atomics.store(array, index, value).
Follow-up: How does this differ from Math? Both expose static operations, but Atomics operates on integer typed-array elements and supports shared-memory synchronization.
QWhat are Atomics.wait and Atomics.notify for?
The wait and notify methods allow agents to coordinate through a shared-memory location. wait checks the value and can block until notification or timeout, while notify wakes agents waiting at an index.
Follow-up: When should waitAsync be preferred? It is non-blocking and can be used on the main thread, returning either an immediate result or a Promise.
Related
SharedArrayBufferArrayBufferInt32ArrayBigInt64ArrayAtomics.add()Atomics.compareExchange()Atomics.exchange()Atomics.load()