Skip to main content

Cluster

interface Cluster
extends EventEmitter

Deno compatibility

This symbol is a non-functional stub.

Properties Jump to heading

deprecated
readonly
Jump to headingisMaster: boolean
readonly
Jump to headingisPrimary: 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.

readonly
Jump to headingisWorker: 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 is a global setting and effectively frozen once either the first worker is spawned, or .setupPrimary() is called, whichever comes first.

SCHED_RR is the default on all operating systems except Windows. Windows will change to SCHED_RR once libuv is able to effectively distribute IOCP handles without incurring a large performance hit.

cluster.schedulingPolicy can also be set through the NODE_CLUSTER_SCHED_POLICY environment variable. Valid values are 'rr' and 'none'.

After calling .setupPrimary() (or .fork()) this settings object will contain the settings, including the default values.

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

readonly
optional
Jump to headingworker: Worker | undefined

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

import cluster from 'node:cluster';

if (cluster.isPrimary) {
  console.log('I am primary');
  cluster.fork();
  cluster.fork();
} else if (cluster.isWorker) {
  console.log(`I am worker #${cluster.worker.id}`);
}
readonly
optional
Jump to headingworkers: Dict<Worker> | undefined

A hash that stores the active worker objects, keyed by id field. This makes it easy to loop through all the workers. It is only available in the primary process.

A worker is removed from cluster.workers after the worker has disconnected and exited. The order between these two events cannot be determined in advance. However, it is guaranteed that the removal from the cluster.workers list happens before the last 'disconnect' or 'exit' event is emitted.

import cluster from 'node:cluster';

for (const worker of Object.values(cluster.workers)) {
  worker.send('big announcement to all workers');
}
readonly
Jump to headingSCHED_RR: number
Jump to headingdisconnect(callback?: () => void): void

Spawn a new worker process.

This can only be called from the primary process.

deprecated
Jump to headingsetupMaster(settings?: ClusterSettings): void

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

Any settings changes only affect future calls to .fork() and have no effect on workers that are already running.

The only attribute of a worker that cannot be set via .setupPrimary() is the env passed to .fork().

The defaults above apply to the first call only; the defaults for later calls are the current values at the time of cluster.setupPrimary() is called.

import cluster from 'node:cluster';

cluster.setupPrimary({
  exec: 'worker.js',
  args: ['--use', 'https'],
  silent: true,
});
cluster.fork(); // https worker
cluster.setupPrimary({
  exec: 'worker.js',
  args: ['--use', 'http'],
});
cluster.fork(); // http worker

This can only be called from the primary process.

Jump to headingaddListener(
event: string,
listener: (...args: any[]) => void,
): this

events.EventEmitter

  1. disconnect
  2. exit
  3. fork
  4. listening
  5. message
  6. online
  7. setup
Jump to headingaddListener(
event: "disconnect",
listener: (worker: Worker) => void,
): this
Jump to headingaddListener(
event: "exit",
listener: (
worker: Worker,
code: number,
signal: string,
) => void,
): this
Jump to headingaddListener(
event: "fork",
listener: (worker: Worker) => void,
): this
Jump to headingaddListener(
event: "listening",
listener: (
worker: Worker,
address: Address,
) => void,
): this
Jump to headingaddListener(
event: "message",
listener: (
worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this
Jump to headingaddListener(
event: "online",
listener: (worker: Worker) => void,
): this
Jump to headingaddListener(
event: "setup",
listener: (settings: ClusterSettings) => void,
): this
Jump to headingemit(
event: string | symbol,
...args: any[],
): boolean
Jump to headingemit(
event: "disconnect",
worker: Worker,
): boolean
Jump to headingemit(
event: "exit",
worker: Worker,
code: number,
signal: string,
): boolean
Jump to headingemit(
event: "fork",
worker: Worker,
): boolean
Jump to headingemit(
event: "listening",
worker: Worker,
address: Address,
): boolean
Jump to headingemit(
event: "message",
worker: Worker,
message: any,
handle: net.Socket | net.Server,
): boolean
Jump to headingemit(
event: "online",
worker: Worker,
): boolean
Jump to headingemit(
event: "setup",
settings: ClusterSettings,
): boolean
Jump to headingon(
event: string,
listener: (...args: any[]) => void,
): this
Jump to headingon(
event: "disconnect",
listener: (worker: Worker) => void,
): this
Jump to headingon(
event: "exit",
listener: (
worker: Worker,
code: number,
signal: string,
) => void,
): this
Jump to headingon(
event: "fork",
listener: (worker: Worker) => void,
): this
Jump to headingon(
event: "listening",
listener: (
worker: Worker,
address: Address,
) => void,
): this
Jump to headingon(
event: "message",
listener: (
worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this
Jump to headingon(
event: "online",
listener: (worker: Worker) => void,
): this
Jump to headingon(
event: "setup",
listener: (settings: ClusterSettings) => void,
): this
Jump to headingonce(
event: string,
listener: (...args: any[]) => void,
): this
Jump to headingonce(
event: "disconnect",
listener: (worker: Worker) => void,
): this
Jump to headingonce(
event: "exit",
listener: (
worker: Worker,
code: number,
signal: string,
) => void,
): this
Jump to headingonce(
event: "fork",
listener: (worker: Worker) => void,
): this
Jump to headingonce(
event: "listening",
listener: (
worker: Worker,
address: Address,
) => void,
): this
Jump to headingonce(
event: "message",
listener: (
worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this
Jump to headingonce(
event: "online",
listener: (worker: Worker) => void,
): this
Jump to headingonce(
event: "setup",
listener: (settings: ClusterSettings) => void,
): this
Jump to headingprependListener(
event: string,
listener: (...args: any[]) => void,
): this
Jump to headingprependListener(
event: "disconnect",
listener: (worker: Worker) => void,
): this
Jump to headingprependListener(
event: "exit",
listener: (
worker: Worker,
code: number,
signal: string,
) => void,
): this
Jump to headingprependListener(
event: "fork",
listener: (worker: Worker) => void,
): this
Jump to headingprependListener(
event: "listening",
listener: (
worker: Worker,
address: Address,
) => void,
): this
Jump to headingprependListener(
event: "message",
listener: (
worker: Worker,
message: any,
handle?: net.Socket | net.Server,
) => void,
): this
Jump to headingprependListener(
event: "online",
listener: (worker: Worker) => void,
): this
Jump to headingprependListener(
event: "setup",
listener: (settings: ClusterSettings) => void,
): this
Jump to headingprependOnceListener(
event: string,
listener: (...args: any[]) => void,
): this
Jump to headingprependOnceListener(
event: "disconnect",
listener: (worker: Worker) => void,
): this
Jump to headingprependOnceListener(
event: "exit",
listener: (
worker: Worker,
code: number,
signal: string,
) => void,
): this
Jump to headingprependOnceListener(
event: "fork",
listener: (worker: Worker) => void,
): this
Jump to headingprependOnceListener(
event: "listening",
listener: (
worker: Worker,
address: Address,
) => void,
): this
Jump to headingprependOnceListener(
event: "message",
listener: (
worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this
Jump to headingprependOnceListener(
event: "online",
listener: (worker: Worker) => void,
): this
Jump to headingprependOnceListener(
event: "setup",
listener: (settings: ClusterSettings) => void,
): this
Back to top