Таймеры

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

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

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

Класс: Immediate

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

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

immediate.hasRef()

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

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

immediate.ref()

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

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

По умолчанию все объекты Immediate являются «ссылаемыми», что обычно делает вызов immediate.ref() ненужным, если функция immediate.unref() не была вызвана ранее.

immediate.unref()

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

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

Класс: Timeout

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

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

timeout.hasRef()

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

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

timeout.ref()

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

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

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

timeout.refresh()

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

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

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

timeout.unref()

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

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

Вызов timeout.unref() создает внутренний таймер, который разбудит цикл событий Node.js. Создание слишком большого количества таких таймеров может негативно повлиять на производительность приложения Node.js.

timeout[Symbol.toPrimitive]()

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

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

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

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

setImmediate(callback[, ...args])

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

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

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

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

Этот метод имеет специальную версию для промисов, доступную с помощью util.promisify():

const util = require('util');
const setImmediatePromise = util.promisify(setImmediate);

setImmediatePromise('foobar').then((value) => {
  // value === 'foobar' (passing values is optional)
  // This is executed after all I/O callbacks.
});

// Or with async function
async function timerExample() {
  console.log('Before I/O callbacks');
  await setImmediatePromise();
  console.log('After I/O callbacks');
}
timerExample();

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

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

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

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

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

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

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

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

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

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

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

Этот метод имеет специальную версию для промисов, которая доступна с помощью util.promisify():

const util = require('util');
const setTimeoutPromise = util.promisify(setTimeout);

setTimeoutPromise(40, 'foobar').then((value) => {
  // value === 'foobar' (passing values is optional)
  // This is executed after about 40 milliseconds.
});

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

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

Отменить таймеры, созданные с помощью промисифицированных вариантов setImmediate(), setTimeout() нельзя.

clearImmediate(immediate)

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

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

clearInterval(timeout)

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

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

clearTimeout(timeout)

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

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