The previous lesson spread Escena Viva across seven workers and multiplied the server's capacity by almost five. But it left one problem untouched, and we said so bluntly: cluster does not unblock the event loop. When a worker settles down to compose the QR PDF for the 500 tickets of the Festival de Jazz de Primavera opening (evt-003, Auditorio Ribera), that process stops serving everybody for as long as the computation lasts.

In this lesson we measure that blocking with the instrumentation from Module 2, understand why threads are the right tool for CPU work (and cluster is not), and build our own ThreadPool inside Escena Viva, because creating one thread per request is worse than not using threads at all.

1. The blocking, measured with monitorEventLoopDelay
2. Cluster versus worker threads: the decision rule
3. node:worker_threads: the basic mechanism
4. Structured clone: what travels between threads and what it costs
5. Transfer versus copy: ArrayBuffer, SharedArrayBuffer and Atomics
6. Escena Viva's thread: src/workers/generate-tickets.js
7. ThreadPool: why one thread per request is a mistake
8. Errors inside the thread and how they propagate
9. Measurement before and after
10. When NOT to use threads

In Module 3 we left src/utils/ticket-qr.js with { encodeQr, decodeQr }: it signs the content with HMAC and encodes it as base64url. Generating the tickets for a full session means doing that once per ticket, plus composing the PDF. It is synchronous, CPU-bound work: there is no I/O to delegate, only computation.

Let's measure it before forming an opinion. This script simulates generating the 500 opening-night tickets while a timer tries to tick every 20 ms:

Result on the reference machine: Generation: 4180 ms, Beats: 3 (expected ~209), Maximum delay: 4176.44 ms.

Three beats where there should be 209. For 4.18 seconds the process ran absolutely nothing else: it answered no requests, serviced no PostgreSQL connection, processed no keep-alive. With SCHED_RR, the primary kept sending it connections —it has no idea the worker is busy— and those connections piled up in the system queue. When the worker came back, a traffic jam was waiting for it and the 99th percentile of the whole application shot up. With 7 workers the damage is 1/7 of the traffic; but if three organizers generate tickets at the same time (perfectly normal on opening night), three out of seven workers are frozen.

The decision rule, worth memorizing: cluster to scale I/O, threads to get CPU out of the way. They are not alternatives: in Escena Viva we will use both. Seven cluster workers, and inside each one a small pool of threads for the heavy work. And mind the arithmetic: 7 workers × 4 threads = 28 CPU threads on an 8-core machine is overselling. We will come back to it in section 7.

The module exposes the essentials in very few pieces:

A minimal example, with the events that matter:

And the thread's file, where workerData arrives already cloned (it is a copy, not a reference):

Two important nuances. First, postMessage does not end the thread; the thread lives until it runs out of pending work or somebody calls terminate(), and it can keep receiving tasks through parentPort.on('message', ...). This is precisely what allows reusing it in a pool. Second, each thread loads its own modules: if generate-tickets.js does a require of Sequelize, that require runs once per thread, with its startup and memory cost.

Messages between threads do not share memory by default: they are copied with the structured clone algorithm (the same one used by postMessage in the browser and by structuredClone). It is more capable than JSON.stringify, but it has strict limits.

The direct consequence for Escena Viva: you cannot send a Ticket or an Order instance and expect it to keep its methods. Our domain (src/domain/) uses classes; when crossing the thread boundary you must serialize to plain data and rebuild on the other side, which is why we will design it that way: the thread receives primitive data and returns primitive data. Copying is not free either: cloning 500 ticket objects is on the order of a millisecond, but cloning an 8 MB PDF as a Buffer is on the order of tens. If the result is large, transfer it instead of copying it.

postMessage accepts a second argument with the list of transferable objects: parentPort.postMessage({ data: arrayBuffer }, [arrayBuffer]). A transferred ArrayBuffer is not copied, it changes owner, and the sending thread is left with a detached buffer (byteLength === 0). It is the right way to return a PDF of several megabytes, and we will see it applied in section 6.

SharedArrayBuffer goes one step further: the same memory is visible from several threads at once, with no copy and no transfer. It is the tool for shared counters, such as the number of tickets generated on opening night:

A serious warning. Until now, in single-threaded JavaScript, memory race conditions simply did not exist: between two lines of your function nobody could modify your variables. SharedArrayBuffer opens that door. counters[0] += 1 is three operations (read, add, write) and two threads can interleave them and lose increments. That is why Atomics exists (add, load, store, compareExchange, wait, notify). Use it always to touch shared memory, and use shared memory only when you genuinely need it: for structured data, cloning is slower but infinitely safer.

The thread receives the plain data for a batch of tickets, generates each one's signed QR reusing encodeQr from Module 3, composes the PDF and returns the result by transferring the buffer.

Notice the design decision: the thread does not throw exceptions upwards, it turns them into responses. An uncaught throw would fire the error event and kill the thread, forcing the pool to create another one. Catching inside and answering with ok: false keeps the thread reusable.

We measured the startup cost of a thread that does a require of our code: between 18 and 40 ms. If the task lasts 4,000 ms, that cost is noise. But for small batches —a single ticket bought by Lucía for ses-001-1— the task lasts 12 ms and startup costs three times as much as the work. Worse still: 50 simultaneous requests would create 50 threads, that is 50 V8 instances competing for 8 cores, with hundreds of megabytes of memory and a collapse from context switching.

The solution is a pool: a fixed, small number of threads created at startup, a task queue, and reuse.

About the pool size: for purely CPU-bound work, more threads than cores adds nothing but context switching. And since each cluster worker has its own pool, the real calculation is clusterWorkers × poolSize ≤ cores. With 7 workers on 8 cores, the pool should be 1 or 2 threads. This tension —cluster and threads competing for the same cores— is why many architectures end up taking the heavy work out of the web server entirely, into a separate process with a queue: lesson 10-03. In production, moreover, the piscina library does all this and more (cancellation with AbortSignal, thread recycling after N tasks, queue limits, metrics); we wrote our own to understand what it does inside.

The application service ends up this simple:

It fits without friction into the Module 9 refactor: controllers are factories with injected dependencies, so the pool is injected as one more dependency and in tests it is replaced by a Sinon double.

One nuance about the timeout: our run rejects the promise, but the thread keeps computing. For a genuine infinite loop you have to call terminate() and recreate the thread (exercise 2).

Scenario: Festival de Jazz opening night, with a base load of 500 requests per second against the catalog and, every 2 seconds, an organizer requesting the PDF for a batch of 500 tickets.

Read that last row carefully: the generation takes slightly longer (4,390 versus 4,180 ms), because the input request has to be cloned, the result transferred and the pool coordinated. Threads do not speed up the heavy task; what they do is get it out of everyone else's way. The catalog p99 drops from 6.8 seconds to 74 milliseconds, and that is the only figure that matters to somebody trying to buy a ticket while the batch is generated.

Threads have a real cost (memory, startup, complexity, serialization). Do not use them if:

1. The task is I/O. Reading a file, querying PostgreSQL, calling the currency API: that is already asynchronous and blocks nothing. Putting a SQL query in a thread does not speed it up; it only adds a data copy and a hop between threads. This is the most frequent misunderstanding.
2. The task is trivial. If the work lasts 2 ms, the cloning and handover cost more than doing it on the spot. Rough threshold: below ~10-20 ms of CPU it is not worth it.
3. The task can be chunked. In Module 2 we saw how to split a long loop with setImmediate to hand control back to the loop between chunks. If the work can be cut cleanly and is not enormous, chunking is simpler than a pool.

Chunking cuts the maximum loop delay down to the duration of one chunk (about 200 ms in our case), which is already acceptable for many applications, and it costs neither a thread nor a megabyte. The trade-off is that the total task takes longer and still consumes the one and only main thread.

4. The task is genuinely long. If generating and e-mailing the 500 opening-night tickets takes minutes, neither a thread nor chunking is the answer: the HTTP request should not wait at all. You have to take the work out of the process and enqueue it, answer 202 Accepted with an identifier, and let the client poll the status. That is the subject of the next lesson.

• Creating a Worker per request. The most expensive mistake. Always a pool, created when the process starts.
• Sending domain class instances. They arrive as plain objects with no methods: serialize to data and rebuild on the other side.
• Putting I/O in a thread. It improves nothing: the I/O was already asynchronous.
• Using SharedArrayBuffer without Atomics, or forgetting that a transferred ArrayBuffer is left empty in the sender.
• Not setting a timeout on tasks. A hung thread holds its slot in the pool forever and ends up stopping all generation.
• Tip: expose pool.status() in your health endpoint. A queue that grows without stopping tells you the pool is undersized or that you need to enqueue outside the process.
• Tip: always measure with monitorEventLoopDelay before and after. If the delay does not drop, threads were not the problem.

Write a script that starts a minimal HTTP server with a /block route that computes 500 SHA-256 hashes of 100,000 iterations each, synchronously, and a /ping route that answers { ok: true }. With autocannon against /ping, measure the p99 at rest and while /block is running. Record the loop delay with monitorEventLoopDelay.

Modify ThreadPool so that, when timeoutMs expires, besides rejecting the promise it calls terminate() on the blocked thread and replaces it. Check the behavior with a thread that runs while (true) {}.

With 4 threads each incrementing the same Int32Array over a SharedArrayBuffer 100,000 times, compare the result using counters[0] += 1 versus Atomics.add(counters, 0, 1). Explain the difference.

Exercise 1. At rest, /ping gives a p99 of 2-4 ms. During /block, every request to /ping piles up and the p99 climbs to several seconds: exactly the duration of the synchronous computation. The histogram shows a max almost identical to that duration, because the loop did not turn even once. The correct reading is that /ping has no problem at all: the problem is a noisy neighbor on the same thread. It is this lesson's entire argument in 30 lines of code.

Exercise 2. Inside run's setTimeout, you locate the thread with this.threads.find((t) => t.currentTask === taskId), remove it from the pool, call await hungThread.terminate() —which kills the thread even if it is in a loop— and create a new one before rejecting the promise. With while (true) {} in the thread, without terminate() the pool slot is lost forever and after N hung tasks the pool is unusable. With terminate(), the pool recovers on its own. Note: terminate() kills the thread immediately and no graceful shutdown is possible inside it.

Exercise 3. With counters[0] += 1 the expected total is 400,000 but the observed one is around 120,000-250,000, and it varies on every run. The reason is that += is three steps (read, add, write) and two threads can read the same value and write the same result, losing one increment. With Atomics.add the total is exactly 400,000, always: the operation is indivisible at the CPU level. The moral is twofold: shared memory introduces a class of bugs that did not exist in JavaScript, and those bugs are non-deterministic, so your Module 9 tests can pass a thousand times and fail in production on opening night.

We have turned a 4.18-second block into an 11-millisecond delay. We measured the problem with monitorEventLoopDelay, drew a clear line between when cluster applies (I/O concurrency) and when threads do (CPU work), understood what travels between threads through structured clone and what does not, learned to transfer instead of copy and to share memory with Atomics without opening the door to race conditions, and built src/workers/generate-tickets.js and src/workers/pool.js with a queue, reuse, a timeout and error recovery. We also learned the limits: threads do not speed the task up, they only move it aside; they are useless for I/O; they are not worth it for trivial work; and they compete for the same cores as the cluster workers, which forces you to size things sensibly.

And one piece is still out of place. Generating the PDF no longer blocks, but the Auditorio Ribera organizer is still waiting four and a half seconds with the HTTP request open for it to finish. If those 500 tickets also have to be e-mailed, the wait becomes absurd. The answer is not a faster thread: it is not waiting. In the next lesson, Caching and Job Queues with Redis, we will move the heavy work out of the process, answer 202 Accepted with a job identifier, cache the catalog that today is recomputed on every request, and along the way settle the debt lesson 10-01 left behind: sessions and rate limits shared across every worker.