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

{{DISPLAYTITLE:الوحدة Timer في Node.js}}
توفر الوحدة <code>timer</code> واجهة برمجيّة (API) عامة (global) لجدولة (scheduling) الدوال، مما يُمكِّن استدعاءها في فترة مستقبليّة معينة. لا حاجة لاستيراد الوحدة عبر الدالة <code>require('timers')‎‎</code> لاستخدام الواجهة البرمجيّة؛ وذلك لكون دوال المكتبة عامة.

تصنَع دوال المؤقتات (timers)، في Node.js، واجهة برمجيّة مشابهة لتلك الموجودة في مُتصفحات الويب ولكن باستخدام بنيّة داخليّة مُختلفة مبنيّة اعتمادًا على تقنيّة حلقة الأحداث (Event Loop).

== الصنف <code>Immediate</code> ==
ينشَأ هذا الكائن داخليًا ويُعاد من الدالة <code>[[Node.js/timers#setImmediate.28callback.5B.2C ...args.5D.29.E2.80.8E|‎setImmediate()‎]]</code>. يُمكِن تمرير هذا الكائِن إلى الدالة <code>[[Node.js/timers#clearImmediate.28immediate.29.E2.80.8E|clearImmediate()‎‎]]</code> لإلغاء الأحداث المُجدولة.

ستستمر حلقة الأحداث بالعمل، افتراضيًا عند جدولة الكائِن <code>immediate</code>، طالما هذا الكائِن فعّال. يُصدِّر الكائِن <code>Immediate</code>، الذي ترجعه الدالة <code>[[Node.js/timers#setImmediate.28callback.5B.2C ...args.5D.29.E2.80.8E|‎setImmediate()‎]]</code>، التابعين <code>immediate.ref()‎‎‎</code> و <code>‎immediate.unref()‎</code> الذين يُمكِن استخدامهما للتحكم بهذا السلوك الافتراضي.

=== <code>immediate.ref()‎</code> ===
<small>أُضيفَ في الإصدار 9.7.0</small>
* القيمة المعادة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Immediate|<Immediate>]]، مرجع للصنف <code>immediate</code>.
يطلب التابع، عند استدعاءه، استمرار حلقة الأحداث طالما أنَّ الصنف <code>Immediate</code> نشط. لن يُحدِث استدعاء هذا التابع عدّة مرّات أثرًا.

يعمل هذا الصنف، تلقائيًا وافتراضيًا، على جميع الكائِنات من النوع <code>Immediate</code>، ما يعني أنَّه لا ضرورة لاستدعاء التابع <code>Immediate.ref()‎</code> ما لم يُستدعَ التابع <code>Immediate.unref()‎‎</code> قبله.

=== <code>immediate.unref()‎</code> ===
<small>أُضيفَ في الإصدار 9.7.0</small>
* القيمة المعادة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Immediate|<Immediate>]]، مرجع (reference) للصنف <code>immediate</code>.
يسحب التابع، عند استدعاءه، طلبه باستمرار حلقة الأحداث طالما أنَّ الصنف <code>Immediate</code> نشط. قد تتوقف حلقة الأحداث، في حال عدم وجود نشاطات أخرى تتطلَّب استمرار عملها، قبل استدعاء الدالة المقرونة بكائِن المؤقت (المُعامِل <code>callback</code>). لن يُحدِث استدعاء هذا التابع عدّة مرّات أثرًا.

== الصنف <code>Timeout</code> ==
ينشَأ هذا الكائن داخليًا ويُعاد من الدالة <code>[[Node.js/timers#setTimeout.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setTimeout()‎]]</code> و <code>[[Node.js/timers#setInterval.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setInterval()‎]]</code>. يُمكِن تمرير هذا الكائِن إلى الدالة <code>[[Node.js/timers#clearTimeout.28timeout.29.E2.80.8E|clearTimeout()‎‎]]</code> أو <code>[[Node.js/timers#clearInterval.28timeout.29.E2.80.8E|clearInterval()‎‎]]</code> لإلغاء العمليات المُجدولة. ستستمر حلقة الأحداث بالعمل، افتراضيًا عند جدولة المؤقت بأحد التابعين السالف ذكرهما (<code>setTimeout()‎</code> و <code>()setInterval</code>)، طالما أنَّ المؤقِّت نشطٌ. يُصدِّر الكائِن <code>Timeout</code> التابعين <code>timeout.ref()‎‎‎</code> و <code>timeout.unref()‎</code> الذين يُمكِن استخدامهما للتحكم بهذا السلوك الافتراضي.

=== <code>timeout.ref()‎</code> ===
<small>أُضيفَ في الإصدار 0.9.1</small>
* القيمة المعادة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]]، مرجِع للصنف <code>timeout</code>.
يطلب التابع، عند استدعاءه، استمرار حلقة الأحداث طالما أنَّ الصنف <code>Timeout</code> نشطٌ. لن يُحدِث استدعاء هذا التابع عدّة مرّات أثرًا.

يعمل هذا الصنف، تلقائيًا وافتراضيًا، على جميع الكائِنات من النوع <code>Timeout</code>، ما يعني أنَّه لا ضرورة لاستدعاء التابع <code>timeout.ref()‎</code> ما لم يُستدعَ التابع <code>timeout.unref()‎‎</code> قبله.

=== <code>timeout.refresh()‎</code> ===
<small>أُضيفَ في الإصدار 10.2.0</small>
* القيمة المعادة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]]، مرجِع للصنف <code>timeout</code>.
يُعيّن التابِع وقت بدء المؤقت إلى الوقت الحالي، ويُعيد جدولة المؤقت ليستدعي دالة رد النداء عند حلول وقت البدء الجديد. استخدام هذا التابع مُفيد لاستحداث مؤقت دون الحاجة لحجز كائن JavaScript جديد.

استخدام هذا التابع على مؤقت اُستدعيت الدالة المقرونة به يؤدي إلى إعادة تنشيط المؤقت مرَّة أخرى.

=== <code>timeout.unref()‎</code> ===
<small>أُضيفَ في الإصدار 0.9.1</small>
* القيمة المعادة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]]، مرجع (reference) للصنف <code>timeout</code>.
يسحب التابع، عند استدعاءه، طلبه باستمرار حلقة الأحداث طالما أنَّ الصنف <code>Immediate</code> نشط. قد تتوقف حلقة الأحداث، في حال عدم وجود نشاطات أخرى تتطلَّب استمرار عملها، قبل استدعاء الدالة المقرونة بكائِن المؤقت (المُعامِل <code>callback</code>). لن يُحدِث استدعاء هذا التابع عدّة مرّات أثرًا.

يُنشئ استدعاء التابِع <code>timeout.unref()‎</code> مؤقتًا داخليًا يُنبِّه حلقة أحداث Node.js. إنشاء الكثير من هذه المُنبِّهات، التي يُنشِئُها استدعاء هذا التابِع، قد يؤثر سلبًا على أداء البرمجيّة.

== جدولة المؤقتات ==
المؤقت في Node.js هو عبارة عن بناء داخلي يستدعي دالة مُمرَّرة له بعض فترة زمنيّة مُعينة. يختلف موعد استدعاء دالة المؤقت بناءً على الطريقة المُستخدمة لإنشاءه والأعمال التي تقوم بها حلقة الأحداث.

=== <code>setImmediate(callback[, ...args])‎</code> ===
<small>أُضيفَ في الإصدار 0.9.1</small>
* <code>callback</code> من النوع [[JavaScript/Function|<Function>]]: الدالة التي ستُستدعى في نهاية الدورة الحالية لحلقة الأحداث.
* <code>args...</code> من النوع [[JavaScript#.D8.A7.D9.84.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.B9.D8.A7.D9.85.D8.A9|<any>]]: مُعطيات ستُمرَّر للمُعامِل <code>callback</code> عندما يُستدعى (مُعامِل اختياري).

* القيمة المعادة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Immediate|<Immediate>]] لاستخدامه مع التابع <code>[[Node.js/timers#clearImmediate.28immediate.29.E2.80.8E|clearImmediate()‎]]</code>.
يُجدول التابِع تنفيذ المُعامِل <code>callback</code> بعد تنفيذ أحداث الإدخال والإخراج (I/O events' callbacks) في حلقة الأحداث.

عند استدعاء الدالة <code>setImmediate()‎</code> عدّة مرَّات، يتم صَف الدوال في المعاملات <code>callback</code> في طابور التنفيذ بالترتيب الذي أُنشِئت به. يُعالَج طابور التنفيذ (الذي يحوي جميع دوال رد النداء) بكامله في كل دورة لحلقة الأحداث. إذا وُجِد مؤقت فوري (immediate timer) بداخل آخر قيد التنفيذ، لن يُنفَّذ حتّى قدوم الدورة التالية من حلقة الأحداث.

سيَصدُر الخطأ <code>[[JavaScript/TypeError|TypeError]]</code> في حال لم تُمرَّر دالة للمُعامِل <code>callback</code>.

يتعامل التابع بطريقة مخصَّصة مع الوعود (promises) المُنشأة بواسطة التابع <code>()util.promisify</code>:<syntaxhighlight lang="javascript">
const util = require('util');
const setImmediatePromise = util.promisify(setImmediate);

setImmediatePromise('foobar').then((value) => {
 // value === 'foobar' (تمرير القيم أمر اختياري)
‎‎// ستُنفَّذ الشيفرة هنا بعد جميع أحداث الإدخال والإخراج
});


‎‎// أو باستخدام الدوال الغير متزامنة
async function timerExample() {
  console.log('Before I/O callbacks');
  await setImmediatePromise();
  console.log('After I/O callbacks');
}
timerExample();
</syntaxhighlight>

=== <code>setInterval(callback, delay[, ...args])‎</code> ===
<small>أُضيفَ في الإصدار 0.0.1</small>
* <code>callback</code> من النوع [[JavaScript/Function|<Function>]]: الدالة التي سيتم استدعاؤها في نهاية الدورة الحالية لحلقة الأحداث.
* <code>delay</code> من النوع [[JavaScript/Number|<number>]]: الفترة الزمنيّة (مُقاسة بالمِلِّي ثانية) الُمنتظرة قبل تنفيذ الدالة المُمرَّرة للمُعامِل <code>callback</code>.
* <code>args...</code> من النوع [[JavaScript#.D8.A7.D9.84.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.B9.D8.A7.D9.85.D8.A9|<any>]]: مُعطيات ستُمرَّر للمُعامِل <code>callback</code> عندما يُستدعى (مُعامِل اختياري).

* القيمة المُرجعة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]] لاستخدامه مع التابع <code>[[Node.js/timers#clearInterval.28timeout.29.E2.80.8E|clearInterval()‎]]</code>.
يُجدول التابِع تنفيذ المُعامِل <code>callback</code> بشكل مُتكرِّر كل <code>delay</code> (الفترة الزمنيّة المُمرَّرة للمُعامِل).

تُحال قيمة المُعامِل <code>delay</code> إلى <code>1</code> في حال كانت قيمته أكبر من <code>2147483647</code> أو أصغر من <code>1</code>.

سيَصدُر الخطأ <code>[[JavaScript/TypeError|TypeError]]</code> في حال لم تُمرَّر دالة للمُعامِل <code>callback</code>.

=== <code>setTimeout(callback, delay[, ...args])‎</code> ===
<small>أُضيفَ في الإصدار 0.0.1</small>
* <code>callback</code> من النوع [[JavaScript/Function|<Function>]]: الدالة التي سيتم استدعاؤها في نهاية الدورة الحالية لحلقة الأحداث.
* <code>delay</code> من النوع [[JavaScript/Number|<number>]]: الفترة الزمنيّة (مُقاسة بالمِلِّي ثانية) الُمنتظرة قبل تنفيذ الدالة المُمرَّرة للمُعامِل <code>callback</code>.
* <code>args...</code> من النوع [[JavaScript#.D8.A7.D9.84.D9.83.D8.A7.D8.A6.D9.86.D8.A7.D8.AA .D8.A7.D9.84.D8.B9.D8.A7.D9.85.D8.A9|<any>]]: مُعطيات ستُمرَّر للمُعامِل <code>callback</code> عندما يُستدعى (مُعامِل اختياري).

* القيمة المُرجعة: الكائِن [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]] لاستخدامه مع التابع <code>[[Node.js/timers#clearTimeout.28timeout.29.E2.80.8E|clearTimeout()‎]]</code>.
يُجدول التابِع تنفيذ المُعامِل <code>callback</code> مرَّة واحدة بعد مرور <code>delay</code> (الفترة الزمنيّة المُمرَّرة للمُعامِل).

من المُحتمَل ألّا تُستدعى الدالة في الوقت المُحدَّد تمامًا. لا توفر Node.js أيّة ضمانات حول الوقت أو الترتيب الذي تُنفَّذ فيه الدوال. ستُستدعى الدالة المجدولة بأقرب وقت مُمكِن للوقت المُحدَّد.

تُحال قيمة المُعامِل <code>delay</code> إلى <code>1</code> في حال كانت قيمته أكبر من <code>2147483647</code> أو أصغر من <code>1</code>.

سيَصدُر الخطأ <code>[[JavaScript/TypeError|TypeError]]</code> في حال لم تُمرَّر دالة للمُعامِل <code>callback</code>.

يتعامل التابع بطريقة مخصَّصة مع الوعود (promises) المُنشأة بواسطة التابع <code>()util.promisify</code>:<syntaxhighlight lang="javascript">
‎‎const util = require('util');
const setTimeoutPromise = util.promisify(setTimeout);

setTimeoutPromise(40, 'foobar').then((value) => {
  // value === 'foobar' (تمرير القيم أمر اختياري)
 ‎‎// ستُنفَّذ الشيفرة هنا بعد حوالي 40 مِلِّي ثانية
});
</syntaxhighlight>

== إلغاء المؤقتات ==
تعيد كل من التوابع <code>[[Node.js/timers#setImmediate.28callback.5B.2C ...args.5D.29.E2.80.8E|setImmediate()‎‎]]</code> و [[Node.js/timers#setInterval.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|‎<code>setInterval()‎</code>]] و <code>[[Node.js/timers#setTimeout.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setTimeout()‎‎]]</code> كائنًا يُمثِّل مؤقِتًا. يُمكن استخدام هذه الكائنات لإلغاء المؤقت ومنع استدعائه.

لا يُمكِن إلغاء مؤقت أُنشِئ باستخدام نسخة الوعود من <code>[[Node.js/timers#setImmediate.28callback.5B.2C ...args.5D.29.E2.80.8E|‎‎setImmediate()‎]]</code> و ‎<code>[[Node.js/timers#setTimeout.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setTimeout()‎]]</code>.

=== <code>clearImmediate(immediate)‎</code> ===
<small>أُضيفَ في الإصدار 0.9.1</small>
* <code>immediate</code> [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Immediate|<Immediate>‎‎]]: كائن من النوع <code>Immediate</code> مُعاد بواسطة التابع <code>‎[[Node.js/timers#setImmediate.28callback.5B.2C ...args.5D.29.E2.80.8E|setImmediate()‎]]</code>.
يُلغي التابِع كائن مؤقِت من النوع <code>Immediate</code> مُنشأ بواسطة التابع <code>‎[[Node.js/timers#setImmediate.28callback.5B.2C ...args.5D.29.E2.80.8E|setImmediate()‎]]</code>.

=== <code>clearInterval(timeout)‎</code> ===
<small>أُضيفَ في الإصدار 0.0.1</small>
* <code>timeout</code> [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]]‎‎: كائن من النوع <code>Timeout</code> مُعاد بواسطة التابع <code>[[Node.js/timers#setInterval.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setInterval()‎]]</code>.
يُلغي التابِع كائن مؤقِت من النوع <code>Timeout</code> مُنشأ بواسطة التابع <code>[[Node.js/timers#setInterval.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setInterval()‎]]</code>.

=== <code>clearTimeout(timeout)‎</code> ===
<small>أُضيفَ في الإصدار 0.0.1</small>
* <code>timeout</code> [[Node.js/timers#.D8.A7.D9.84.D8.B5.D9.86.D9.81 Timeout|<Timeout>]]‎‎: كائن من النوع <code>Timeout</code> مُعاد بواسطة التابع <code>[[Node.js/timers#setTimeout.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setTimeout()‎]]</code>.
يُلغي التابِع كائن مؤقِت من النوع <code>Timeout</code> مُنشأ بواسطة التابع <code>[[Node.js/timers#setTimeout.28callback.2C delay.5B.2C ...args.5D.29.E2.80.8E|setTimeout()‎]]</code>.

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