Timer

[Stabil: 2 - Stabil]

Stabil: 2 Stabilität: 2 - Stabil

Quellcode: lib/timers.js

Das timer-Modul stellt eine globale API zur Verfügung, um Funktionen zu planen, 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 in Node.js implementieren eine ähnliche API wie die Timer-API, die von Webbrowsern bereitgestellt wird, verwenden jedoch eine andere interne Implementierung, die um die Node.js Event Loop herum aufgebaut ist.

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 wird die Node.js-Event-Loop so lange ausgeführt, wie eine Immediate aktiv ist. Das von setImmediate() zurückgegebene Immediate-Objekt exportiert sowohl immediate.ref()- als auch immediate.unref()-Funktionen, die verwendet werden können, um dieses Standardverhalten zu steuern.

immediate.hasRef()

Hinzugefügt in: v11.0.0

• Gibt zurück: <boolean>

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

immediate.ref()

Hinzugefügt in: v9.7.0

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

Wenn diese Funktion aufgerufen wird, fordert sie an, dass die Node.js-Event-Loop nicht beendet wird, solange die Immediate aktiv ist. Der mehrmalige Aufruf von immediate.ref() hat keine Auswirkung.

Standardmäßig sind alle Immediate-Objekte "ref'ed", wodurch es normalerweise nicht notwendig 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 zu immediate

Wenn diese Funktion aufgerufen wird, erfordert das aktive Immediate-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 Rückruf des Immediate-Objekts aufgerufen wird. Das mehrfache 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 entweder an clearTimeout() oder clearInterval() übergeben werden, um die geplanten Aktionen abzubrechen.

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

timeout.close()

Hinzugefügt in: v0.9.1

[Stabil: 3 - Veraltet]

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

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

Bricht das 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

Wenn diese Funktion aufgerufen wird, wird angefordert, dass die Node.js-Ereignisschleife nicht beendet wird, solange der Timeout aktiv ist. Mehrfaches Aufrufen von timeout.ref() hat keine Auswirkung.

Standardmäßig sind alle Timeout-Objekte "referenziert", sodass es normalerweise nicht erforderlich ist, 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 mit der zuvor angegebenen Dauer, angepasst an die aktuelle Zeit, aufzurufen. Dies ist nützlich, um einen Timer aufzufrischen, ohne ein neues JavaScript-Objekt zu erzeugen.

Die Verwendung dieser Funktion auf einem Timer, dessen Callback bereits aufgerufen wurde, reaktiviert den Timer.

timeout.unref()

Hinzugefügt in: v0.9.1

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

Wenn diese Funktion aufgerufen wird, benötigt 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. Mehrfaches Aufrufen von timeout.unref() hat keine Auswirkung.

timeout[Symbol.toPrimitive]()

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

• Gibt zurück: <integer> eine Zahl, die verwendet werden kann, um diesen timeout zu referenzieren.

Konvertiert ein Timeout in einen primitiven Wert. Der primitive Wert kann verwendet werden, um das Timeout zu löschen. Der primitive Wert kann nur in demselben Thread verwendet werden, in dem das Timeout erstellt wurde. Daher muss er zuerst an den richtigen Thread übergeben werden, um ihn über worker_threads hinweg zu verwenden. 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.

Scheduling-Timer

Ein Timer in Node.js ist ein internes Konstrukt, das eine gegebene Funktion nach einer bestimmten Zeitspanne aufruft. Wann die Funktion eines Timers aufgerufen wird, hängt davon ab, welche Methode zum Erstellen des Timers verwendet wurde und welche andere Arbeit die Node.js-Ereignisschleife gerade erledigt.

setImmediate(callback[, ...args])

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft nun 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 callbacks übergeben werden.
• Gibt zurück: <Immediate> zur Verwendung mit clearImmediate()

Plant die "sofortige" Ausführung des callbacks 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 bei 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]])

[History]

Version	Änderungen
v18.0.0	Das Übergeben eines ungültigen Callbacks an das callback-Argument wirft nun 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 callbacks übergeben werden.
• 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 ganzen Zahl gekürzt.

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

[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 <Funktion> Die Funktion, die aufgerufen werden soll, wenn der Timer abläuft.
• delay <Zahl> Die Anzahl der Millisekunden, die vor dem Aufrufen des callback gewartet werden soll. Standard: 1.
• ...args <beliebig> 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 exakt nach delay Millisekunden aufgerufen. Node.js gibt keine Garantie für die genaue Zeit, zu der Callbacks ausgelöst werden, noch für ihre 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 zu verhindern, dass er ausgelöst wird.

Für die promisifizierten Varianten von setImmediate() und setTimeout() kann ein AbortController verwendet werden, um den Timer abzubrechen. Wenn abgebrochen wird, 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, also wird `ac.abort()` gleichzeitig aufgerufen.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('Das Immediate wurde abgebrochen')
  })

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('Das Immediate wurde abgebrochen')
  })

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, also wird `ac.abort()` gleichzeitig aufgerufen.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('Das Timeout wurde abgebrochen')
  })

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('Das Timeout wurde abgebrochen')
  })

ac.abort()

clearImmediate(immediate)

Hinzugefügt in: v0.9.1

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

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, das von setInterval() zurückgegeben wird, oder der primitive Wert 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, das von setTimeout() zurückgegeben wird, oder der primitive Wert 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	Aus dem experimentellen Status entlassen.
v15.0.0	Hinzugefügt in: v15.0.0

Das timers/promises-API bietet eine alternative Reihe von Timerfunktionen, die Promise-Objekte zurückgeben. Auf das API kann über require('node:timers/promises') zugegriffen werden.

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 das geplante Timeout nicht erfordert, dass die Node.js-Ereignisschleife 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 das geplante Immediate nicht erfordert, dass die Node.js-Ereignisschleife 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 asynchronen Iterator zurück, der Werte in einem Intervall von delay ms generiert. Wenn ref true ist, müssen Sie next() des asynchronen Iterators explizit oder implizit aufrufen, um die Event-Loop am Leben 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ückgibt.
• options <Object>
  • ref <boolean> Auf false setzen, um anzugeben, dass der geplante Timeout zwischen den Iterationen nicht erfordern soll, dass die Node.js-Ereignisschleife aktiv bleibt. Standard: true.
  • signal <AbortSignal> Ein optionales AbortSignal, das verwendet werden kann, um den geplanten Timeout zwischen den 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 das Promise aufgelöst wird.

• options <Object>

  • ref <boolean> Auf false setzen, um anzugeben, dass der geplante Timeout nicht erfordern soll, dass die Node.js-Ereignisschleife aktiv bleibt. Standard: true.
  • signal <AbortSignal> Ein optionales AbortSignal, das verwendet werden kann, um das Warten abzubrechen.

• Gibt zurück: <Promise>

Eine experimentelle API, die durch die Scheduling APIs Entwurfsspezifikation definiert wird und 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 den Entwurf der Scheduling APIs definiert wird und als Standard-Webplattform-API entwickelt wird.

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