5 A single instance of Node.js runs in a single thread. To take advantage of
6 multi-core systems the user will sometimes want to launch a cluster of Node.js
7 processes to handle the load.
9 The cluster module allows you to easily create child processes that
10 all share server ports.
12 var cluster = require('cluster');
13 var http = require('http');
14 var numCPUs = require('os').cpus().length;
16 if (cluster.isMaster) {
18 for (var i = 0; i < numCPUs; i++) {
22 cluster.on('exit', function(worker, code, signal) {
23 console.log('worker ' + worker.process.pid + ' died');
26 // Workers can share any TCP connection
27 // In this case it is an HTTP server
28 http.createServer(function(req, res) {
30 res.end("hello world\n");
34 Running Node.js will now share port 8000 between the workers:
36 % NODE_DEBUG=cluster node server.js
37 23521,Master Worker 23524 online
38 23521,Master Worker 23526 online
39 23521,Master Worker 23523 online
40 23521,Master Worker 23528 online
42 Please note that, on Windows, it is not yet possible to set up a named pipe
49 The worker processes are spawned using the `child_process.fork` method,
50 so that they can communicate with the parent via IPC and pass server
51 handles back and forth.
53 The cluster module supports two methods of distributing incoming
56 The first one (and the default one on all platforms except Windows),
57 is the round-robin approach, where the master process listens on a
58 port, accepts new connections and distributes them across the workers
59 in a round-robin fashion, with some built-in smarts to avoid
60 overloading a worker process.
62 The second approach is where the master process creates the listen
63 socket and sends it to interested workers. The workers then accept
64 incoming connections directly.
66 The second approach should, in theory, give the best performance.
67 In practice however, distribution tends to be very unbalanced due
68 to operating system scheduler vagaries. Loads have been observed
69 where over 70% of all connections ended up in just two processes,
70 out of a total of eight.
72 Because `server.listen()` hands off most of the work to the master
73 process, there are three cases where the behavior between a normal
74 Node.js process and a cluster worker differs:
76 1. `server.listen({fd: 7})` Because the message is passed to the master,
77 file descriptor 7 **in the parent** will be listened on, and the
78 handle passed to the worker, rather than listening to the worker's
79 idea of what the number 7 file descriptor references.
80 2. `server.listen(handle)` Listening on handles explicitly will cause
81 the worker to use the supplied handle, rather than talk to the master
82 process. If the worker already has the handle, then it's presumed
83 that you know what you are doing.
84 3. `server.listen(0)` Normally, this will cause servers to listen on a
85 random port. However, in a cluster, each worker will receive the
86 same "random" port each time they do `listen(0)`. In essence, the
87 port is random the first time, but predictable thereafter. If you
88 want to listen on a unique port, generate a port number based on the
91 There is no routing logic in Node.js, or in your program, and no shared
92 state between the workers. Therefore, it is important to design your
93 program such that it does not rely too heavily on in-memory data objects
94 for things like sessions and login.
96 Because workers are all separate processes, they can be killed or
97 re-spawned depending on your program's needs, without affecting other
98 workers. As long as there are some workers still alive, the server will
99 continue to accept connections. If no workers are alive, existing connections
100 will be dropped and new connections will be refused. Node.js does not
101 automatically manage the number of workers for you, however. It is your
102 responsibility to manage the worker pool for your application's needs.
108 A Worker object contains all public information and method about a worker.
109 In the master it can be obtained using `cluster.workers`. In a worker
110 it can be obtained using `cluster.worker`.
112 ### Event: 'disconnect'
114 Similar to the `cluster.on('disconnect')` event, but specific to this worker.
116 cluster.fork().on('disconnect', function() {
117 // Worker has disconnected
122 This event is the same as the one provided by `child_process.fork()`.
124 In a worker you can also use `process.on('error')`.
126 [ChildProcess.send()]: child_process.html#child_process_child_send_message_sendhandle_callback
130 * `code` {Number} the exit code, if it exited normally.
131 * `signal` {String} the name of the signal (eg. `'SIGHUP'`) that caused
132 the process to be killed.
134 Similar to the `cluster.on('exit')` event, but specific to this worker.
136 var worker = cluster.fork();
137 worker.on('exit', function(code, signal) {
139 console.log("worker was killed by signal: "+signal);
140 } else if( code !== 0 ) {
141 console.log("worker exited with error code: "+code);
143 console.log("worker success!");
147 ### Event: 'listening'
151 Similar to the `cluster.on('listening')` event, but specific to this worker.
153 cluster.fork().on('listening', function(address) {
154 // Worker is listening
157 It is not emitted in the worker.
163 Similar to the `cluster.on('message')` event, but specific to this worker.
165 This event is the same as the one provided by `child_process.fork()`.
167 In a worker you can also use `process.on('message')`.
169 As an example, here is a cluster that keeps count of the number of requests
170 in the master process using the message system:
172 var cluster = require('cluster');
173 var http = require('http');
175 if (cluster.isMaster) {
177 // Keep track of http requests
179 setInterval(function() {
180 console.log("numReqs =", numReqs);
184 function messageHandler(msg) {
185 if (msg.cmd && msg.cmd == 'notifyRequest') {
190 // Start workers and listen for messages containing notifyRequest
191 var numCPUs = require('os').cpus().length;
192 for (var i = 0; i < numCPUs; i++) {
196 Object.keys(cluster.workers).forEach(function(id) {
197 cluster.workers[id].on('message', messageHandler);
202 // Worker processes have a http server.
203 http.Server(function(req, res) {
205 res.end("hello world\n");
207 // notify master about the request
208 process.send({ cmd: 'notifyRequest' });
214 Similar to the `cluster.on('online')` event, but specific to this worker.
216 cluster.fork().on('online', function() {
220 It is not emitted in the worker.
222 ### worker.disconnect()
224 In a worker, this function will close all servers, wait for the 'close' event on
225 those servers, and then disconnect the IPC channel.
227 In the master, an internal message is sent to the worker causing it to call
228 `.disconnect()` on itself.
230 Causes `.suicide` to be set.
232 Note that after a server is closed, it will no longer accept new connections,
233 but connections may be accepted by any other listening worker. Existing
234 connections will be allowed to close as usual. When no more connections exist,
235 see [server.close()](net.html#net_event_close), the IPC channel to the worker
236 will close allowing it to die gracefully.
238 The above applies *only* to server connections, client connections are not
239 automatically closed by workers, and disconnect does not wait for them to close
242 Note that in a worker, `process.disconnect` exists, but it is not this function,
243 it is [disconnect](child_process.html#child_process_child_disconnect).
245 Because long living server connections may block workers from disconnecting, it
246 may be useful to send a message, so application specific actions may be taken to
247 close them. It also may be useful to implement a timeout, killing a worker if
248 the `disconnect` event has not been emitted after some time.
250 if (cluster.isMaster) {
251 var worker = cluster.fork();
254 worker.on('listening', function(address) {
255 worker.send('shutdown');
257 timeout = setTimeout(function() {
262 worker.on('disconnect', function() {
263 clearTimeout(timeout);
266 } else if (cluster.isWorker) {
267 var net = require('net');
268 var server = net.createServer(function(socket) {
269 // connections never end
274 process.on('message', function(msg) {
275 if(msg === 'shutdown') {
276 // initiate graceful close of any connections to server
285 Each new worker is given its own unique id, this id is stored in the
288 While a worker is alive, this is the key that indexes it in
291 ### worker.isConnected()
293 This function returns `true` if the worker is connected to its master via its IPC
294 channel, `false` otherwise. A worker is connected to its master after it's been
295 created. It is disconnected after the `disconnect` event is emitted.
299 This function returns `true` if the worker's process has terminated (either
300 because of exiting or being signaled). Otherwise, it returns `false`.
302 ### worker.kill([signal='SIGTERM'])
304 * `signal` {String} Name of the kill signal to send to the worker
307 This function will kill the worker. In the master, it does this by disconnecting
308 the `worker.process`, and once disconnected, killing with `signal`. In the
309 worker, it does it by disconnecting the channel, and then exiting with code `0`.
311 Causes `.suicide` to be set.
313 This method is aliased as `worker.destroy()` for backwards compatibility.
315 Note that in a worker, `process.kill()` exists, but it is not this function,
316 it is [kill](process.html#process_process_kill_pid_signal).
320 * {ChildProcess object}
322 All workers are created using `child_process.fork()`, the returned object
323 from this function is stored as `.process`. In a worker, the global `process`
326 See: [Child Process module](
327 child_process.html#child_process_child_process_fork_modulepath_args_options)
329 Note that workers will call `process.exit(0)` if the `'disconnect'` event occurs
330 on `process` and `.suicide` is not `true`. This protects against accidental
333 ### worker.send(message[, sendHandle][, callback])
336 * `sendHandle` {Handle object}
337 * `callback` {Function}
340 Send a message to a worker or master, optionally with a handle.
342 In the master this sends a message to a specific worker. It is identical to
343 [ChildProcess.send()][].
345 In a worker this sends a message to the master. It is identical to
348 This example will echo back all messages from the master:
350 if (cluster.isMaster) {
351 var worker = cluster.fork();
352 worker.send('hi there');
354 } else if (cluster.isWorker) {
355 process.on('message', function(msg) {
364 Set by calling `.kill()` or `.disconnect()`, until then it is `undefined`.
366 The boolean `worker.suicide` lets you distinguish between voluntary and accidental
367 exit, the master may choose not to respawn a worker based on this value.
369 cluster.on('exit', function(worker, code, signal) {
370 if (worker.suicide === true) {
371 console.log('Oh, it was just suicide\' – no need to worry').
378 ## Event: 'disconnect'
380 * `worker` {Worker object}
382 Emitted after the worker IPC channel has disconnected. This can occur when a
383 worker exits gracefully, is killed, or is disconnected manually (such as with
384 worker.disconnect()).
386 There may be a delay between the `disconnect` and `exit` events. These events
387 can be used to detect if the process is stuck in a cleanup or if there are
388 long-living connections.
390 cluster.on('disconnect', function(worker) {
391 console.log('The worker #' + worker.id + ' has disconnected');
396 * `worker` {Worker object}
397 * `code` {Number} the exit code, if it exited normally.
398 * `signal` {String} the name of the signal (eg. `'SIGHUP'`) that caused
399 the process to be killed.
401 When any of the workers die the cluster module will emit the 'exit' event.
403 This can be used to restart the worker by calling `.fork()` again.
405 cluster.on('exit', function(worker, code, signal) {
406 console.log('worker %d died (%s). restarting...',
407 worker.process.pid, signal || code);
411 See [child_process event: 'exit'](child_process.html#child_process_event_exit).
415 * `worker` {Worker object}
417 When a new worker is forked the cluster module will emit a 'fork' event.
418 This can be used to log worker activity, and create your own timeout.
421 function errorMsg() {
422 console.error("Something must be wrong with the connection ...");
425 cluster.on('fork', function(worker) {
426 timeouts[worker.id] = setTimeout(errorMsg, 2000);
428 cluster.on('listening', function(worker, address) {
429 clearTimeout(timeouts[worker.id]);
431 cluster.on('exit', function(worker, code, signal) {
432 clearTimeout(timeouts[worker.id]);
436 ## Event: 'listening'
438 * `worker` {Worker object}
441 After calling `listen()` from a worker, when the 'listening' event is emitted on
442 the server, a listening event will also be emitted on `cluster` in the master.
444 The event handler is executed with two arguments, the `worker` contains the worker
445 object and the `address` object contains the following connection properties:
446 `address`, `port` and `addressType`. This is very useful if the worker is listening
447 on more than one address.
449 cluster.on('listening', function(worker, address) {
450 console.log("A worker is now connected to " + address.address + ":" + address.port);
453 The `addressType` is one of:
457 * `-1` (unix domain socket)
458 * `"udp4"` or `"udp6"` (UDP v4 or v6)
462 * `worker` {Worker object}
465 Emitted when any worker receives a message.
468 [child_process event: 'message'](child_process.html#child_process_event_message).
472 * `worker` {Worker object}
474 After forking a new worker, the worker should respond with an online message.
475 When the master receives an online message it will emit this event.
476 The difference between 'fork' and 'online' is that fork is emitted when the
477 master forks a worker, and 'online' is emitted when the worker is running.
479 cluster.on('online', function(worker) {
480 console.log("Yay, the worker responded after it was forked");
485 * `settings` {Object}
487 Emitted every time `.setupMaster()` is called.
489 The `settings` object is the `cluster.settings` object at the time
490 `.setupMaster()` was called and is advisory only, since multiple calls to
491 `.setupMaster()` can be made in a single tick.
493 If accuracy is important, use `cluster.settings`.
495 ## cluster.disconnect([callback])
497 * `callback` {Function} called when all workers are disconnected and handles are
500 Calls `.disconnect()` on each worker in `cluster.workers`.
502 When they are disconnected all internal handles will be closed, allowing the
503 master process to die gracefully if no other event is waiting.
505 The method takes an optional callback argument which will be called when finished.
507 This can only be called from the master process.
509 ## cluster.fork([env])
511 * `env` {Object} Key/value pairs to add to worker process environment.
512 * return {Worker object}
514 Spawn a new worker process.
516 This can only be called from the master process.
522 True if the process is a master. This is determined
523 by the `process.env.NODE_UNIQUE_ID`. If `process.env.NODE_UNIQUE_ID` is
524 undefined, then `isMaster` is `true`.
530 True if the process is not a master (it is the negation of `cluster.isMaster`).
532 ## cluster.schedulingPolicy
534 The scheduling policy, either `cluster.SCHED_RR` for round-robin or
535 `cluster.SCHED_NONE` to leave it to the operating system. This is a
536 global setting and effectively frozen once you spawn the first worker
537 or call `cluster.setupMaster()`, whatever comes first.
539 `SCHED_RR` is the default on all operating systems except Windows.
540 Windows will change to `SCHED_RR` once libuv is able to effectively
541 distribute IOCP handles without incurring a large performance hit.
543 `cluster.schedulingPolicy` can also be set through the
544 `NODE_CLUSTER_SCHED_POLICY` environment variable. Valid
545 values are `"rr"` and `"none"`.
550 * `execArgv` {Array} list of string arguments passed to the Node.js
551 executable. (Default=`process.execArgv`)
552 * `exec` {String} file path to worker file. (Default=`process.argv[1]`)
553 * `args` {Array} string arguments passed to worker.
554 (Default=`process.argv.slice(2)`)
555 * `silent` {Boolean} whether or not to send output to parent's stdio.
557 * `uid` {Number} Sets the user identity of the process. (See setuid(2).)
558 * `gid` {Number} Sets the group identity of the process. (See setgid(2).)
560 After calling `.setupMaster()` (or `.fork()`) this settings object will contain
561 the settings, including the default values.
563 It is effectively frozen after being set, because `.setupMaster()` can
566 This object is not supposed to be changed or set manually, by you.
568 ## cluster.setupMaster([settings])
570 * `settings` {Object}
571 * `exec` {String} file path to worker file. (Default=`process.argv[1]`)
572 * `args` {Array} string arguments passed to worker.
573 (Default=`process.argv.slice(2)`)
574 * `silent` {Boolean} whether or not to send output to parent's stdio.
577 `setupMaster` is used to change the default 'fork' behavior. Once called,
578 the settings will be present in `cluster.settings`.
582 * any settings changes only affect future calls to `.fork()` and have no
583 effect on workers that are already running
584 * The *only* attribute of a worker that cannot be set via `.setupMaster()` is
585 the `env` passed to `.fork()`
586 * the defaults above apply to the first call only, the defaults for later
587 calls is the current value at the time of `cluster.setupMaster()` is called
591 var cluster = require('cluster');
592 cluster.setupMaster({
594 args: ['--use', 'https'],
597 cluster.fork(); // https worker
598 cluster.setupMaster({
599 args: ['--use', 'http']
601 cluster.fork(); // http worker
603 This can only be called from the master process.
609 A reference to the current worker object. Not available in the master process.
611 var cluster = require('cluster');
613 if (cluster.isMaster) {
614 console.log('I am master');
617 } else if (cluster.isWorker) {
618 console.log('I am worker #' + cluster.worker.id);
625 A hash that stores the active worker objects, keyed by `id` field. Makes it
626 easy to loop through all the workers. It is only available in the master
629 A worker is removed from cluster.workers after the worker has disconnected _and_
630 exited. The order between these two events cannot be determined in advance.
631 However, it is guaranteed that the removal from the cluster.workers list happens
632 before last `'disconnect'` or `'exit'` event is emitted.
634 // Go through all workers
635 function eachWorker(callback) {
636 for (var id in cluster.workers) {
637 callback(cluster.workers[id]);
640 eachWorker(function(worker) {
641 worker.send('big announcement to all workers');
644 Should you wish to reference a worker over a communication channel, using
645 the worker's unique id is the easiest way to find the worker.
647 socket.on('data', function(id) {
648 var worker = cluster.workers[id];