Класс: 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 «ссылаются», что обычно делает ненужным вызов 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 «ссылаются», что обычно делает ненужным вызов 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 <Функция> Функция, которая должна быть вызвана в конце текущего цикла Node.js цикла событий
• ...args <любой> Дополнительные аргументы, передаваемые при вызове callback.
• Возвращает: <Немедленный> для использования с clearImmediate()

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

При множественных вызовах 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('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(); copy

Для 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.error('The timeout was aborted');
  });

ac.abort(); copy

clearImmediate(immediate)

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

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

clearInterval(timeout)

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

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

clearTimeout(timeout)

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

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

API таймеров Promisses

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

Модули MJS

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

Модули CJS

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

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

• delay <число> Количество миллисекунд, которое необходимо подождать, прежде чем выполнить promise. По умолчанию: 1.
• value <любой> Значение, с которым выполняется promise.
• 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('node:timers/promises');

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

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

• value <любой> Значение, с которым выполняется promise.
• 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('node:timers/promises');

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

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

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

• 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('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 <число> Количество миллисекунд, которое необходимо подождать, прежде чем выполнить promise.
• options <Объект>
  • signal <AbortSignal> Необязательный AbortSignal для отмены ожидания.
• Возвращает: <Promise>

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

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

import { scheduler } from 'node:timers/promises';

await scheduler.wait(1000); // Wait one second before continuing copy

timersPromises.scheduler.yield()

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

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

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