NodeJS | Таймеры

NodeJS | Таймеры

Внимание!!! Информация актуальна только на дату публикации. Информация может быть устаревшей.

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

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

 

Класс: Immediate

  • immediate.hasRef()
  • immediate.ref()
  • immediate.unref()

Класс: Timeout

  • timeout.close()
  • timeout.hasRef()
  • timeout.ref()
  • timeout.refresh()
  • timeout.unref()
  • timeout[Symbol.toPrimitive]()

Таймеры планирования (Таймеры расписания)

  • setImmediate(callback[, …args])
  • setInterval(callback[, delay[, …args]])
  • setTimeout(callback[, delay[, …args]])

Отмена таймеров (Остановка таймеров)

  • clearImmediate(immediate)
  • clearInterval(timeout)
  • clearTimeout(timeout)

API обещаний таймеров

  • timersPromises.setTimeout([delay[, value[, options]]])
  • timersPromises.setImmediate([value[, options]])
  • timersPromises.setInterval([delay[, value[, options]]])
  • timersPromises.scheduler.wait(delay[, options])
  • timersPromises.scheduler.yield()

 

Класс: Immediate

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

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

immediate.hasRef()

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

Возвращает: <логическое значение>

Если задано значение 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() не будет иметь никакого эффекта.

 

Класс: Timeout

Этот объект создаётся внутри и возвращается из setTimeout() и setInterval(). Его можно передать либо в clearTimeout(), либо в clearInterval(), чтобы отменить запланированные действия.

По умолчанию, когда таймер запланирован с помощью setTimeout() или setInterval(), цикл событий Node.js будет продолжать работать, пока таймер активен. Каждый из объектов Timeout, возвращаемых этими функциями, экспортирует функции timeout.ref() и timeout.unref(), которые можно использовать для управления поведением по умолчанию.

timeout.close()

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

Стабильность: 3 — Устаревшие: вместо этого используйте clearTimeout().

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

Отменяет тайм-аут.

timeout.hasRef()

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

Возвращает: <логическое значение>

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

timeout.ref()

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

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

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

По умолчанию все объекты Timeout имеют «ref’ed», что обычно делает ненужным вызов timeout.ref(), если ранее не был вызван timeout.unref().

timeout.refresh()

Добавлено в: v10.2.0

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

Устанавливает время запуска таймера на текущее время и переназначает таймер для вызова обратного вызова с ранее указанной продолжительностью, скорректированной с учетом текущего времени. Это полезно для обновления таймера без выделения нового объекта JavaScript.

Использование этого на таймере, который уже вызвал свой обратный вызов, повторно активирует таймер.

 

timeout.unref()

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

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

При вызове активный объект Timeout не требует, чтобы цикл событий Node.js оставался активным. Если нет других действий, поддерживающих выполнение цикла событий, процесс может завершиться до того, как будет вызван обратный вызов объекта Timeout. Многократный вызов timeout.unref() не будет иметь никакого эффекта.

timeout[Symbol.toPrimitive]()

Добавлено в: v14.9.0, v12.19.0

Возвращает: <integer> число, которое можно использовать для ссылки на этот тайм-аут.

Принудительный тайм-аут к примитиву. Примитив можно использовать для сброса тайм-аута. Примитив можно использовать только в том же потоке, в котором был создан тайм-аут. Следовательно, чтобы использовать его в worker_threads, его нужно сначала передать в правильный поток. Это обеспечивает улучшенную совместимость с реализациями браузеров setTimeout() и setInterval().

 

 

Таймеры планирования (Таймеры расписания)

Таймер в Node.js — это внутренняя конструкция, которая вызывает заданную функцию через определенный промежуток времени. Когда вызывается функция таймера, зависит от того, какой метод использовался для создания таймера и какую другую работу выполняет цикл обработки событий event loop в Node.js.

 

setImmediate(callback[, …args])

  • callback <Function> Функция для вызова в конце этого хода цикла событий Node.js.
  • …args <любой> Необязательные аргументы для передачи при вызове обратного вызова.
  • Возвращает: <Immediate> для использования с clearImmediate().

Планирует «немедленное» выполнение обратного вызова после обратных вызовов событий ввода-вывода.

При выполнении нескольких вызовов setImmediate() функции обратного вызова ставятся в очередь для выполнения в том порядке, в котором они были созданы. Вся очередь обратного вызова обрабатывается при каждой итерации цикла обработки событий. Если немедленный таймер поставлен в очередь внутри выполняющегося обратного вызова, этот таймер не будет запущен до следующей итерации цикла обработки событий.

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

У этого метода есть собственный вариант для промисов, доступный с помощью timersPromises.setImmediate().

 

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

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

Планирует повторное выполнение обратного вызова каждые миллисекунды задержки.

Когда задержка больше 2 147 483 647 или меньше 1, для задержки будет установлено значение 1. Нецелочисленные задержки усекаются до целого числа.

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

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

 

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

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

Планирует выполнение одноразового обратного вызова после задержки в миллисекундах.

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

Когда задержка больше 2 147 483 647 или меньше 1, для задержки будет установлено значение 1. Нецелочисленные задержки усекаются до целого числа.

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

У этого метода есть собственный вариант для промисов, доступный с помощью timersPromises.setTimeout().

 

 

Отмена таймеров (Остановка таймеров)

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

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

Для setImmediate():

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.log(‘The immediate was aborted’);

  });

 

ac.abort();

 

Для setTimeout():

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.log(‘The timeout was aborted’);

  });

 

ac.abort();

 

clearImmediate(immediate)

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

immediate <Immediate> Объект Immediate, возвращенный функцией setImmediate().

Отменяет объект Immediate, созданный функцией setImmediate().

 

clearInterval(timeout)

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

время ожидания <Тайм-аут> | <строка> | <number> Объект Timeout, возвращаемый функцией setInterval(), или примитив объекта Timeout в виде строки или числа.

Отменяет объект Timeout, созданный setInterval().

 

clearTimeout(timeout)

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

время ожидания <Тайм-аут> | <строка> | <number> Объект Timeout, возвращаемый функцией setTimeout(), или примитив объекта Timeout в виде строки или числа.

Отменяет объект Timeout, созданный функцией setTimeout().

 

API обещаний таймеров

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

import {

    setTimeout,

    setImmediate,

    setInterval,

  } from ‘timers/promises’;

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

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

delay <число> Количество миллисекунд ожидания перед выполнением обещания. По умолчанию: 1.

value <любое> Значение, с которым выполняется обещание.

опции <Объект>

ref <boolean> Установите значение false, чтобы указать, что запланированный тайм-аут не должен требовать, чтобы цикл событий Node.js оставался активным. По умолчанию: правда.

signal <AbortSignal> Необязательный сигнал AbortSignal, который можно использовать для отмены запланированного тайм-аута.

import {

    setTimeout,

  } from ‘timers/promises’;

 

  const res = await setTimeout(100, ‘result’);

 

  console.log(res);  // Prints ‘result’

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

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

value <любое> Значение, с которым выполняется обещание.

опции <Объект>

ref <boolean> Установите значение false, чтобы указать, что запланированное Immediate не должно требовать, чтобы цикл событий Node.js оставался активным. По умолчанию: правда.

signal <AbortSignal> Необязательный сигнал AbortSignal, который можно использовать для отмены запланированного Immediate.

import {

    setImmediate,

  } from ‘timers/promises’;

 

  const res = await setImmediate(‘result’);

 

  console.log(res);  // Prints ‘result’

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

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

Возвращает асинхронный итератор, который генерирует значения с интервалом задержки мс.

delay <число> Количество миллисекунд ожидания между итерациями. По умолчанию: 1.

value <любое> Значение, которое возвращает итератор.

опции <Объект>

ref <boolean> Установите значение false, чтобы указать, что запланированный тайм-аут между итерациями не должен требовать, чтобы цикл событий Node.js оставался активным.

По умолчанию: правда.

signal <AbortSignal> Дополнительный сигнал AbortSignal, который можно использовать для отмены запланированного тайм-аута между операциями.

import {

    setInterval,

  } from ‘timers/promises’;

 

  const interval = 100;

  for await (const startTime of setInterval(interval, Date.now())) {

    const now = Date.now();

    console.log(now);

    if ((nowstartTime) > 1000)

      break;

  }

  console.log(Date.now());

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

Добавлено в: v17.3.0, v16.14.0

Стабильность: 1 — Экспериментальная

delay <число> Количество миллисекунд ожидания перед разрешением промиса.

опции <Объект>

signal <AbortSignal> Необязательный сигнал AbortSignal, который можно использовать для отмены ожидания.

Возвращает: <Обещание>

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

Вызов timersPromises.scheduler.wait(delay, options) примерно эквивалентен вызову timersPromises.setTimeout(delay, undefined, options), за исключением того, что параметр ref не поддерживается.

import { scheduler } from ‘node:timers/promises’;

 

await scheduler.wait(1000); // Подождите одну секунду, прежде чем продолжить

timersPromises.scheduler.yield()

Добавлено в: v17.3.0, v16.14.0

Стабильность: 1 — Экспериментальная

Возвращает: <Обещание>

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

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

 

Информационные ссылки

Стандарт NodeJS — Модуль «Timers» — https://nodejs.org/dist/latest-v18.x/docs/api/timers.html