Node.js v25.0.0 ドキュメンテーション

イベント: 'disconnect'#

cluster.on('disconnect')イベントに似ていますが、このワーカーに固有のものです。

cluster.fork().on('disconnect', () => {
  // Worker has disconnected
}); copy

イベント: 'error'#

このイベントはchild_process.fork()によって提供されるものと同じです。

ワーカー内では、process.on('error')も使用できます。

イベント: 'exit'#

• code <number> 正常に終了した場合の終了コード。
• signal <string> プロセスを強制終了させたシグナルの名前（例：'SIGHUP'）。

cluster.on('exit')イベントに似ていますが、このワーカーに固有のものです。

import cluster from 'node:cluster';

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('exit', (code, signal) => {
    if (signal) {
      console.log(`worker was killed by signal: ${signal}`);
    } else if (code !== 0) {
      console.log(`worker exited with error code: ${code}`);
    } else {
      console.log('worker success!');
    }
  });
}const cluster = require('node:cluster');

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.on('exit', (code, signal) => {
    if (signal) {
      console.log(`worker was killed by signal: ${signal}`);
    } else if (code !== 0) {
      console.log(`worker exited with error code: ${code}`);
    } else {
      console.log('worker success!');
    }
  });
}copy

イベント: 'listening'#

• address <Object>

cluster.on('listening')イベントに似ていますが、このワーカーに固有のものです。

cluster.fork().on('listening', (address) => {
  // Worker is listening
});cluster.fork().on('listening', (address) => {
  // Worker is listening
});copy

ワーカーでは発行されません。

イベント: 'message'#

• message <Object>
• handle <undefined> | <Object>

clusterの'message'イベントに似ていますが、このワーカーに固有のものです。

ワーカー内では、process.on('message')も使用できます。

process イベント: 'message'を参照してください。

以下はメッセージシステムを使用した例です。ワーカーが受信したHTTPリクエストの数をプライマリープロセスでカウントし続けます。

import cluster from 'node:cluster';
import http from 'node:http';
import { availableParallelism } from 'node:os';
import process from 'node:process';

if (cluster.isPrimary) {

  // Keep track of http requests
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // Count requests
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // Start workers and listen for messages containing notifyRequest
  const numCPUs = availableParallelism();
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  for (const id in cluster.workers) {
    cluster.workers[id].on('message', messageHandler);
  }

} else {

  // Worker processes have a http server.
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // Notify primary about the request
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();
const process = require('node:process');

if (cluster.isPrimary) {

  // Keep track of http requests
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // Count requests
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // Start workers and listen for messages containing notifyRequest
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  for (const id in cluster.workers) {
    cluster.workers[id].on('message', messageHandler);
  }

} else {

  // Worker processes have a http server.
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // Notify primary about the request
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}copy

イベント: 'online'#

cluster.on('online')イベントに似ていますが、このワーカーに固有のものです。

cluster.fork().on('online', () => {
  // Worker is online
}); copy

ワーカーでは発行されません。

worker.disconnect()#

• 戻り値: <cluster.Worker> workerへの参照。

ワーカーでは、この関数はすべてのサーバーを閉じ、それらのサーバーで'close'イベントを待ち、その後IPCチャネルを切断します。

プライマリーでは、内部メッセージがワーカーに送信され、ワーカー自身で.disconnect()を呼び出すようになります。

.exitedAfterDisconnectが設定される原因となります。

サーバーが閉じられた後、新しい接続は受け付けられなくなりますが、他のリッスンしているワーカーによって接続が受け付けられる場合があります。既存の接続は通常通り閉じることが許可されます。接続がなくなると、server.close()を参照してください、ワーカーへのIPCチャネルが閉じ、正常に終了できるようになります。

上記はサーバー接続にのみ適用され、クライアント接続はワーカーによって自動的に閉じられることはなく、disconnectは終了する前にそれらが閉じるのを待ちません。

ワーカーにはprocess.disconnectが存在しますが、それはこの関数ではなく、disconnect()です。

長寿命のサーバー接続がワーカーの切断を妨げる可能性があるため、メッセージを送信して、アプリケーション固有のアクションで接続を閉じさせると便利です。また、タイムアウトを実装し、一定時間後に'disconnect'イベントが発行されない場合にワーカーを強制終了させることも有用かもしれません。

if (cluster.isPrimary) {
  const worker = cluster.fork();
  let timeout;

  worker.on('listening', (address) => {
    worker.send('shutdown');
    worker.disconnect();
    timeout = setTimeout(() => {
      worker.kill();
    }, 2000);
  });

  worker.on('disconnect', () => {
    clearTimeout(timeout);
  });

} else if (cluster.isWorker) {
  const net = require('node:net');
  const server = net.createServer((socket) => {
    // Connections never end
  });

  server.listen(8000);

  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      // Initiate graceful close of any connections to server
    }
  });
} copy

worker.exitedAfterDisconnect#

• 型: <boolean>

このプロパティは、ワーカーが.disconnect()によって終了した場合はtrueです。ワーカーが他の方法で終了した場合はfalseです。ワーカーが終了していない場合はundefinedです。

ブール値のworker.exitedAfterDisconnectは、自発的な終了と偶発的な終了を区別することを可能にし、プライマリーはこの値に基づいてワーカーを再生成しないことを選択できます。

cluster.on('exit', (worker, code, signal) => {
  if (worker.exitedAfterDisconnect === true) {
    console.log('Oh, it was just voluntary – no need to worry');
  }
});

// kill worker
worker.kill(); copy

worker.id#

• 型: <integer>

新しいワーカーにはそれぞれ一意のIDが与えられ、このIDはidに保存されます。

ワーカーが生きている間、これはcluster.workers内でワーカーをインデックスするためのキーです。

worker.isConnected()#

この関数は、ワーカーがIPCチャネルを介してプライマリーに接続されている場合はtrueを、そうでない場合はfalseを返します。ワーカーは作成された後にプライマリーに接続されます。'disconnect'イベントが発行された後に切断されます。

worker.isDead()#

この関数は、ワーカーのプロセスが終了した場合（終了またはシグナルによる強制終了）はtrueを返します。それ以外の場合はfalseを返します。

import cluster from 'node:cluster';
import http from 'node:http';
import { availableParallelism } from 'node:os';
import process from 'node:process';

const numCPUs = availableParallelism();

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('fork', (worker) => {
    console.log('worker is dead:', worker.isDead());
  });

  cluster.on('exit', (worker, code, signal) => {
    console.log('worker is dead:', worker.isDead());
  });
} else {
  // Workers can share any TCP connection. In this case, it is an HTTP server.
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Current process\n ${process.pid}`);
    process.kill(process.pid);
  }).listen(8000);
}const cluster = require('node:cluster');
const http = require('node:http');
const numCPUs = require('node:os').availableParallelism();
const process = require('node:process');

if (cluster.isPrimary) {
  console.log(`Primary ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('fork', (worker) => {
    console.log('worker is dead:', worker.isDead());
  });

  cluster.on('exit', (worker, code, signal) => {
    console.log('worker is dead:', worker.isDead());
  });
} else {
  // Workers can share any TCP connection. In this case, it is an HTTP server.
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end(`Current process\n ${process.pid}`);
    process.kill(process.pid);
  }).listen(8000);
}copy

worker.kill([signal])#

• signal <string> ワーカープロセスに送信するkillシグナルの名前。デフォルト: 'SIGTERM'

この関数はワーカーを強制終了します。プライマリーワーカーでは、worker.processを切断し、切断後にsignalで強制終了することでこれを行います。ワーカーでは、プロセスをsignalで強制終了することで行います。

kill()関数は、正常な切断を待たずにワーカープロセスを強制終了します。これはworker.process.kill()と同じ動作です。

このメソッドは、後方互換性のためにworker.destroy()としてエイリアスされています。

ワーカーにはprocess.kill()が存在しますが、それはこの関数ではなく、kill()です。

worker.process#

• 型: <ChildProcess>

すべてのワーカーはchild_process.fork()を使用して作成され、この関数から返されたオブジェクトは.processとして保存されます。ワーカーでは、グローバルなprocessが保存されます。

参照: 子プロセスモジュール。

processで'disconnect'イベントが発生し、かつ.exitedAfterDisconnectがtrueでない場合、ワーカーはprocess.exit(0)を呼び出します。これは偶発的な切断から保護します。

worker.send(message[, sendHandle[, options]][, callback])#

• message <Object>
• sendHandle <Handle>
• options <Object> options引数が存在する場合、特定の種類のハンドルの送信をパラメータ化するために使用されるオブジェクトです。optionsは次のプロパティをサポートします。
  • keepOpen <boolean> net.Socketのインスタンスを渡すときに使用できる値。trueの場合、ソケットは送信プロセスで開いたままになります。デフォルト: false。
• callback <Function>
• 戻り値: <boolean>

ワーカーまたはプライマリーにメッセージを送信します。オプションでハンドルを付けることもできます。

プライマリーでは、これにより特定のワーカーにメッセージが送信されます。これはChildProcess.send()と同一です。

ワーカーでは、これによりプライマリーにメッセージが送信されます。これはprocess.send()と同一です。

この例では、プライマリーからのすべてのメッセージをエコーバックします。

if (cluster.isPrimary) {
  const worker = cluster.fork();
  worker.send('hi there');

} else if (cluster.isWorker) {
  process.on('message', (msg) => {
    process.send(msg);
  });
} copy