Таймеры

[Стабильно: 2 - Стабильно]

Стабильно: 2 Стабильность: 2 - Стабильно

Исходный код: lib/timers.js

Модуль timer предоставляет глобальный API для планирования вызова функций через определенный промежуток времени. Поскольку функции таймера являются глобальными, вызывать require('node:timers') для использования API не нужно.

Функции таймера в Node.js реализуют API, аналогичный API таймеров, предоставляемому веб-браузерами, но используют другую внутреннюю реализацию, основанную на цикле событий Node.js.

Класс: `Immediate`

Этот объект создается внутренне и возвращается из setImmediate(). Он может быть передан в clearImmediate() для отмены запланированных действий.

По умолчанию, когда запланировано немедленное действие, цикл событий Node.js будет продолжать работу, пока немедленное действие активно. Объект Immediate, возвращаемый функцией setImmediate(), экспортирует функции immediate.ref() и immediate.unref(), которые можно использовать для управления этим поведением по умолчанию.

`immediate.hasRef()`

Добавлен в: v11.0.0

Возвращает: <boolean>

Если true, объект Immediate будет поддерживать активность цикла событий Node.js.

`immediate.ref()`

Добавлен в: v9.7.0

Возвращает: <Immediate> ссылку на immediate

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока Immediate активен. Многократный вызов immediate.ref() не будет иметь эффекта.

По умолчанию все объекты Immediate являются "ссылочными" (ref'ed), поэтому обычно нет необходимости вызывать 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>

Если true, объект Timeout будет поддерживать активность цикла событий Node.js.

`timeout.ref()`

Добавлен в: v0.9.1

Возвращает: <Timeout> ссылку на timeout

При вызове запрашивает, чтобы цикл событий Node.js не завершался, пока Timeout активен. Многократный вызов timeout.ref() не окажет никакого эффекта.

По умолчанию все объекты Timeout являются "ref'ed", что обычно делает ненужным вызов 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

Возвращает: <целое число> число, которое можно использовать для ссылки на этот 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 после обратных вызовов событий ввода-вывода.

При нескольких вызовах 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]])`

[История]

Версия	Изменения
v18.0.0	Передача недопустимого обратного вызова в аргумент `callback` теперь вызывает исключение `ERR_INVALID_ARG_TYPE` вместо `ERR_INVALID_CALLBACK`.
v0.0.1	Добавлено в: v0.0.1

callback <Функция> Функция, которая будет вызвана по истечении таймера.
delay <число> Количество миллисекунд ожидания перед вызовом callback. По умолчанию: 1.
...args <любой> Необязательные аргументы для передачи при вызове callback.
Возвращает: <Timeout> для использования с clearTimeout()

Планирует однократное выполнение callback после delay миллисекунд.

callback может быть вызван не точно через delay миллисекунд. Node.js не гарантирует точное время срабатывания обратных вызовов, а также их порядок. Обратный вызов будет вызван как можно ближе ко времени, указанному в параметрах.

Если delay больше 2147483647 или меньше 1, или равно NaN, то delay будет установлен в 1. Нецелые значения delay усекаются до целого числа.

Если callback не является функцией, будет выброшено исключение TypeError.

Этот метод имеет пользовательский вариант для промисов, доступный с помощью timersPromises.setTimeout().

Отмена таймеров

Методы setImmediate(), setInterval() и setTimeout() возвращают объекты, представляющие запланированные таймеры. Их можно использовать для отмены таймера и предотвращения его срабатывания.

Для варианта с промисами методов setImmediate() и setTimeout() может использоваться AbortController для отмены таймера. При отмене возвращаемые промисы будут отклонены с ошибкой 'AbortError'.

Для setImmediate():

ESMCJS

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()

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():

ESMCJS

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()

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().

API таймеров на основе Promise

[История]

Версия	Изменения
v16.0.0	Выпуск из экспериментальной версии.
v15.0.0	Добавлено в: v15.0.0

API timers/promises предоставляет альтернативный набор функций таймеров, которые возвращают объекты Promise. API доступен через require('node:timers/promises').

ESMCJS

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

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

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

Добавлено в: v15.0.0

delay <number> Количество миллисекунд ожидания перед выполнением promise. По умолчанию: 1.
value <any> Значение, с которым выполняется promise.
options <Object>
- ref <boolean> Установите в false, чтобы указать, что запланированному Timeout не требуется, чтобы цикл событий Node.js оставался активным. По умолчанию: true.
- signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены запланированного Timeout.

ESMCJS

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

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

console.log(res) // Выведет 'result'

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

setTimeout(100, 'result').then(res => {
  console.log(res) // Выведет 'result'
})

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

Добавлено в: v15.0.0

value <any> Значение, с которым выполняется promise.
options <Object>
- ref <boolean> Установите в false, чтобы указать, что запланированному Immediate не требуется, чтобы цикл событий Node.js оставался активным. По умолчанию: true.
- signal <AbortSignal> Необязательный AbortSignal, который можно использовать для отмены запланированного Immediate.

ESMCJS

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

const res = await setImmediate('result')

console.log(res) // Выведет 'result'

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 между операциями.

ESMCJS

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())

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> Количество миллисекунд ожидания перед разрешением promise.
options <Object>
- ref <boolean> Устанавливается в false, чтобы указать, что запланированный Timeout не должен требовать поддержания активности цикла событий Node.js. По умолчанию: true.
- signal <AbortSignal> Необязательный AbortSignal, который может использоваться для отмены ожидания.
Возвращает: <Promise>

Экспериментальный API, определённый в черновике спецификации Scheduling APIs, разрабатываемом в качестве стандартного API веб-платформы.

Вызов 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>

Экспериментальный API, определённый в черновике спецификации API планирования, разрабатываемом в качестве стандартного API веб-платформы.

Вызов timersPromises.scheduler.yield() эквивалентен вызову timersPromises.setImmediate() без аргументов.

Таймеры ​

Класс: Immediate ​

immediate.hasRef() ​

immediate.ref() ​

immediate.unref() ​

immediate[Symbol.dispose]() ​

Класс: Timeout ​

timeout.close() ​

timeout.hasRef() ​

timeout.ref() ​

timeout.refresh() ​

timeout.unref() ​

timeout[Symbol.toPrimitive]() ​

timeout[Symbol.dispose]() ​

Планировщики таймеров ​

setImmediate(callback[, ...args]) ​

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

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

Отмена таймеров ​

clearImmediate(immediate) ​

clearInterval(timeout) ​

clearTimeout(timeout) ​

API таймеров на основе Promise ​

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

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

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

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

timersPromises.scheduler.yield() ​

Таймеры

Класс: `Immediate`

`immediate.hasRef()`

`immediate.ref()`

`immediate.unref()`

`immediate[Symbol.dispose]()`

Класс: `Timeout`

`timeout.close()`

`timeout.hasRef()`

`timeout.ref()`

`timeout.refresh()`

`timeout.unref()`

`timeout[Symbol.toPrimitive]()`

`timeout[Symbol.dispose]()`

Планировщики таймеров

`setImmediate(callback[, ...args])`

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

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

Отмена таймеров

`clearImmediate(immediate)`

`clearInterval(timeout)`

`clearTimeout(timeout)`

API таймеров на основе Promise

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

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

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

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

`timersPromises.scheduler.yield()`