Node.js Cluster Module

Clusters of Node.js processes can be used to run multiple instances of Node.js that can distribute workloads among their application threads.

When process isolation is not needed, use the worker_threads module instead, which allows running multiple application threads within a single Node.js instance.

The worker processes are spawned using the child_process.fork() method, so that they can communicate with the parent via IPC and pass server handles back and forth.

The cluster module supports two methods of distributing incoming connections.

Extends: <EventEmitter>

A Worker object contains all public information and method about a worker. In the primary it can be obtained using cluster.workers. In a worker it can be obtained using cluster.worker.

Similar to the cluster.on('disconnect') event, but specific to this worker.

This event is the same as the one provided by child_process.fork().

Within a worker, process.on('error') may also be used.

code <number> The exit code, if it exited normally.

signal <string> The name of the signal (e.g., 'SIGHUP') that caused the process to be killed.

Similar to the cluster.on('exit') event, but specific to this worker.

address <Object>

Similar to the cluster.on('listening') event, but specific to this worker.

It is not emitted in the worker.

message <Object>

handle <undefined> | <Object>

Similar to the 'message' event of cluster, but specific to this worker.

Within a worker, process.on('message') may also be used.

Similar to the cluster.on('online') event, but specific to this worker.

Returns: <cluster.Worker> A reference to worker.

In a worker, this function will close all servers, wait for the 'close' event on those servers, and then disconnect the IPC channel.

In the primary, an internal message is sent to the worker causing it to call .disconnect() on itself.

<boolean>

This property is true if the worker exited due to .disconnect(). If the worker exited any other way, it is false. If the worker has not exited, it is undefined.

<integer>

Each new worker is given its own unique id, this id is stored in the id.

While a worker is alive, this is the key that indexes it in cluster.workers.

This function returns true if the worker is connected to its primary via its IPC channel, false otherwise. A worker is connected to its primary after it has been created. It is disconnected after the 'disconnect' event is emitted.

This function returns true if the worker's process has terminated (either because of exiting or being signaled). Otherwise, it returns false.

signal <string> Name of the kill signal to send to the worker process. Default: 'SIGTERM'

This function will kill the worker. In the primary worker, it does this by disconnecting the worker.process, and once disconnected, killing with signal. In the worker, it does it by killing the process with signal.

<ChildProcess>

All workers are created using child_process.fork(), the returned object from this function is stored as .process. In a worker, the global process is stored.

Send a message to a worker or primary, optionally with a handle.

worker <cluster.Worker>

Emitted after the worker IPC channel has disconnected. This can occur when a worker exits gracefully, is killed, or is disconnected manually (such as with worker.disconnect()).

When any of the workers die, the cluster module will emit the 'exit' event.

worker <cluster.Worker>

When a new worker is forked, the cluster module will emit a 'fork' event. This can be used to log worker activity and create a custom timeout.

worker <cluster.Worker>

address <Object>

After calling listen() from a worker, when the 'listening' event is emitted on the server, a 'listening' event will also be emitted on cluster in the primary.

worker <cluster.Worker>

message <Object>

handle <undefined> | <Object>

Emitted when the cluster primary receives a message from any worker.

worker <cluster.Worker>

After forking a new worker, the worker should respond with an online message. When the primary receives an online message, it will emit this event.

settings <Object>

Emitted every time .setupPrimary() is called.

The settings object is the cluster.settings object at the time .setupPrimary() was called and is advisory only, since multiple calls to .setupPrimary() can be made in a single tick.

callback <Function> Called when all workers are disconnected and handles are closed.

Calls .disconnect() on each worker in cluster.workers. When they are disconnected, all internal handles will be closed, allowing the primary process to die gracefully if no other event is waiting.

env <Object> Key/value pairs to add to the worker process environment.

Spawns a new worker process. This can only be called from the primary process.

<boolean> True if the process is a primary. This is determined by the process.env.NODE_UNIQUE_ID. If process.env.NODE_UNIQUE_ID is undefined, then isPrimary is true.

<boolean> True if the process is not a primary (it is the negation of cluster.isPrimary).

The scheduling policy, either cluster.SCHED_RR for round-robin or cluster.SCHED_NONE to leave it to the operating system.

This object is not intended to be changed or set manually.

setupPrimary is used to change the default 'fork' behavior. Once called, the settings will be present in cluster.settings.

A reference to the current worker object. Not available in the primary process.

A hash that stores the active worker objects, keyed by id field. This makes it easy to loop through all the workers.