JS 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.

Note: 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

Warning: 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

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;

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

Note: 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.

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

Example: Worker Waiting for a Value

// 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);

Complete Atomics Reference

Revised December 2025

• Atomics are for communication between threads using shared memory
• You use them with SharedArrayBuffer and Typed Arrays
• Atomics operations can not be interrupted by other threads
• Use Atomics only when you need low-level synchronization
• Most JavaScript code does not need Atomics

Note: Learn More: Typed Array Tutorial Typed Array Methods Typed Array Reference Array Buffers DataViews