JavaScript Atomics

The Atomics Object

The Atomics Object provides low-level atomic operations on shared memory.

It is used with SharedArrayBuffer and Typed Arrays to share data between workers.

What Are Atomics?

When multiple threads (for example, the main thread and one or more workers) access the same data, you can get race conditions. Atomics helps avoid these race conditions by providing operations that:

Work on shared typed arrays
Are performed atomically (cannot be interrupted halfway)
Return the previous value of the element

The Atomics object is a global object (like Math) with static methods such as Atomics.load(), Atomics.store(), Atomics.add(), and more.

Atomics are an advanced feature.

You typically use Atomics when you work with:

Web Workers
Worker Threads
Shared memory

Requirements

To use Atomics you need:

A SharedArrayBuffer
A typed array that uses the shared buffer (e.g. Int32Array)
One or more workers (or threads) that share the same buffer

Security: Browsers may require special headers (like COOP/COEP) for SharedArrayBuffer to be enabled on the web.

Basic Atomics Usage

Example: Creating a Shared Typed Array

Create a shared buffer and a shared integer array:

const buffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);

// Shared integer array with 4 elements
const sharedArray = new Int32Array(buffer);

// Initialize the array
sharedArray[0] = 10;
sharedArray[1] = 20;
sharedArray[2] = 30;
sharedArray[3] = 40;

Try it Yourself »

Atomic Read and Write

Use Atomics.load() to read and Atomics.store() to write an element in a shared typed array.

Example: Atomics.load() and Atomics.store()

var buffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
var sharedArray = new Int32Array(buffer);

// Store a value atomically
Atomics.store(sharedArray, 0, 123);

// Load the value atomically
var value = Atomics.load(sharedArray, 0);

console.log("Value:", value); // Value: 123

Atomics.store() returns the value you stored.

Atomics.load() returns the current value of the element.

Atomic Add and Subtract

Atomics.add() and Atomics.sub() change a value and return the old value.

Example: Atomics.add()

var buffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
var sharedArray = new Int32Array(buffer);

sharedArray[0] = 5;

var oldValue = Atomics.add(sharedArray, 0, 3);

console.log("Old:", oldValue); // Old: 5
console.log("New:", sharedArray[0]);// New: 8

Example: Atomics.sub()

var buffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
var sharedArray = new Int32Array(buffer);

sharedArray[0] = 10;

var oldValue = Atomics.sub(sharedArray, 0, 4);

console.log("Old:", oldValue); // Old: 10
console.log("New:", sharedArray[0]);// New: 6

Atomic Exchange and CompareExchange

Atomics.exchange() sets a new value and returns the old one. Atomics.compareExchange() only sets a new value if the current value is equal to a given expected value.

Example: Atomics.exchange()

var buffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
var sharedArray = new Int32Array(buffer);

sharedArray[0] = 1;

var oldValue = Atomics.exchange(sharedArray, 0, 99);

console.log("Old:", oldValue); // Old: 1
console.log("New:", sharedArray[0]); // New: 99

Example: Atomics.compareExchange()

var buffer = new SharedArrayBuffer(4 * Int32Array.BYTES_PER_ELEMENT);
var sharedArray = new Int32Array(buffer);

sharedArray[0] = 10;

// Only replace 10 with 20 if the current value is 10
var oldValue = Atomics.compareExchange(sharedArray, 0, 10, 20);

console.log("Old:", oldValue); // Old: 10
console.log("New:", sharedArray[0]); // New: 20

// Now it will NOT change because the expected value does not match
oldValue = Atomics.compareExchange(sharedArray, 0, 10, 30);

console.log("Old:", oldValue); // Old: 20
console.log("New:", sharedArray[0]); // New: 20

Atomics.wait() and Atomics.notify()

Atomics.wait() (in workers) can put a thread to sleep until the value at a position changes, and Atomics.notify() wakes up one or more sleeping threads.

Important: Atomics.wait() can only be used in worker contexts (not on the main thread) in browsers.

Example: Worker Waiting for a Value

Main thread (simplified):

// main.js
var buffer = new SharedArrayBuffer(4);
var sharedArray = new Int32Array(buffer);

sharedArray[0] = 0;

var worker = new Worker("worker.js");

// Send the shared buffer to the worker
worker.postMessage(buffer);

// Simulate some work, then set the value and notify the worker
setTimeout(function() {
Atomics.store(sharedArray, 0, 1);
Atomics.notify(sharedArray, 0, 1); // wake 1 worker
}, 1000);

Worker (worker.js):

// worker.js
onmessage = function(e) {
  var buffer = e.data;
  var sharedArray = new Int32Array(buffer);

  console.log("Worker waiting...");
  var result = Atomics.wait(sharedArray, 0, 0); // wait while value is 0

  console.log("Worker woken, result =", result);
  console.log("New value:", Atomics.load(sharedArray, 0));
};

Complete Atomics Reference

Revised December 2025

Method	Description
load(typedArray, index)	Reads and returns the value at index.
store(typedArray, index, value)	Stores value at index and returns it.
add(typedArray, index, value)	Adds value to the element and returns the old value.
sub(typedArray, index, value)	Subtracts value and returns the old value.
and(typedArray, index, value)	Performs bitwise AND with value and returns the old value.
or(typedArray, index, value)	Performs bitwise OR with value and returns the old value.
xor(typedArray, index, value)	Performs bitwise XOR with value and returns the old value.
exchange(typedArray, index, value)	Replaces the value at index and returns the old value.
compareExchange(typedArray, index, expected, value)	Replaces the value at index with value if the current value is expected. Returns the old value.
wait(typedArray, index, value, timeout?)	(Worker only) Blocks the calling thread until the element changes or timeout.
notify(typedArray, index, count)	Wakes up sleeping threads that are waiting on index.