عرض مصدر Node.js/async hooks

<noinclude>{{DISPLAYTITLE:الخطافات غير المتزامنة في Node.js}}</noinclude>
الاستقرار: 1-تجريبي

توفِّر الوحدة <code>async_hooks</code> واجهة برمجية (API) لتسجيل دوال ردود النداء التي تتعقَّب دورة حياة (lifetime) الموارد غير المتزامنة (asynchronous resources) المُنشأَة داخل تطبيقات Node.js. يمكن الوصول إلى هذه الوحدة باستعمال الأمر التالي:<syntaxhighlight lang="javascript">
const async_hooks = require('async_hooks');
</syntaxhighlight>

== اصطلاحات ==
يمثِّل المورد غير المتزامن كائنًا مرفقًا به رد نداء. قد يُستدعَى رد النداء هذا عدَّة مرات، مثل الحدث 'conection' في <code>net.createServer()</code>‎، أو مرةً واحدة فقط، مثل <code>fs.open()‎</code>. يمكن أن يُغلق المورد أيضًا قبل أن يُستدعَى رد النداء. لا تفرِّق الوحدة <code>AsyncHook</code> بشكل واضح بين هاتين الحالتين المختلفتين، ولكن ستمثلهما بمفهوم مجرَّد بوصفهما موردًا.

إن استُعمِل الصنف <code>worker</code>، فسيكون لكل خيط (thread) واجهة <code>async_hooks</code> مستقلة وستُستعمَل مجموعةٌ جديدةٌ من المعرِّفات غير المتزامنة (async IDs).

== الواجهات البرمجية العامة (Public API) ==

=== نظرة سريعة ===
تشرح الشيفرة التالية بشكل سريع وشامل الواجهات البرمجيَّة العامَّة:<syntaxhighlight lang="javascript">
const async_hooks = require('async_hooks');

// تعيد مُعرِّف محتوى التنفيذ الحالي
const eid = async_hooks.executionAsyncId();

// تعيد معرِّف المعالج المراد استدعاؤه والمسؤول عن 
// استدعاء رد النداء لمجال التنفيذ الحالي
const tid = async_hooks.triggerAsyncId();

// .جميع ردود النداء هذه هي اختيارية .AsyncHook إنشاء نسخة جديدة من
const asyncHook =
    async_hooks.createHook({ init, before, after, destroy, promiseResolve });

// هذه. هذا ليس فعلًا ضمنيًا AsyncHook السماح باستدعاء ردود نداء النسخة
// .ينفَّذ بعد تشغيل الدالة البانية، ويجب التصريح به بشكل واضح لبدء تنفيذ ردود النداء
asyncHook.enable();

// تعطيل استعمال الأحداث غير المتزامنة الجديدة
asyncHook.disable();

//
// createHook() ما يلي هو ردود النداء التي يمكن تمريرها إلى
//


//  خلال إنشاء الكائن. ربما لم يكتمل إنشاء المورد بعد عندما ينفَّذ رد النداء init يستدعى رد النداء
// .قد مُلئت بعد "asyncId" هذا، لذا لا تكون جميع حقول المورد المشار إليه من قبل
function init(asyncId, type, triggerAsyncId, resource) { }

// N فقط قبل استدعاء رد نداء المورد. يمكن أن يستدعى من 0 إلى before يستدعى رد النداء 
// بينما يستدعى مرة واحدة فقط مع ،TCPWrap مرة مع المعالجات مثل
// FSReqWrap الطلبات مثل
function before(asyncId) { }

// فقط بعد أن يكون رد نداء المورد قد اكتمل after يستدعى رد النداء
function after(asyncId) { }

// AsyncWrap عندما تدمر نسخةٌ من destroy  يستدعى رد النداء
function destroy(asyncId) { }

// عندما تمرر Promise فقط من أجل الموارد promiseResolve يستدعى 
// الباني المستدعى `Promise` إلى الكائن `resolve` الدالة
// .(Promise إما بشكل مباشرةً أو عبر وسائل أخرى لاستبيان الكائن)
function promiseResolve(asyncId) { }
</syntaxhighlight>أضيفت في الإصدار: v8.1.0
* <code>callbacks</code>: ‏[[JavaScript/Object|<Object>]] ردود نداء الخطاف (Hook Callbacks) المراد تسجيلها، ويمكن أن يحوي إحدى الدوال التالية:
** <code>init</code>: [[JavaScript/Function|‏<Function>]] دالة رد النداء <code>init</code>.
** <code>before</code>: ‏[[JavaScript/Function|‏<Function>]] دالة رد النداء <code>before</code>.
** <code>after</code>: ‏[[JavaScript/Function|‏<Function>]] دالة رد النداء <code>after</code>.
** <code>destroy</code>: ‏[[JavaScript/Function|‏<Function>]] دالة رد النداء <code>destroy</code>.
تعيد هذه الدالة نسخةً من خطاف غير متزامن <code>AsyncHook</code> يستعمل لتعطيل وتشغيل الخطافات.

تسجِّل الدالة <code>async_hooks.createHook(callbacks)‎</code> الدوال المراد استدعاؤها في مختلف أوقات تنفيذ أحداث كل عمليَّة غير متزامنة.

تُستدعَى ردود النداء <code>init()</code>‎، و <code>before()</code>‎، و <code>after()</code>‎، و <code>destroy()</code>‎ للحدث غير المتزامن الخاص بها خلال فترة تواجد المورد.

جميع ردود النداء اختياريَّة. إن احتجت مثلًا إلى تعقُّب عمليَّة مسح مورد فقط، فمرِّر رد النداء <code>destroy</code>. مواصفات جميع الدوال التي يمكن تمريرها إلى <code>callbacks</code> موجودةٌ في القسم "ردود نداء الخطاف" الذي سيأتي ذكره لاحقًا.<syntaxhighlight lang="javascript">
const async_hooks = require('async_hooks');

const asyncHook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) { },
  destroy(asyncId) { }
});

</syntaxhighlight>انتبه إلى أنَّ ردود النداء ستُورَّث بوساطة سلسلة <code>prototype</code>:<syntaxhighlight lang="javascript">
class MyAsyncCallbacks {
  init(asyncId, type, triggerAsyncId, resource) { }
  destroy(asyncId) {}
}

class MyAddedCallbacks extends MyAsyncCallbacks {
  before(asyncId) { }
  after(asyncId) { }
}

const asyncHook = async_hooks.createHook(new MyAddedCallbacks());

</syntaxhighlight>

===== معالجة الأخطاء =====
إن رُميت أيَّة ردود النداء <code>AsyncHook</code>، فسيطبع التطبيق تقرير متعقِّب المكدس (stack trace) ويُغلق بعدها. يتبع مسار الخروج نفس مسار الاستثناء <code>uncaught</code>، ولكن يحذف جميع المستمعين 'uncaughtException' وتجبر العمليَّة بذلك على الخروج. لا تزال تُستدعَى ردود النداء 'exit' إلا إذ شُغِّل البرنامج مع الراية ‎--abort-on-uncaught-exception وفي هذه الحالة سيُطبَع تقرير متعقِّب المكدس وسيُغلَق التطبيق مغادرًا ملف النواة.

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

===== الطباعة في ردود النداء <code>AsyncHooks</code> =====
لمَّا كانت الطباعة في الطرفية عمليةً غير متزامنة، فستتسبَّب <code>console.log()</code>‎ في أن تستدعى ردود النداء <code>AsyncHooks</code>؛ لذا، سيُسبِّب استعمال <code>console.log()</code>‎ أو أيَّة عمليَّة غير متزامنة مشابهة داخل دالة رد النداء <code>AsyncHooks</code> عودية لا نهاية. هنالك حل بسيط لهذا الأمر عند تصحيح الأخطاء هو استعمال عمليَّة تسجيل (logging) غير متزامنة مثل <code>fs.writeSync(1, msg)‎</code>. سيطبع هذا على مجرى الخرج القياسي (stdout)، إذ يُمثَّل 1 في واصف الملف (file descriptor) بمجرى الخرج القياسي ولن يستدعي ردود النداء AsyncHooks بشكل تعاودي لأنَّها متزامنة.<syntaxhighlight lang="javascript">
const fs = require('fs');
const util = require('util');

function debug(...args) {
  // AsyncHooks استعمل دالةً مثل هذه عند تصحيح الأخطاء داخل رد النداء 
  fs.writeSync(1, `${util.format(...args)}\n`);
}
</syntaxhighlight>إن دعت الحاجة إلى استعمال عمليَّة غير متزامنة للتسجيل (logging)، فمن الممكن تعقُّب الذي سبب العمليَّة غير المتزامنة باستمرار عبر استعمال المعلومات التي توفِّرها <code>AsyncHooks</code> نفسها. يجب تخطي عمليَّة التسجيل نفسها عندما تكون هي السبب وراء استدعاء رد النداء <code>AsyncHooks</code>. عند تنفيذ ذلك، ستتحطم التعاودي اللانهائيَّة.

==== <code>asyncHook.enable()‎</code> ====
تعيد هذه الدالة مرجعًا إلى <code>asyncHook</code>، إذ تُفعَّل ردود النداء للنسخة <code>AsyncHook</code> المعطاة. إن لم يعطَ أي رد نداء، فلن يكون لاستدعاء هذه الدالة أي تأثير.

تكون النسخة <code>AsyncHook</code> المنشأة معطَّلة افتراضيًّا. لتفعيلها مباشرةً بعد إنشائها، يمكنك اتباع النموذج التالي:<syntaxhighlight lang="javascript">
const async_hooks = require('async_hooks');
const hook = async_hooks.createHook(callbacks).enable();
</syntaxhighlight>

==== <code>asyncHook.disable()‎</code> ====
تعيد هذه الدالة مرجعًا إلى <code>asyncHook</code>، إذ تعطِّل ردود النداء للنسخة <code>asyncHook</code> المعطاة من مجموعة (pool) ردود النداء <code>asyncHook</code> العامَّة المراد تنفيذها. لن يستدعَ الخطاف مرةً أخرى متى ما عُطِّل حتى يفعَّل من جديد.

من أجل تناسق الواجهة البرمجية (API)، تعيد <code>disable()‎</code> نسخةً من <code>AsyncHook</code> أيضًا.

==== ردود نداء الخطاف (Hook Callbacks) ====
صُنِّفَت الأحداث key خلال فترة وجود الأحداث غير المتزامنة إلى أربعة أقسام هي: أثناء الإنشاء، وقبل استدعاء رد النداء، وبعد استدعاء رد النداء، وعند إزالة النسخة.

===== <code>init(asyncId, type, triggerAsyncId, resource)‎</code> =====
* <code>asyncId</code>: [[JavaScript/Number|‏<number>]] عددٌ يمثِّل معرِّفًا (ID) فريدًا للمورد غير المتزامن.
* <code>type</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيةٌ تمثِّل نوع المورد غير المتزامن.
* <code>triggerAsyncId</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل معرفًا فريدًا للمورد غير المتزامن الذي يخص سياق التنفيذ حيث أنشئ هذا المورد ضمنه.
* <code>resource</code>:‏ [[JavaScript/Object|<Object>]] كائنٌ يحوي مرجعًا إلى المورد الذي يمثِّل العمليَّة غير المتزامنة، وهو الذي يُطلَق أثناء عمليَّة الإزالة.
تُستدعَى هذه الدالة عند إنشاء صنفٍ قادرٍ على إطلاق حدث غير متزامن. هذا لا يعني أنَّه ينبغي على النسخة استدعاء رد النداء <code>before</code> ورد النداء <code>after</code> قبل أن يُستدعَى رد النداء <code>destroy</code> وإنَّما يمتلك المقدرة على ذلك فقط.

يمكن أن يُراقَب هذا السلوك بفعل شيء مثل فتح موردٍ ثمَّ إغلاقه قبل أن يُستعمَل. توضِّح قطعة الشيفرة التالية ذلك:<syntaxhighlight lang="javascript">
require('net').createServer().listen(function() { this.close(); });
// أو
clearTimeout(setTimeout(() => {}, 10));

</syntaxhighlight>يسند لكل مورد جديد مُعرِّف (ID) فريد ضمن مجال نسخة Node.js الحاليَّة.

====== المعامل type ======
المعامل type هو سلسلة نصيَّة تُعرِّف نوع المورد الذي أدى إلى استدعاء رد النداء init. عمومًا، سيتطابق مع اسم باني المورد.<syntaxhighlight lang="javascript">
FSEVENTWRAP, FSREQWRAP, GETADDRINFOREQWRAP, GETNAMEINFOREQWRAP, HTTPPARSER,
JSSTREAM, PIPECONNECTWRAP, PIPEWRAP, PROCESSWRAP, QUERYWRAP, SHUTDOWNWRAP,
SIGNALWRAP, STATWATCHER, TCPCONNECTWRAP, TCPSERVER, TCPWRAP, TIMERWRAP, TTYWRAP,
UDPSENDWRAP, UDPWRAP, WRITEWRAP, ZLIB, SSLCONNECTION, PBKDF2REQUEST,
RANDOMBYTESREQUEST, TLSWRAP, Timeout, Immediate, TickObject

</syntaxhighlight>هنالك أيضًا نوع المورد <code>PROMISE</code> الذي يُستعمَل لتعقُّب نُسَخ الكائن [[jQuery/promise|Promise]] والعمل غير المتزامن المُجَدْوَل من طرفهم.

يستطيع المستخدمون أن يعرِّفوا نوعهم الخاص بهم عند استعمال الواجهة البرمجيَّة Embedder (API)‎ العامَّة.

من الممكن حصول تعارض في أسماء الأنواع، لذا ينصح باستعمال بادئة فريدة، مثل اسم الحزمة npm، لمنع أي تعارض عند الاستماع إلى الخطافات.

====== المعامل <code>triggerAsyncId</code> ======
المعامل <code>triggerAsyncId</code> هو المُعرِّف <code>asyncId</code> للمورد الذي تسبَّب في تهيئة المورد الجديد والذي أدى بعدها إلى استدعاء رد النداء <code>init</code>. هذا مختلفٌ عن <code>async_hooks.executionAsyncId()‎</code> الذي يُظهِر متى أنشئ المورد بينما يُظهِر <code>triggerAsyncId</code> لماذا أنشئ المورد.

الشيفرة التالية هي شرح عملي بسيط حول المعامل <code>triggerAsyncId</code>:<syntaxhighlight lang="javascript">
async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = async_hooks.executionAsyncId();
    fs.writeSync(
      1, `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`);
  }
}).enable();

require('net').createServer((conn) => {}).listen(8080);

</syntaxhighlight>سيعطي هذا المثال النتيجة التالية عند إرسال <code>nc localhost 8080</code> إلى الخادم:<syntaxhighlight lang="javascript">
TCPSERVERWRAP(2): trigger: 1 execution: 1
TCPWRAP(4): trigger: 2 execution: 0

</syntaxhighlight>نجد أنَّ <code>TCPSERVERWRAP</code> هو الخادم الذي يستقبل الاتصالات، وأنَّ <code>TCPWRAP</code> هو اتصال جديد من العميل. عندما يُؤسَّس اتصال جديد، ستُنشَأ نسخةٌ من <code>TCPWrap</code> مباشرةً وهذا يحدث خارج مكدس [[JavaScript]] (القيمة 0 التي أعادها <code>executionAsyncId()</code>‎ تشير إلى أنه يُنفَّذ الآن من C++‎ دون وجود مكدس [[JavaScript]] فوقه). مع تلك المعلومات فقط، يستحيل ربط الموارد مع بعضهم بعضًا من طرف من تَسبَّب في إنشائهم، لذا يعطى <code>triggerAsyncId</code> مهمة نشر (propagate) أيَّ مورد مسؤول عن وجود المورد الجديد.

====== المعامل <code>resource</code> ======
المعامل <code>resource</code> هو كائنٌ يمثِّل المورد غير المتزامن الفعلي الذي قد تمت تهيئته، ويمكن أن يحتوي على معلوماتٍ مفيدة تختلف باختلاف قيمة المعامل <code>type</code>. على سبيل المثال، يوفِّر المعامل <code>resource</code> من أجل نوع المورد <code>GETADDRINFOREQWRAP</code> اسم المضيف (hostname) المُستعمَل عند البحث عن العنوان IP الخاص به في <code>net.Server.listen()</code>‎. لا تُعدُّ الواجهة البرمجيَّة (API) التي توفِّر الوصول إلى هذه المعلومات عامَّةً حاليًا. مع ذلك، يستطيع المستخدمون باستعمال الواجهة البرمجيَّة المُضمِّنة (Embedder API) توفير وتوثيق الكائنات <code>resource</code> الخاصَّة بهم. فيمكن مثلًا توفير كائن <code>resource</code> يستطيع أن يحوي تعليمة [[SQL]] لكي تُنفَّذ حينذاك.

في حالة الوعود (Promises)، سيكون للكائن <code>resource</code> الخاصِّيَّة <code>promise</code> التي تشير إلى الكائن [[jQuery/promise|Promise]] الذي يُهيَّأ آنذاك، والخاصِّيَّة <code>isChainedPromise</code> التي تُضبَط إلى القيمة <code>true</code> إن كان للكائن [[jQuery/promise|Promise]] كائن أب من النوع [[jQuery/promise|Promise]] أيضًا أو إلى القيمة <code>false</code> خلاف ذلك. فإذا نظرنا مثلًا إلى <code>b = a.then(handler)</code>‎، نجد أنَّ <code>a</code> يُعدُّ كائن [[jQuery/promise|Promise]] أب للكائن <code>b</code>؛ ويُعدُّ <code>b</code> هنا وعدًا متسلسلًا (chained promise).

في بعض الأحيان، يُعاد استعمال الكائن <code>resource</code> لأسباب متعلقة بالأداء إلا أنَّه من غير الآمن استعماله كمفتاح في الكائن <code>WeakMap</code> أو إضافة خاصِّيَّات إليه.

====== مثال عن سياق غير متزامن ======
يوضح المثال التالي كيفيَّة استدعاء رد النداء <code>init</code> بين استدعاء ردي النداء <code>before</code> و <code>after</code>، وكيف سيبدو رد النداء للدالة <code>listen()‎</code> تحديدًا. تنسيق المخرجات مفصَّلة بشكل واسع لتسهيل قراءة سياق الاستدعاء.<syntaxhighlight lang="javascript">
let indent = 0;
async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    const eid = async_hooks.executionAsyncId();
    const indentStr = ' '.repeat(indent);
    fs.writeSync(
      1,
      `${indentStr}${type}(${asyncId}):` +
      ` trigger: ${triggerAsyncId} execution: ${eid}\n`);
  },
  before(asyncId) {
    const indentStr = ' '.repeat(indent);
    fs.writeSync(1, `${indentStr}before:  ${asyncId}\n`);
    indent += 2;
  },
  after(asyncId) {
    indent -= 2;
    const indentStr = ' '.repeat(indent);
    fs.writeSync(1, `${indentStr}after:   ${asyncId}\n`);
  },
  destroy(asyncId) {
    const indentStr = ' '.repeat(indent);
    fs.writeSync(1, `${indentStr}destroy: ${asyncId}\n`);
  },
}).enable();

require('net').createServer(() => {}).listen(8080, () => {
  // Let's wait 10ms before logging the server started.
  setTimeout(() => {
    console.log('>>>', async_hooks.executionAsyncId());
  }, 10);
});
</syntaxhighlight>ستظهر المخرجات التالية بدءًا من عمل الخادم:<syntaxhighlight lang="javascript">
TCPSERVERWRAP(2): trigger: 1 execution: 1
TickObject(3): trigger: 2 execution: 1
before:  3
  Timeout(4): trigger: 3 execution: 3
  TIMERWRAP(5): trigger: 3 execution: 3
after:   3
destroy: 3
before:  5
  before:  4
    TTYWRAP(6): trigger: 4 execution: 4
    SIGNALWRAP(7): trigger: 4 execution: 4
    TTYWRAP(8): trigger: 4 execution: 4
>>> 4
    TickObject(9): trigger: 4 execution: 4
  after:   4
after:   5
before:  9
after:   9
destroy: 4
destroy: 9
destroy: 5
</syntaxhighlight>كما هو موضَّح في المثال، يُحدِّد كلًا من <code>executionAsyncId()</code>‎ و <code>execution</code> قيمة سياق التنفيذ الحالي التي توصف بدقة عبر استدعاء <code>before</code> و <code>after</code>.

استعمل <code>execution</code> لوضع نتائج تخصيص موردٍ في مخطط بالشكل التالي:<syntaxhighlight lang="javascript">
TTYWRAP(6) -> Timeout(4) -> TIMERWRAP(5) -> TickObject(3) -> root(1)
</syntaxhighlight>لا يُعدُّ <code>TCPSERVERWRAP</code> جزءًا من هذا المخطط رغم أنَّه كان سببًا في استدعاء <code>console.log()</code>‎. هذا بسبب أنَّ عمليَّة ربط منفذٍ دون وجود اسم مضيف هي عمليَّة متزامنة. على أي حال، لإبقاء الواجهة البرمجية غير متزامنة بشكل كامل، يجب وضع رد نداء المستخدم في <code>process.nextTick()</code>‎.

يُظهِر المخطط متى أُنشِأ المورد فقط ولا يُظهِر كيفيَّة ذلك، لذا استعمل <code>triggerAsyncId</code> لتعقُّب كيفيَّة الإنشاء.

===== <code>before(asyncId)‎</code> =====
* <code>asyncId</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثل معرِّفًا (ID) فريدًا للمورد غير المتزامن.
عندما تبدأ عمليةٌ غير متزامنة (مثل استقبال خادم TCP اتصالًا جديدًا) أو تصبح مكتملة (مثل كتابة بيانات إلى القرص الصلب)، يُستدعَى رد نداءٍ لتنبيه المستخدم ولكن يستدعى رد النداء <code>before</code> فقط قبل تنفيذه، إذ يُمرَّر إليه المُعرِّف الفريد الذي أُسنِد إلى المورد الذي على وشك تنفيذ رد النداء.

سيُستدعَى رد النداء <code>before</code> من 0 إلى N مرة، إذ لن يستدعى مطلقًا (أي 0 مرة) إن ألغيت العمليَّة غير المتزامنة أو لم يستلم خادم TCP مثلًا أي اتصال.

ستستدعي الموارد المستمرة -مثل خادم TCP- رد النداء <code>before</code> عدَّة مرات عادةً بينما ستستدعيه الموارد الأخرى -مثل <code>fs.open()</code>‎- مرةً واحدةً.

===== <code>after(asyncId)‎</code> =====
* <code>asyncId</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثل معرِّفًا (ID) فريدًا للمورد غير المتزامن.
يُستدعَى رد النداء <code>after</code> بعد اكتمال رد النداء المحدَّد في <code>before</code> مباشرةً.

إن وقع الاستثناء <code>uncaught</code> خلال تنفيذ رد النداء، فسيُنفَّذ <code>after</code> حينئذ ٍبعد أن يُطلَق الحدث 'uncaughtException' أو ينفَّذ معالج النطاق domain.

===== <code>destroy(asyncId)‎</code> =====
* <code>asyncId</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل معرِّفًا (ID) فريدًا للمورد غير المتزامن.
يستدعى رد النداء <code>destroy</code> بعد تدمير المورد المقابل للمعامل <code>asyncId</code> المعطى. يستدعى أيضًا بشكل غير متزامن من الواجهة البرمجية المُضمِّنَة (embedder) عبر <code>emitDestroy()</code>‎.

تعتمد بعض الموارد على مجموعة المخلفات (garbage collection) المراد مسحها، لذا إن أُنشِئ موردٌ للكائن <code>resource</code> المُمرَّر إلى رد النداء <code>init</code>، فمن المحتمل أن لا يُستدعَى رد النداء <code>destroy</code> مطلقًا محدثًا بذلك تسربًا في الذاكرة ضمن التطبيق. لا يؤخذ هذا الأمر بالحسبان إن لم يكن المورد يعتمد على تلك المخلفات.

===== <code>promiseResolve(asyncId)‎</code> =====
* <code>asyncId</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثل معرِّفًا (ID) فريدًا للمورد غير المتزامن.
يستدعى رد النداء هذا عندما تُستدعَى الدالة <code>resolve()‎</code> المُمرَّرة إلى الكائن [[jQuery/promise|Promise]] الباني (سواءً بشكل مباشر أو عبر طرائق أخرى لاستبيان الكائن [[jQuery/promise|Promise]]).

انتبه إلى أنَّ الدالة <code>resolve()‎</code> لا تجري أي عمل متزامن ملحوظ.

ليس بالضرورة أن يكتمل الكائن [[jQuery/promise|Promise]] أو يُرفَض عند هذه النقطة إن كان قد قُبِلَ بناءً على افتراض حالة معيَّنة لكائن [[jQuery/promise|Promise]] آخر.<syntaxhighlight lang="javascript">
new Promise((resolve) => resolve(true)).then((a) => {});
</syntaxhighlight>استدعِ ردود النداء التالية:<syntaxhighlight lang="javascript">
init for PROMISE with id 5, trigger id: 1
  promise resolve 5      # resolve(true) هذا يقابل
init for PROMISE with id 6, trigger id: 5  # Promise الكائن then() تعيد الدالة
  before 6                     # then() أعطي رد النداء
  promise resolve 6      # promise بدوره الكائن then() يقبل رد النداء 
  after 6
</syntaxhighlight>

==== <code>async_hooks.executionAsyncId()‎</code> ====
أضيفت في الإصدار: v8.1.0

تعيد هذه الدالة العدد <code>asyncId</code> الذي يمثِّل معرفًا فريدًا لسياق التنفيذ الحالي، وهو مفيد في عمليَّة التعقُّب عند استدعاء أي شيء.<syntaxhighlight lang="javascript">
const async_hooks = require('async_hooks');

console.log(async_hooks.executionAsyncId());  // 1 - bootstrap
fs.open(path, 'r', (err, fd) => {
  console.log(async_hooks.executionAsyncId());  // 6 - open()
});

</syntaxhighlight>يتعلق المُعرِّف الذي تعيده الدالة <code>executionAsyncId()‎</code> بوقت التنفيذ وليس بمسبِّباته (استعمل <code>triggerAsyncId()‎</code> من أجل معرفة المسببات):<syntaxhighlight lang="javascript">
const server = net.createServer(function onConnection(conn) {
  // يعاد معرف الخادم وليس الاتصال الجديد لأن 
  // يعمل في مجال onConnection رد النداء
  // MakeCallback() تنفيذ الخادم
  async_hooks.executionAsyncId();

}).listen(port, function onListening() {
  // لأن (process.nextTick() مثل) TickObject يعاد معرف الكائن 
  // nextTick() مغلفةٌ في .listen() جميع ردود النداء المُمرَّرة إلى
  async_hooks.executionAsyncId();
});
</syntaxhighlight>انتبه إلى أنَّ السياق <code>Promise</code> قد لا يجلب قيمة صحيحة للمُعرِّف <code>executionAsyncIds</code> بشكل افتراضي. (انظر قسم "تعقُّب تنفيذ الوعد" اللاحق.)

==== <code>async_hooks.triggerAsyncId()‎</code> ====
تعيد هذه الدالة مُعرِّف المورد المسؤول عن استدعاء رد النداء الذي يُنفَّذ حاليًا.<syntaxhighlight lang="javascript">
const server = net.createServer((conn) => {
  // كان المورد المتسبب في استدعاء رد النداء هذا هو ذلك الاتصال 
  // triggerAsyncId() الجديد. بناءً على ذلك، القيمة التي تعيدها
  // "conn" هي معرف الاتصال
  async_hooks.triggerAsyncId();

}).listen(port, () => {
  // إلا ،nextTick() مغلفةٌ في .listen() رغم أن جميع ردود النداء المُمرَّرة إلى
  // .listen() أنَّ وجود رد النداء نفسه عائد إلى استدعاء الخادم
  // نتيجة لذلك، سيعاد مُعرِّف هذا الخادم
  async_hooks.triggerAsyncId();
});
</syntaxhighlight>انتبه إلى أنَّ السياق <code>Promise</code> قد لا يجلب قيمة صحيحة للمُعرِّف <code>executionAsyncIds</code> بشكل افتراضي. (انظر قسم "تعقب تنفيذ الوعد" اللاحق.)

== تعقب تنفيذ الوعد (Promise execution tracking) ==
لا يُسنَد لتنفيذ الوعد أيًّا من المُعرِّفات <code>asyncId</code> نتيجةً للطبيعة المكلفة لواجهة عمليات التحقُّق الداخلية البرمجيَّة للكائن [[jQuery/promise|Promise]] التي أُوجدَت في الإصدار v8. هذا يعني أنَّ البرامج التي تستعمل الوعود، أو المعامل <code>[[JavaScript/await|await]]</code>، أو <code>[[JavaScript/async function|async]]</code> لن تجلب قيمة صحيحة لمُعرِّفات التنفيذ والاستدعاء لسياق ردود النداء <code>Promise</code> بشكل افتراضي.

إليك هذا المثال:<syntaxhighlight lang="javascript">
const ah = require('async_hooks');
Promise.resolve(1729).then(() => {
  console.log(`eid ${ah.executionAsyncId()} tid ${ah.triggerAsyncId()}`);
});
// :سينتج
// eid 1 tid 0
</syntaxhighlight>لاحظ أنَّ رد النداء <code>then()‎</code> يتطلَّب أن يُنفَّذ في سياق المجال الخارجي (outer scope) رغم وجود عقدة غير متزامنة (asynchronous hop) مشتركة. لاحظ أيضًا أنَّ قيمة المُعرِّف <code>triggerAsyncId</code> هي 0 وهذا يعني أنَّنا نفقد سياقًا عن المورد الذي تسبب في استدعاء رد النداء <code>then()‎</code> لتنفيذه.

إنَّ تثبيت الخطافات غير المتزامنة عبر <code>async_hooks.createHook</code> يُفعِّل تعقُّب تنفيذ الوعد. تفحَّص مثلًا الشيفرة التالية:<syntaxhighlight lang="javascript">
const ah = require('async_hooks');
ah.createHook({ init() {} }).enable(); // رغمًا عنه PromiseHooks يُفعَّل
Promise.resolve(1729).then(() => {
  console.log(`eid ${ah.executionAsyncId()} tid ${ah.triggerAsyncId()}`);
});
// :سينتج
// eid 7 tid 6
</syntaxhighlight>في هذا المثال، إضافة أيَّة دالة خطاف فعليَّة يُفعِّل تعقُّب الوعود. هنالك وعدين في هذا المثال؛ أولهما أنشئ عبر <code>Promise.resolve()</code>‎، وثانيهما أعيد عبر استدعاء <code>then()</code>‎. كانت قيمة المُعرِّف <code>asyncId</code> للوعد الأول هي 6 وللوعد الثاني هي 7. أثناء تنفيذ رد النداء <code>then()</code>‎، كنا نُنفِّذ حينذاك في سياق الوعد الذي يملك القيمة 7 للمُعرِّف <code>asyncId</code>. استُدعِي هذا الوعد عبر المورد 6 غير المتزامن.

أمر آخر متعلق بدقة الوعود هو أنَّ ردي النداء <code>before</code> و <code>after</code> لا ينفذان إلا مع الوعود المتسلسلة (chained promises). هذا يعني أن الوعود التي لا تنشئها الدالة <code>then()‎</code> أو الدالة <code>catch()‎</code> لن يُطلَق معها ردي النداء <code>before</code> و <code>after</code>. للمزيد من المعلومات، راجع تفاصيل الإصدار V8 للواجهة البرمجية <code>PromiseHooks</code>.

== الواجهة البرمجية المُضمِّنة (Embedder API) في JavaScript ==
هي مكتبةٌ للمطورين تسمح لهم بالتعامل مع أداء المهام للموارد غير المتزامنة الخاصَّة بهم مثل المدخلات والمخرجات (I/O)، أو تجمُّع الاتصالات (connection pooling)، أو إدارة طوابير ردود النداء التي قد تتطلب الحاجة إلى استعمال الواجهة البرمجية AsyncWrap من [[JavaScript]] لاستدعاء جميع ردود النداء المناسبة.

=== الصنف AsyncResource ===
صُمِّم الصنف <code>AsyncResource</code> ليكون قابلًا للتوسع بوساطة الموارد المُضمِّنَة (embedder) غير المتزامنة. عند استعماله، يستطيع المستخدمون بسهولة استدعاء الأحداث في أي وقت مع الموارد الخاصَّة بهم.

سيُستدعَى رد النداء <code>init</code> عندما ينشأ نسخةٌ من الصنف <code>AsyncResource</code>. تعطي الشيفرة التالية نظرة عامة عن الواجهة البرمجيَّة <code>AsyncResource</code>:<syntaxhighlight lang="javascript">
const { AsyncResource, executionAsyncId } = require('async_hooks');

// سيُوسَّع. يؤدي إنشاء نسخة جديدة AsyncResource() هذا يعني أنَّ
// إن لم يعطَ المعامل .init إلى استدعاء رد النداء AsyncResource() من
// async_hook.executionAsyncId() فسيستعمل ،triggerAsyncId
const asyncResource = new AsyncResource(
  type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false }
);

// تشغيل دالةٍ في سياق تنفيذ المورد يؤدي إلى
// * إنشاء سياق المورد
// * قبل ردود النداء AsyncHooks استدعاء
// * المعطاة مع الوسائط المتوافرة `fn` استدعاء الدالة
// * بعد ردود النداء AsyncHooks استدعاء
// * استرجاع سياق التنفيذ الأصلي
asyncResource.runInAsyncScope(fn, thisArg, ...args);

// يدمر ردود النداء AsyncHooks استدعاء
asyncResource.emitDestroy();

// AsyncResource إعادة المعرف الفريد المسند للنسخة
asyncResource.asyncId();

// AsyncResource للنسخة (triggerAsyncId أو المعرف ،trigger ID) إعادة معرف الاستدعاء
asyncResource.triggerAsyncId();
</syntaxhighlight>

==== <code>AsyncResource(type[, options])‎</code> ====
* <code>type</code>: ‏[[JavaScript/String|<string>]] سلسلةٌ نصيٌة تمثِّل نوع الحدث غير المتزامن.
* <code>options</code>: ‏[[JavaScript/Object|<Object>]] كائنٌ من النوع Object يحتوي على إحدى الخيارات التالية:
** <code>triggerAsyncId</code>: ‏[[JavaScript/Number|<number>]] عددٌ يمثِّل مُعرِّف سياق التنفيذ الذي أنشأ هذا الحدث غير المتزامن. القيمة الافتراضيَّة هي: <code>executionAsyncId()</code>‎.
** <code>requireManualDestroy</code>: [[JavaScript/Boolean|‏<boolean>]] قيمةٌ منطقيَّةٌ تعطِّل أو تفعِّل <code>emitDestroy</code> تلقائيًّا عندما يُجلَب الكائن من المهملات. لا يُضبَط هذا الخيار عادةً (حتى لو استدعيت <code>emitDestroy</code> يدويًّا) إلا إذا أعيد المُعرِّف <code>asyncId</code> للمورد ثمَّ استُعمِل مع الواجهة البرمجيَّة <code>emitDestroy</code>. القيمة الافتراضيَّة هي: <code>false</code>.
تفحَّص المثال العملي التالي الذي يشرح استعمال هذه الدالة:<syntaxhighlight lang="javascript">
class DBQuery extends AsyncResource {
  constructor(db) {
    super('DBQuery');
    this.db = db;
  }

  getInfo(query, callback) {
    this.db.get(query, (err, data) => {
      this.runInAsyncScope(callback, null, err, data);
    });
  }

  close() {
    this.db = null;
    this.emitDestroy();
  }
}
</syntaxhighlight>

==== <code>asyncResource.runInAsyncScope(fn[, thisArg, ...args])‎</code> ====
أضيفت في الإصدار: v9.6.0
* <code>fn</code>: ‏[[JavaScript/Function|<Function>]] دالةٌ يراد استدعاؤها في سياق التنفيذ لهذا المورد المتزامن.
* <code>thisArg</code>: ‏<any> أيُّ نوعٍ من أنواع بيانات [[JavaScript]]، ويمثِّل المُستقبِل (recever) المراد استخدامه مع استدعاء الدالة.
* <code>...args</code>: ‏<any> أي نوع من أنواع بيانات [[JavaScript]]، ويمثِّل الوسائط الإضافيَّة المراد تمريرها إلى الدالة.
تفحَّص المثال العملي التالي الذي يشرح استعمال هذه الدالة:<syntaxhighlight lang="javascript">
class DBQuery extends AsyncResource {
  constructor(db) {
    super('DBQuery');
    this.db = db;
  }

  getInfo(query, callback) {
    this.db.get(query, (err, data) => {
      this.runInAsyncScope(callback, null, err, data);
    });
  }

  close() {
    this.db = null;
    this.emitDestroy();
  }
}
</syntaxhighlight>

==== <code>asyncResource.runInAsyncScope(fn[, thisArg, ...args])‎</code> ====
أضيفت في الإصدار: v9.6.0
* <code>fn</code>: ‏[[JavaScript/Function|<Function>]] دالةٌ يراد استدعاؤها في سياق تنفيذ هذا المورد غير المتزامن.
* <code>thisArg</code>: ‏<any> أيُّ نوعٍ من أنواع بيانات [[JavaScript]]، ويمثِّل المُستقبِل (recever) المراد استخدامه مع استدعاء الدالة.
* <code>...args</code>: ‏<any> أي نوع من أنواع بيانات [[JavaScript]]، ويمثِّل الوسائط الإضافيَّة المراد تمريرها إلى الدالة.
تستدعي هذه الدالةُ الدالةَ المُمرَّرة إليها مع الوسائط المعطاة في سياق التنفيذ للمورد غير المتزامن. هذا سيؤدي إلى إنشاء السياق، ثمَّ إطلاق <code>AsyncHooks</code> قبل ردود النداء، ثمَّ استدعاء الدالة، ثمَّ إطلاق <code>AsyncHooks</code> بعد ردود النداء، ثمَّ استعادة سياق التنفيذ الأصلي.

==== <code>asyncResource.emitBefore()‎</code> ====
أهملت منذ الإصدار: v9.6.0

الاستقرار: 0-مهمل: استعمل الدالة <code>asyncResource.runInAsyncScope()‎</code> عوضًا عنها.

تستدعي هذه الدالة جميع ردود النداء <code>before</code> للتنبيه ببدء إنشاء سياق تنفيذ جديد. إن استُدعيَت <code>emitBefore()‎</code> عدة مرات، فسيُتعقَّب المُعرِّفات <code>asyncId</code> في المكدس وسيُتخلَّص منها بالترتيب الذي استُدعيَت به.

يجب إزالة ردي النداء <code>before</code> و <code>after</code> بنفس الترتيب الذي استدعيا به وإلا سيًطلَق استثناء لا يمكنك إصلاحه، وستُوقف العمليَّة حينذاك. لهذا السبب، أهملت الواجهتان البرمجيتان <code>emitBefore</code> و <code>emitAfter</code>. استعمل رجاءً الدالة <code>runInAsyncScope</code> عوضًا عن هذه الدالة فهي أكثر أمانًا.

==== <code>asyncResource.emitAfter()‎</code> ====
أهملت منذ الإصدار: v9.6.0

الاستقرار: 0-مهمل: استعمل الدالة <code>asyncResource.runInAsyncScope()‎</code> عوضًا عنها.

تستدعي هذه الدالة جميع ردود النداء <code>after</code>. إن استُدعيَت <code>emitAfter()‎</code> عدَّة مرات بطريقة متشعِّبة، فسيُتعقَّب المُعرِّفات <code>asyncId</code> في المكدس وسيُتخلَّص منها بالترتيب الذي استدعيت به.

إن رَمَت ردود نداء المستخدم استثناءً، فستُستدعى <code>emitAfter()‎</code> تلقائيًّا مع جميع المُعرِّفات <code>asyncIds</code> الموجودة في المكدس إن تمت معالجة الخطأ عبر معالج النطاق (domain handler) أو المعالج 'uncaughtException'.

يجب إزالة ردي النداء <code>before</code> و <code>after</code> بنفس الترتيب الذي استدعيا به وإلا سيُطلَق استثناءٌ لا يمكنك إصلاحه، وستُوقف العمليَّة. لهذا السبب، أهملت الواجهتان البرمجيتان <code>emitBefore</code> و <code>emitAfter</code>. استعمل رجاءً الدالة <code>runInAsyncScope</code> عوضًا عن هذه الدالة فهي أكثر أمانًا.

==== <code>asyncResource.emitDestroy()‎</code> ====
تستدعي هذه الدالة جميع الخطافات <code>destroy</code>. يجب استدعاؤها مرةً واحدةً فقط يدويًّا، وسيُرمى خطأٌ إن استدعيت أكثر من ذلك. إن تُرِكَ المورد ليُجمَّع عبر مُجمِّع المهملات (garbage collection، ويدعى اختصارًا GC)، فلن تُستدعَى الخطافات <code>destroy</code> حينها.

==== <code>asyncResource.asyncId()‎</code> ====
تعيد هذه الدالة عددًا يمثِّل المُعرِّف <code>asyncId</code> الفريد المُسنَد إلى المورد.

==== <code>asyncResource.triggerAsyncId()‎</code> ====
تعيد هذه الدالة عددًا يمثِّل المُعرِّف <code>triggerAsyncId</code> نفسه الذي مُرِّر إلى الصنف <code>AsyncResource</code> الباني.

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