Таймеры

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

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

Класс: Immediate

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

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

immediate.hasRef()

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

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

immediate.ref()

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

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

По умолчанию все объекты Immediate имеют ссылку (ref'ed), поэтому обычно вызывать immediate.ref() не нужно, если ранее не был вызван immediate.unref().

immediate.unref()

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

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

immediate[Symbol.dispose]()

Отменяет immediate-вызов. Это аналогично вызову clearImmediate().

Класс: Timeout

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

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

timeout.close()

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

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

timeout.hasRef()

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

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

timeout.ref()

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

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

По умолчанию все объекты Timeout имеют ссылку (ref'ed), поэтому обычно вызывать timeout.ref() не нужно, если ранее не был вызван timeout.unref().

timeout.refresh()

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

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

Вызов этого метода для таймера, функция обратного вызова которого уже была вызвана, повторно активирует таймер.

timeout.unref()

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

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

timeout[Symbol.toPrimitive]()

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

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

timeout[Symbol.dispose]()

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

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

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

setImmediate(callback[, ...args])

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

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

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

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

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

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

• 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]])

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

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

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

// We do not `await` the promise so `ac.abort()` is called concurrently.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

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('The immediate was aborted');
  });

ac.abort();

Для setTimeout():

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

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

// We do not `await` the promise so `ac.abort()` is called concurrently.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

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('The timeout was aborted');
  });

ac.abort();

clearImmediate(immediate)

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

Отменяет объект Immediate, созданный с помощью setImmediate().

clearInterval(timeout)

• timeout <Timeout> | <string> | <number> Объект Timeout, возвращенный из setInterval(), или примитивное значение объекта Timeout в виде строки или числа.

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

clearTimeout(timeout)

• timeout <Timeout> | <string> | <number> Объект Timeout, возвращенный из setTimeout(), или примитивное значение объекта Timeout в виде строки или числа.

Отменяет объект Timeout, созданный с помощью setTimeout().

API промисов таймеров

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

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

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

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

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

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

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

console.log(res);  // Prints 'result'

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

setTimeout(100, 'result').then((res) => {
  console.log(res);  // Prints 'result'
});

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

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

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

const res = await setImmediate('result');

console.log(res);  // Prints 'result'

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

setImmediate('result').then((res) => {
  console.log(res);  // Prints 'result'
});

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

Возвращает асинхронный итератор, генерирующий значения с интервалом delay мс. Если ref имеет значение true, необходимо явно или неявно вызвать next() асинхронного итератора, чтобы цикл событий оставался активным.

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

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

• delay <number> Время в миллисекундах до разрешения промиса.
• 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); // Wait one second before continuing
mjscopy

timersPromises.scheduler.yield()

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

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

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