Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Node.js worker_threads: SharedArrayBuffer and CPU Offloading

Each worker has its own isolate, event loop, and module cache. postMessage copies unless you transfer, and Atomics.wait on the main thread blocks the whole server.

~4 min readNode.js
#Node.js#Worker Threads#Concurrency#Performance
3D illustration of a main thread cube beside worker cubes sharing a memory grid slab

Quick Summary

worker_threads runs JavaScript in parallel inside one process. Each Worker has its own V8 isolate, its own event loop, and its own module cache; memory is shared only if you use a SharedArrayBuffer. That makes it the tool for CPU-bound work — hashing, image resize, JSON parsing of large payloads, report generation — that would otherwise block the main event loop.

Communication is postMessage: values are copied by structured clone, or transferred when an ArrayBuffer or MessagePort is listed in the transfer list, which moves ownership without copying.

The cost is startup. A new Worker re-initialises V8 and re-parses its module graph, tens of milliseconds on a laptop and more on a small container. Spawning one per request is slower than doing the work inline; a pool with a fixed size is the pattern that pays off.

Basic Syntax and Core Signatures

js
// main.js import { Worker, isMainThread, parentPort, workerData, MessageChannel, SHARE_ENV } from 'node:worker_threads'; const worker = new Worker(new URL('./worker.js', import.meta.url), { workerData: { imagePath: 'a.png' }, transferList: [], env: SHARE_ENV, // share process.env instead of copying execArgv: [], // do not inherit --inspect etc. resourceLimits: { maxOldGenerationSizeMb: 256, stackSizeMb: 4 }, name: 'resizer', }); worker.postMessage({ type: 'resize', width: 512 }); worker.on('message', (msg) => console.log('result', msg)); worker.on('messageerror', (err) => console.error('deserialise failed', err)); worker.on('error', (err) => console.error('worker crashed', err)); worker.on('exit', (code) => console.log('exit', code)); await worker.terminate(); // resolves with the exit code
js
// worker.js import { parentPort, workerData, threadId } from 'node:worker_threads'; parentPort.postMessage({ threadId, started: Date.now(), input: workerData }); parentPort.on('message', async ({ type, width }) => { const out = await resize(width); parentPort.postMessage({ type: 'done', out }, [out.buffer]); // transfer, no copy });
js
// Shared memory instead of messaging const sab = new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 4); const counter = new Int32Array(sab); worker.postMessage({ sab }); // worker side: Atomics.add(counter, 0, 1); Atomics.notify(counter, 0); // main side (waiting blocks this thread): Atomics.wait(counter, 0, 0, 1000); // value, expected, timeout

Key Comparison Table

MechanismIsolationShared stateStartup costUse for
worker_threadsSeparate isolate, same processSharedArrayBuffer, transferred buffersTens of msCPU-bound work, in-process parallelism
child_process.forkSeparate processIPC messages onlyHigher, full Node bootIsolation, crash containment
clusterSeparate processesNothing, shared listening portHigherScaling an HTTP server across cores
postMessage copy—NoPer-message copySmall structured data
transferList—Ownership movesNear-zeroLarge buffers
SharedArrayBuffer—Yes, with AtomicsAllocation onlyCounters, ring buffers, numeric arrays
EventFires whenTypical handling
messagepostMessage arrivedResult handling
messageerrorValue could not be deserialisedLog, treat as a bug
errorUncaught exception in the workerMark worker unusable, replace
exitThread ended, code 0 or non-zeroPool bookkeeping
onlineWorker started executingTiming measurements

Practical Edge Cases and Deep Dives

1. A worker per request is slower than no worker

js
// Wrong under load app.post('/render', async (req, res) => { const w = new Worker(new URL('./render.js', import.meta.url)); const out = await once(w, 'message'); res.send(out[0]); await w.terminate(); });

Each request pays isolate startup, module parse, and teardown — often more than the render itself — and a burst of 200 requests spawns 200 isolates, each with its own heap. A fixed pool (four workers on a four-core box, or os.availableParallelism() minus one for the main thread) queues work instead. piscina implements the pool, task queue, and recycling; hand-rolling it is fine for one job type but gets subtle with cancellation and backpressure.

2. Atomics.wait on the main thread blocks everything

js
const sab = new SharedArrayBuffer(4); const flag = new Int32Array(sab); worker.postMessage(sab); Atomics.wait(flag, 0, 0, 5000); // main thread sleeps: no HTTP, no timers, no GC

Atomics.wait blocks the calling thread, and on the main thread that thread runs the event loop. Waiting for a worker this way turns a CPU-bound problem into a total outage. Message-based await once(worker, 'message') is the non-blocking equivalent; Atomics.wait belongs inside the worker, where blocking only pauses that thread.

3. Transferring a pooled ArrayBuffer

js
const buf = Buffer.from('secret-token'); // from the 8 KiB pool worker.postMessage({ buf: buf.buffer }, [buf.buffer]); // detaches the whole pool

The transferred ArrayBuffer is the pool slab, not just your bytes, so the worker receives neighbouring allocations too, and your own buffer becomes unusable (byteLength 0). Copy first when transferring: const copy = new Uint8Array(buf); worker.postMessage({ buf: copy }, [copy.buffer]). The same rule applies to any buffer produced by Buffer.allocUnsafe or Buffer.concat on small inputs.

4. Module state is not shared

js
// main.js import { registry } from './registry.js'; // one instance // worker.js import { registry } from './registry.js'; // a different instance registry.set('k', 1); // invisible to the main thread

Each worker has its own module cache, so singletons, connection pools, and caches are duplicated per thread. A database client created at module scope opens n pools instead of one, which is how a four-worker setup exhausts max_connections. The fix is either to keep I/O in the main thread and send only pure work to workers, or to create the pool inside each worker with a size divided by the thread count.

5. Crashes, resourceLimits, and worker lifetime

js
const worker = new Worker(url, { resourceLimits: { maxOldGenerationSizeMb: 128 } }); worker.on('error', (err) => { if (err.code === 'ERR_WORKER_OUT_OF_MEMORY') replace(worker); }); worker.unref(); // do not keep the process alive for this worker

An uncaught exception inside a worker emits error on the parent; if nothing listens, it crashes the main process. A worker that dies cannot be restarted in place — create a new one and remove the dead entry from the pool. resourceLimits is the only way to cap a worker's heap, and exceeding it terminates the thread with ERR_WORKER_OUT_OF_MEMORY rather than degrading the whole process. A worker keeps the process alive by default, so unref() is required for background workers in a CLI.

6. cluster versus workers for an HTTP server

js
import cluster from 'node:cluster'; if (cluster.isPrimary) { for (let i = 0; i < 4; i++) cluster.fork(); } else { http.createServer(handler).listen(3000); }

cluster starts separate processes that share the listening socket, so each has its own heap and one crashing does not take down the others — at the cost of per-process memory and no shared state at all. worker_threads shares the process, which makes passing buffers cheap and memory smaller, but a fatal error in one thread can still end the process. Modern advice is to run one Node process per container and scale with the container, using worker_threads only for CPU-bound tasks inside it.

Common Node.js Runtime Mistakes

SymptomCauseFix
Throughput drops when workers are addedWorker created per taskFixed-size pool
API stops responding under loadAtomics.wait on the main threadMessage-based waiting
Worker receives unrelated bytesTransferred a pooled ArrayBufferCopy before transfer
DataCloneError on postMessageValue is not structured-cloneable (function, class instance)Send plain data
ERR_WORKER_OUT_OF_MEMORYresourceLimits too low, or a real leakRaise the limit, fix the leak
Process never exitsActive workerworker.unref() or terminate()
Database connections multiplied by fourModule-scope pool per workerSplit the pool, or keep I/O in main
Main process crashes on a worker bugNo 'error' listenerHandle 'error', replace the worker
Stale config after a changeEach worker parsed the module at startupRecycle workers on deploy

Try matching browser tools

All tools

Small utilities that fit Node.js work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Node.js guides

More in Node.js

All Node.js guides

The guides filed next to this one in Node.js, in library order.