skip to content

Multi-Core Execution

Getting more than one core out of Node: worker threads for CPU work in-process, child processes and cluster for separate ones. Asked which you would pick, which turns on how much data must be copied.

on this pageshow

explore

questions

20

What does Node's cluster module do, and how does one entry script know whether it is running as the primary or a worker?

level: juniorimportance: must knowfreq 60%

answer

  1. same script, two roles
  2. child_process.fork under the hood
  3. an environment variable decides
  4. cluster.isPrimary vs cluster.isWorker

basics

~20 s

Node's cluster module runs one script as a primary that calls cluster.fork() and as worker processes that share its server ports. cluster.isPrimary, derived from an environment variable the primary sets for each worker, tells the script which role it has.

solid answer

~40 s

`node:cluster` lets one Node program use several cores by running several processes. The primary calls `cluster.fork()`, which uses `child_process.fork()` to start the same entry script again (`cluster.settings.exec` defaults to `process.argv[1]`) with an IPC channel and a `NODE_UNIQUE_ID` environment variable. That variable is how `cluster.isPrimary` and `cluster.isWorker` get their values, so the script branches on them: the primary forks and supervises, workers create their servers and call `listen()`, and the primary arranges for them to share the port. Each worker is a full process with its own V8 heap and event loop, so nothing in memory is shared. Node does not size or maintain the pool: the primary picks a count, often `os.availableParallelism()`, and forks replacements itself.

code

javascript · 14 lines
javascript
import cluster from 'node:cluster';
import http from 'node:http';
import { availableParallelism } from 'node:os';
import process from 'node:process';

if (cluster.isPrimary) {
  console.log(`primary ${process.pid}`);
  for (let i = 0; i < availableParallelism(); i++) cluster.fork();
} else {
  http
    .createServer((req, res) => res.end(`worker ${cluster.worker.id}\n`))
    .listen(8000);
  console.log(`worker ${cluster.worker.id} is pid ${process.pid}`);
}

go deeper

for a junior

Recall the two roles, that cluster.fork() starts the same script again, and that cluster.isPrimary is how the script branches between them.

for a middle

Explain that workers are child_process.fork() processes with their own heap and event loop, and that the primary owns the shared port.

for a senior

Point out what Node leaves to you: worker count, respawning on exit and retiring workers are all primary code you write and test.

for a principal

Frame cluster as a per-host supervisor with a single primary, and say when a platform's process supervisor or more replicas would own that job instead.

## Why the cluster module exists A Node.js process runs your JavaScript on **one main thread** with one event loop. However many cores the machine has, that main thread keeps at most one of them busy with your JavaScript. The `node:cluster` module is Node's built-in answer for network servers: it starts **several Node processes from the same program** and lets them share a listening port, so a server can use every core without a separate proxy in front of each process. Two words matter from here on: - **Primary**: the first process you start. It forks workers, supervises them and, under the default scheduling policy, accepts incoming connections on their behalf. - **Worker**: a process the primary started with `cluster.fork()`. Workers run your server code and handle requests. ## Two roles, one script `cluster.fork()` is built on `child_process.fork()`. It starts a new Node process running the file in `cluster.settings.exec`, which defaults to `process.argv[1]`, the script you launched. So the **same entry file runs in every process**, and the file has to branch on its role. The branch uses `cluster.isPrimary` (or its negation, `cluster.isWorker`). The value comes from the environment: when the primary forks a worker it adds a `NODE_UNIQUE_ID` variable holding the worker's id. While a process boots, before your code runs, Node checks for that variable: if it is absent, the process is the primary; if it is present, it is a worker. Node then deletes the variable from the worker's `process.env`, so a child process the worker spawns later does not mistake itself for a cluster worker. | | Primary | Worker | |---|---|---| | `cluster.isPrimary` | `true` | `false` | | Can call `cluster.fork()` | yes | no | | Sees `cluster.workers` | yes, keyed by id | no | | Sees `cluster.worker` | no | yes, its own `Worker` object | | Usually runs | the fork loop and restart logic | `http.createServer(...).listen(port)` | Older code uses `cluster.isMaster` and `cluster.setupMaster()`. Both have been deprecated aliases since Node 16 for `cluster.isPrimary` and `cluster.setupPrimary()`; they still work in Node 24, but new code should use the new names. ## What a worker is, and is not A cluster worker is a **full operating-system process**, not a thread: - it has its **own V8 heap**, its own event loop and its own copy of every module-level variable; - it reruns all of the entry script's top-level code, including imports and startup work, so expensive initialisation belongs behind the role check; - it talks to the primary through the **IPC channel** that `child_process.fork()` opened, using `process.send()` and `process.on('message')` in the worker and `worker.send()` in the primary; - if it crashes, the other workers keep serving. When process isolation is not needed and the goal is to move CPU-heavy work off the main thread inside one process, the Node docs point to `worker_threads` instead; that module is covered in its own lesson. ## Sharing a port In a worker, `server.listen(8000)` does not simply bind port 8000. The worker sends a message to the primary, and the primary owns the listening socket. Under the default policy on every platform except Windows, the primary accepts each connection and hands it to a worker in turn; on Windows the workers accept from a socket the primary shares with them. The details of that choice are a separate question; for the basics, the point is that **many workers can call `listen()` on the same port** without an `EADDRINUSE` error, because the primary arranges the sharing. ## What the primary must do itself Node deliberately does very little management. The docs are explicit that **Node.js does not automatically manage the number of workers**: 1. The primary decides how many to fork. `os.availableParallelism()` is the usual starting point for one worker per core. 2. The primary listens for the `'exit'` event and calls `cluster.fork()` again if it wants a replacement; nothing respawns a dead worker for you. 3. The primary decides when to retire workers, for example with `worker.disconnect()` during a deploy. If every worker dies, existing connections are dropped and new ones are refused, even though the primary is still running. ## Common misconceptions - Treating workers as threads that share memory: a `Map` filled in one worker is invisible to the others. - Expecting Node to fork one worker per core on its own: nothing is forked until the primary calls `cluster.fork()`. - Writing a separate worker file because "the primary and workers must differ": the default is one file with a role branch, although `cluster.setupPrimary({ exec })` can point workers at another file. - Assuming a crashed worker comes back by itself.

  • Why does expensive startup work at the top of the entry script run once per worker?
    `cluster.fork()` starts a brand-new Node process on the same entry file, so every top-level import and statement runs again in each worker. The primary's loaded modules and variables are not copied across. Put work only the primary needs inside the `cluster.isPrimary` branch, and work each worker needs (database pools, caches, the HTTP server) in the worker branch, remembering it is repeated N times.
  • What are cluster.isMaster and cluster.setupMaster(), and should new code use them?
    They are the original names, deprecated since Node 16 in favour of `cluster.isPrimary` and `cluster.setupPrimary()`. In Node 24 they remain aliases that behave identically, so old code keeps running, but new code and reviews should use the primary names.
  • How does a worker learn its own identity, and how does the primary find every worker?
    In a worker, `cluster.worker` is its own `Worker` object and `cluster.worker.id` its unique id. In the primary, `cluster.workers` maps each live worker's id to its `Worker` object, so `Object.values(cluster.workers)` iterates them. A worker is removed from that map once it has both disconnected and exited.

  • Cluster workers are threads sharing one heap with the primary.
  • Importing node:cluster forks one worker per CPU core automatically.
  • The primary and workers must live in separate script files.
  • Node restarts a crashed cluster worker without code in the primary.
  • Each cluster worker must listen on its own port behind a proxy.
open as a page

In Node.js, which kinds of work belong in worker_threads, and why do I/O-bound endpoints gain little from moving there?

level: juniorimportance: must knowfreq 72%

basics

~20 s

Worker threads suit CPU-bound JavaScript, such as a long PDF layout or a heavy calculation, that would otherwise freeze the event loop. I/O-bound work already waits outside the JavaScript thread, so a worker adds startup and copying cost without adding throughput.

open as a page

In Node.js's node:child_process module, how do spawn, exec, execFile and fork differ in shell use, output handling and communication?

level: middleimportance: must knowfreq 70%

basics

~20 s

spawn starts a program without a shell and streams its stdio; exec runs a command string through a shell and buffers the output; execFile buffers too but skips the shell; fork starts a Node.js module with an IPC channel.

open as a page

In Node.js, how do worker_threads, child_process.fork() and the cluster module compare on memory, messaging cost and crash isolation?

level: middleimportance: must knowfreq 75%

basics

~20 s

worker_threads run inside one process: cheaper messaging and shareable memory, but a native crash or process-wide out-of-memory kills them all. fork() and cluster start full processes: more memory and JSON IPC by default, but a crash ends only that process.

open as a page

In Node.js, what does worker.postMessage() do with the value you pass, and how does a transferList change the cost of sending an ArrayBuffer?

level: middleimportance: must knowfreq 62%

basics

~20 s

postMessage() copies the value with the structured clone algorithm, paid by both threads. Listing an ArrayBuffer in transferList moves its memory instead: no copy, but the sender's views become unusable. Pooled Buffers cannot be transferred and are cloned with their whole pool.

open as a page

A Node.js conversion endpoint builds a child_process.exec command string from the uploaded file's name; what is wrong, and how should the call be rewritten?

level: seniorimportance: must knowfreq 60%

basics

~20 s

exec hands the whole string to /bin/sh, so a file name containing shell syntax runs commands. Use execFile or spawn with a fixed binary path and an argument array, keep shell off, and never pass the client's name through.

open as a page

After a Node.js WebSocket chat server moves to one cluster worker per core, why do users get logged out and miss room messages, and what fixes it?

level: seniorimportance: must knowfreq 62%

basics

~20 s

Each cluster worker is a separate process with its own memory, and Node routes connections without regard to who holds what. Sessions, room lists and counters split N ways; move sessions to a shared store and relay broadcasts between workers.

open as a page

A Node.js image-resizing endpoint creates a new worker_threads.Worker for every request, and under load latency and memory climb sharply. Why, and how should it be restructured?

level: seniorimportance: must knowfreq 58%

basics

~20 s

Every new Worker boots a V8 isolate and Node environment and reloads its modules, and unbounded workers outnumber the cores and multiply heaps. Use a fixed pool of long-lived workers fed by a bounded queue, transfer image bytes, and replace workers that die.

open as a page

In Node.js, after starting a program with child_process.spawn, how do you read its output, get its exit code, and detect that it never started?

level: juniorimportance: should knowfreq 50%

basics

~10 s

child_process.spawn returns a ChildProcess: read subprocess.stdout and subprocess.stderr as streams, take the exit code from the 'close' event, and listen for 'error', which fires with ENOENT when the program cannot be started.

open as a page

In Node.js, what does child_process.fork add on top of spawn, and how do messages sent over its IPC channel behave?

level: middleimportance: should knowfreq 45%

basics

~20 s

child_process.fork starts a new Node.js process running a module, with its own memory and V8 instance, plus an IPC channel: send() and 'message' carry copies serialized as JSON by default, or by the v8 serializer when serialization is 'advanced'.

open as a page

A Node.js service converting documents with child_process.execFile now fails with 'stdout maxBuffer length exceeded'; what did Node do, and how do you fix it?

level: middleimportance: should knowfreq 40%

basics

~20 s

execFile buffers stdout and stderr up to maxBuffer bytes each (1024 * 1024 by default); past that Node truncates the output, signals the child with killSignal and fails with ERR_CHILD_PROCESS_STDIO_MAXBUFFER. Stream large output with spawn instead.

open as a page

How does Node's cluster module distribute incoming TCP connections across workers, and why is round-robin the default everywhere except Windows?

level: middleimportance: should knowfreq 42%

basics

~20 s

Under the default cluster.SCHED_RR, the primary accepts each connection and hands it to the next ready worker over IPC. Under SCHED_NONE, workers accept from one shared socket, which the docs say balances badly; Windows uses it because round-robin performs poorly with IOCP.

open as a page

In Node.js, what happens to a worker_threads.Worker and to the main thread when code inside the worker throws an uncaught exception?

level: middleimportance: should knowfreq 45%

basics

~20 s

The worker thread is terminated and its Worker object emits 'error' with the exception, then 'exit' with code 1. The main thread keeps running only if something listens for 'error'; with no listener, the error is rethrown there and crashes the process.

open as a page

A Node.js service calls subprocess.kill() on converter jobs that time out, yet stray converter processes keep piling up on the host; why, and how do you fix it?

level: seniorimportance: should knowfreq 35%

basics

~20 s

subprocess.kill() sends SIGTERM to the one process Node started; a shell wrapper's or converter's own children survive, and a program may ignore SIGTERM. Spawn with detached: true, signal the group with process.kill(-pid), and escalate to SIGKILL.

open as a page

With Node's cluster module, how should the primary replace crashed workers and roll all workers onto new code without refusing connections?

level: seniorimportance: should knowfreq 48%

basics

~20 s

In cluster's 'exit' handler, fork a replacement unless worker.exitedAfterDisconnect is true, and stop after repeated crashes. To roll, fork a new worker, wait for 'listening', then disconnect() one old worker with a kill() timer, one at a time.

open as a page

When a Node.js service already runs as several container replicas behind a load balancer, why is adding the cluster module inside each container often redundant?

level: seniorimportance: should knowfreq 50%

basics

~20 s

The orchestrator already runs, restarts and load-balances replicas. Cluster repeats that inside each container, hiding worker crashes from health checks, sizing from a CPU count the container may not get, and packing several V8 heaps into one memory limit.

open as a page

A Node.js API renders PDF exports in a worker_threads pool, yet one large export sometimes kills the whole pod and its unrelated requests. Why, and what would you change?

level: seniorimportance: should knowfreq 45%

basics

~20 s

Worker threads share one process and one container memory limit. resourceLimits caps only each worker's JavaScript heap, not Buffers or native memory, so concurrent large exports can exhaust the process. Cap concurrency and budget memory, or render in a separate process.

open as a page

In Node.js 24, how do you cap a worker_threads.Worker's heap with resourceLimits, what happens when the worker exceeds it, and what does the cap not cover?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Pass resourceLimits such as maxOldGenerationSizeMb to new Worker(). Exceeding it terminates only that worker, which emits 'error' with ERR_WORKER_OUT_OF_MEMORY and then 'exit'. The cap covers the JS heap only, not ArrayBuffers or other external memory.

open as a page

Your Node.js API mixes I/O endpoints with a CPU-heavy PDF export and runs on Kubernetes; how would you choose between worker_threads, child processes, cluster and more replicas?

level: principalimportance: should knowfreq 40%

basics

~20 s

Scale the I/O endpoints as one Node.js process per container plus replicas. Run the export where its failures may land: a bounded worker_threads pool if it can share fate, forked children for isolation, or a queue-fed deployment for independent scaling.

open as a page

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?

level: seniorimportance: nice to knowfreq 30%

basics

~20 s

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

open as a page