Skip to content
Tutorials Center
My learning

Topics

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.

NODE
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

Node.js A minimal pool

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.

Node.js Why a pool beats one worker per task

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

  1. Create a fixed number of workers up front (or lazily, up to a maximum).
  2. Queue each incoming task. A task is just a message plus the promise functions that will settle it.
  3. Dispatch the next queued task whenever a worker is idle, and tag every message with an id so replies can be matched to tasks.
  4. Release the worker when its reply arrives and dispatch again.
  5. 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 ArrayBuffer in the transfer list or share a SharedArrayBuffer; 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 resourceLimits setting per worker (see resourceLimits) and a timeout that calls worker.terminate() for jobs that run too long.
  • Close the pool on shutdown. Idle workers keep the process alive unless you terminate() them or call worker.unref().
  • Libraries: piscina is 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.