Blocking the loop and the thread pool
One slow synchronous call freezes every user on the process. Learn to spot event-loop blockers and the hidden four-thread pool behind fs, DNS and zlib.
Because one thread runs all JavaScript, any synchronous work holds up everyone. A 200 ms JSON.parse of a 50 MB tool result stops the loop for 200 ms. Every other user's token stream freezes for exactly that long, and every pending timer and socket read waits.
Three streams and one big parse
- Longest gap between tokens
- ≈ 200 ms
- Users affected
- All 3
- Main thread during parse
- Busy
Fixes, in order of preference
- 01Do less
Do not parse what you will not read. Cap tool output by bytes before parsing, or keep it as text.
- 02Stream it
Parse incrementally as bytes arrive, so no single step is long.
- 03Chunk it
Break the work into pieces and yield between them with
setImmediate. - 04Move it
Run it in a
worker_threador a separate process. Workers have their own event loop and heap, and communicate by message passing or SharedArrayBuffer.
The libuv thread pool
Not all I/O in Node is non-blocking in the kernel. File system calls, dns.lookup, zlib compression and some crypto functions run on libuv's thread pool, which has 4 threads by default. If four slow DNS lookups occupy the pool, an unrelated fs.readFile waits in line behind them.
Four threads, one queue
- fs.readFile("config.json")waiting 1.6 s
- crypto.pbkdf2(…)waiting
- Thread 1
dns.lookup("api.slow.example")2.1 s and counting - Thread 2
dns.lookup("cdn.slow.example")1.8 s and counting - Thread 3
dns.lookup("auth.slow.example")1.6 s and counting - Thread 4
zlib.gzip(8 MB)40 ms
fs.readFile waits in the queue though the disk is idle. Network sockets do not use the pool; they go through epoll on the main loop.# Raise the pool size before Node starts (read once at startup)
UV_THREADPOOL_SIZE=16 node server.js
# Find event-loop blockers with a CPU profile
node --cpu-prof server.js # writes a .cpuprofile; open it in Chrome DevTools
# Or warn on blocking sync calls during development
node --trace-sync-io server.jsdns.resolve* uses c-ares on the network instead of the thread pool. dns.lookup uses the system resolver through the pool.
Where you will meet it
Agent servers cap and stream tool output, and parse big JSON in workers, so one heavy run does not stall others on the same instance.
Services have stalled file I/O because a resolver became slow and dns.lookup calls filled the thread pool.
Image resizing and PDF parsing are usually moved to worker pools or separate services, keeping the request loop free.
Check yourself
Answer out loud before you open each one.
Why can one JSON.parse hurt every user?
It runs synchronously on the single event-loop thread, so nothing else runs until it finishes.
Which Node operations use the libuv thread pool?
File system calls, dns.lookup, zlib and some crypto such as pbkdf2 and scrypt.
How would you find what is blocking the loop?
Measure loop delay, then take a CPU profile or flame graph during the stall and look for long synchronous frames.
Try it
Start a Node HTTP server with a /stream endpoint that writes a line every 20 ms and a /parse endpoint that parses a 50 MB JSON string. Hit /stream with curl, then call /parse and watch the stream pause. Move the parse into a worker and repeat.