المؤقتات

[مستقر: 2 - مستقر]

مستقر: 2 استقرار: 2 - مستقر

رمز المصدر: lib/timers.js

يعرض مُودول timer واجهة برمجة تطبيقات عالمية لجدولة وظائف تُدعى في فترة زمنية مستقبلية. نظرًا لأن وظائف المؤقتات هي وظائف عالمية، فلا داعي لاستدعاء require('node:timers') لاستخدام واجهة البرمجة التطبيقات.

تقوم وظائف المؤقتات داخل Node.js بتنفيذ واجهة برمجة تطبيقات مشابهة لواجهة برمجة تطبيقات المؤقتات التي توفرها متصفحات الويب، ولكنها تستخدم تنفيذًا داخليًا مختلفًا مبنيًا حول حلقة الأحداث في Node.js حلقة الأحداث.

الفئة: Immediate

يُنشأ هذا الكائن داخليًا ويتم إرجاعه من setImmediate(). يمكن تمريره إلى clearImmediate() لإلغاء الإجراءات المجدولة.

بشكل افتراضي، عند جدولة أمر فوري، ستستمر حلقة أحداث Node.js في العمل طالما أن الأمر الفوري نشط. يُصدر كائن Immediate الذي يُرجعه setImmediate() كل من وظيفتي immediate.ref() و immediate.unref() اللتين يمكن استخدامهما للتحكم في هذا السلوك الافتراضي.

immediate.hasRef()

مضاف في: v11.0.0

• المُرجَع: <boolean>

إذا كان صحيحًا، فسيبقي كائن Immediate حلقة أحداث Node.js نشطة.

immediate.ref()

مضاف في: v9.7.0

• المُرجَع: <Immediate> مرجع إلى immediate

عند استدعائه، يطلب ألا تخرج حلقة أحداث Node.js طالما أن Immediate نشط. لن يكون لاستدعاء immediate.ref() عدة مرات أي تأثير.

بشكل افتراضي، كل كائنات Immediate "مرجعية"، مما يجعل من غير الضروري عادةً استدعاء immediate.ref() إلا إذا تم استدعاء immediate.unref() مسبقًا.

immediate.unref()

مضاف في: v9.7.0

• الإرجاع: <Immediate> مرجع إلى immediate

عند استدعائه، لن يحتاج كائن Immediate النشط إلى بقاء حلقة أحداث Node.js نشطة. إذا لم يكن هناك نشاط آخر يحافظ على تشغيل حلقة الأحداث، فقد يخرج البرنامج قبل استدعاء دالة الاستدعاء الخاصة بكائن Immediate. لن يكون لاستدعاء immediate.unref() عدة مرات أي تأثير.

immediate[Symbol.dispose]()

مضاف في: v20.5.0، v18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

يلغي الفوري. هذا مشابه لاستدعاء clearImmediate().

الصف: Timeout

يتم إنشاء هذا الكائن داخليًا ويتم إرجاعه من setTimeout() و setInterval(). يمكن تمريره إلى clearTimeout() أو clearInterval() من أجل إلغاء الإجراءات المجدولة.

بشكل افتراضي، عند جدولة مؤقت باستخدام setTimeout() أو setInterval()، ستستمر حلقة أحداث Node.js في التشغيل طالما كان المؤقت نشطًا. كل كائن Timeout الذي تُرجعه هذه الدوال يُصدر كل من دالتي timeout.ref() و timeout.unref() اللتين يمكن استخدامهما للتحكم في هذا السلوك الافتراضي.

timeout.close()

مضاف في: v0.9.1

[مستقر: 3 - تراثي]

مستقر: 3 الثبات: 3 - تراثي: استخدم clearTimeout() بدلاً من ذلك.

• الإرجاع: <Timeout> مرجع إلى timeout

يلغي مهلة الوقت.

timeout.hasRef()

مضاف في: v11.0.0

• الإرجاع: <boolean>

إذا كان صحيحًا، فسيكون كائن Timeout الحفاظ على حلقة أحداث Node.js نشطة.

timeout.ref()

مُضاف في: v0.9.1

• مُخرجات: <Timeout> مرجع إلى timeout

عند استدعائه، يطلب من حلقة أحداث Node.js عدم الخروج طالما أن Timeout نشط. لن يكون لاستدعاء timeout.ref() عدة مرات أي تأثير.

بشكل افتراضي، يتم "إحالة" جميع كائنات Timeout، مما يجعل من غير الضروري عادةً استدعاء timeout.ref() إلا إذا تم استدعاء timeout.unref() مسبقًا.

timeout.refresh()

مُضاف في: v10.2.0

• مُخرجات: <Timeout> مرجع إلى timeout

يُعيّن وقت بدء المُؤقّت إلى الوقت الحالي، ويعيد جدولة المُؤقّت لاستدعاء دالة الاستدعاء الخاصة به عند المدة المحددة سابقًا المُعدّلة وفقًا للوقت الحالي. هذا مفيد لتحديث مؤقت دون تخصيص كائن JavaScript جديد.

سيؤدي استخدام هذا في مؤقت قام بالفعل باستدعاء دالة الاستدعاء الخاصة به إلى إعادة تنشيط المؤقت.

timeout.unref()

مُضاف في: v0.9.1

• مُخرجات: <Timeout> مرجع إلى timeout

عند استدعائه، لن يتطلب كائن Timeout النشط بقاء حلقة أحداث Node.js نشطة. إذا لم تكن هناك أي أنشطة أخرى تحافظ على تشغيل حلقة الأحداث، فقد يخرج البرنامج قبل استدعاء دالة الاستدعاء لكائن Timeout. لن يكون لاستدعاء timeout.unref() عدة مرات أي تأثير.

timeout[Symbol.toPrimitive]()

مُضاف في: v14.9.0، v12.19.0

• مُخرجات: <integer> رقم يمكن استخدامه للإشارة إلى هذا timeout

إجبار Timeout على بدائي. يمكن استخدام البدائي لمسح Timeout. لا يمكن استخدام البدائي إلا في نفس الخيط الذي تم فيه إنشاء المؤقت. لذلك، لاستخدامه عبر worker_threads يجب أولاً تمريره إلى الخيط الصحيح. هذا يسمح بتوافق محسّن مع تنفيذات setTimeout() و setInterval() الخاصة بالمتصفح.

timeout[Symbol.dispose]()

مُضاف في: v20.5.0، v18.18.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

يلغي المؤقت.

جدولة المؤقتات

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

setImmediate(callback[, ...args])

[السجل]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُنادٍ غير صحيح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v0.9.1	أُضيف في: v0.9.1

• callback <Function> الدالة التي سيتم مناداته في نهاية هذه الدورة من حلقة أحداث Node.js حلقة الأحداث
• ...args <any> وسيطات اختيارية لتمريرها عند مناداة callback.
• القيمة المُرجعة: <Immediate> للاستخدام مع clearImmediate()

يُحدّد التنفيذ "الفوري" لـ callback بعد مُناديات أحداث I/O.

عندما يتم إجراء العديد من المُناديات لـ setImmediate()، يتم وضع دوال callback في قائمة الانتظار للتنفيذ بالترتيب الذي تم إنشاؤها به. تتم معالجة قائمة الانتظار بأكملها في كل تكرار لحلقة الأحداث. إذا تم وضع مؤقّت فوري من داخل مُنادٍ قيد التنفيذ، فلن يتم تشغيل هذا المؤقّت حتى تكرار حلقة الأحداث التالي.

إذا لم تكن callback دالة، فسيتم إلقاء TypeError.

تتميز هذه الطريقة بمتغيّر مخصص للوعود، وهو متوفر باستخدام timersPromises.setImmediate().

setInterval(callback[, delay[, ...args]])

[السجل]

الإصدار	التغييرات
v18.0.0	يُلقي تمرير مُنادٍ غير صحيح إلى وسيطة callback الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v0.0.1	أُضيف في: v0.0.1

• callback <Function> الدالة التي سيتم مناداته عند انقضاء المؤقّت.
• delay <number> عدد ميلي ثانية الانتظار قبل مناداة callback. الافتراضي: 1.
• ...args <any> وسيطات اختيارية لتمريرها عند مناداة callback.
• القيمة المُرجعة: <Timeout> للاستخدام مع clearInterval()

يُحدّد التنفيذ المُتكرّر لـ callback كلّ delay ميلي ثانية.

عندما يكون delay أكبر من 2147483647 أو أقل من 1 أو NaN، سيتم تعيين delay إلى 1. يتم تقريب التأخيرات غير الصحيحة إلى عدد صحيح.

إذا لم تكن callback دالة، فسيتم إلقاء TypeError.

تتميز هذه الطريقة بمتغيّر مخصص للوعود، وهو متوفر باستخدام timersPromises.setInterval().

setTimeout(callback[, delay[, ...args]])

[History]

الإصدار	التغييرات
v18.0.0	تمرير مُدعًى غير صالح إلى وسيطة callback يُلقِ الآن ERR_INVALID_ARG_TYPE بدلاً من ERR_INVALID_CALLBACK.
v0.0.1	تمت الإضافة في: v0.0.1

• callback <Function> الدالة التي سيتم استدعاؤها عند انتهاء المؤقت.
• delay <number> عدد ميلي ثانية الانتظار قبل استدعاء callback. الافتراضي: 1.
• ...args <any> وسيطات اختيارية لإرسالها عند استدعاء callback.
• القيمة المُرجعة: <Timeout> للاستخدام مع clearTimeout()

يُحدد جدولة تنفيذ callback لمرة واحدة بعد delay ميلي ثانية.

من المحتمل ألا يتم استدعاء callback بدقة في delay ميلي ثانية. لا تقدم Node.js أي ضمانات حول التوقيت الدقيق لاستدعاء المُدعيات، أو حول ترتيبها. سيتم استدعاء المُدعى أقرب ما يكون إلى الوقت المحدد.

عندما يكون delay أكبر من 2147483647 أو أقل من 1 أو NaN، سيتم تعيين delay إلى 1. يتم اقتطاع التأخيرات غير الصحيحة إلى عدد صحيح.

إذا لم تكن callback دالة، فسيتم رمي TypeError.

تحتوي هذه الطريقة على متغير مخصص للوعد متاح باستخدام timersPromises.setTimeout().

إلغاء المؤقتات

كل من طرق setImmediate()، وsetInterval()، وsetTimeout() تُرجع كائنات تمثل المؤقتات المجدولة. يمكن استخدام هذه لإلغاء المؤقت ومنعه من التشغيل.

بالنسبة للنسخ المُعدّة للوعد من setImmediate() و setTimeout()، يمكن استخدام AbortController لإلغاء المؤقت. عند إلغائه، سيتم رفض الوعود المُرجعة مع 'AbortError'.

بالنسبة إلى setImmediate():

ESM

import { setImmediate as setImmediatePromise } from 'node:timers/promises'

const ac = new AbortController()
const signal = ac.signal

// نحن لا ننتظر الوعد حتى يتم استدعاء `ac.abort()` بالتزامن.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('تم إلغاء الفوري')
  })

ac.abort()

CJS

const { setImmediate: setImmediatePromise } = require('node:timers/promises')

const ac = new AbortController()
const signal = ac.signal

setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('تم إلغاء الفوري')
  })

ac.abort()

بالنسبة إلى setTimeout():

ESM

import { setTimeout as setTimeoutPromise } from 'node:timers/promises'

const ac = new AbortController()
const signal = ac.signal

// نحن لا ننتظر الوعد حتى يتم استدعاء `ac.abort()` بالتزامن.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('تم إلغاء مهلة الوقت')
  })

ac.abort()

CJS

const { setTimeout: setTimeoutPromise } = require('node:timers/promises')

const ac = new AbortController()
const signal = ac.signal

setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('تم إلغاء مهلة الوقت')
  })

ac.abort()

clearImmediate(immediate)

مضاف في: v0.9.1

• immediate <Immediate> كائن Immediate كما تم إرجاعه بواسطة setImmediate().

يلغي كائن Immediate تم إنشاؤه بواسطة setImmediate().

clearInterval(timeout)

مضاف في: v0.0.1

• timeout <Timeout> | <string> | <number> كائن Timeout كما تم إرجاعه بواسطة setInterval() أو البدائي لكائن Timeout كسلسلة أو رقم.

يلغي كائن Timeout تم إنشاؤه بواسطة setInterval().

clearTimeout(timeout)

مضاف في: v0.0.1

• timeout <Timeout> | <string> | <number> كائن Timeout كما تم إرجاعه بواسطة setTimeout() أو البدائي لكائن Timeout كسلسلة أو رقم.

يلغي كائن Timeout تم إنشاؤه بواسطة setTimeout().

واجهة برمجة تطبيقات وعود المؤقتات

[السجل]

الإصدار	التغييرات
v16.0.0	تمّت ترقيته من تجريبي.
v15.0.0	مضاف في: v15.0.0

توفر واجهة برمجة تطبيقات timers/promises مجموعة بديلة من وظائف المؤقتات التي تُرجع كائنات Promise. يمكن الوصول إلى واجهة برمجة التطبيقات عبر require('node:timers/promises').

ESM

import { setTimeout, setImmediate, setInterval } from 'node:timers/promises'

CJS

const { setTimeout, setImmediate, setInterval } = require('node:timers/promises')

timersPromises.setTimeout([delay[, value[, options]]])

أضيف في: v15.0.0

• delay <number> عدد ميلي ثانية الانتظار قبل تحقيق الوعد. الافتراضي: 1.
• value <any> قيمة يتم بها تحقيق الوعد.
• options <Object>
  • ref <boolean> ضبط على false للإشارة إلى أن Timeout المجدول لا يتطلب بقاء حلقة حدث Node.js نشطة. الافتراضي: true.
  • signal <AbortSignal> AbortSignal اختياري يمكن استخدامه لإلغاء Timeout المجدول.

ESM

import { setTimeout } from 'node:timers/promises'

const res = await setTimeout(100, 'result')

console.log(res) // يطبع 'result'

CJS

const { setTimeout } = require('node:timers/promises')

setTimeout(100, 'result').then(res => {
  console.log(res) // يطبع 'result'
})

timersPromises.setImmediate([value[, options]])

أضيف في: v15.0.0

• value <any> قيمة يتم بها تحقيق الوعد.
• options <Object>
  • ref <boolean> ضبط على false للإشارة إلى أن Immediate المجدول لا يتطلب بقاء حلقة حدث Node.js نشطة. الافتراضي: true.
  • signal <AbortSignal> AbortSignal اختياري يمكن استخدامه لإلغاء Immediate المجدول.

ESM

import { setImmediate } from 'node:timers/promises'

const res = await setImmediate('result')

console.log(res) // يطبع 'result'

CJS

const { setImmediate } = require('node:timers/promises')

setImmediate('result').then(res => {
  console.log(res) // يطبع 'result'
})

timersPromises.setInterval([delay[, value[, options]]])

مضاف في: v15.9.0

يرجع مُكررًا غير متزامن يُولّد قيمًا على فترات زمنية قدرها delay مللي ثانية. إذا كانت ref تساوي true، فأنت بحاجة إلى استدعاء next() من المُكرر غير المتزامن صراحةً أو ضمناً لإبقاء حلقة الحدث نشطة.

• delay <number> عدد مللي الثواني التي يجب الانتظارها بين التكرارات. الافتراضي: 1.
• value <any> قيمة يُعيد المُكرر بها.
• options <Object>
  • ref <boolean> يُعيّن إلى false للإشارة إلى أن Timeout المُجدول بين التكرارات لا يتطلب بقاء حلقة حدث Node.js نشطة. الافتراضي: true.
  • signal <AbortSignal> AbortSignal اختياري يمكن استخدامه لإلغاء Timeout المُجدول بين العمليات.

ESM

import { setInterval } from 'node:timers/promises'

const interval = 100
for await (const startTime of setInterval(interval, Date.now())) {
  const now = Date.now()
  console.log(now)
  if (now - startTime > 1000) break
}
console.log(Date.now())

CJS

const { setInterval } = require('node:timers/promises')
const interval = 100

;(async function () {
  for await (const startTime of setInterval(interval, Date.now())) {
    const now = Date.now()
    console.log(now)
    if (now - startTime > 1000) break
  }
  console.log(Date.now())
})()

timersPromises.scheduler.wait(delay[, options])

مضاف في: v17.3.0، v16.14.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• delay <number> عدد مللي الثواني التي يجب الانتظار قبل حل الوعد.

• options <Object>

  • ref <boolean> يُعيّن إلى false للإشارة إلى أن Timeout المُجدول لا يتطلب بقاء حلقة حدث Node.js نشطة. الافتراضي: true.
  • signal <AbortSignal> AbortSignal اختياري يمكن استخدامه لإلغاء الانتظار.

• عوائد: <Promise>

واجهة برمجة تطبيقات تجريبية مُعرّفة بواسطة مواصفات مسودة واجهات برمجة التخطيط قيد التطوير كواجهة برمجة تطبيقات قياسية لمنصة الويب.

إن استدعاء timersPromises.scheduler.wait(delay, options) يُعادل استدعاء timersPromises.setTimeout(delay, undefined, options).

import { scheduler } from 'node:timers/promises'

await scheduler.wait(1000) // الانتظار ثانية واحدة قبل المتابعة

timersPromises.scheduler.yield()

مضاف في: v17.3.0، v16.14.0

[مستقر: 1 - تجريبي]

مستقر: 1 الثبات: 1 - تجريبي

• الإرجاع: <Promise>

واجهة برمجة تطبيقات تجريبية مُعرّفة بمواصفات مسودة واجهات برمجة التخطيط قيد التطوير كواجهة برمجة تطبيقات قياسية لمنصة الويب.

إن استدعاء timersPromises.scheduler.yield() يُعادل استدعاء timersPromises.setImmediate() بدون أي وسيطات.