Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท child_process, worker_threads and cluster

Cluster scheduling in Node.js

How the Node.js cluster module distributes connections: round-robin in the primary, shared handles handled by the OS, schedulingPolicy and NODE_CLUSTER_SCHED_POLICY.

When several cluster workers call listen() on the same port, something has to decide which worker gets each new connection. That decision is the cluster's scheduling policy. Node.js has two:

  • Round-robin (cluster.SCHED_RR): the primary process owns the listening socket, accepts every connection itself, and hands each one to the next worker in turn.
  • Shared handle (cluster.SCHED_NONE): the primary creates the listening socket and passes it to the workers, which all accept from it; the operating system decides who wins each connection.

Round-robin is the default on every platform except Windows, where the default is the shared-handle policy because passing handles around is costly there.

NODE
import cluster from "node:cluster";

cluster.schedulingPolicy = cluster.SCHED_RR;     // before the first fork()

Try it

Node.js The policy constants

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Round-robin spreads connections evenly

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

How each policy works

Round-robin. The primary listens, accepts each socket and sends it over the IPC channel to a worker chosen in rotation, skipping workers that are not ready. Distribution is even by connection count. The cost is that every new connection passes through the primary, which becomes a single point of work (it is usually fast enough, because it only accepts and forwards).

Shared handle. The primary creates the listening socket and shares the handle with each worker. The workers register it with the operating system and race to accept. On Linux this often gives very uneven results: a few workers can take most of the connections, because the kernel wakes whichever process is most recently or most eagerly waiting. Other systems behave differently.

What is balanced. Both policies balance connections, not requests or CPU time. A client that keeps one connection open (HTTP keep-alive, WebSocket) stays with one worker, so a few busy long-lived connections can load one worker heavily while others idle.

Usage notes

  • Choose the policy before the first cluster.fork(). Set cluster.schedulingPolicy right after importing the module, or use the environment variable NODE_CLUSTER_SCHED_POLICY with the value rr or none. Changing it later has no effect on workers that already exist.
  • Default: SCHED_RR on Linux and macOS, SCHED_NONE on Windows.
  • Different port, different server. Workers listening on port 0 or on the same address and port share one handle; workers listening on different ports each get their own.
  • Workers with their own socket. A worker can open a listener with exclusive: true in server.listen() options; it then does not share the handle with others and is bound separately.
  • Keep-alive affects fairness. If load is uneven, shorten keep-alive times, spread clients through a load balancer in front, or limit concurrent connections per worker.
  • Cluster balances only on one machine. To spread load across machines you still need a load balancer (nginx, a cloud load balancer, or Kubernetes services).
  • Sticky sessions are not automatic. Round-robin may send the same client to different workers on different connections; use shared storage for sessions or a sticky layer in front.