Working with Cluster Module
1. Creating Master Process
Example
import cluster from "node:cluster";
import os from "node:os";
if (cluster.isPrimary) {
for (let i = 0; i < os.availableParallelism(); i++) cluster.fork();
} else {
startServer();
}| Property | Meaning |
|---|---|
cluster.isPrimary | True in primary |
cluster.isWorker | True in worker |
cluster.worker | Current worker (in worker) |
2. Forking Worker Processes (cluster.fork)
| API | Use |
|---|---|
cluster.fork(env?) | Spawn new worker |
cluster.workers | Object of active workers by id |
3. Handling Worker Events
| Event | Fires |
|---|---|
fork | Worker spawned |
online | Worker running |
listening | Worker listening |
disconnect | IPC closed |
exit | Worker died |
4. Load Balancing Requests
| Policy | Behavior |
|---|---|
SCHED_RR | Round-robin (default on most OSes) |
SCHED_NONE | OS decides (Windows default) |
5. Communicating Between Master and Workers
Example
// primary
worker.send({ action: "shutdown" });
// worker
process.on("message", (m) => { if (m.action === "shutdown") gracefulExit(); });6. Getting Worker Count (Object.keys(cluster.workers))
| Snippet | Returns |
|---|---|
Object.keys(cluster.workers).length | Active count |
worker.id / worker.process.pid | Identity |
7. Setting Scheduling Policy (cluster.schedulingPolicy)
8. Graceful Shutdown
Shutdown Flow
- Primary receives
SIGTERM - Send
shutdownmessage to each worker - Workers stop accepting new connections (
server.close()) - Wait for in-flight requests to finish
- Worker exits cleanly
9. Respawning Dead Workers
Example
cluster.on("exit", (worker, code, signal) => {
if (!worker.exitedAfterDisconnect) cluster.fork();
});10. Using PM2 for Process Management
| Command | Use |
|---|---|
pm2 start app.js -i max | Cluster mode, all CPUs |
pm2 reload app | Zero-downtime reload |
pm2 logs | Tail logs |
pm2 monit | Live monitor |
pm2 startup + pm2 save | Boot persistence |