Класс: Immediate

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

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

immediate.hasRef()

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

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

immediate.ref()

• Возвращает: <Немедленное> ссылка на immediate

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

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

immediate.unref()

• Возвращает: <Немедленное> ссылка на immediate

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

Класс: Timeout

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

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

timeout.close()

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

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

timeout.hasRef()

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

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

timeout.ref()

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

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

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

timeout.refresh()

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

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

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

timeout.unref()

• Возвращает: <Таймаут> ссылка на 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.
• Возвращает: <Непосредственный> для использования с clearImmediate()

Планирует «немедленное» выполнение callback после обращений к функциям I/O-событий.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для setImmediate():

const { setImmediate: setImmediatePromise } = require('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('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)

• immediate <Объект Немедленного Выполнения> Объект Immediate возвращённый методом setImmediate().

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

clearInterval(timeout)

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

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

clearTimeout(timeout)

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

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

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

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

Модули MJS

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

Модули CJS

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

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

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

Модули MJS

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

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

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

Модули CJS

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

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

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

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

Модули MJS

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

const res = await setImmediate('result');

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

Модули CJS

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

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

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

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

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

Модули MJS

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 ((now - startTime) > 1000)
    break;
}
console.log(Date.now());

Модули CJS

const {
  setInterval,
} = require('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());
})();