Cluster - cluster - Node

interface Cluster

extends EventEmitter

Usage in Deno

import { type Cluster } from "node:cluster";

Deno compatibility

This symbol is a non-functional stub.

Properties

deprecated

readonly



isMaster: boolean

readonly



isPrimary: 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



isWorker: boolean

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



schedulingPolicy: number

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'.

readonly



settings: ClusterSettings

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



worker: 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



workers: 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



SCHED_NONE: number

readonly



SCHED_RR: number

Methods



disconnect(callback?: () => void): void



fork(env?: any): Worker

Spawn a new worker process.

This can only be called from the primary process.

deprecated



setupMaster(settings?: ClusterSettings): void



setupPrimary(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.



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

events.EventEmitter

disconnect
exit
fork
listening
message
online
setup



addListener(event: "disconnect",
listener: (worker: Worker) => void,
): this



addListener(event: "exit",
listener: (worker: Worker,
code: number,
signal: string,
) => void,
): this



addListener(event: "fork",
listener: (worker: Worker) => void,
): this



addListener(event: "listening",
listener: (worker: Worker,
address: Address,
) => void,
): this



addListener(event: "message",
listener: (worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this



addListener(event: "online",
listener: (worker: Worker) => void,
): this



addListener(event: "setup",
listener: (settings: ClusterSettings) => void,
): this



emit(event: string | symbol,
...args: any[],
): boolean



emit(event: "disconnect",
worker: Worker,
): boolean



emit(event: "exit",
worker: Worker,
code: number,
signal: string,
): boolean



emit(event: "fork",
worker: Worker,
): boolean



emit(event: "listening",
worker: Worker,
address: Address,
): boolean



emit(event: "message",
worker: Worker,
message: any,
handle: net.Socket | net.Server,
): boolean



emit(event: "online",
worker: Worker,
): boolean



emit(event: "setup",
settings: ClusterSettings,
): boolean



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



on(event: "disconnect",
listener: (worker: Worker) => void,
): this



on(event: "exit",
listener: (worker: Worker,
code: number,
signal: string,
) => void,
): this



on(event: "fork",
listener: (worker: Worker) => void,
): this



on(event: "listening",
listener: (worker: Worker,
address: Address,
) => void,
): this



on(event: "message",
listener: (worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this



on(event: "online",
listener: (worker: Worker) => void,
): this



on(event: "setup",
listener: (settings: ClusterSettings) => void,
): this



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



once(event: "disconnect",
listener: (worker: Worker) => void,
): this



once(event: "exit",
listener: (worker: Worker,
code: number,
signal: string,
) => void,
): this



once(event: "fork",
listener: (worker: Worker) => void,
): this



once(event: "listening",
listener: (worker: Worker,
address: Address,
) => void,
): this



once(event: "message",
listener: (worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this



once(event: "online",
listener: (worker: Worker) => void,
): this



once(event: "setup",
listener: (settings: ClusterSettings) => void,
): this



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



prependListener(event: "disconnect",
listener: (worker: Worker) => void,
): this



prependListener(event: "exit",
listener: (worker: Worker,
code: number,
signal: string,
) => void,
): this



prependListener(event: "fork",
listener: (worker: Worker) => void,
): this



prependListener(event: "listening",
listener: (worker: Worker,
address: Address,
) => void,
): this



prependListener(event: "message",
listener: (worker: Worker,
message: any,
handle?: net.Socket | net.Server,
) => void,
): this



prependListener(event: "online",
listener: (worker: Worker) => void,
): this



prependListener(event: "setup",
listener: (settings: ClusterSettings) => void,
): this



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



prependOnceListener(event: "disconnect",
listener: (worker: Worker) => void,
): this



prependOnceListener(event: "exit",
listener: (worker: Worker,
code: number,
signal: string,
) => void,
): this



prependOnceListener(event: "fork",
listener: (worker: Worker) => void,
): this



prependOnceListener(event: "listening",
listener: (worker: Worker,
address: Address,
) => void,
): this



prependOnceListener(event: "message",
listener: (worker: Worker,
message: any,
handle: net.Socket | net.Server,
) => void,
): this



prependOnceListener(event: "online",
listener: (worker: Worker) => void,
): this



prependOnceListener(event: "setup",
listener: (settings: ClusterSettings) => void,
): this