عرض مصدر Node.js/cluster

<noinclude>{{DISPLAYTITLE:العناقيد في Node.js}}</noinclude>
الاستقرار: 2-مستقر

تعمل نسخةٌ واحدةٌ من Node.js في خيط (thread) واحد. للاستفادة من الأنظمة ذات الأنوية المتعدِّدة (multi-core)، سيضطر المستخدم حينها إلى تشغيل عنقود من عمليات Node.js لمعالجة الحمل.

تسمح الوحدة <code>cluster</code> بإنشاء عمليات أبناء بسهولة تتشارك جميعها منافذ الخادم نفسها.<syntaxhighlight lang="javascript">
const cluster = require('cluster');
const http = require('http');
const numCPUs = require('os').cpus().length;

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

  // (worker) تفريع مسار العمليات العاملة
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on('exit', (worker, code, signal) => {
    console.log(`worker ${worker.process.pid} died`);
  });
} else {
  // TCP تستطيع العمليات أن تتشارك أي اتصال
  // http في هذه الحالة، الخادم هو خادم
  http.createServer((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');
  }).listen(8000);

  console.log(`Worker ${process.pid} started`);
}
</syntaxhighlight>ستشارك Node.js التي تعمل الآن المنفذ 8000 بين العمليات العاملة (workers):<syntaxhighlight lang="javascript">
$ node server.js
Master 3596 is running
Worker 4324 started
Worker 4520 started
Worker 6056 started
Worker 5644 started
</syntaxhighlight>انتبه رجاءً إلى أنَّه ليس بالإمكان إعداد أنبوب مسمى (named pipe) لخادم في عمليَّة عاملة في بيئة ويندوز.

== كيفية العمل ==
تُولَّد العمليات العاملة باستعمال التابع <code>child_process.fork()‎</code>، لذا بإمكان هذه العمليات التواصل مع العمليات الأب لها عبر قناة الاتصال IPC وتمرير معالجات الخادم ذهابًا وإيابًا.

تدعم وحدة العناقيد (cluster) أسلوبين لتوزيع الاتصالات الواردة؛ أولهما (ويعدُّ الاسلوب الافتراضي في جميع المنصات باستثناء ويندوز) يعتمد على التناوب (round-robin)، إذ تستمع العمليَّة الرئيسية (master process) إلى المنفذ، وتقبل الاتصالات الجديدة، ثمَّ تُوزِّعها بطريقة التناوب مع وجود بعض الذكاء المدمج لمنع التحميل الزائد لعمليَّة عاملة. أمَّا أسلوب التابع الثاني فيعتمد على إنشاء العمليَّة الرئيسية مقبس استماع ثمَّ إرساله إلى العمليَّة العاملة المعنيَّة؛ تقبل بعدئذٍ العمليَّة العاملة الاتصالات الواردة مباشرةً.

نظريًّا، يجب أن يعطي الأسلوب الثاني أداءً أفضل. أمَّا عمليًّا، وُجِد أنَّ أسلوب التوزيع يفقد توازنه نتيجة حدوث تقلبات في مُجَدوِل نظام التشغيل، إذ تمت مراقبة أحمال معيَّنة ولوحظ أنَّ 70% من جميع الاتصالات قد وُزِّعت على عمليتين فقط من أصل ثمان عمليات!

لمَّا كان التابع <code>server.listen()</code>‎ يُسنِد غالب العمل إلى العمليَّة الرئيسية، نتج لدينا ثلاثة حالات يختلف فيها سلوك عمليَّة Node.js الطبيعية عن سلوك العمليَّة العاملة في عنقود وهي:
# <code>server.listen({fd: 7})</code>‎: لمَّا كانت الرسائل تُمرَّر إلى العمليَّة الرئيسية، فسيكون واصف الملف 7 في العمليَّة الأب مستمعًا، وسيُمرَّر المعالج إلى العمليَّة العاملة بدلًا من الاستماع إلى تخمين العمليَّة العاملة حول موارد واصف الملف ذي الرقم 7 المحتملة.
# <code>server.listen(handle)‎</code>: سيُسبِّب الاستماع إلى المعالجات بشكل صريح بجعل العمليَّة العاملة تستعمل المعامل المعطى بدلًا من التحدث إلى العمليَّة الرئيسية.
# <code>server.listen(0)‎</code>: هذا سيجعل الخادم يستمع إلى منفذٍ عشوائيٍّ. مع ذلك، ستستلم كل عمليَّة عاملة في عنقود نفس المنفذ العشوائي في كل مرة يُستدعَى فيها <code>listen(0)‎</code>. الخلاصة، يكون المنفذ عشوائيًّا في المرة الأولى فقط ويمكن بعدها تخمين المنفذ. لاستعمال منفذ فريد، يمكن توليد رقم المنفذ اعتمادًا على معرف (ID) العمليَّة العاملة في العنقود.
لا توفِّر Node.js التوجيه المنطقي (routing logic). بناءً على ذلك، من المهم تصميم تطبيقٍ لا يعتمد بشكل كبير على الكائنات التي تخزِّن بياناتها في الذاكرة من أجل بعض الأمور مثل الجلسات وتسجيل الدخول.

بما أنَّ العمليات العاملة هي عمليات منفصلة تمامًا، يمكن قتلها أو إعادة توليدها بناءً على حاجة التطبيق دون التأثير على أيَّة عمليَّة عاملة أخرى. يستمر الخادم بقبول الاتصالات طالما هنالك بعض عمليات عاملة ما زالت على قيد الحياة. إن لم يعد هنالك أيَّة عمليَّة عاملة تعمل، فستنهى الاتصالات الموجودة آنذاك وستُرفض أيُّة اتصالات جديدة. لا تدير Node.js عدد العمليات العاملة تلقائيًّا، إذ يُعدُّ هذا من مسؤوليات التطبيق ليدير مجمِّع العمليَّة العاملة بقدر ما يحتاج.

رغم أنَّ الهدف الرئيسي من الوحدة <code>cluster</code> هو استعمالها في الشبكات إلا أنَّه يمكن استعمالها في حالات أخرى حيث تتطلب عمليات عاملة.

== الصنف <code>Worker</code> ==
أضيف في الإصدار v0.7.0.

يحوي الكائن <code>Worker</code> على جميع المعلومات والتوابع العامة المتعلقة بالعمليات العاملة (worker). في حالة عمليَّة رئيسية (master)، يمكن الحصول عليه باستعمال <code>cluster.workers</code>. أمَّا في حالة عمليَّة عاملة (worker)، يمكن الحصول عليه باستعمال <code>cluster.worker</code>.

=== الحدث 'disconnect' ===
أضيف في الإصدار v0.7.7.

يشبه هذا الحدثُ الحدثَ <code>cluster.on('disconnect')</code>‎ باستثناء أنَّه يمكن استعماله بشكل خاص مع الصنف <code>Worker</code>.<syntaxhighlight lang="javascript">
cluster.fork().on('disconnect', () => {
  // فُصِلَت العمليَّة العاملة الآن
});
</syntaxhighlight>

=== الحدث 'error' ===
أضيف في الإصدار v0.7.3.

هذا الحدث مماثل تمامًا لذلك الذي يوفره التابع [[Node.js/child process#child process.fork.28modulePath.5B.2C args.5D.5B.2C options.5D.29|<code>child_process.fork()</code>]]‎.

يمكن استدعاء <code>process.on('error')‎</code> أحيانًا ضمن العمليَّة العاملة.

=== الحدث 'exit' ===
أضيف في الإصدار v0.11.2.
* <code>code</code>: ‏[[JavaScript/Number|<number>]] حالة الخروج إن تم الخروج من العمليَّة بشكل طبيعي.
* <code>signal</code>: ‏[[JavaScript/String|<string>]] اسم الإشارة التي تسبَّبت في قتل أو إنهاء العمليَّة، مثل الإشارة SIGHUP.
يشبه هذا الحدثُ الحدثَ <code>cluster.on('exit')‎</code> باستثناء أنَّه يمكن استعماله بشكل خاص مع الصنف <code>Worker</code>.<syntaxhighlight lang="javascript">
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!');
  }
});
</syntaxhighlight>

=== الحدث 'listening' ===
أضيف في الإصدار v0.7.0.
* <code>address</code>: ‏[[JavaScript/Object|<Object>]]
يشبه هذا الحدثُ الحدثَ <code>cluster.on('exit')‎</code> باستثناء أنَّه يمكن استعماله بشكل خاص مع الصنف <code>Worker</code>.<syntaxhighlight lang="javascript">
cluster.fork().on('listening', (address) => {
  // العمليَّة العاملة تستمع الآن
});

</syntaxhighlight>لا يُطلق هذا الحدث ضمن العمليَّة العاملة.

=== الحدث 'message' ===
أضيف في الإصدار v0.7.0.
* <code>Message</code>: ‏[[JavaScript/Object|<Object>]]
* <code>handle</code>: ‏[[JavaScript/undefined|<undefined>]] | ‏[[JavaScript/Object|<Object>]]
هذا الحدث مشابهٌ للحدث 'message' الخاص بوحدة العناقيد (تجده في الأسفل) باستثناء أنَّه يمكن استعماله بشكل خاص مع الصنف <code>Worker</code>.

يمكن استدعاء <code>process.on('message')‎</code> أحيانًا ضمن العمليَّة العاملة.

انظر أيضًا الحدث 'message' في الكائن <code>process</code>.

في المثال التالي، سننشئ عنقودًا يَعُدُ الطلبيات في العمليَّة الرئيسية باستعمال نظام الرسائل:<syntaxhighlight lang="javascript">
const cluster = require('cluster');
const http = require('http');

if (cluster.isMaster) {

  // http الاستمرار في تعقب طلبيات
  let numReqs = 0;
  setInterval(() => {
    console.log(`numReqs = ${numReqs}`);
  }, 1000);

  // عدُّ الطلبيات
  function messageHandler(msg) {
    if (msg.cmd && msg.cmd === 'notifyRequest') {
      numReqs += 1;
    }
  }

  // notifyRequest بدء العمليات العاملة والاستماع إلى الرسائل التي تحوي العبارة
  const numCPUs = require('os').cpus().length;
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

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

} else {

  // http تملك العمليات العاملة خادم
  http.Server((req, res) => {
    res.writeHead(200);
    res.end('hello world\n');

    // تنبيه العمليَّة الرئيسية حول الطلبية
    process.send({ cmd: 'notifyRequest' });
  }).listen(8000);
}

</syntaxhighlight>

=== الحدث 'online' ===
أضيف في الإصدار v0.7.0.

يشبه هذا الحدثُ الحدثَ <code>cluster.on('online')‎</code> باستثناء أنَّه يمكن استعماله بشكل خاص مع الصنف <code>Worker</code>.<syntaxhighlight lang="javascript">
cluster.fork().on('online', () => {
  // العمليَّة العاملة متصلة الآن
});
</syntaxhighlight>لا يُطلق هذا الحدث ضمن العمليَّة العاملة.

=== <code>worker.disconnect()‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v7.3.0
|أصبح هذا التابع يعيد مرجعًا إلى الكائن <code>worker</code>.
|-
|v0.0.7
|أضيف هذا التابع.
|}
* القيم المعادة: <cluster.Worker> مرجعٌ إلى الكائن <code>worker</code>.
إن استدعي هذا التابع ضمن عمليَّة عاملة، فستُغلَق جميع الخوادم، وستنتظر هذه الخوادم الحدث 'close'، ثمَّ ستُفصَل قناة الاتصال IPC.

أمَّا إن استدعي هذا التابع ضمن عمليَّة رئيسية، فسترسل رسالة داخلية إلى العمليَّة العاملة تطلب منها استدعاء <code>‎.disconnect()‎</code> من تلقاء نفسها.

يتسبَّب هذا التابع أيضًا في ضبط الخاصية ‎<code>.exitedAfterDisconnect</code>.

انتبه إلى أنَّه لن تُقبَل الاتصالات الجديدة بعد إغلاق الخادم، وقد تقبل هذه الاتصالات عبر أيَّة عمليَّة عاملة مستمعة أخرى. أضف إلى ذلك أنَّ إغلاق جميع الاتصالات يسمح بإغلاق الخادم بشكل طبيعي. عندما لم يعد هنالك أيَّة اتصالات موجودة، ستُغلَق القناة IPC للعمليَّة العاملة مما يسمح بموت العمليَّة بأمان (ارجع إلى التابع <code>server.close()‎</code> للمزيد من التفاصيل).

ينطبق كل ما سبق على اتصالات الخادم فقط، إذ لا تُغلِق العمليات العاملة اتصالات العميل تلقائيًّا ولا تنتظر عمليَّة قطع الاتصال إغلاق تلك الاتصالات قبل الخروج.

انتبه إلى وجود التابع <code>process.disconnect()</code>‎ في العمليَّة العاملة، إذ ليس هذا التابع هو التابع الذي نتحدث عنه بل هو التابع [[Node.js/child process#.D8.A7.D9.84.D8.AA.D8.A7.D8.A8.D8.B9 subprocess.disconnect.28.29.E2.80.8E|<code>subprocess.disconnect()‎</code>]].

لمَّا كانت اتصالات الخادم التي تدوم لفترة طويلة تمنع أحيانًا العمليات الأبناء من قطع الاتصال، فهذا قد يكون مفيدًا لإرسال رسالة تنبِّه التطبيق لاتخاذ إجراءٍ محدَّدٍ تُغلَق عبره تلك الاتصالات. يمكن أيضًا أن يكون ذلك مفيدًا لتطبيق مهلة زمنية محدَّدة، إذ يمكن قتل العمليَّة العاملة إن لم يُطلَق الحدث 'disconnect' بعد فترة زمنيَّة معيَّنة.<syntaxhighlight lang="javascript">
if (cluster.isMaster) {
  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('net');
  const server = net.createServer((socket) => {
    // لن تنتهي الاتصالات مطلقًا
  });

  server.listen(8000);

  process.on('message', (msg) => {
    if (msg === 'shutdown') {
      // بدء إغلاق أية اتصالات للخادم
    }
  });
}

</syntaxhighlight>

=== الخاصية <code>worker.exitedAfterDisconnect</code> ===
أضيفت في الإصدار v6.0.0.
* [[JavaScript/Boolean|<boolean>]]
تُضبَط هذه الخاصية عند استدعاء التابع <code>‎.kill()‎</code> أو التابع ‎<code>.disconnect()‎</code>، وتكون قيمتها قبل ذلك <code>[[JavaScript/undefined|undefined]]</code>.

تساعد هذه الخاصية على التمييز بين الخروج الطوعي والخروج العَرَضي، إذ قد تتخذ العمليَّة الرئيسية قرارًا يتعلق بإعادة توليد العمليَّة أم لا بناءً على قيمة هذه الخاصية.<syntaxhighlight lang="javascript">
cluster.on('exit', (worker, code, signal) => {
  if (worker.exitedAfterDisconnect === true) {
    console.log('Oh, it was just voluntary – no need to worry');
  }
});

// قتل العمليَّة العاملة
worker.kill();

</syntaxhighlight>

=== الخاصية <code>worker.id</code> ===
أضيفت في الإصدار v0.8.0.
* [[JavaScript/Number|<number>]]
تمثِّل هذه الخاصية المعرِّف الفريد المعطى للعمليَّة العاملة. طالما كانت العمليَّة على قيد الحياة، تكون قيمة هذه الخاصية هي المفتاح الذي يشير إلى تلك العمليَّة في <code>cluster.workers</code>.

=== <code>worker.isConnected()‎</code> ===
أضيف في الإصدار v0.11.14.

يعيد هذا التابع القيمة true إن كانت العمليَّة العاملة متصلةً مع العمليَّة الرئيسية لها عبر قناة الاتصال IPC، أو تعيد القيمة <code>false</code> خلاف ذلك. تتصل العمليَّة العاملة مع العمليَّة الرئيسية لها بعد إنشائها، ويُقطع الاتصال بينهما بعد إطلاق الحدث 'disconnect'.

=== <code>worker.isDead()‎</code> ===
أضيف في الإصدار v0.11.14.

يعيد هذا التابع القيمة <code>true</code> إن أُنهيَت العمليَّة العاملة (سواءً خرجت العمليَّة بطوعها أو أُرسلت إشارة تجبرها على التوقف). خلا ذلك، تعيد القيمة <code>false</code>.

=== <code>worker.kill([signal='SIGTERM'])‎</code> ===
أضيف في الإصدار v0.9.12.
* <code>signal</code>: ‏[[JavaScript/String|<string>]] اسم الإشارة المراد إرسالها إلى العمليَّة العاملة. القيمة الافتراضية هي: 'SIGTERM'.
يُستعمَل هذ التابع لقتل العمليَّة العاملة عند استدعائها هنالك. إن استدعي في العمليَّة الرئيسية، فسيُفعِّل ذلك عبر قطع اتصال <code>worker.process</code> ثمَّ -متى ما قُطِع الاتصال- يرسل الإشارة <code>signal</code> إلى العمليَّة العاملة لقتلها. أمَّا إن استدعي في العمليَّة العاملة نفسها، فسيقطع اتصال القناة أولًا ثمَّ يجبر العمليَّة على الخروج مع حال الخروج 0.

يتسبَّب هذا التابع أيضًا في ضبط الخاصية ‎<code>.exitedAfterDisconnect</code>.

يُعدُّ هذا التابع اسمًا بديلًا للتابع <code>worker.destroy()‎</code>، إذ أُوجِد من أجل التوافقية الرجوعيَّة (backwards compatibility)

'''ملاحظة''': في العمليَّة العاملة، يكون التابع <code>process.kill()‎</code> هو المسؤول عن قتل العمليَّة وليس هذا التابع.

=== الخاصية <code>worker.process</code> ===
أضيفت في الإصدار v0.7.0.
* <ChildProcess>
تنشأ جميع العمليات العاملة باستعمال التابع <code>[[Node.js/child process#.E2.80.8Echild process.fork.28modulePath.5B.2C args.5D.5B.2C options.5D.29.E2.80.8E|child_process.fork()]]</code>‎ ويُخزَّن الكائن المعاد بعد استدعائه في الخاصية <code>‎.process</code>، وسيصبح المتغير العام <code>process</code> متاحًا في العملية العاملة.

انظر أيضًا توثيق العمليات الأبناء للمزيد من التفاصيل.

انتبه أيضًا إلى أنَّ العمليات العاملة ستستدعي <code>process.exit(0)‎</code> إن أطلق الحدث 'disconnect' مع الكائن <code>process</code> وقيمة الخاصية <code>‎.exitedAfterDisconnect</code> آنذاك هي <code>false</code>. هذا يساعد على تجنب الخروج عند انقطاع الاتصال بشكل غير مقصود.

=== <code>worker.send(message[, sendHandle][, callback])‎</code> ===
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v4.0.0
|أضيف المعامل <code>callback</code>.
|-
|v0.7.0
|أضيف هذا التابع.
|}
* <code>message</code>:‏ [[JavaScript/Object|<Object>]]
* <code>sendHandle</code>:‏ <Handle>
* <code>callback</code>:‏ [[JavaScript/Function|<Function>]]
* القيم المعادة: [[JavaScript/Boolean|<boolean>]]
يرسل هذا التابع رسالةً إلى العمليَّة العاملة أو العمليَّة الرئيسية مع إمكانية إرسالة معالج أيضًا.

إن استدعي هذا التابع في عمليَّة رئيسية، فسيُرسل رسالةً إلى عمليَّة عاملة محدَّدة، ويكافي في هذه الحالة التابع <code>ChildProcess.send()‎</code>.

أمَّا إن استدعي في العمليَّة العاملة، فسيرسل رسالةً إلى العمليَّة الرئيسية لها، ويكافئ في هذه الحالة التابع <code>process.send()‎</code>.

يوضِّح المثال التالي كيفية إرجاع الرسائل المرسلة من العمليَّة الرئيسية إليها:<syntaxhighlight lang="javascript">
if (cluster.isMaster) {
  const worker = cluster.fork();
  worker.send('hi there');

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

== الحدث 'exit' ==
أضيف في الإصدار v0.7.9.
* <code>worker</code>: ‏<cluster.Worker>
* <code>code</code>: ‏[[JavaScript/Number|<number>]] حالة الخروج إن تم الخروج بشكل طبيعي.
* <code>signal</code>: ‏[[JavaScript/String|<string>]] اسم الإشارة التي تسببت في قتل العمليَّة، مثل 'SIGHUP'.
يُطلَق الحدث 'exit' عندما تخرج أو تتوقف أي عمليَّة عاملة.

يمكن أن يُستعمَل هذا الحدث لإعادة تشغيل العمليَّة من جديد عبر استدعاء <code>‎[[Node.js/child process#.E2.80.8Echild process.fork.28modulePath.5B.2C args.5D.5B.2C options.5D.29.E2.80.8E|.fork()]]</code>‎ مجدَّدًا.<syntaxhighlight lang="javascript">
cluster.on('exit', (worker, code, signal) => {
  console.log('worker %d died (%s). restarting...',
              worker.process.pid, signal || code);
  cluster.fork();
});
</syntaxhighlight>انظر أيضًا قسم «<nowiki/>[[Node.js/child process#.D8.A7.D9.84.D8.AD.D8.AF.D8.AB .27exit.27|الحدث 'exit']]» في توثيق العمليات الأبناء.

== الحدث 'fork' ==
أضيف في الإصدار v0.7.0.
* <code>worker</code>: ‏<cluster.Worker>
يُطلَق الحدث 'fork' عندما تتفرَّع عمليَّة عاملة جديدة. يمكن الاستفادة من هذا الحدث في مراقبة نشاط عميلة عاملة معيَّنة أو تحديد مهلة زمنيَّة مخصصة لها.<syntaxhighlight lang="javascript">
const timeouts = [];
function errorMsg() {
  console.error('Something must be wrong with the connection ...');
}

cluster.on('fork', (worker) => {
  timeouts[worker.id] = setTimeout(errorMsg, 2000);
});
cluster.on('listening', (worker, address) => {
  clearTimeout(timeouts[worker.id]);
});
cluster.on('exit', (worker, code, signal) => {
  clearTimeout(timeouts[worker.id]);
  errorMsg();
});
</syntaxhighlight>

== الحدث 'listening' ==
أضيف في الإصدار v0.7.0.
* <code>worker</code>:‏ <cluster.Worker>
* <code>address</code>:‏ [[JavaScript/Object|<Object>]]
يُطلَق الحدث 'listening' في الخادم بعد استدعاء <code>listen()‎</code> من عمليَّة عاملة، ويُطلَق أيضًا في <code>cluster</code> في العمليَّة الرئيسية.

يُنفَّذ معالج هذا الحدث مع وسيطين؛ الأول هو <code>worker</code> الذي يحتوي على الكائن <code>worker</code>، والثاني هو <code>address</code> الذي يحتوي على خاصِّيَّات الاتصال <code>address</code>، و <code>port</code>، و <code>addressType</code>. هذا مفيد جدًا عندما تستمع العمليَّة العاملة إلى أكثر من عنوان واحد.<syntaxhighlight lang="javascript">
cluster.on('listening', (worker, address) => {
  console.log(
    `A worker is now connected to ${address.address}:${address.port}`);
});
</syntaxhighlight>يأخذ المعامل <code>addressType</code> إحدى القيم التالية:
* 4: تشير إلى TCPv4، أو
* 6: تشير إلى TCPv6، أو
* -1: تشير إلى مقبس نطاق يونكس (unix domain socket)، أو
* 'udp4' أو 'udp6': تشير إلى UDPv4 أو UDPv6 على التوالي.

== الحدث 'message' ==
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v6.0.0
|أصبح بالإمكان تمرير المعامل <code>worker</code> الآن.
|-
|v2.5.0
|أضيف هذا الحدث.
|}
* <code>worker</code>: ‏<cluster.Worker>
* <code>message</code>:‏ [[JavaScript/Object|<Object>]]
* <code>handle</code>: ‏[[JavaScript/undefined|<undefined>]] |‏ [[JavaScript/Object|<Object>]]
يُطلَق هذا الحدث عندما يستلم العنقود الرئيسي رسالةً من أي عمليَّة عاملة.

انظر أيضًا الحدث 'message' في توثيق العمليات الأبناء.

'''ملاحظة''': قبل الإصدار Node.js v6.0، كان هذا الحدث يُطلِق المعامل <code>message</code> والمعامل <code>handle</code> فقط دون المعامل <code>worker</code> أي عكس ما كان مذكورًا في التوثيق.

يُطلَب استعمال الإصدارات الأحدث دومًا إن كانت مدعومة. مع ذلك، يمكن الاستغناء عن الكائن <code>worker</code>، إذ من الممكن التغلب على هذا التناقض عبر التحقُّق من عدد المعاملات بالشكل التالي:<syntaxhighlight lang="javascript">
cluster.on('message', (worker, message, handle) => {
  if (arguments.length === 2) {
    handle = message;
    message = worker;
    worker = undefined;
  }
  // ...
});
</syntaxhighlight>

== الحدث 'online' ==
أضيف في الإصدار v0.7.0.
* <code>worker</code>:‏ <cluster.Worker>
يجب على العمليَّة العاملة الجديدة أن ترسل رسالة إلى العمليَّة الرئيسية تخبره بأنَّها أصبحت متصلة. عندما تستلم العمليَّة الرئيسية هذه الرسالة، يُطلَق هذا الحدث. الفارق بين الحدث 'fork' والحدث 'online' هو أنَّ الأول يُطلَق عندما تنشئ العمليَّة الرئيسية عمليَّة عاملة، والثاني يطلق عندما تبدأ العمليَّة العاملة في العمل.<syntaxhighlight lang="javascript">
cluster.on('online', (worker) => {
 console.log('Yay, the worker responded after it was forked');
});

</syntaxhighlight>

== الحدث 'setup' ==
أضيف في الإصدار v0.7.1.
* <code>settings</code>:‏ [[JavaScript/Object|<Object>]]
يُطلَق هذا الحدث في كل مرة يُستدعَى فيها التابع <code>‎.setupMaster()‎</code>.

يصبح الكائن <code>settings</code> هو الكائن <code>cluster.settings</code> نفسه في الوقت الذي يستدعى فيه التابع ‎<code>.setupMaster()</code>‎ وهو توجيهي (advisory) فقط، إذ من الممكن استدعاء <code>‎.setupMaster()</code>‎ عدَّة مرات بضغطة بسيطة.

إن كانت الدقة مهمة جدًا، فاستعمل الكائن <code>cluster.settings</code>.

== <code>cluster.disconnect([callback])‎</code> ==
أضيف في الإصدار v0.7.7.
* <code>callback</code>: [[JavaScript/Function|‏<Function>]] دالةٌ تستدعى عندما تصبح جميع العمليات العاملة غير متصلة وتغلق جميع المعالجات.
يستدعى التابع <code>‎.disconnect()</code>‎ مع كل عمليَّة عاملة في <code>cluster.workers</code>. عندما تصبح تلك العمليات غير متصلة وتغلق جميع معالجات الأحداث، سيؤدي ذلك إلى موت العمليَّة الرئيسية بأمان إن لم يكن هنالك أيَّة أحداث منتظرة.

يمكن تمرير دالة رد نداء إلى هذا التابع اختياريًّا لاستدعائها عند الانتهاء.

لا يمكن استدعاء هذا التابع إلا مع عمليَّة رئيسية.

== <code>cluster.fork([env])‎</code> ==
أضيف في الإصدار v0.6.0.
* <code>env</code>: ‏[[JavaScript/Object|<Object>]] زوجٌ من مفتاح/قيمة يراد إضافته إلى بيئة العمليَّة العاملة.
* القيم المعادة: <cluster.Worker>
يولِّد هذا التابع عمليَّة عاملة جديدة.

لا يمكن استدعاء هذا التابع إلا من العمليَّة الرئيسية.

== الخاصية <code>cluster.isMaster</code> ==
أضيف في الإصدار v0.8.1.
* [[JavaScript/Boolean|<boolean>]]
تحدِّد هذه الخاصية إن كانت العمليَّة عمليَّةً رئيسيةً باستعمال <code>process.env.NODE_UNIQUE_ID</code>، إذ تكون قيمة هذه الخاصية <code>true</code> إن كانت قيمة <code>process.env.NODE_UNIQUE_ID</code> هي <code>[[JavaScript/undefined|undefined]]</code>.

الخلاصة، تكون قيمة هذه الخاصية true إن كانت العمليَّة عمليَّةً رئيسية.

== الخاصية <code>cluster.isWorker</code> ==
أضيفت في الإصدار v0.6.0.
* [[JavaScript/Boolean|<boolean>]]
تحدِّد هذه الخاصية إن كانت العمليَّة عمليَّةً عاملة، إذ تكون قيمتها <code>true</code> إن لم تكن العمليَّة عمليَّةً رئيسية (هي عكس الخاصية <code>cluster.isMaster</code> تمامًا).

== الخاصية <code>cluster.schedulingPolicy</code> ==
أضيفت في الإصدار v0.11.2.

تمثِّل هذه الخاصية أسلوب الجدولة، إذ إمَّا أن تكون قيمتها <code>cluster.SCHED_RR</code> من أجل أسلوب التناوب (round-robin) أو <code>cluster.SCHED_NONE</code> لترك الأمر إلى نظام التشغيل. هذه الخاصية هي خاصية عامة وتكون غير فعالة ولا يمكن ضبطها متى ما ولدت أول عمليَّة عاملة أو متى ما استدعي التابع <code>cluster.setupMaster()</code>‎ أيهما يحدث أولًا.

القيمة الافتراضيَّة لهذه الخاصية هي <code>SCHED_RR</code> على جميع المنصات باستثناء ويندوز. سيغيِّر ويندوز قيمة هذه الخاصية إلى <code>SCHED_RR</code> متى ما توافرت المكتبة libuv لنشر المعالجات IOCP بكفاءة دون استهلاك قدر كبير من الأداء.

يمكن ضبط الخاصية <code>cluster.schedulingPolicy</code> عبر متغير البيئة <code>NODE_CLUSTER_SCHED_POLICY</code>، إذ يمكن استعمال إحدى القيمتين: 'rr' أو 'none'.

== الخاصية <code>cluster.settings</code> ==
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v9.5.0
|إضافة الخيار <code>cwd</code>.
|-
|v9.4.0
|إضافة الخيار <code>windowsHide</code>.
|-
|v8.2.0
|إضافة الخيار <code>inspectPort</code>.
|-
|v6.4.0
|إضافة الخيار <code>stdio</code>.
|-
|v0.7.1
|إضافة هذه الخاصية.
|}
* <code>options</code>: [[JavaScript/Object|‏<Object>]] كائنٌ يمكن أن يحتوي على الخيارات التالية:
** <code>execArgv</code>: ‏[[JavaScript/String|<string[]‎‎>]] قائمة سلاسل نصية تمثِّل الوسائط المراد تمريرها إلى عمليَّة Node.js القابلة للتنفيذ. القيمة الافتراضيَّة هي: <code>process.execArgv</code>.
** <code>exec</code>: ‏[[JavaScript/String|<string>]] المسار الذي يشير إلى ملف العمليَّة العاملة. القيمة الافتراضية هي: <code>process.argv[1]‎</code>.
** <code>args</code>: [[JavaScript/String|‏<string[]‎‎>]] قائمةٌ من سلاسل نصية تمثِّل الوسائط المراد تمريرها إلى العمليَّة العاملة. القيمة الافتراضية هي: <code>process.argv.slice(2)‎</code>.
** <code>cwd</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل مجلد العمل الحالي للعمليَّة العاملة. القيمة الافتراضيَّة هي: <code>[[JavaScript/undefined|undefined]]</code> (تورث من العمليَّة الأب).
** <code>silent</code>: [[JavaScript/Boolean|‏<boolean>]] قيمة منطقيَّة تحدِّد إن كان يراد إسال المخرجات إلى مجرى الخرج القياسي للعمليَّة الأب أم لا. القيمة الافتراضية هي: <code>false</code>.
** <code>stdio</code>: ‏[[JavaScript/Array|<Array>]] ضبط مجاري الخرج والدخل القياسية للعمليَّة الفرعية. لمَّا كانت الوحدة <code>[[Node.js/cluster|cluster]]</code> تعتمد على القناة IPC، فيجب أن يحوي هذا الضبط على 'ipc'. عندما يعطى هذا الضبط، يُتجاهل الضبط <code>silent</code>.
** <code>uid</code>: [[JavaScript/Number|‏<number>]] عددٌ يحدِّد مُعرِّف المستخدم المالك للعمليَّة (ارجع إلى <code>[http://man7.org/linux/man-pages/man2/setuid.2.html setuid(2)‎]</code>).
** <code>gid</code>: ‏[[JavaScript/Number|<number>]] عددٌ يحدِّد مُعرِّف المجموعة المالكة للعمليَّة (ارجع إلى <code>[http://man7.org/linux/man-pages/man2/setgid.2.html setgid(2)‎]</code>).
** <code>inspectPort</code>: ‏[[JavaScript/Number|<number>]] | ‏[[JavaScript/Function|<Function>]] يعين منفذ مراقب للعمليَّة العاملة. يمكن أن يكون هذا الضبط عددًا أو دالةً تعيد عددًا دون أن يُمرَّر إليها أي وسيط. افتراضيًّا، يكون لكل عمليَّة عاملة منفذًا خاصًّا بها يتزايد بدءًا من المنفذ <code>process.debugPort</code> الخاص بالعمليَّة الرئيسية.
** <code>windowsHide</code>: ‏[[JavaScript/Boolean|<boolean>]] قيمةٌ منطقيةٌ تتحكم بإظهار وإخفاء نافذة الطرفية للعمليَّة الفرعية التي ستُنشأ دومًا بشكل اعتيادي في أنظمة ويندوز. القيمة الافتراضيَّة هي: <code>false</code>.
سيحتوي الكائن <code>settings</code> على الإعدادات بعد استدعاء التابع ‎<code>.setupMaster()</code>‎ (أو التابع <code>[[Node.js/child process#.E2.80.8Echild process.fork.28modulePath.5B.2C args.5D.5B.2C options.5D.29.E2.80.8E|‎.fork()]]‎</code>) من ضمنها الإعدادات الافتراضية.

لا يفترض تغيير هذا الكائن أو ضبطه يدويًّا.

== <code>cluster.setupMaster([settings])‎</code> ==
{| class="wikitable mw-collapsible"
|+سجل التغييرات
!الإصدار
!التغييرات
|-
|v6.4.0
|أضيف الخيار <code>stdio</code>.
|-
|v0.7.1
|أضيف هذا التابع.
|}
* <code>settings</code>: ‏[[JavaScript/Object|<Object>]] ارجع إلى الخاصية <code>cluster.settings</code>.
يستعمل هذا التابع لتغيير سلوك 'fork' الافتراضي، إذ ستصبح الإعدادات المضبوطة في الخاصية <code>cluster.settings</code> هي الإعدادات الحاليَّة متى ما استدعي.

يرجى الانتباه إلى النقاط التالية:
* ستصبح التغييرات الحاصلة سارية المفعول مع الاستدعاءات اللاحقة للتابع <code>[[Node.js/child process#.E2.80.8Echild process.fork.28modulePath.5B.2C args.5D.5B.2C options.5D.29.E2.80.8E|‎.fork()]]</code>‎ فقط ولن تؤثر مطلقًا على العمليات العاملة التي تعمل مسبقًا.
* الخاصية الوحيدة التي لا يمكن للعمليَّة العاملة عبر <code>‎.setupMaster()‎</code> هي <code>env</code> المُمرَّرة إلى التابع <code>[[Node.js/child process#.E2.80.8Echild process.fork.28modulePath.5B.2C args.5D.5B.2C options.5D.29.E2.80.8E|‎.fork()]]</code>‎.
* تطبق الإعدادات الافتراضيَّة المذكورة في الأعلى عند استدعاء التابع ‎<code>.setupMaster()‎</code> لأول مرة فقط، ثمَّ تصبح الاعدادات الافتراضية للاستدعاءات اللاحقة هي القيم الحالية المضبوطة في الوقت الذي يستدعى التابع ‎<code>.setupMaster()</code>‎ فيه.
تفحَّص المثال التالي:<syntaxhighlight lang="javascript">
const cluster = require('cluster');
cluster.setupMaster({
  exec: 'worker.js',
  args: ['--use', 'https'],
  silent: true
});
cluster.fork(); // عاملة http عمليَّة
cluster.setupMaster({
  exec: 'worker.js',
  args: ['--use', 'http']
});
cluster.fork(); // عاملة http عمليَّة
</syntaxhighlight>لا يمكن تنفيذ هذه الشيفرة إلا من عمليَّة رئيسية.

== الخاصية <code>cluster.worker</code> ==
أضيفت في الإصدار v0.7.0.
* [[JavaScript/Object|<Object>]]
تمثل هذه الخاصية مرجعًا إلى الكائن <code>worker</code> الحالي، وهي غير متاحة في العمليَّة الرئيسية.<syntaxhighlight lang="javascript">
const cluster = require('cluster');

if (cluster.isMaster) {
  console.log('I am master');
  cluster.fork();
  cluster.fork();
} else if (cluster.isWorker) {
  console.log(`I am worker #${cluster.worker.id}`);
}
</syntaxhighlight>

== الخاصية <code>cluster.workers</code> ==
أضيفت في الإصدار v0.7.0.
* [[JavaScript/Object|<Object>]]
تُخزِّن هذه الخاصية الكائنات <code>worker</code> الفعالة آنذاك، إذ يربط كل كائن مع معرِّف <code>id</code>. يمكن الاستفادة من هذه الخاصية بتطبيق حلقة تكراريَّة على جميع العمليات العاملة، وهي متاحةٌ فقط في العمليَّة الرئيسية.

تزال العمليَّة العاملة من <code>cluster.workers</code> بعد أن تصبح غير متصلة ثمَّ تخرج، ولا يمكن أن يحدَّد ترتيب وقوع هذين الحدثين (الحدث 'disconnected' والحدث 'exit') مسبقًا. مع ذلك، يُضمن بإزالة العمليَّة العاملة من القائمة <code>cluster.workers</code> قبل إطلاق آخر الحدثين 'disconnected' و 'exit'.<syntaxhighlight lang="javascript">
// تطبيق حلقة تكرارية لفعل شيء مع جميع العمليات العاملة
function eachWorker(callback) {
  for (const id in cluster.workers) {
    callback(cluster.workers[id]);
  }
}
eachWorker((worker) => {
  worker.send('big announcement to all workers');
});
</syntaxhighlight>استعمال مُعرِّف العمليَّة العاملة الفريد هو أسهل طريقة لتحديد هذه العمليَّة.<syntaxhighlight lang="javascript">
socket.on('data', (id) => {
  const worker = cluster.workers[id];
});

</syntaxhighlight>

== مصادر ==
* [https://nodejs.org/dist/latest-v10.x/docs/api/cluster.html صفحة Cluster في توثيق Node.js الرسمي.]
[[تصنيف:Node.js|{{SUBPAGENAME}}]]