skip to content

In Node.js, what does the libuv poll phase wait on, and how does the loop decide how long to block there?

level: middleimportance: should knowfreq 45%

answer

  1. the one place the loop sleeps
  2. kernel notifier on watched descriptors
  3. nearest timer sets the deadline
  4. zero when there is other work

basics

~20 s

Node's poll phase waits in the kernel's I/O notifier for watched sockets to become ready and for finished threadpool tasks. It blocks until the nearest timer, indefinitely with no timers, and not at all if immediates or closing handles are pending.

solid answer

~40 s

In the poll phase libuv hands its watched file descriptors (listening sockets, connections, pipes, and the internal channel pool threads use to report finished tasks) to the platform notifier: epoll on Linux, kqueue on macOS and the BSDs, event ports on SunOS, IOCP on Windows. It then runs the callbacks for whatever is ready. Before blocking it computes a timeout: zero if the loop is stopping, has no active handles or requests, has handles waiting to close, or, in Node, has `setImmediate()` callbacks queued; otherwise the time until the nearest timer, or no limit when there are no timers. That is why an idle Node server uses almost no CPU, why a timer cannot fire before its threshold, and why a process holding only a listening socket simply waits in poll.

go deeper

for a junior

Recall that poll is where Node waits for I/O and that it sleeps in the kernel rather than spinning.

for a middle

Explain the timeout rules: zero when immediates, closing handles or no work exist, the nearest timer otherwise, infinite with no timers.

for a senior

Use the rules to explain production symptoms: a process that never exits, timers firing late behind long callbacks, near-zero CPU on an idle server.

for a principal

Connect the waiting model to capacity: a loop that is rarely in poll is saturated, which is the signal to measure loop utilisation and move work elsewhere.

## What the poll phase does The **poll phase** is the part of each Node.js event loop iteration that collects new I/O events. It does three things, in order: 1. **Compute a timeout**: how long it may block waiting for I/O. 2. **Block** in the operating system's notifier for at most that long. 3. **Run the callbacks** for every handle that became ready, until the queue is empty or a system-dependent maximum is reached. It is the only phase in which libuv deliberately sleeps. Every other phase runs what is already queued and moves on. ## What it waits on libuv's design notes describe the loop as single-threaded asynchronous I/O over **non-blocking** descriptors, polled with the best mechanism the platform offers: | Platform | Notifier | |---|---| | Linux | epoll | | macOS and other BSDs | kqueue | | SunOS | event ports | | Windows | IOCP | The things registered with that notifier include: - listening server sockets, for new connections; - connected TCP sockets, pipes and similar stream handles, for data or a hangup; - an internal wake-up channel through which libuv's threadpool reports that a task has finished, so an `fs.readFile()` or `crypto.pbkdf2()` callback is delivered in poll as well. The kernel answers with only the descriptors that are ready, and libuv invokes the matching callbacks, which become your `'connection'`, `'data'` or completion callbacks in JavaScript. ## How long it blocks libuv calculates the poll timeout from a short list of rules: | Situation | Poll timeout | |---|---| | The loop is being stopped | 0 | | No active handles or requests | 0 | | Handles waiting to be closed | 0 | | Idle handles are active | 0 | | None of the above, timers are pending | time until the closest timer | | None of the above, no timers | infinite | Node adds its own rule on top, stated in the Node.js guide: if the poll queue is empty and `setImmediate()` callbacks are waiting, the loop ends poll and moves to the check phase instead of waiting; if nothing is scheduled, it waits for callbacks to be added and runs them straight away. Once poll is done, any timers whose thresholds have passed run. The timeout is recomputed on every iteration, so a timer that a callback adds now shortens the next wait. ## A worked example Take a service that hashes a password with `crypto.pbkdf2()` and has a maintenance timer due in 200 ms. No sockets are ready. 1. The loop reaches poll with an empty queue, no immediates and a timer 200 ms away, so it blocks for at most 200 ms. 2. After 80 ms a pool thread finishes the hash and signals the loop. The notifier wakes poll early and the hash callback runs. 3. The loop recomputes the timeout: about 120 ms remain until the timer, so the next poll blocks for up to that long unless a socket becomes ready first. 4. When the deadline arrives, the timers phase runs the timer callback. If a long poll callback was still running, the timer simply runs late; nothing interrupts a running callback. ## What this explains in production - **Loop utilisation is measured against this wait**: Node's `perf_hooks` defines event loop utilisation as the share of time spent outside the event provider (for example `epoll_wait`), so a loop that rarely sleeps in poll is saturated. - **Idle servers use almost no CPU**: with no timers due, the main thread sleeps inside the kernel notifier. - **Timers are thresholds**: the deadline only bounds how long poll may sleep; a slow callback in any phase still pushes the timer later. - **Why the process stays up**: a listening server is an active, ref'd handle, so the loop is alive and, with no timers, blocks in poll indefinitely. - **Poll cannot starve everything forever**: libuv caps how many poll callbacks it runs in one pass so other phases get a turn, though a single slow callback is never interrupted. - **Recursive `process.nextTick()` work is a different hazard**: it runs between callbacks rather than in a phase, so the poll limit does not protect against it; that is covered in the lesson on tick-queue priority.

  • If a Node.js process has an open listening server and nothing else, why does it never exit?
    The listening socket is an active, ref'd handle, so libuv considers the loop alive. With no timers and no pending immediates the poll timeout is infinite, so the loop blocks in poll waiting for connections. It exits only once the server is closed, or unref'd with `server.unref()`, and nothing else keeps the loop alive.
  • In Node.js, can the poll phase starve timers by running I/O callbacks forever?
    Not indefinitely. The Node.js guide notes that libuv has a system-dependent hard maximum after which it stops polling for more events and moves on, so timers and check still get a turn. What it cannot do is interrupt a single long callback, so one slow handler still delays every due timer.

  • The poll phase spins the CPU checking each socket until data arrives.
  • Node's loop wakes every millisecond to look for new work.
  • A due timer interrupts a running poll callback so it fires on time.
  • The poll phase handles network sockets only, never threadpool results.
  • With no timers scheduled, the poll phase never blocks at all.