Timer

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/timers.js

Das timer-Modul stellt eine globale API zum Planen von Funktionen bereit, die zu einem späteren Zeitpunkt aufgerufen werden sollen. Da die Timer-Funktionen global sind, ist es nicht erforderlich, require('node:timers') aufzurufen, um die API zu verwenden.

Die Timer-Funktionen innerhalb von Node.js implementieren eine ähnliche API wie die von Webbrowsern bereitgestellte Timer-API, verwenden jedoch eine andere interne Implementierung, die auf der Node.js Event Loop basiert.

Klasse: Immediate

Dieses Objekt wird intern erstellt und von setImmediate() zurückgegeben. Es kann an clearImmediate() übergeben werden, um die geplanten Aktionen abzubrechen.

Standardmäßig läuft die Node.js-Ereignisschleife weiter, solange ein Immediate aktiv ist. Das von setImmediate() zurückgegebene Immediate-Objekt exportiert sowohl immediate.ref()- als auch immediate.unref()-Funktionen, mit denen dieses Standardverhalten gesteuert werden kann.

immediate.hasRef()

Hinzugefügt in: v11.0.0

• Gibt zurück: <boolean>

Wenn true, hält das Immediate-Objekt die Node.js-Ereignisschleife aktiv.

immediate.ref()

Hinzugefügt in: v9.7.0

• Gibt zurück: <Immediate> eine Referenz auf immediate

Wenn aufgerufen, wird angefordert, dass die Node.js-Ereignisschleife nicht beendet wird, solange das Immediate aktiv ist. Das mehrmalige Aufrufen von immediate.ref() hat keine Auswirkungen.

Standardmäßig sind alle Immediate-Objekte "ref'ed", wodurch es normalerweise unnötig ist, immediate.ref() aufzurufen, es sei denn, immediate.unref() wurde zuvor aufgerufen.

immediate.unref()

Hinzugefügt in: v9.7.0

• Gibt zurück: <Immediate> eine Referenz auf immediate

Wenn diese Funktion aufgerufen wird, benötigt das aktive Immediate-Objekt nicht, dass die Node.js-Ereignisschleife aktiv bleibt. Wenn es keine andere Aktivität gibt, die die Ereignisschleife am Laufen hält, kann der Prozess beendet werden, bevor der Callback des Immediate-Objekts aufgerufen wird. Das mehrmalige Aufrufen von immediate.unref() hat keine Auswirkung.

immediate[Symbol.dispose]()

Hinzugefügt in: v20.5.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Bricht das Immediate ab. Dies ist ähnlich wie der Aufruf von clearImmediate().

Klasse: Timeout

Dieses Objekt wird intern erstellt und von setTimeout() und setInterval() zurückgegeben. Es kann an entweder clearTimeout() oder clearInterval() übergeben werden, um die geplanten Aktionen abzubrechen.

Standardmäßig wird die Node.js-Ereignisschleife weiterhin ausgeführt, solange der Timer aktiv ist, wenn ein Timer entweder mit setTimeout() oder setInterval() geplant wird. Jedes der von diesen Funktionen zurückgegebenen Timeout-Objekte exportiert sowohl timeout.ref() als auch timeout.unref()-Funktionen, mit denen dieses Standardverhalten gesteuert werden kann.

timeout.close()

Hinzugefügt in: v0.9.1

[Stabil: 3 - Legacy]

Stabil: 3 Stabilität: 3 - Legacy: Verwenden Sie stattdessen clearTimeout().

• Gibt zurück: <Timeout> eine Referenz auf timeout

Bricht den Timeout ab.

timeout.hasRef()

Hinzugefügt in: v11.0.0

• Gibt zurück: <boolean>

Wenn true, hält das Timeout-Objekt die Node.js-Ereignisschleife aktiv.

timeout.ref()

Hinzugefügt in: v0.9.1

• Gibt zurück: <Timeout> eine Referenz auf timeout

Fordert beim Aufruf an, dass die Node.js-Ereignisschleife nicht beendet wird, solange das Timeout aktiv ist. Das mehrmalige Aufrufen von timeout.ref() hat keine Auswirkungen.

Standardmäßig sind alle Timeout-Objekte "ref'ed", was es normalerweise unnötig macht, timeout.ref() aufzurufen, es sei denn, timeout.unref() wurde zuvor aufgerufen.

timeout.refresh()

Hinzugefügt in: v10.2.0

• Gibt zurück: <Timeout> eine Referenz auf timeout

Setzt die Startzeit des Timers auf die aktuelle Zeit und plant den Timer neu, um seinen Callback zur zuvor angegebenen Dauer, angepasst an die aktuelle Zeit, aufzurufen. Dies ist nützlich, um einen Timer zu aktualisieren, ohne ein neues JavaScript-Objekt zu erstellen.

Die Verwendung auf einem Timer, der seinen Callback bereits aufgerufen hat, reaktiviert den Timer.

timeout.unref()

Hinzugefügt in: v0.9.1

• Gibt zurück: <Timeout> eine Referenz auf timeout

Beim Aufruf erfordert das aktive Timeout-Objekt nicht, dass die Node.js-Ereignisschleife aktiv bleibt. Wenn keine andere Aktivität die Ereignisschleife am Laufen hält, kann der Prozess beendet werden, bevor der Callback des Timeout-Objekts aufgerufen wird. Das mehrmalige Aufrufen von timeout.unref() hat keine Auswirkungen.

timeout[Symbol.toPrimitive]()

Hinzugefügt in: v14.9.0, v12.19.0

• Gibt zurück: <integer> eine Zahl, die verwendet werden kann, um auf dieses timeout zu verweisen

Konvertiert ein Timeout in einen primitiven Datentyp. Der primitive Datentyp kann verwendet werden, um das Timeout zu löschen. Der primitive Datentyp kann nur in demselben Thread verwendet werden, in dem das Timeout erstellt wurde. Um ihn also über worker_threads zu verwenden, muss er zuerst an den korrekten Thread übergeben werden. Dies ermöglicht eine verbesserte Kompatibilität mit Browser-Implementierungen von setTimeout() und setInterval().

timeout[Symbol.dispose]()

Hinzugefügt in: v20.5.0, v18.18.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

Bricht das Timeout ab.

Timer planen

Ein Timer in Node.js ist ein internes Konstrukt, das eine bestimmte Funktion nach einer bestimmten Zeitspanne aufruft. Wann die Funktion eines Timers aufgerufen wird, hängt davon ab, mit welcher Methode der Timer erstellt wurde und welche andere Arbeit die Node.js-Ereignisschleife gerade ausführt.

setImmediate(callback[, ...args])

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.9.1	Hinzugefügt in: v0.9.1

• callback <Function> Die Funktion, die am Ende dieser Runde der Node.js-Ereignisschleife aufgerufen werden soll.
• ...args <any> Optionale Argumente, die beim Aufruf des callback übergeben werden sollen.
• Gibt zurück: <Immediate> zur Verwendung mit clearImmediate()

Plant die "sofortige" Ausführung des callback nach den Callbacks von I/O-Ereignissen.

Wenn mehrere Aufrufe von setImmediate() erfolgen, werden die callback-Funktionen in der Reihenfolge ihrer Erstellung zur Ausführung in die Warteschlange gestellt. Die gesamte Callback-Warteschlange wird in jeder Iteration der Ereignisschleife verarbeitet. Wenn ein Immediate-Timer innerhalb eines ausgeführten Callbacks in die Warteschlange gestellt wird, wird dieser Timer erst bei der nächsten Iteration der Ereignisschleife ausgelöst.

Wenn callback keine Funktion ist, wird ein TypeError ausgelöst.

Diese Methode hat eine benutzerdefinierte Variante für Promises, die mit timersPromises.setImmediate() verfügbar ist.

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

[Verlauf]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.0.1	Hinzugefügt in: v0.0.1

• callback <Function> Die Funktion, die aufgerufen werden soll, wenn der Timer abläuft.
• delay <number> Die Anzahl der Millisekunden, die gewartet werden soll, bevor der callback aufgerufen wird. Standard: 1.
• ...args <any> Optionale Argumente, die beim Aufruf des callback übergeben werden sollen.
• Gibt zurück: <Timeout> zur Verwendung mit clearInterval()

Plant die wiederholte Ausführung von callback alle delay Millisekunden.

Wenn delay größer als 2147483647 oder kleiner als 1 oder NaN ist, wird delay auf 1 gesetzt. Nicht-ganzzahlige Verzögerungen werden zu einer Ganzzahl abgeschnitten.

Wenn callback keine Funktion ist, wird ein TypeError ausgelöst.

Diese Methode hat eine benutzerdefinierte Variante für Promises, die mit timersPromises.setInterval() verfügbar ist.

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

[Historie]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft jetzt ERR_INVALID_ARG_TYPE anstelle von ERR_INVALID_CALLBACK.
v0.0.1	Hinzugefügt in: v0.0.1

• callback <Function> Die Funktion, die aufgerufen wird, wenn der Timer abläuft.
• delay <number> Die Anzahl der Millisekunden, die gewartet werden soll, bevor der callback aufgerufen wird. Standard: 1.
• ...args <any> Optionale Argumente, die beim Aufruf des callback übergeben werden.
• Gibt zurück: <Timeout> zur Verwendung mit clearTimeout()

Plant die Ausführung eines einmaligen callback nach delay Millisekunden.

Der callback wird wahrscheinlich nicht genau nach delay Millisekunden aufgerufen. Node.js gibt keine Garantien für das genaue Timing der Auslösung von Callbacks oder deren Reihenfolge. Der Callback wird so nah wie möglich an der angegebenen Zeit aufgerufen.

Wenn delay größer als 2147483647 oder kleiner als 1 oder NaN ist, wird delay auf 1 gesetzt. Nicht-ganzzahlige Verzögerungen werden zu einer Ganzzahl abgeschnitten.

Wenn callback keine Funktion ist, wird ein TypeError ausgelöst.

Diese Methode hat eine benutzerdefinierte Variante für Promises, die mit timersPromises.setTimeout() verfügbar ist.

Timer abbrechen

Die Methoden setImmediate(), setInterval() und setTimeout() geben jeweils Objekte zurück, die die geplanten Timer darstellen. Diese können verwendet werden, um den Timer abzubrechen und seine Auslösung zu verhindern.

Für die promisifizierten Varianten von setImmediate() und setTimeout() kann ein AbortController verwendet werden, um den Timer abzubrechen. Wenn abgebrochen, werden die zurückgegebenen Promises mit einem 'AbortError' abgelehnt.

Für setImmediate():

ESM

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

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

// Wir `await` das Promise nicht, sodass `ac.abort()` gleichzeitig aufgerufen wird.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The immediate was aborted');
  });

ac.abort();

CJS

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();

Für setTimeout():

ESM

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

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

// Wir `await` das Promise nicht, sodass `ac.abort()` gleichzeitig aufgerufen wird.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('The timeout was aborted');
  });

ac.abort();

CJS

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)

Hinzugefügt in: v0.9.1

• immediate <Immediate> Ein Immediate-Objekt, wie von setImmediate() zurückgegeben.

Bricht ein Immediate-Objekt ab, das von setImmediate() erstellt wurde.

clearInterval(timeout)

Hinzugefügt in: v0.0.1

• timeout <Timeout> | <string> | <number> Ein Timeout-Objekt, wie von setInterval() zurückgegeben, oder das primitive des Timeout-Objekts als String oder Zahl.

Bricht ein Timeout-Objekt ab, das von setInterval() erstellt wurde.

clearTimeout(timeout)

Hinzugefügt in: v0.0.1

• timeout <Timeout> | <string> | <number> Ein Timeout-Objekt, wie von setTimeout() zurückgegeben, oder das primitive des Timeout-Objekts als String oder Zahl.

Bricht ein Timeout-Objekt ab, das von setTimeout() erstellt wurde.

Timers Promises API

[Verlauf]

Version	Änderungen
v16.0.0	Von experimentell befördert.
v15.0.0	Hinzugefügt in: v15.0.0

Die timers/promises-API bietet einen alternativen Satz von Timer-Funktionen, die Promise-Objekte zurückgeben. Die API ist über require('node:timers/promises') zugänglich.

ESM

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

CJS

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

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

Hinzugefügt in: v15.0.0

• delay <number> Die Anzahl der Millisekunden, die gewartet werden soll, bevor das Promise erfüllt wird. Standard: 1.
• value <any> Ein Wert, mit dem das Promise erfüllt wird.
• options <Object>
  • ref <boolean> Auf false setzen, um anzugeben, dass der geplante Timeout nicht erfordert, dass die Node.js-Event-Schleife aktiv bleibt. Standard: true.
  • signal <AbortSignal> Ein optionales AbortSignal, das verwendet werden kann, um das geplante Timeout abzubrechen.

ESM

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

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

console.log(res);  // Gibt 'result' aus

CJS

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

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

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

Hinzugefügt in: v15.0.0

• value <any> Ein Wert, mit dem das Promise erfüllt wird.
• options <Object>
  • ref <boolean> Auf false setzen, um anzugeben, dass der geplante Immediate nicht erfordert, dass die Node.js-Event-Schleife aktiv bleibt. Standard: true.
  • signal <AbortSignal> Ein optionales AbortSignal, das verwendet werden kann, um das geplante Immediate abzubrechen.

ESM

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

const res = await setImmediate('result');

console.log(res);  // Gibt 'result' aus

CJS

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

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

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

Hinzugefügt in: v15.9.0

Gibt einen Async-Iterator zurück, der Werte in einem Intervall von delay ms generiert. Wenn ref true ist, müssen Sie next() des Async-Iterators explizit oder implizit aufrufen, um die Event Loop aktiv zu halten.

• delay <number> Die Anzahl der Millisekunden, die zwischen den Iterationen gewartet werden soll. Standard: 1.
• value <any> Ein Wert, mit dem der Iterator zurückkehrt.
• options <Object>
  • ref <boolean> Auf false setzen, um anzugeben, dass das geplante Timeout zwischen den Iterationen nicht erfordert, dass die Node.js-Ereignisschleife aktiv bleibt. Standard: true.
  • signal <AbortSignal> Ein optionales AbortSignal, das verwendet werden kann, um das geplante Timeout zwischen Operationen abzubrechen.

ESM

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());

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

Hinzugefügt in: v17.3.0, v16.14.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• delay <number> Die Anzahl der Millisekunden, die gewartet werden soll, bevor die Promise aufgelöst wird.

• options <Object>

  • ref <boolean> Auf false setzen, um anzugeben, dass das geplante Timeout nicht erfordert, dass die Node.js-Ereignisschleife aktiv bleibt. Standard: true.
  • signal <AbortSignal> Ein optionales AbortSignal, das zum Abbrechen des Wartens verwendet werden kann.

• Gibt zurück: <Promise>

Eine experimentelle API, die von der Entwurfsspezifikation der Scheduling APIs definiert wird, die als Standard-Webplattform-API entwickelt wird.

Der Aufruf von timersPromises.scheduler.wait(delay, options) entspricht dem Aufruf von timersPromises.setTimeout(delay, undefined, options).

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

await scheduler.wait(1000); // Eine Sekunde warten, bevor fortgefahren wird

timersPromises.scheduler.yield()

Hinzugefügt in: v17.3.0, v16.14.0

[Stabil: 1 - Experimentell]

Stabil: 1 Stabilität: 1 - Experimentell

• Gibt zurück: <Promise>

Eine experimentelle API, die durch die Entwurfsspezifikation der Scheduling APIs definiert ist, die als Standard-Webplattform-API entwickelt wird.

Der Aufruf von timersPromises.scheduler.yield() entspricht dem Aufruf von timersPromises.setImmediate() ohne Argumente.