Node.js is called single-threaded, yet a slow file read does not stall other requests; which threads does a Node process actually use?
answer
- one thread runs your JavaScript
- libuv underneath the runtime
- sockets versus files
- a small fixed pool of helpers
basics
~20 sAll JavaScript runs on one main thread that drives the event loop. Socket I/O is watched by the kernel from that thread, while async fs calls, dns.lookup(), zlib and some crypto run on libuv's threadpool, four threads by default.
solid answer
~40 sNode runs every JavaScript callback on one main thread that drives libuv's event loop, so two of your callbacks never run at the same instant on it. That thread does not do the waiting itself. Network I/O uses non-blocking sockets that the loop registers with the kernel's notifier (epoll, kqueue, event ports or IOCP), so one thread can watch thousands of connections. Work with no non-blocking operating-system interface, such as the callback and promise `fs` APIs, `dns.lookup()`, async `zlib` calls and crypto like `crypto.pbkdf2()`, goes to libuv's threadpool, which has 4 threads unless `UV_THREADPOOL_SIZE` says otherwise. When a pool task finishes, its callback is run back on the main thread. Your own CPU-heavy JavaScript gets none of this help: it stays on the main thread unless you move it to `worker_threads`.
go deeper
Recall the split: one main thread runs all JavaScript, the kernel watches sockets, and a four-thread libuv pool handles files, dns.lookup(), zlib and some crypto.
Explain why sockets need no pool thread (non-blocking descriptors and readiness notification) while file reads do, and that a finished pool task's callback still runs on the main thread.
Show that the pool is small and shared by every loop in the process, worker threads included, so one slow task type can delay unrelated file or DNS work.
Treat the model as a capacity map: decide which work a service puts on the main thread, the pool and separate workers, and which of the three saturates first.
## The short answer "Single-threaded" is true of **your JavaScript**, not of the Node process. A Node process has one **main thread** that runs every JavaScript callback and drives the **event loop**, plus a small pool of helper threads that libuv, the C library under Node, uses for operations the operating system cannot perform asynchronously. A slow file read does not stall other requests because the read itself happens on one of those helper threads; only the short callback that receives the result runs on the main thread. ## The main thread: one loop for all JavaScript The main thread does three jobs in turn: - runs your module's top-level code once at startup; - runs each callback when its event arrives: a request on a socket, a finished file read, a due timer, a `setImmediate()` callback; - asks the operating system which watched handles are ready, and waits when there is nothing to do. Because there is only one such thread, two callbacks never run at the same instant on it. That is what makes Node simple to reason about, and it is also its main constraint: a callback that computes for 300 ms can hold up every other client for up to 300 ms. (How to detect and fix that is the subject of the lesson on blocking the loop.) ## Network I/O: the kernel does the waiting Sockets need no extra threads. libuv puts every socket in **non-blocking** mode and registers it with the platform's readiness notifier: **epoll** on Linux, **kqueue** on macOS and the BSDs, **event ports** on SunOS and **IOCP** on Windows. One call asks the kernel "which of these thousands of sockets can be read or written now?", and the loop runs the callbacks for the ones that can. libuv's own design notes put it plainly: network I/O is always performed on the loop's thread. ## The threadpool: blocking calls made asynchronous Some operations have no portable non-blocking interface. Reading a regular file, or calling the system resolver `getaddrinfo`, blocks the calling thread until it finishes. libuv runs these on its **threadpool** and reports completion back to the loop, so they look asynchronous to JavaScript. | Runs on the main thread | Runs on libuv's threadpool | |---|---| | Your JavaScript, every callback and promise reaction | Callback and promise `fs` APIs (not the file watchers) | | Socket reads and writes for `net`, `http`, `tls` | `dns.lookup()` and `dns.lookupService()` | | `dns.resolve*()` network queries | Async `zlib` calls such as `zlib.gzip()` | | `*Sync` APIs such as `fs.readFileSync()` | Async crypto: `crypto.pbkdf2()`, `crypto.scrypt()`, `crypto.randomBytes()`, `crypto.randomFill()`, `crypto.generateKeyPair()` | Key facts about the pool: 1. Its default size is **4**, set with the `UV_THREADPOOL_SIZE` environment variable (the libuv maximum is 1024). 2. It is **global to the process**: every event loop, including the one inside each `worker_threads.Worker`, shares it. 3. When a task finishes, its result is handed back and your callback runs on the **main thread**, not on the pool thread. Each pool task therefore has two halves: the blocking work, done on a pool thread, and a completion callback that libuv calls on the loop thread, where Node runs your JavaScript callback. That is why the result of an `fs.readFile()` never races with your other code: it arrives as an ordinary event in the loop's poll phase, between other callbacks. ## What "single-threaded" gets right and wrong - Right: you never need locks around ordinary JavaScript state, because only one callback runs at a time on the main thread. - Right: CPU-heavy JavaScript on the main thread blocks everyone; the threadpool does not run your functions. - Wrong: Node does not do all I/O on one thread. File, `dns.lookup()`, compression and async crypto work run in parallel on pool threads. - Wrong: an `async` function or a promise does not move work to another thread. It only changes when the callback runs, still on the main thread. - Wrong: each connection does not get a thread. Ten thousand idle sockets cost no threads at all. Parallelism for your own JavaScript needs an explicit choice: `worker_threads`, child processes, or several processes behind a load balancer, each covered in the lessons on multi-core execution.
- If the threadpool exists, why does a long synchronous loop in a request handler still freeze the whole Node.js server?The threadpool runs only the native operations Node submits to it, such as `fs` calls or `crypto.pbkdf2()`. Your JavaScript, including a `for` loop or a large `JSON.parse()`, always runs on the main thread. While it runs, the loop cannot pick up socket events or completed pool results, so every other request waits until it returns.
- Does every `worker_threads.Worker` get its own libuv threadpool?No. Each worker thread runs its own event loop, but libuv's threadpool is global and shared by all loops in the process. File system work, `dns.lookup()` and async crypto from the main thread and from every worker compete for the same `UV_THREADPOOL_SIZE` threads.
- Node.js is single-threaded, so the process uses exactly one operating-system thread.
- Every asynchronous call, socket reads included, runs on a threadpool thread.
- The threadpool runs my async functions and promise callbacks in parallel.
- Each incoming connection is handed its own thread from the pool.
- Marking a function async moves its work off the main thread.