Таймеры

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

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

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

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

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

Класс: `Immediate`

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

По умолчанию, когда планируется немедленное выполнение, цикл событий Node.js будет продолжать работать до тех пор, пока Immediate активен. Объект 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 - Экспериментальная

Отменяет immediate. Это аналогично вызову 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

Возвращает: <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 Event Loop
...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]])`

[История]

Версия	Изменения
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():

ESMCJS

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

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

// Мы не используем `await` для промиса, поэтому `ac.abort()` вызывается параллельно.
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():

ESMCJS

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

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

// Мы не используем `await` для промиса, поэтому `ac.abort()` вызывается параллельно.
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)`

Добавлено в: 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().

Timers Promises API

[История]

Версия	Изменения
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> Количество миллисекунд для ожидания перед выполнением промиса. По умолчанию: 1.
value <any> Значение, с которым выполняется промис.
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> Значение, с которым выполняется промис.
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

[Stable: 1 - Experimental]

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

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); // Подождите одну секунду, прежде чем продолжить

`timersPromises.scheduler.yield()`

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

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

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

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

Экспериментальный API, определенный черновиком спецификации Scheduling APIs, разрабатываемым как стандартный 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) ​

Timers Promises API ​

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

Timers Promises API

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

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

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

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

`timersPromises.scheduler.yield()`