Atomics

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 Atomics object provides atomic operations as static methods. They are used with SharedArrayBuffer objects.

The Atomic operations are installed on an Atomics module. Unlike the other global objects, Atomics is not a constructor. You cannot use it with a new operator or invoke the Atomics object as a function. All properties and methods of Atomics are static (as is the case with the Math object, for example).

Methods

Atomic operations

When memory is shared, multiple threads can read and write the same data in memory. Atomic operations make sure that predictable values are written and read, that operations are finished before the next operation starts and that operations are not interrupted.

Atomics.add()
Adds a given value at a given position in the array. Returns the old value at that position.
Atomics.and()
Computes a bitwise AND at a given position in the array. Returns the old value at that position.
Atomics.compareExchange()
Stores a given value at a given position in the array, if it equals a given value. Returns the old value.
Atomics.exchange()
Stores a given value at a given position in the array. Returns the old value.
Atomics.load()
Returns the value at the given position in the array.
Atomics.or()
Computes a bitwise OR at a given position in the array. Returns the old value at that position.
Atomics.store()
Stores a given value at the given position in the array. Returns the value.
Atomics.sub()
Subtracts a given value at a given position in the array. Returns the old value at that position.
Atomics.xor()
Computes a bitwise XOR at a given position in the array. Returns the old value at that position.

Wait and wake

The wait() and wake() methods are modeled on Linux futexes ("fast user-space mutex") and provide ways for waiting until a certain condition becomes true and are typically used as blocking constructs.

Atomics.wait()

Verifies that a given position in the array still contains a given value and sleeps awaiting or times out. Returns either "ok", "not-equal", or "timed-out". If waiting is not allowed in the calling agent then it throws an Error exception (most browsers will not allow wait() on the browser's main thread).

Atomics.wake()
Wakes up some agents that are sleeping in the wait queue on the given array position. Returns the number of agents that were woken up.
Atomics.isLockFree(size)

An optimization primitive that can be used to determine whether to use locks or atomic operations. Returns true, if an atomic operation on arrays of the given element size will be implemented using a hardware atomic operation (as opposed to a lock). Experts only.

Specifications

Specification Status Comment
ECMAScript Shared Memory and Atomics
The definition of 'Atomics' 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] [3] 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

[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

Compatibility notes

[3] The Shared memory specification is still stabilizing. Prior to SpiderMonkey 48 (Firefox 48 / Thunderbird 48 / SeaMonkey 2.45), the latest API names and semantics weren't implemented yet. The changes between Firefox version 46 and version 48 are:

  • The methods Atomics.futexWakeOrRequeue() and Atomics.fence() are now removed entirely (bug 1259544 and bug 1225028).
  • The methods Atomics.wait() and Atomics.wake() were named Atomics.futexWait() and Atomics.futexWake() (bug 1260910). The old names will remain as an alias for one cycle and are planned to be removed in version 49 (bug 1262062).
  • The properties Atomics.OK, Atomics.TIMEDOUT, Atomics.NOTEQUAL have been removed. The Atomics.wait() method now returns the strings "ok", "timed-out" and "not-equal" (bug 1260835).
  • The count parameter of the Atomics.wake() method has been changed: it now defaults to +Infinity, not 0 (bug 1253350).

See also

Document Tags and Contributors

 Contributors to this page: fscholz, Kaku, lth, Sheppy
 Last updated by: fscholz,