In Node.js, which core APIs run on libuv's threadpool rather than kernel I/O notification, and why do crypto.pbkdf2() and socket reads scale differently?
answer
- no portable non-blocking file API
- getaddrinfo is a blocking call
- fs, dns.lookup, zlib, async crypto
- four slots and a queue
basics
~20 sAsync fs calls, dns.lookup(), async zlib and crypto such as crypto.pbkdf2() and crypto.scrypt() run on libuv's threadpool, four threads by default, so only four proceed at once. Socket reads use kernel readiness notification and need no pool thread.
solid answer
~40 sNode uses the operating system's asynchronous interfaces where they exist and libuv's threadpool where they do not. Socket I/O, `dns.resolve*()` queries and timers are handled by the loop thread: non-blocking descriptors are registered with epoll, kqueue, event ports or IOCP, so ten thousand idle connections cost no threads. The pool runs blocking calls on Node's behalf: callback and promise `fs` APIs except the file watchers, `dns.lookup()` and `dns.lookupService()`, non-sync `zlib` calls, and async crypto such as `crypto.pbkdf2()`, `crypto.scrypt()`, `crypto.randomBytes()` and `crypto.generateKeyPair()`. With the default 4 threads a fifth concurrent `crypto.pbkdf2()` waits in the queue, and so does any `fs` call behind it. Hash throughput is capped by pool threads and cores; socket reads scale with what the kernel can watch.
code
javascript · 9 linesimport { pbkdf2 } from 'node:crypto';
const start = performance.now();
for (let i = 1; i <= 6; i++) {
pbkdf2('secret', 'salt', 1_000_000, 64, 'sha512', (err) => {
if (err) throw err;
console.log(`hash ${i} done after ${Math.round(performance.now() - start)} ms`);
});
}go deeper
Recall the four families on the pool: async fs, dns.lookup(), async zlib and async crypto such as crypto.pbkdf2(); sockets are not on it.
Explain why each family needs a thread (a blocking system interface or CPU work) and why sockets do not (readiness notification on non-blocking descriptors).
Show the queueing consequence: four default slots shared by unrelated work, dns.lookup() hidden inside every new outbound connection, and CPU-bound tasks capped by cores.
Treat the pool as a shared, process-wide resource with a fixed budget, and decide which work a service may place on it and which belongs in separate workers.
## Two ways Node waits for work Node's I/O is asynchronous from JavaScript's point of view in every case, but libuv achieves that in two different ways: 1. **Kernel readiness notification.** Where the operating system offers a non-blocking interface, libuv uses it directly on the loop thread. Sockets are put in non-blocking mode and registered with **epoll** (Linux), **kqueue** (macOS, BSDs), **event ports** (SunOS) or **IOCP** (Windows). The kernel reports which ones are ready; the loop reads or writes only those. 2. **The threadpool.** Where only a blocking interface exists, libuv runs the blocking call on one of its pool threads and reports completion to the loop. Regular file I/O has no portable non-blocking form, and the system resolver `getaddrinfo` blocks the thread that calls it. Either way, the JavaScript callback that receives the result runs on the main thread; only where the waiting or the work happens differs. ## What goes to the threadpool Node's CLI documentation lists the threadpool users, and the libuv docs confirm the file system and `getaddrinfo`/`getnameinfo` parts: | API family | Uses the pool | Why | |---|---|---| | `fs` callback and promise APIs | Yes, except the file watchers | File reads, writes and `stat` calls block the caller | | `*Sync` APIs (`fs.readFileSync()`, `crypto.pbkdf2Sync()`) | No, they run on the calling thread | They are synchronous by contract | | `dns.lookup()`, `dns.lookupService()` | Yes | They call `getaddrinfo(3)` and `getnameinfo(3)`, which block | | `dns.resolve4()` and other `resolve*()` | No | They send DNS queries over the network asynchronously | | `zlib` async calls such as `zlib.gzip()` | Yes | Compression is CPU work done off the main thread | | Async crypto: `crypto.pbkdf2()`, `crypto.scrypt()`, `crypto.randomBytes()`, `crypto.randomFill()`, `crypto.generateKeyPair()` | Yes | Key derivation and key generation are CPU-heavy | | `crypto.createHash()` and `crypto.hash()` | No | `hash.update()` and `hash.digest()` return synchronously | | `net`, `http`, `tls` socket traffic | No | Readiness notification on the loop thread | One subtlety: `http.request()` and `net.connect()` to a **hostname** call `dns.lookup()` by default before connecting, so even pure network code puts one pool task per new connection on the queue. Connecting to an IP address skips that lookup. ## What stays off the threadpool - Socket reads and writes for every network protocol. - `dns.resolve*()` and `dns.reverse()`, which do not read `/etc/hosts` and do not follow the same configuration files as `dns.lookup()`. - Timers and immediates, which are the loop's own bookkeeping. - All your JavaScript, including any CPU loop you write yourself. ## Why a hash and a socket read scale differently Take a service that hashes passwords with `crypto.pbkdf2()` while serving sockets, on the default pool of 4 threads: 1. A socket read costs the loop thread a little work when data is ready, and nothing while the client is idle. Ten thousand slow clients mean ten thousand registered descriptors, not ten thousand threads. 2. A `crypto.pbkdf2()` call occupies one pool thread for its whole duration, typically tens to hundreds of milliseconds depending on the iteration count. 3. With 4 threads, at most 4 hashes run at once. A fifth waits in the pool's queue, and so does every `fs` call and `dns.lookup()` submitted after it. 4. Throughput is therefore roughly `pool size / hash duration`, and it cannot exceed what the free CPU cores can compute, however large the pool is. So socket concurrency scales with the kernel's notifier, while pool-bound work scales with the pool size and the cores behind it, and it shares that pool with unrelated file and DNS work. ## Consequences - The pool is **global to the process** and shared by every event loop, including those of `worker_threads`. - Its size is fixed from startup by `UV_THREADPOOL_SIZE` (default 4, maximum 1024). - `fs.readFile()` reads in chunks, so a big file does not monopolise one pool thread for its whole length; a single large `crypto.randomBytes()` call is one task. - Libraries count too: any dependency that reads files, compresses responses or resolves hostnames draws from the same threads, so pool pressure is a property of the whole process, not of one module. - Raising the pool size helps work that waits (slow disks, `getaddrinfo` waiting on a DNS server) and buys free slots beside CPU-bound tasks; it does nothing for socket concurrency.
- Why does `dns.lookup()` use the threadpool while `dns.resolve4()` does not?`dns.lookup()` calls the operating system's `getaddrinfo(3)`, a blocking call, so Node runs it on a pool thread; in exchange it resolves names the way other programs on the host do, `/etc/hosts` included. `dns.resolve4()` sends DNS queries over the network itself, asynchronously and without the pool, but it does not consult `/etc/hosts` or the same configuration files.
- Does an `http.request()` to a hostname touch the threadpool even though HTTP traffic is network I/O?Usually once per new connection. Before connecting, `net` resolves the hostname with its default `lookup`, which is `dns.lookup()`, a pool task. The socket traffic afterwards is kernel-driven. Passing an IP address skips the lookup, and both `http.request()` and `net.connect()` accept a custom `lookup` function, for example one that caches results.
- Is `crypto.createHash('sha256')` offloaded to the threadpool like `crypto.pbkdf2()`?No. `hash.update()` and `hash.digest()` are synchronous and run on the calling thread, as does the one-shot `crypto.hash()`. They are fast for small inputs, but hashing a very large buffer this way occupies the main thread; for large data, feed the hash in chunks from a stream so other callbacks run between chunks, or do it in a `worker_threads.Worker`.
- Socket reads and writes are executed on libuv's threadpool threads.
- fs.promises APIs avoid the threadpool because they return promises.
- dns.resolve4() and dns.lookup() both tie up a pool thread per query.
- crypto.createHash() runs in the background just like crypto.pbkdf2().
- Raising UV_THREADPOOL_SIZE lets a server hold more open connections.