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?
- Work on shared typed arrays
- Are performed atomically (cannot be interrupted halfway)
- Return the previous value of the element
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
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: 123Atomics.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: 8Example: 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: 6Atomic 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: 99Example: 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: 20Atomics.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. 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 Learn More: Typed Array Tutorial Typed Array Methods Typed Array Reference Array Buffers DataViews
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. 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 Learn More: Typed Array Tutorial Typed Array Methods Typed Array Reference Array Buffers DataViews
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));
};Learn More
Typed Array Methods
Typed Array Reference
Array Buffers
DataViews