Node.js Reference ยท child_process, worker_threads and cluster
Worker pools in Node.js
How to build a worker pool in Node.js with worker_threads: reuse threads, queue tasks, handle errors and crashes, size the pool and know when to use a library.
A worker pool is a fixed set of long-lived Worker threads plus a queue of tasks. Instead of starting a new thread for every job, you send the job to an idle worker, wait for the answer, and give the worker the next job. Node.js has no built-in pool class; you write a small one or use a library.
Starting a worker takes tens of milliseconds and a few megabytes, because each worker is a whole new JavaScript engine instance with its own event loop. For many small tasks that startup cost dominates. A pool pays it once per worker and also puts an upper limit on how many threads run at the same time.
const pool = new WorkerPool(workerSource, 4); // four reusable threads const result = await pool.run({ n: 40 }); // queued if all are busy await pool.close();
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.
How a pool works
- Create a fixed number of workers up front (or lazily, up to a maximum).
- Queue each incoming task. A task is just a message plus the promise functions that will settle it.
- Dispatch the next queued task whenever a worker is idle, and tag every message with an id so replies can be matched to tasks.
- Release the worker when its reply arrives and dispatch again.
- Handle failure: an
'error'or unexpected'exit'event means every task running on that worker is lost. Reject those promises and replace the worker.
Usage notes
- Size the pool by cores. For CPU-bound jobs,
os.availableParallelism()workers (or one less, to leave a core for the main thread) is a good start. More threads than cores just add context switching. - Pools suit CPU work, not I/O. Node's asynchronous I/O already scales without threads; use workers for compression, parsing, hashing, image processing and similar.
- Mind the cost of messages. Data is copied with the structured clone algorithm. For big binary payloads, transfer the
ArrayBufferin the transfer list or share aSharedArrayBuffer; see Transferring and sharing memory. - Send one job at a time per worker, or tag messages with ids as shown. A worker runs its message handlers one at a time, so a second job simply waits behind the first.
- Always replace crashed workers and reject their pending tasks; otherwise the pool slowly loses capacity and callers hang forever.
- Add limits for safety: a
resourceLimitssetting per worker (see resourceLimits) and a timeout that callsworker.terminate()for jobs that run too long. - Close the pool on shutdown. Idle workers keep the process alive unless you
terminate()them or callworker.unref(). - Libraries:
piscinais a widely used, well-tested pool for Node. Prefer it over a hand-written pool in production; the sketch above leaves out timeouts, replacement and cancellation.