Atomics.wait()
BaselineWidely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since December 2021.
TheAtomics.wait()
static method verifies that a shared memory location contains a given value and if so sleeps, awaiting a wake-up notification or a time out. It returns a string which is"not-equal"
if the memory location does not match the given value,"ok"
if woken byAtomics.notify()
, or"timed-out"
if the timeout expires.
Atomics.wait()
andAtomics.notify()
are used together to enable thread synchronization based on a value in shared memory. A thread can proceed immediately if the synchronization value has changed, or it can wait for notification from another thread when it reaches the synchronization point.
This method only works with anInt32Array
orBigInt64Array
that views aSharedArrayBuffer
. It is blocking and cannot be used in the main thread. For a non-blocking, asynchronous version of this method, seeAtomics.waitAsync()
.
Syntax
Atomics.wait(typedArray, index, value)Atomics.wait(typedArray, index, value, timeout)
Parameters
typedArray
An
Int32Array
orBigInt64Array
that views aSharedArrayBuffer
.index
The position in the
typedArray
to wait on.value
The expected value to test.
timeout
OptionalTime to wait in milliseconds.
NaN
(and values that get converted toNaN
, such asundefined
) becomesInfinity
. Negative values become0
.
Return value
A string which is either"not-equal"
,"ok"
, or"timed-out"
.
"not-equal"
is returned immediately if the initialvalue
does not equal what is stored atindex
."ok"
is returned if woken up by a call toAtomics.notify()
,regardless of whether the expected value has changed."timed-out"
is returned if a sleeping wait exceeds the specifiedtimeout
without being woken up byAtomics.notify()
.
Exceptions
TypeError
Thrown in one of the following cases:
- If
typedArray
is not anInt32Array
orBigInt64Array
that views aSharedArrayBuffer
. - If the current thread cannot be blocked (for example, because it's the main thread).
- If
RangeError
Thrown if
index
is out of bounds in thetypedArray
.
Examples
Using wait()
Given a sharedInt32Array
:
const sab = new SharedArrayBuffer(1024);const int32 = new Int32Array(sab);
A reading thread is sleeping and waiting on location 0 because the providedvalue
matches what is stored at the providedindex
.The reading thread will not move on until the writing thread has calledAtomics.notify()
on position 0 of the providedtypedArray
.Note that if, after being woken up, the value of location 0 has not been changed by the writing thread, the reading thread willnot go back to sleep, but will continue on.
Atomics.wait(int32, 0, 0);console.log(int32[0]); // 123
A writing thread stores a new value and notifies the waiting thread once it haswritten:
console.log(int32[0]); // 0;Atomics.store(int32, 0, 123);Atomics.notify(int32, 0, 1);
Specifications
Specification |
---|
ECMAScript® 2026 Language Specification # sec-atomics.wait |