Node's Event Loop (libuv)

This topic assumes you've read languages/javascript/27-event_loop (js_event_loop_theory_1.md and js_event_loop_theory_2.md). That topic already covers the generic call-stack/queue mechanism, and its "Under the Hood" section already introduced libuv's six phases by name (timers → pending callbacks → idle/prepare → poll → check → close callbacks). This topic does not re-introduce that list — it goes further: which specific Node APIs land in which phase, and why, plus the thread pool's role from an architectural standpoint. Part 2 covers process.nextTick, setImmediate vs setTimeout ordering in depth, and UV_THREADPOOL_SIZE tuning.

1The Phases Aren't Generic — Each One Is Backed By Specific Node Machinery

2Two Fundamentally Different Roads Into the Poll Phase

The most important architectural fact this topic adds on top of the phase list: fs.readFile and a net socket read both eventually surface their callback in the poll phase, but they get there through completely different mechanisms.

const fs = require("fs");
const net = require("net");

fs.readFile(__filename, () => console.log("fs callback — poll phase, via THREADPOOL"));

net.createServer((socket) => {
  socket.on("data", () => console.log("socket callback — poll phase, via OS EPOLL/KQUEUE"));
}); // (not started — illustrative)

• fs.readFile: Node hands the blocking read() syscall to a libuv threadpool worker thread. The worker blocks (that's fine — it's not the JS thread), and when it finishes, it posts a completion event back to the loop. The loop picks that up and runs your callback during the poll phase.
• net socket data: libuv registers the socket file descriptor with the OS's native async I/O facility (epoll on Linux, kqueue on macOS/BSD, IOCP on Windows) via a single call in the poll phase itself. No thread pool worker is spent per socket — the OS itself notifies libuv "this fd is readable," and libuv fires the callback directly. This is architecturally why Node can hold open tens of thousands of idle sockets cheaply: it costs one file descriptor and a kernel-level registration, not a thread.

3setImmediate — Deliberately a Separate Phase From timers

const fs = require("fs");

fs.readFile(__filename, () => {
  setTimeout(() => console.log("timeout"), 0);
  setImmediate(() => console.log("immediate"));
  // inside an I/O callback, immediate ALWAYS logs first — deterministically
});

setImmediate exists specifically to run "right after I/O, this same iteration," which is exactly what "check phase, right after poll" gives you. That's a different guarantee than setTimeout(fn, 0), which lands in the timers phase — a phase the loop only reaches at the top of its next full cycle. When both are scheduled inside an I/O callback (as above), the loop is already past timers for this cycle and is sitting in poll; it proceeds to check next, so setImmediate reliably wins. At the top level of a script (outside any I/O callback), which one wins depends on how much time has elapsed reaching that point relative to the timer's expiry — which is why that specific case is the famous "non-deterministic" one (Part 2 covers this ordering question in more depth alongside process.nextTick).

⚠️ Common Pitfalls

1. Assuming all async Node APIs work the same way — fs and net both "feel" async from JS, but one consumes a threadpool thread and one doesn't; this matters for capacity planning under load (see Part 1's Architecture and Runtime topic for the threadpool-sizing implications).
2. Expecting setImmediate and setTimeout(fn, 0) to have a fixed relative order everywhere — it's deterministic inside an I/O callback, not at the top level of a script.
3. Forgetting the poll phase can BLOCK — if nothing else is scheduled, the loop waits in poll for I/O rather than spinning; this is why an idle Node process uses ~0% CPU instead of busy-looping.
4. Confusing "pending callbacks" (a specific phase for deferred system callbacks) with "any pending async operation" — it's a narrow, mostly-internal phase, not a general term.

📋 Quick Reference

fs.*            → threadpool → poll phase
net/http sockets → OS epoll/kqueue/IOCP → poll phase (no threadpool)
setTimeout/Interval → timers phase (min-heap by expiry)
setImmediate     → check phase (always right after poll)
socket 'close'   → close callbacks phase

Part 1 mapped Node's APIs onto libuv's six phases. This part covers the queue that ISN'T one of the six phases at all — process.nextTick — and pulls everything (phases, microtasks, nextTick) into one precise ordering model, then covers UV_THREADPOOL_SIZE tuning in practice.

1process.nextTick Is Not Part of libuv

This is the single most commonly misunderstood fact about Node's loop: process.nextTick has nothing to do with libuv's phases. It's a Node-specific queue, drained by Node's C++ layer — not a libuv construct at all — and it runs before Promise microtasks, and after every single callback, not just once per phase.

console.log("1: sync");

setTimeout(() => console.log("5: timeout"), 0);

process.nextTick(() => console.log("3: nextTick"));

Promise.resolve().then(() => console.log("4: promise microtask"));

console.log("2: sync");

Output: 1, 2, 3, 4, 5 — nextTick beats the Promise microtask, and both beat the macrotask-equivalent timer, exactly matching the generic microtask-drains-before-macrotask rule from languages/javascript/27-event_loop, but with nextTick given strict priority even over Promise callbacks.

2The Complete, Precise Ordering

after EVERY callback that runs (not just once per phase, EVERY single one):
  1. drain process.nextTick queue COMPLETELY (including new nextTicks added while draining)
  2. drain the Promise microtask queue COMPLETELY (including new ones added while draining)
  3. proceed to the next scheduled callback (may be same phase, or move to next phase)

This nests inside the six-phase cycle from Part 1: every time the loop is about to move from one callback to the next — even within the same phase, not just at phase boundaries — it stops and fully drains nextTick, then microtasks, before continuing.

const fs = require("fs");

fs.readFile(__filename, () => {
  console.log("A: fs callback (poll phase)");
  process.nextTick(() => console.log("B: nextTick"));
  Promise.resolve().then(() => console.log("C: microtask"));
  setImmediate(() => console.log("D: setImmediate (check phase)"));
});

Output: A, B, C, D — after the poll-phase callback (A) finishes, nextTick (B) and microtasks (C) drain completely before the loop even considers moving to the check phase for D.

3Why the Top-Level setTimeout vs setImmediate Race Is Genuinely Non-Deterministic

setTimeout(() => console.log("timeout"), 0);
setImmediate(() => console.log("immediate"));

At the top level of a script, both timers and check are still ahead of the loop when it starts. Which one the loop reaches "first" this cycle depends on exactly how much wall-clock time elapsed between process start and the loop's first pass through the timers phase — if more than ~1ms has already passed (process startup, module loading), the 0ms timer is already "expired" and fires in the timers phase before the loop even reaches check; if not, the timer isn't expired yet, the loop moves on to poll/check first, and setImmediate wins. This is real OS scheduling jitter, not a bug — which is exactly why Node's own docs call this specific ordering "not guaranteed" only at the top level.

4Threadpool Sizing in Practice

UV_THREADPOOL_SIZE=8 node server.js

// or, before ANY threadpool-using call in your entry file:
process.env.UV_THREADPOOL_SIZE = 8;

Raising the pool size gives more concurrent slots for fs.*, dns.lookup, and async crypto calls to run without queueing behind each other — useful for I/O-heavy workloads issuing many concurrent filesystem operations. It does not help:

• Network-socket-heavy workloads (net/http don't use the pool at all — see Part 1 §2).
• CPU-bound JavaScript (a tight loop in your own JS still fully occupies the one JS thread; more pool threads doesn't give your JS more places to run — see the Worker Threads topic for actual parallel JS execution).

UV_THREADPOOL_SIZE too small → fs-heavy code queues, throughput caps well below CPU capacity
UV_THREADPOOL_SIZE raised     → more concurrent fs/dns/crypto slots, up to the OS's own I/O limits
UV_THREADPOOL_SIZE raised, but bottleneck is CPU-bound JS → no improvement, wrong knob entirely

⚠️ Common Pitfalls

1. Treating process.nextTick as "the same as" setImmediate — the names invite confusion, but they're opposite ends of the priority spectrum: nextTick runs before even microtasks, setImmediate runs in the check phase, one of the last things each cycle.
2. Recursively scheduling process.nextTick can starve the entire event loop (no phase, no I/O, no timer ever runs) — the same starvation risk the generic microtask topic describes, but worse here because nextTick is drained with even higher priority than microtasks.
3. Relying on setTimeout(fn, 0) vs setImmediate() ordering at the top level of a script — only reliable inside an I/O callback (Part 1 §3); flaky at the top level.
4. Raising UV_THREADPOOL_SIZE to "fix" a slow server without profiling first — if the bottleneck is CPU-bound JS or network sockets, this env var changes nothing.

📋 Quick Reference

process.nextTick  → Node-specific queue, NOT libuv, drained before microtasks, after every callback
Promise microtasks → drained after nextTick, still after every callback
six libuv phases   → nested OUTSIDE the nextTick/microtask draining, not the other way around
setImmediate vs setTimeout(fn,0): deterministic inside I/O callbacks only (immediate wins)
UV_THREADPOOL_SIZE: helps fs/dns/crypto concurrency; does nothing for sockets or CPU-bound JS

🎤 Interview Q&A

🛠️ Practice exercises

Each exercise is a file in this topic folder. Code exercises are self-checking: run them and make the checks pass.

✅ Check yourself

Source: node_event_loop_libuv_theory_1.md, node_event_loop_libuv_theory_2.md · generated by tools/build_lessons.py