In Node.js, how do the main thread and a worker_threads.Worker share a SharedArrayBuffer and signal each other with Atomics.wait and Atomics.notify, and why avoid Atomics.wait on the main thread?
answer
- same bytes, two threads
- posted, never transferred
- Int32Array view, index, expected value
- a blocked loop runs nothing
basics
~20 sPost a SharedArrayBuffer, or a typed-array view of it, through workerData or postMessage(); both threads then see the same memory. Atomics.wait blocks a thread until Atomics.notify wakes it. Node permits it on the main thread, but it freezes the whole event loop.
solid answer
~40 sA `SharedArrayBuffer` passed in `workerData` or a `postMessage()` value is not copied: the receiver gets a view of the same memory, and it cannot be listed in `transferList`. Threads update it with `Atomics.store` or `Atomics.add`, and one thread can sleep with `Atomics.wait(int32, index, expected)` until another calls `Atomics.notify(int32, index)`. Unlike a browser page, Node lets the main thread call `Atomics.wait`, and Node's own module-hooks code does so to wait synchronously on its hooks thread. For a service it is still a trap: while the main thread waits, no timers, I/O callbacks or `'message'` events run, and even a worker's `console.log` output, which travels through the parent, stalls. Block inside workers; on the main thread use `Atomics.waitAsync` or a message.
code
javascript · 17 linesimport { Worker, isMainThread, workerData } from 'node:worker_threads';
if (isMainThread) {
const shared = new Int32Array(new SharedArrayBuffer(8));
const worker = new Worker(new URL(import.meta.url), { workerData: shared });
worker.once('error', (err) => console.error('worker failed:', err));
const result = Atomics.waitAsync(shared, 0, 0);
const settled = result.async ? result.value : Promise.resolve(result.value);
settled.then((outcome) => {
console.log(outcome, 'result =', Atomics.load(shared, 1));
});
} else {
const shared = workerData;
Atomics.store(shared, 1, 6 * 7);
Atomics.store(shared, 0, 1);
Atomics.notify(shared, 0);
}go deeper
Recall that SharedArrayBuffer is the one way Node threads see the same memory, while normal messages are copies.
Explain how the buffer reaches the worker, through workerData or postMessage and never a transferList, and the wait and notify handshake on an Int32Array flag.
Show why the main thread should wait with Atomics.waitAsync or messages, how worker stdout and messages stall otherwise, and why every wait needs a timeout.
Judge when shared memory is worth its race risk and review cost compared with transferring buffers, and who on the team may introduce it.
## Sharing memory instead of copying it Messages between threads in `node:worker_threads` are normally copied with structured clone. A **`SharedArrayBuffer`** (SAB) is the exception: it is a block of memory that several threads can map at once. The `postMessage()` documentation says SAB instances in a message "are accessible from either thread" and that they "cannot be listed in `transferList`". Sharing is what you post, not a transfer. You hand a SAB to a worker in either of two ways: - **At creation**: `new Worker(file, { workerData: new Int32Array(sab) })`. The typed-array view is cloned, but the memory it points to is shared. - **Later**: `worker.postMessage({ frame: sab })` or over any `MessagePort`. Both sides then wrap the memory in typed arrays (`Int32Array`, `Float64Array`, `Uint8Array`) and read and write the same bytes. That is how a report generator can write progress counters, or an image pipeline can share one large frame between several workers, without per-message copies. ## Coordinating with Atomics Plain reads and writes on shared memory are not synchronised, so threads coordinate through the `Atomics` global, a standard JavaScript object available in Node: | Call | What it does | |---|---| | `Atomics.store(ta, i, v)` / `Atomics.load(ta, i)` | Write and read one element atomically | | `Atomics.add(ta, i, v)` | Atomically add and return the old value | | `Atomics.wait(i32, i, expected[, timeout])` | Block the calling thread while `i32[i]` equals `expected`, until notified or timed out | | `Atomics.notify(i32, i[, count])` | Wake threads waiting on `i32[i]` | | `Atomics.waitAsync(i32, i, expected[, timeout])` | Return an object whose `value` is a promise (or an immediate result) instead of blocking | `Atomics.wait` returns `'ok'`, `'not-equal'` or `'timed-out'`, and it works only on an `Int32Array` or `BigInt64Array` over shared memory. The usual handshake is a flag word: 1. The waiter checks the flag and, while it is still `0`, calls `Atomics.wait(flags, 0, 0)`. If the producer has already set it, the call returns `'not-equal'` at once, so no signal is lost. 2. The producer writes its data into the shared region. 3. The producer publishes it with `Atomics.store(flags, 0, 1)` and wakes the waiter with `Atomics.notify(flags, 0)`. 4. The waiter wakes, sees `1`, and reads the data. Memory-ordering theory and compare-and-swap loops belong to the concurrency foundations; the Node point is which thread is allowed to block, and what blocking costs. ## Why the main thread should not block In a browser page, `Atomics.wait` throws on the main thread. **Node does not forbid it**: Node's own implementation of asynchronous module-customisation hooks calls it on the main thread to wait synchronously for its hooks thread, then reads that thread's reply synchronously. Being allowed is not the same as being wise. While the main thread sits in `Atomics.wait`: - **The event loop does not turn.** No timers fire, no sockets are read, no HTTP requests are answered. - **Worker messages queue up.** `'message'` events cannot be delivered until the wait ends. - **Worker output stalls.** A worker's `process.stdout` is implemented with message passing to the parent, and the documentation warns that its output "can get blocked by synchronous code on the receiving end that is blocking the Node.js event loop". So the rule for a server is: 1. **Block in workers, not in the main thread.** A worker that has nothing to do until a producer signals can sit in `Atomics.wait` cheaply. 2. **On the main thread, wait asynchronously.** `Atomics.waitAsync` returns `{ async, value }`: when `async` is true, `value` is a promise that resolves to `'ok'` or `'timed-out'`; when the value already differs, `value` is the string `'not-equal'` immediately. A plain `postMessage()` notification is often simpler still. 3. **Use timeouts.** A waiter whose producer crashed waits forever unless `Atomics.wait` was given a timeout. ## Costs that come with shared memory - **Races are now your problem.** Any non-atomic read of data another thread is writing can see a half-updated value; design a clear ownership protocol (who writes which region, which flag publishes it). - **Outside the heap caps.** SAB memory is external to every isolate, so a worker's `resourceLimits` does not count it. - **Lifetime.** The memory stays allocated while any thread still references it, so a long-lived shared buffer is a long-lived allocation. Shared memory pays off when several threads repeatedly read the same large block or need very low-latency signalling. For one-off hand-offs, transferring an `ArrayBuffer` is simpler and just as copy-free.
- Why must a SharedArrayBuffer not be listed in postMessage()'s transferList?Transferring means moving ownership so the sender loses access, which is the opposite of sharing. The `node:worker_threads` documentation states that `SharedArrayBuffer` instances in a message are accessible from either thread and cannot be listed in `transferList`; you simply include the buffer, or a view of it, in the posted value.
- A worker calls Atomics.wait(flags, 0, 0) without a timeout and the producing thread crashes. What happens, and how do you guard against it?The waiting worker stays blocked indefinitely, because no one will call `Atomics.notify`. Pass a timeout and treat `'timed-out'` as a failure, and have the parent watch the producer's `'error'` and `'exit'` events so it can terminate or notify the waiters when the producer dies.
- Believing Node throws when Atomics.wait is called on the main thread
- Calling Atomics.wait on a server's main thread while waiting for a worker
- Listing a SharedArrayBuffer in transferList to share it
- Reading shared data with plain loads while another thread writes it
- Waiting on shared memory without a timeout for a producer that may crash