How do you know the event loop is actually blocked?

Node.js runs your JavaScript on one thread. While a function is executing, the event loop cannot accept new connections, fire timers, or run callbacks for I/O that has already completed. If a request handler spends 200 ms hashing a password, resizing an image, or parsing a large JSON payload, every other request that arrives in that window waits too. Concurrency comes from interleaving many short tasks, and one long synchronous task stops that interleaving. Because tail latency rises across unrelated endpoints, the cause often gets blamed on the database or the network.

Confirm the problem before changing your architecture. Use two measurements.

Measure event loop delay

perf_hooks.monitorEventLoopDelay() returns a histogram that samples how late the loop is compared to when it should have run. Call enable(), let it collect under realistic load, then read percentile(99), max, and mean. The values are in nanoseconds. A healthy service usually shows a p99 delay of a few milliseconds. A p99 in the tens or hundreds of milliseconds means something is holding the thread. Export these values as metrics so you can line up spikes with traffic and deploys.

Find what is holding the thread

Delay tells you that the loop is blocked, not why. Start the process with node --cpu-prof, reproduce the load, and open the resulting .cpuprofile file in Chrome DevTools. Look for wide, deep stacks in your own code or in a dependency.

If the profile shows that a specific function dominates CPU time and lines up with the delay spikes, you have a CPU-bound task that is worth offloading. If it does not, worker threads will not fix your latency.

// server.js: run with `node --cpu-prof server.js`, load both routes, then press Ctrl+C.
// On exit, Node writes a .cpuprofile file to the working directory. Open it in Chrome DevTools.
const http = require('node:http');
const crypto = require('node:crypto');
const { monitorEventLoopDelay } = require('node:perf_hooks');

// Sample loop lateness every 20 ms. Histogram values are in nanoseconds.
const histogram = monitorEventLoopDelay({ resolution: 20 });
histogram.enable();

const toMs = (ns) => (ns / 1e6).toFixed(1);

// Report every 5 s, then reset so each line covers one window.
// In production, export these values as metrics instead of logging them.
setInterval(() => {
  console.log(
    `loop delay p99=${toMs(histogram.percentile(99))}ms ` +
    `max=${toMs(histogram.max)}ms mean=${toMs(histogram.mean)}ms`
  );
  histogram.reset();
}, 5000).unref();

http.createServer((req, res) => {
  if (req.url === '/hash') {
    // Synchronous CPU-bound work holds the only JS thread until it finishes.
    const key = crypto.pbkdf2Sync('example-password', 'example-salt', 500000, 64, 'sha512');
    res.end(key.toString('hex'));
    return;
  }
  // This route is cheap, but it still waits while a /hash call is running.
  res.end('ok');
}).listen(3000);

// --cpu-prof writes the profile on a normal exit, so turn Ctrl+C into one.
process.on('SIGINT', () => process.exit(0));

A minimal HTTP server that logs event loop delay percentiles from monitorEventLoopDelay while a synchronous pbkdf2Sync route blocks the thread, and that runs under --cpu-prof so the blocking function shows up in the profile.

Which workloads are CPU-bound, and who should use worker threads?

Worker threads do not help with waiting, only with computing. A request that spends 200 ms waiting on Postgres is not using the CPU during that time. libuv parks the socket in the OS's readiness mechanism (epoll, kqueue, IOCP) and the event loop keeps serving other requests. Moving that call into a worker adds a thread and a message hop but still waits the same 200 ms.

CPU-bound work is different. When JavaScript computes a SHA-256 over a large buffer, resizes an image in pure JS, or runs JSON.parse on a 50 MB payload, nothing else on that thread can run until it finishes.

Workload Bound by Worker threads help?
Database queries, HTTP calls, socket I/O Network latency No. Already non-blocking
File reads via fs async APIs Disk, libuv thread pool No. Already off the main thread
Async crypto.pbkdf2, scrypt, async zlib CPU, but already on the libuv pool Rarely
Sync hashing/compression, JS image processing CPU on the main thread Yes
Large JSON.parse/stringify, bulk data transforms CPU on the main thread Yes, if the data can cross threads cheaply

The last row has an important limit. Sending a large object to a worker means structured-cloning it, which is itself CPU work on the main thread. If you clone a 50 MB object to save 30 ms of transformation, you lose time overall.

The target audience is services that have a measured hot path which recurs under real traffic. Worker threads are not a general way to make Node faster.

What are Node.js worker threads and how do they work?

The worker_threads module exposes a small API. In the main thread, you create a Worker and pass it the path of a script to run. Inside that script, isMainThread is false, parentPort is the communication endpoint back to the parent, and workerData holds a copy of whatever value you passed in the constructor's options. Because isMainThread lets one file detect which role it is playing, a single module can do both jobs. When it is the main thread, it spawns a worker pointing at itself (__filename in CommonJS, new URL(import.meta.url) in ESM). When it is the worker, it does the computation. The example below uses this pattern.

Communication is message passing, not shared variables. Either side calls postMessage(), and the other side receives the value through a 'message' event. The value is copied using the structured clone algorithm. On the Worker object, the main thread should also listen for two more events:

  • 'error' fires when the worker throws an uncaught exception.
  • 'exit' fires with an exit code when the worker stops.

If you skip these listeners, a crashed worker can leave a request waiting forever.

The isolation goes deep. Each worker gets its own V8 isolate, its own heap and garbage collector, its own event loop, and its own copy of every module it imports. That is why a worker can burn CPU without stalling your HTTP server.

That isolation is also why spawning a worker per request is a mistake. Each spawn boots a new JavaScript environment, re-parses and re-evaluates modules, and starts with cold JIT state. The startup cost and memory overhead can easily exceed the work you meant to offload. Workers are meant to be created once and reused.

// fib-worker.js: one file plays both roles (CommonJS)
const { Worker, isMainThread, parentPort, workerData } = require('node:worker_threads');

// Deliberately slow, CPU-bound function
function fib(n) {
  return n < 2 ? n : fib(n - 1) + fib(n - 2);
}

if (isMainThread) {
  // Main thread: spawn a worker that runs this same file
  const worker = new Worker(__filename, { workerData: { n: 40 } });

  worker.on('message', (result) => {
    console.log(`fib(40) = ${result}`);
  });

  // An uncaught exception inside the worker arrives here
  worker.on('error', (err) => {
    console.error('worker failed:', err);
  });

  // Always fires when the worker stops; non-zero code means abnormal exit
  worker.on('exit', (code) => {
    if (code !== 0) console.error(`worker exited with code ${code}`);
  });

  // The main event loop stays free while the worker computes
  const timer = setInterval(() => console.log('main thread still responsive'), 500);
  worker.on('exit', () => clearInterval(timer));
} else {
  // Worker: workerData is a structured-clone copy of what the parent passed
  const result = fib(workerData.n);
  parentPort.postMessage(result);
  // No more pending work, so the worker's event loop drains and it exits with code 0
}

A single CommonJS file uses isMainThread to act as both parent and worker: it passes input through workerData, returns the result with parentPort.postMessage, and handles the 'message', 'error' and 'exit' events while the main event loop keeps running.

How does data move between threads without killing performance?

Every value you pass to postMessage() crosses an isolate boundary, so the runtime must decide whether to copy it, move it, or share it. That choice often decides whether offloading pays off.

By default, Node uses the structured clone algorithm. It walks the object graph and builds an independent copy on the receiving side. That is safe because neither thread can see the other's changes. The cost grows with payload size, though, and it is paid on the sending thread. Cloning a large nested object can block the event loop you were trying to free.

For binary data, list the ArrayBuffer in the transferList argument: port.postMessage(buf, [buf]). Ownership moves to the receiver without copying the bytes. The sender's buffer becomes detached and reports byteLength 0. Any later access there will throw or read nothing.

SharedArrayBuffer is never copied or moved. Both threads hold the same memory. That avoids all copying, but it also removes the isolation that made message passing safe. Concurrent reads and writes race unless you coordinate them with Atomics (Atomics.add, Atomics.wait, Atomics.notify). Missing synchronization produces torn values and intermittent bugs that rarely reproduce under a debugger.

Mechanism Cost Ownership after send Use when
Structured clone Proportional to payload Both sides have independent copies Small or moderate plain objects
Transfer (transferList) Near-constant Receiver only; sender's buffer is detached Large binary buffers handed off once
SharedArrayBuffer + Atomics No copy, but synchronization overhead Shared by both Repeated access to large state, coordinated deliberately

Make message passing the default. Transfer large buffers, and reach for shared memory only after profiling shows that copying is the bottleneck.

// Run with: node transfer-vs-copy.js
const { MessageChannel } = require('node:worker_threads');

// A MessageChannel uses the same postMessage semantics as a Worker,
// so this shows clone vs transfer vs share without a separate worker file.
const { port1, port2 } = new MessageChannel();

let received = 0;
port2.on('message', ({ label, buf }) => {
  console.log(`receiver got ${label}: ${buf.byteLength} bytes`);
  if (++received === 3) port2.close(); // closing one side closes the channel
});

const SIZE = 64 * 1024 * 1024; // 64 MiB placeholder payload

// 1. Structured clone: bytes are copied on the sending thread.
const copied = new ArrayBuffer(SIZE);
port1.postMessage({ label: 'copy', buf: copied });
console.log('sender after copy:', copied.byteLength); // 67108864, still usable

// 2. Transfer: ownership moves and no bytes are copied.
const moved = new ArrayBuffer(SIZE);
port1.postMessage({ label: 'transfer', buf: moved }, [moved]);
console.log('sender after transfer:', moved.byteLength); // 0, buffer is detached

// 3. Shared: both sides reference the same memory.
// Every concurrent access must go through Atomics to avoid races.
const shared = new SharedArrayBuffer(4);
const counter = new Int32Array(shared);
port1.postMessage({ label: 'shared', buf: shared });
Atomics.add(counter, 0, 1); // atomic write, visible to the receiver
console.log('sender counter:', Atomics.load(counter, 0)); // 1

The same postMessage call copies an ArrayBuffer by default, moves it and detaches the sender's copy when the buffer is listed in transferList, and shares a SharedArrayBuffer that must then be accessed through Atomics.

How do you run worker threads in production with Piscina?

Spawning a Worker per request costs a fresh V8 isolate, module loading and warm-up every time. Under load, it also creates as many threads as there are requests. A fixed pool pays the startup cost once, keeps JIT-optimized code warm, and caps concurrency at a number you choose.

Defining the worker and submitting tasks

A Piscina worker module exports a single function. It receives the task payload and returns a value or a promise. In the main thread, construct the pool with filename pointing at that module, then call pool.run(payload). The call returns a promise, and any exception thrown inside the worker rejects that promise. Callers handle errors as they would for any async function. Large buffers can go in the transferList option.

Sizing and bounding

On some runtimes, os.cpus().length inside a container reports the host's cores, not your CPU quota. A pod limited to two CPUs on a 64-core node will oversubscribe badly. Set maxThreads from the actual limit. Read it from the cgroup quota or pass it in through an environment variable.

Set maxQueue too. Without it, a traffic spike piles tasks into memory until the process dies. With a bound, run() rejects once the queue is full. You can map that rejection to a 503 or a retry signal.

Lifecycle

  • Cancellation and timeouts: Pass signal to run(). AbortSignal.timeout(ms) gives you a deadline. Aborting a task that is already running terminates its thread, and Piscina replaces it.
  • Worker crashes: A thread that exits unexpectedly rejects its in-flight task, and Piscina starts a replacement.
  • Shutdown: On SIGTERM, stop accepting new work and await in-flight promises. Then call pool.destroy() before the process exits.
// worker.js exports one function; Piscina runs it in each pooled thread:
//   module.exports = ({ input }) => expensiveHash(input);

// server.js
const path = require('node:path');
const http = require('node:http');
const Piscina = require('piscina');

// Size from the container's CPU limit, passed in by the deployment.
// os.cpus().length can report the host's cores instead of the quota.
const THREADS = Number(process.env.WORKER_THREADS ?? 2);
const MAX_QUEUE = THREADS * 16; // caps queued tasks so a spike cannot exhaust memory

const pool = new Piscina({
  filename: path.resolve(__dirname, 'worker.js'),
  maxThreads: THREADS,
  maxQueue: MAX_QUEUE,
});

const server = http.createServer(async (req, res) => {
  if (pool.queueSize >= MAX_QUEUE) {
    res.writeHead(503, { 'Retry-After': '1' }).end(); // explicit backpressure
    return;
  }
  try {
    // If the deadline hits while the task runs, its thread is terminated and replaced
    const result = await pool.run({ input: req.url }, { signal: AbortSignal.timeout(2000) });
    res.end(JSON.stringify(result));
  } catch (err) {
    // Worker exceptions, crashed threads, timeouts and queue rejections all reject run()
    const timedOut = err.name === 'AbortError' || err.name === 'TimeoutError';
    res.writeHead(timedOut ? 504 : 500).end();
  }
});
server.listen(3000);

process.on('SIGTERM', () => {
  // Stop accepting connections; the callback runs once in-flight requests finish
  server.close(async () => {
    await pool.destroy(); // tear down worker threads before exiting
    process.exit(0);
  });
});

An HTTP server backed by a bounded Piscina pool. The pool is sized from an injected CPU limit and returns 503 when the queue is full and 504 on timeouts. On SIGTERM it waits for in-flight requests to finish, then destroys the pool.

Worked example: moving a CPU-heavy route handler into a pool

The handler starts as a login route that calls crypto.scryptSync inline. Every request holds the main thread for the full hash, so concurrent logins run one after another, and health checks wait behind them. The refactor moves the hashing call into a worker file that exports a single function taking { password, salt } and returning the derived key as a hex string. The route then awaits pool.run({ password, salt }). Return a string or a small buffer rather than a large object. Whatever crosses the thread boundary is structured-cloned, so keep the payload minimal.

Illustrative estimate (not a measured result)

Assumed inputs: 50 ms per hash, 8 simultaneous requests, 4 cores, a pool of 4 threads, and 1 ms of serialization and messaging overhead per task.

Metric Inline handler Piscina pool (4 threads)
Fastest response 50 ms ~51 ms
Slowest response 400 ms (8 × 50) ~102 ms (2 waves)
Mean response ~225 ms ~77 ms
Main-thread block per request 50 ms ~1 ms

The single-request case gets slightly slower because of the messaging overhead. The gains come from running hashes in parallel and from keeping the event loop free for other work.

Verifying the change

Measure the event loop under the same load you used before the change. Use monitorEventLoopDelay from perf_hooks and call enable() at startup. Then log percentile(99) and max on an interval and call reset() after each read. The histogram reports values in nanoseconds. Before the refactor, p99 should be close to the hash duration. After the refactor, it should fall to near the timer resolution. If p99 stays high, the main thread is still doing synchronous work somewhere else.

What does adopting worker threads cost, and when should you avoid them?

Each worker is a separate V8 isolate with its own heap, module cache and event loop, so memory grows linearly with pool size. On a small container, memory often caps the pool before CPU does.

Illustrative estimate (assumed numbers, not a benchmark): total ≈ main_baseline + workers × (worker_baseline + per_task_peak). Assume an 80 MB main thread, 4 workers, 30 MB per idle worker and 40 MB peak per task: 80 + 4 × (30 + 40) = 360 MB, against a 512 MB limit. Plug in your own heap snapshots.

A pool larger than the CPU quota the container actually gets adds no throughput. The threads compete for the same cores, and the main thread waits for CPU time, so I/O latency goes up. Size the pool from the cgroup quota, not the host core count.

Workers give you concurrency, not fault isolation. A segfault in a native addon or a container OOM kill still ends the whole process. Per-worker heap limits do not cover native memory.

Debugging also gets harder. Stack traces stop at the thread boundary. AsyncLocalStorage context, request IDs and logger bindings do not cross into workers, so you must pass them explicitly in the task payload. Some native modules are not safe to load in multiple threads. Module-level state is duplicated in every worker: in-memory caches, connection pools and counters become N independent copies that drift apart.

A pool library already handles queuing, worker restarts and cancellation. Writing those yourself takes weeks and tends to produce subtle bugs. Measure event loop delay first, and only change the architecture when the numbers show the event loop is blocked.

What are the alternatives to worker threads?

Worker threads are one of four ways to get CPU work off the request path. They differ mainly in where the isolation boundary sits.

Option Isolation Memory sharing Startup cost Communication overhead Deployment complexity
Worker threads Separate V8 isolate, same process SharedArrayBuffer, transferable buffers Low; reuse via a pool Structured clone or zero-copy transfer None beyond the app
Child processes Separate OS process None Higher: a full Node.js runtime per process Serialized IPC messages Low; same host and artifact
Cluster module Separate OS processes sharing a port None Higher, paid once at boot Not designed for task hand-off Low
Separate service Separate host or container None Independent of the API Network hop plus serialization High: its own deploys, scaling and monitoring

The cluster module is often mistaken for an alternative, but it addresses a different problem. It spreads incoming connections across cores. A heavy request still blocks every other request routed to the same process. Use it with workers, not in place of them.

Pick based on three questions:

  • What happens when a task crashes? If a native addon segfault or a runaway allocation must not take down the API, you need a process boundary. Use a child process or a separate service.
  • Does the work scale with request volume or on its own? If a queue of image jobs needs ten times the compute of the HTTP tier, a separate service lets you scale it independently.
  • Can the team run another deployable? If not, keep the work in-process with a worker pool and accept the shared failure domain.

How OneEnv can help

Disclosure: OneEnv is the product behind this blog.

OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.

Applied to node.js worker threads, this is where it helps:

Saves time

  • Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
  • One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
  • Changing a shared variable is one edit and one review instead of editing every service's .env by hand.

Saves cost

  • Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
  • Less duplicated configuration to maintain: one shared definition inherited by many services.
  • A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
  • OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.

These are qualitative benefits, not measured results — how much you save depends on how many services share the value.

Want to try it? Start at oneenv.io.