Node.js Architecture — Event Loop, libuv, and Async I/O

Every Node.js developer eventually hits the wall: the server was handling 10,000 requests per second and suddenly dropped to 200. CPU at 100%, event loop lag spiking to seconds. The fix was moving a synchronous crypto call to a worker thread. Understanding Node.js architecture — not just how to write Express routes — is what separates engineers who can fix production incidents from those who cause them. This article breaks down the event loop phases, libuv's role, the thread pool, and the exact operations that block each phase.

The Single-Threaded Myth: What Node.js Actually Is

Node.js is often described as single-threaded, but that's only half the truth. The JavaScript execution runs on a single thread, but the runtime itself is heavily multi-threaded. libuv, the C library that powers Node's async I/O, maintains a thread pool for operations that the OS can't do asynchronously — like file system calls and DNS lookups. The event loop orchestrates all of this on the main thread, but heavy CPU work blocks it. Understanding this distinction is critical: your JavaScript code is single-threaded, but Node.js is not. This means you can't offload CPU-intensive tasks to the event loop; you need worker threads or child processes.

const crypto = require('crypto');

// This blocks the event loop
const start = Date.now();
crypto.pbkdf2Sync('password', 'salt', 100000, 64, 'sha512');
console.log('Sync took', Date.now() - start, 'ms');

// This does not block because it's async
crypto.pbkdf2('password', 'salt', 100000, 64, 'sha512', (err, key) => {
  console.log('Async took', Date.now() - start, 'ms');
});

console.log('I run immediately');

The Event Loop: Phases and Priorities

The event loop is a loop that processes callbacks in phases. The main phases are: timers (setTimeout, setInterval), pending callbacks (I/O callbacks deferred to next iteration), idle/prepare (internal), poll (retrieve new I/O events), check (setImmediate callbacks), and close callbacks (socket.on('close')). The poll phase is where most I/O callbacks run. If the poll queue is empty, the loop will wait for new I/O events, but only up to the timer's threshold. setImmediate callbacks run after poll, while setTimeout(fn, 0) callbacks run in the timers phase. This ordering matters: setImmediate always fires before setTimeout(fn, 0) if both are in the same I/O cycle. Understanding this prevents subtle timing bugs.

const fs = require('fs');

fs.readFile(__filename, () => {
  setTimeout(() => console.log('timeout'), 0);
  setImmediate(() => console.log('immediate'));
});

// Output order: immediate, then timeout

libuv: The Engine Under the Hood

libuv is the C library that provides the event loop and asynchronous I/O. It abstracts platform-specific async APIs (epoll on Linux, kqueue on macOS, IOCP on Windows) into a unified interface. libuv also manages a thread pool (default size 4) for operations that lack native async support: file I/O, DNS lookups, and some crypto functions. When you call fs.readFile, libuv queues the work to a thread. The thread performs the blocking read, then posts the callback to the event loop's pending queue. This is why Node can handle many file operations without blocking — the threads do the waiting, not the main thread. However, the thread pool is finite; if all threads are busy, subsequent requests queue up.

const crypto = require('crypto');
const start = Date.now();

// Default thread pool size is 4
for (let i = 0; i < 5; i++) {
  crypto.pbkdf2('password', 'salt', 100000, 64, 'sha512', () => {
    console.log(`Done ${i} in ${Date.now() - start}ms`);
  });
}

// Output shows 4 finish quickly, then the 5th waits

Async I/O: Non-Blocking by Default

Node.js uses non-blocking I/O for network operations (sockets, HTTP) and some file operations. When you make an HTTP request, the OS kernel handles the actual network I/O asynchronously. Node registers a callback and continues executing. When the kernel signals completion, libuv adds the callback to the event loop. This is why Node can handle thousands of concurrent connections with a single thread — it never waits for I/O. However, not all I/O is created equal. File system operations on Linux (except for AIO) are blocking in the kernel, so libuv uses threads. Network I/O is truly asynchronous at the OS level. Understanding this helps you choose the right API: use streams for large data, avoid synchronous fs methods in request handlers.

const http = require('http');

// Non-blocking HTTP server
const server = http.createServer((req, res) => {
  // Simulate async work
  setTimeout(() => {
    res.end('Hello');
  }, 100);
});

server.listen(3000, () => {
  console.log('Server listening on port 3000');
});

// This server can handle many concurrent requests without blocking

The Microtask Queue: Promises and process.nextTick

Microtasks are callbacks that are executed after the current operation completes, but before the next event loop iteration. The microtask queue includes Promise callbacks (then/catch/finally) and process.nextTick callbacks. process.nextTick has the highest priority — it runs before any other microtask or macrotask. This can lead to starvation if you recursively call nextTick. Promises are also microtasks but are processed after nextTick. Understanding the microtask queue is crucial for debugging async code: a Promise resolved synchronously will have its .then callback run after the current synchronous code, but before any I/O or timer callbacks. This can cause unexpected ordering.

console.log('start');

setTimeout(() => console.log('timeout'), 0);

Promise.resolve().then(() => console.log('promise'));

process.nextTick(() => console.log('nextTick'));

console.log('end');

// Output: start, end, nextTick, promise, timeout

Common Pitfalls: Blocking the Event Loop

The most common production issue is accidentally blocking the event loop. CPU-intensive operations like JSON.parse on large payloads, cryptographic operations, or complex regex can stall the loop. Even a single synchronous operation can cause latency spikes. Tools like clinic.js or the built-in profiler can detect event loop lag. Another pitfall is forgetting to use the async version of fs methods — fs.readFileSync in a request handler will block all other requests. Also, beware of synchronous loops that do heavy computation. The solution is to offload CPU work to worker threads or split work into chunks with setImmediate.

const http = require('http');

// BAD: blocks the event loop
http.createServer((req, res) => {
  // Simulate CPU-heavy work
  for (let i = 0; i < 1e9; i++) {}
  res.end('done');
}).listen(3000);

// GOOD: offload to worker thread or chunk
http.createServer((req, res) => {
  setImmediate(() => {
    // Do work in chunks
    let i = 0;
    function chunk() {
      for (let j = 0; j < 1e6; j++) { i++; }
      if (i < 1e9) setImmediate(chunk);
      else res.end('done');
    }
    chunk();
  });
}).listen(3001);

Worker Threads: Parallelism for CPU Work

Worker threads (introduced in Node 10) allow JavaScript to run in parallel on separate threads. Each worker has its own V8 instance and event loop, but they share memory via SharedArrayBuffer. Workers are ideal for CPU-intensive tasks like image processing, data transformation, or complex calculations. Unlike child processes, workers are lightweight and can communicate via message passing. However, spawning too many workers can overwhelm the system. A common pattern is to use a worker pool (e.g., workerpool npm module) to limit concurrency. Workers also have access to libuv's thread pool, but they don't share it with the main thread.

const { Worker } = require('worker_threads');

function runWorker(data) {
  return new Promise((resolve, reject) => {
    const worker = new Worker('./worker.js', { workerData: data });
    worker.on('message', resolve);
    worker.on('error', reject);
    worker.on('exit', (code) => {
      if (code !== 0) reject(new Error(`Worker stopped with exit code ${code}`));
    });
  });
}

// worker.js
const { parentPort, workerData } = require('worker_threads');
// Do CPU work
let result = 0;
for (let i = 0; i < 1e9; i++) { result += i; }
parentPort.postMessage(result);

Production Monitoring: Event Loop Lag and Memory

In production, you must monitor event loop lag — the time between when a callback is scheduled and when it actually runs. High lag indicates the event loop is blocked. Use tools like process.hrtime() to measure, or use APM agents (Datadog, New Relic). Also monitor libuv thread pool utilization; if all threads are busy, file I/O will queue up. Memory leaks are another common issue: closures holding references, large buffers not freed, or event listeners not removed. Use heap snapshots and tools like clinic.js to diagnose. Set up alerts for event loop lag > 50ms and memory usage growth.

let lastCheck = process.hrtime.bigint();
setInterval(() => {
  const now = process.hrtime.bigint();
  const lag = Number(now - lastCheck) / 1e6; // ms
  if (lag > 50) {
    console.warn(`Event loop lag: ${lag.toFixed(2)}ms`);
  }
  lastCheck = now;
}, 1000);

Optimizing Async Patterns: Avoiding Anti-Patterns

Common async anti-patterns include: using async/await in loops sequentially (instead of Promise.all), forgetting to handle promise rejections (unhandledRejection), and mixing callbacks with promises. For sequential async operations, use a for loop with await, but for parallel operations, use Promise.all. Be careful with Promise.all — if one promise rejects, all are lost. Use Promise.allSettled for fault tolerance. Also, avoid creating promises for synchronous operations; it adds overhead. Use the async versions of Node APIs (fs.promises) instead of callback-based ones. Finally, avoid deep promise chains; use async/await for readability.

// BAD: sequential
async function bad(urls) {
  const results = [];
  for (const url of urls) {
    results.push(await fetch(url));
  }
  return results;
}

// GOOD: parallel
async function good(urls) {
  return Promise.all(urls.map(url => fetch(url)));
}

// BETTER: with error handling
async function better(urls) {
  const results = await Promise.allSettled(urls.map(url => fetch(url)));
  return results.filter(r => r.status === 'fulfilled').map(r => r.value);
}

The Future: Node.js 22 and Beyond

Node.js continues to evolve. Recent improvements include: stable WebSocket support, built-in test runner, and performance improvements in V8. The event loop remains the core, but new APIs like node:fs promises are now stable. The libuv thread pool size can be set via environment variable. There's ongoing work on making the event loop more efficient, like reducing timer overhead. For production, stay updated with LTS releases. The architecture is unlikely to change drastically, but understanding the fundamentals will always be valuable. Keep an eye on the Node.js roadmap for features like direct TCP support for QUIC.

console.log(`Node version: ${process.version}`);
console.log(`V8 version: ${process.versions.v8}`);
console.log(`libuv version: ${process.versions.uv}`);

Real-World Case Study: Event Loop Blocking in Production

A common real-world scenario: a Node.js API server starts experiencing intermittent high latency. After investigation, you find that a new feature added a synchronous bcrypt.hashSync call in a request handler. This blocks the event loop for 100ms per request. Under load, all requests queue up, causing cascading delays. The fix: replace with bcrypt.hash (async) or offload to a worker thread. Another case: a developer used JSON.parse on a large request body (10MB) synchronously, blocking the loop for 200ms. The solution: use a streaming JSON parser or limit body size. These examples show why understanding the event loop is critical for production reliability.

// BAD: synchronous bcrypt
const bcrypt = require('bcrypt');
app.post('/login', (req, res) => {
  const hash = bcrypt.hashSync(req.body.password, 10); // blocks
  // ...
});

// GOOD: async bcrypt
app.post('/login', async (req, res) => {
  const hash = await bcrypt.hash(req.body.password, 10);
  // ...
});

Conclusion: Mastering the Event Loop for Reliable Systems

Node.js's event loop and libuv are powerful, but they require understanding to avoid pitfalls. The single-threaded nature of JavaScript means you must be careful not to block the loop. Use async I/O, offload CPU work to worker threads, and monitor event loop lag. The architecture is not a black box; it's a well-defined system of phases, queues, and threads. By mastering these concepts, you can build high-performance, reliable Node.js applications. Remember: the event loop is your friend, but only if you treat it right.

// Summary of key points
console.log('1. JavaScript is single-threaded, but Node is not.');
console.log('2. Event loop phases: timers, I/O, poll, check, close.');
console.log('3. libuv provides thread pool for blocking I/O.');
console.log('4. Microtasks run before macrotasks.');
console.log('5. Worker threads for CPU work.');
console.log('6. Monitor event loop lag in production.');

libuv C-Level Internals: epoll, kqueue, IOCP, and io_uring

libuv abstracts operating system asynchronous I/O facilities into a unified API. On Linux, it uses epoll; on macOS/BSD, kqueue; on Windows, IOCP (I/O Completion Ports). Each backend has different characteristics: epoll scales well with many file descriptors but has edge-triggered vs level-triggered nuances; kqueue is efficient for small sets; IOCP is Windows-native with thread pool integration. Since Node.js 20 (libuv v1.44+), io_uring support is available on Linux kernels 5.1+. io_uring reduces syscall overhead by using shared submission and completion queues, enabling true zero-copy I/O and better performance for high-throughput workloads. However, io_uring is not the default yet; you must set the environment variable UV_USE_IO_URING=1 to enable it. The C-level implementation lives in src/unix/ (epoll, kqueue, io_uring) and src/win/ (IOCP). Understanding these backends helps diagnose platform-specific performance issues.

# Check if io_uring is available and enabled
cat /proc/sys/kernel/io_uring_disabled  # 0 means enabled
# Run Node with io_uring
UV_USE_IO_URING=1 node -e "console.log('io_uring active')"

uv_run Modes: DEFAULT, ONCE, NOWAIT

The event loop is driven by uv_run(), which has three modes: UV_RUN_DEFAULT, UV_RUN_ONCE, and UV_RUN_NOWAIT. UV_RUN_DEFAULT runs the loop until there are no more active handles or requests. UV_RUN_ONCE performs a single iteration: it polls for I/O with a timeout, processes pending callbacks, and returns. UV_RUN_NOWAIT polls once without blocking and returns immediately. Node.js uses UV_RUN_DEFAULT for the main loop, but UV_RUN_ONCE is used internally for process.nextTick and microtask draining. Understanding these modes is crucial for embedding libuv in custom C++ addons or when debugging event loop stalls. For example, if you call uv_run(UV_RUN_NOWAIT) in a tight loop, you may starve I/O callbacks. The mode affects how the event loop balances CPU and I/O tasks.

// Simulating uv_run modes in Node.js (conceptual)
const fs = require('fs');

// DEFAULT: full loop
setTimeout(() => console.log('timeout'), 0);
setImmediate(() => console.log('immediate'));
fs.readFile(__filename, () => console.log('I/O'));
console.log('start');
// Output order: start, (I/O or timeout/immediate depending on phase)

// ONCE: one iteration (not directly exposed in Node)
// NOWAIT: poll once, no blocking (not directly exposed)

Handle and Request Lifecycle in libuv

libuv has two core abstractions: handles and requests. Handles represent long-lived objects (e.g., uv_tcp_t, uv_timer_t, uv_signal_t). Requests represent short-lived operations (e.g., uv_connect_t, uv_write_t, uv_fs_t). A handle must be initialized (uv__init), started (uv__start), and eventually closed (uv_close). Requests are allocated, initiated (uv_*_req), and their callbacks fire on completion. Memory management is manual: you must free request structs in callbacks. The lifecycle is: init → start → (callback) → close. For example, a TCP server handle is initialized, bound, listened, and closed on shutdown. A connect request is allocated, initiated, and freed in the connect callback. Misunderstanding this leads to memory leaks or dangling pointers. Node.js abstracts this, but native addon developers must handle it explicitly.

#include <uv.h>
#include <stdio.h>

uv_loop_t *loop;
uv_tcp_t server;

void on_close(uv_handle_t* handle) {
    printf("Closed\n");
}

int main() {
    loop = uv_default_loop();
    uv_tcp_init(loop, &server);
    // ... bind and listen
    uv_close((uv_handle_t*)&server, on_close);
    uv_run(loop, UV_RUN_DEFAULT);
    return 0;
}

Kernel Polling Backend Comparison

The choice of I/O polling backend affects performance and scalability. epoll (Linux) supports edge-triggered and level-triggered modes; edge-triggered requires non-blocking I/O and careful handling of EAGAIN. kqueue (macOS/BSD) supports event filters for file, socket, signal, and process events; it's efficient for small numbers of FDs but doesn't scale as well as epoll for thousands. IOCP (Windows) uses a thread pool and completion ports, inherently supporting asynchronous I/O without polling. io_uring (Linux 5.1+) uses shared ring buffers between user and kernel space, reducing syscall overhead and enabling features like splice and openat2. In practice, epoll is the most battle-tested for high-concurrency Linux servers. io_uring shows promise for high-throughput scenarios (e.g., database drivers, file servers) but has higher setup complexity. For most Node.js applications, the default backend is sufficient; only tune if profiling shows polling as a bottleneck.

// Check which libuv backend is in use
const process = require('process');
const report = process.report.getReport();
console.log('libuv backend:', report.libuv?.backend);
// Or use uv_metrics (Node 22+)
// const { uvMetrics } = require('node:internal/uv');

io_uring Path in libuv (v1.50+)

Since libuv v1.44, io_uring support is available but disabled by default. In v1.50+, the implementation is more mature, supporting read/write, open/close, stat, and sendmsg/recvmsg. To enable, set UV_USE_IO_URING=1. The io_uring path uses a single submission queue (SQ) and completion queue (CQ) shared with the kernel. libuv submits I/O operations as submission queue entries (SQEs) and reaps completions from CQ. This reduces the number of syscalls (no more epoll_wait + read/write). However, not all operations are supported; libuv falls back to epoll for unsupported ones. io_uring also supports IOSQE_IO_LINK for chaining operations and IORING_SETUP_SQPOLL for kernel-side polling. For Node.js, this means lower latency for file I/O and network operations. Benchmarking shows up to 30% improvement in I/O-heavy workloads. To use it, ensure your Linux kernel is 5.1+ and libuv is compiled with -DIO_URING_SUPPORT=1.

# Enable io_uring for Node.js
UV_USE_IO_URING=1 node app.js
# Verify in Node
node -e "console.log(process.report.getReport().libuv.usingIoUring)"