Understanding libuv’s Design: A Deep Dive into Its Event Loop and Cross‑Platform Architecture

Overview

libuv is a cross‑platform asynchronous I/O library originally developed for Node.js, but it is also used by Luvit, Julia, pyuv and other software. It follows an event‑driven asynchronous I/O model.

Beyond simple abstractions of the various I/O polling mechanisms, libuv provides highly abstracted handles and streams for sockets and related objects, as well as cross‑platform file I/O and multithreading interfaces.

Handles and Requests

To let users interact with the event loop, libuv defines two abstractions: handles and requests.

A handle represents a persistent object that can perform operations when activated. For example, a prepare handle’s callback is invoked on every loop iteration, and a TCP server handle’s connection callback runs whenever a new TCP connection arrives.

A request represents a short‑lived operation. Requests may act on a handle, such as write requests that send data to a handle, or they may be independent of any handle, such as getaddrinfo requests that execute directly on the loop.

Event Loop

The event loop is the core of libuv. It creates the context for all I/O operations and runs in a single thread, although multiple loops can run in different threads. Unless otherwise noted, libuv’s loop and its APIs are not thread‑safe.

The loop follows the typical single‑threaded asynchronous I/O behavior: non‑blocking sockets represent network I/O, and libuv selects the optimal polling mechanism for each platform (epoll on Linux, kqueue on macOS/BSD, event ports on SunOS, IOCP on Windows). During each iteration the loop blocks waiting for I/O activity on added sockets, then dispatches callbacks based on the socket’s state (readable, writable, pending).

The following diagram shows one iteration of the event loop.

The iteration consists of the following steps:

Update the loop’s “now” time, caching the current time to reduce system calls.

If the loop is still alive (has active handles, requests, or closing handles), start the iteration; otherwise exit.

Execute due timers—any timer whose timeout is before the current “now”.

Execute pending callbacks. Normally I/O callbacks run immediately after polling, but some may be deferred to the next iteration.

Execute idle handle callbacks. Active idle handles run on every iteration.

Execute prepare handle callbacks before the loop blocks for I/O.

Compute the poll timeout:

If the loop runs with UV_RUN_NOWAIT, the timeout is 0.

If uv_stop() has been called, the timeout is 0.

If there are no active handles or requests, the timeout is 0.

If there are active idle handles, the timeout is 0.

If there are handles waiting to be closed, the timeout is 0.

Otherwise the timeout is the earliest timer’s timeout, or infinity if no timers are active.

Block for I/O using the computed timeout.

Execute check handle callbacks (counterparts of prepare handles) after I/O blocking ends.

Execute close callbacks; a handle closed with uv_close() triggers its close callback.

If no I/O callbacks fired, any timers that have timed out are still executed. When the loop runs with UV_RUN_ONCE, these timer callbacks run at this point.

End the iteration. If the loop was run with UV_RUN_NOWAIT or UV_RUN_ONCE, uv_run() returns. If it was run with UV_RUN_DEFAULT, the loop continues to the next iteration if it is still alive.

Important: although libuv’s asynchronous file I/O is implemented via a thread pool, network I/O always executes in the single thread.

Note: despite different platform‑specific poll mechanisms, libuv’s execution model remains consistent across platforms.

File I/O

Unlike network I/O, there is no platform‑specific non‑blocking file I/O primitive, so libuv performs file operations in a thread pool to simulate asynchrony.

libuv uses a global thread pool shared by all loops. Three kinds of work are dispatched to this pool:

File system operations.

DNS functions ( getaddrinfo and getnameinfo).

User code added via uv_queue_work().

Note: see the dedicated thread‑pool article for more details; the pool size is limited.