Cluster - Node documentation
interface Cluster
extends EventEmitter

Usage in Deno

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

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

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
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}`);
}
optional
readonly
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

  1. disconnect
  2. exit
  3. fork
  4. listening
  5. message
  6. online
  7. 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