Timer

[Stabile: 2 - Stabile]

Stabile: 2 Stabilità: 2 - Stabile

Codice Sorgente: lib/timers.js

Il modulo timer espone un'API globale per la pianificazione di funzioni da chiamare in un futuro periodo di tempo. Poiché le funzioni timer sono globali, non è necessario chiamare require('node:timers') per utilizzare l'API.

Le funzioni timer in Node.js implementano un'API simile all'API timer fornita dai browser Web, ma utilizzano un'implementazione interna diversa basata sull'Event Loop di Node.js.

Classe: Immediate

Questo oggetto viene creato internamente e viene restituito da setImmediate(). Può essere passato a clearImmediate() per annullare le azioni pianificate.

Per impostazione predefinita, quando viene pianificato un immediato, l'event loop di Node.js continuerà a funzionare fintanto che l'immediato è attivo. L'oggetto Immediate restituito da setImmediate() espone sia le funzioni immediate.ref() che immediate.unref() che possono essere utilizzate per controllare questo comportamento predefinito.

immediate.hasRef()

Aggiunto in: v11.0.0

• Restituisce: <boolean>

Se vero, l'oggetto Immediate manterrà attivo l'event loop di Node.js.

immediate.ref()

Aggiunto in: v9.7.0

• Restituisce: <Immediate> un riferimento a immediate

Quando viene chiamato, richiede che l'event loop di Node.js non termini fintanto che Immediate è attivo. Chiamare immediate.ref() più volte non avrà alcun effetto.

Per impostazione predefinita, tutti gli oggetti Immediate sono "ref'ed", rendendo normalmente superfluo chiamare immediate.ref() a meno che immediate.unref() non sia stato chiamato in precedenza.

immediate.unref()

Aggiunto in: v9.7.0

• Restituisce: <Immediate> un riferimento a immediate

Quando viene chiamato, l'oggetto Immediate attivo non richiederà che il loop degli eventi di Node.js rimanga attivo. Se non c'è altra attività che mantiene in esecuzione il loop degli eventi, il processo potrebbe terminare prima che venga invocata la callback dell'oggetto Immediate. Chiamare immediate.unref() più volte non avrà alcun effetto.

immediate[Symbol.dispose]()

Aggiunto in: v20.5.0, v18.18.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Annulla l'immediato. Questo è simile a chiamare clearImmediate().

Classe: Timeout

Questo oggetto viene creato internamente e viene restituito da setTimeout() e setInterval(). Può essere passato a clearTimeout() o clearInterval() per annullare le azioni pianificate.

Per impostazione predefinita, quando un timer viene pianificato usando setTimeout() o setInterval(), il loop degli eventi di Node.js continuerà a funzionare finché il timer è attivo. Ciascuno degli oggetti Timeout restituiti da queste funzioni esporta sia le funzioni timeout.ref() che timeout.unref() che possono essere utilizzate per controllare questo comportamento predefinito.

timeout.close()

Aggiunto in: v0.9.1

[Stabile: 3 - Legacy]

Stabile: 3 Stabilità: 3 - Legacy: Usare clearTimeout() invece.

• Restituisce: <Timeout> un riferimento a timeout

Annulla il timeout.

timeout.hasRef()

Aggiunto in: v11.0.0

• Restituisce: <boolean>

Se vero, l'oggetto Timeout manterrà attivo il loop degli eventi di Node.js.

timeout.ref()

Aggiunto in: v0.9.1

• Restituisce: <Timeout> un riferimento a timeout

Quando viene chiamato, richiede che il loop eventi di Node.js non esca finché il Timeout è attivo. Chiamare timeout.ref() più volte non avrà alcun effetto.

Per impostazione predefinita, tutti gli oggetti Timeout sono "ref'ed", rendendo normalmente inutile chiamare timeout.ref() a meno che timeout.unref() non sia stato chiamato in precedenza.

timeout.refresh()

Aggiunto in: v10.2.0

• Restituisce: <Timeout> un riferimento a timeout

Imposta l'ora di inizio del timer sull'ora corrente e riprogramma il timer per chiamare la sua callback alla durata specificata in precedenza, adattata all'ora corrente. Questo è utile per aggiornare un timer senza allocare un nuovo oggetto JavaScript.

Usarlo su un timer che ha già chiamato la sua callback riattiverà il timer.

timeout.unref()

Aggiunto in: v0.9.1

• Restituisce: <Timeout> un riferimento a timeout

Quando viene chiamato, l'oggetto Timeout attivo non richiederà che il loop eventi di Node.js rimanga attivo. Se non c'è altra attività che mantiene in esecuzione il loop eventi, il processo potrebbe uscire prima che venga invocata la callback dell'oggetto Timeout. Chiamare timeout.unref() più volte non avrà alcun effetto.

timeout[Symbol.toPrimitive]()

Aggiunto in: v14.9.0, v12.19.0

• Restituisce: <intero> un numero che può essere usato per fare riferimento a questo timeout

Costringe un Timeout a un primitivo. Il primitivo può essere usato per cancellare il Timeout. Il primitivo può essere usato solo nello stesso thread in cui è stato creato il timeout. Pertanto, per utilizzarlo tra i worker_threads deve prima essere passato al thread corretto. Ciò consente una maggiore compatibilità con le implementazioni di setTimeout() e setInterval() del browser.

timeout[Symbol.dispose]()

Aggiunto in: v20.5.0, v18.18.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

Annulla il timeout.

Pianificazione dei timer

Un timer in Node.js è una struttura interna che chiama una data funzione dopo un certo periodo di tempo. Quando viene chiamata la funzione di un timer varia a seconda del metodo utilizzato per creare il timer e di quale altro lavoro sta svolgendo il loop degli eventi di Node.js.

setImmediate(callback[, ...args])

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v0.9.1	Aggiunto in: v0.9.1

• callback <Funzione> La funzione da chiamare alla fine di questo turno del loop degli eventi di Node.js Event Loop
• ...args <qualsiasi> Argomenti opzionali da passare quando viene chiamato il callback.
• Restituisce: <Immediato> da utilizzare con clearImmediate()

Pianifica l'esecuzione "immediata" del callback dopo i callback degli eventi I/O.

Quando vengono effettuate più chiamate a setImmediate(), le funzioni callback vengono messe in coda per l'esecuzione nell'ordine in cui vengono create. L'intera coda dei callback viene elaborata ad ogni iterazione del loop degli eventi. Se un timer immediato viene messo in coda dall'interno di un callback in esecuzione, tale timer non verrà attivato fino alla successiva iterazione del loop degli eventi.

Se callback non è una funzione, verrà generato un TypeError.

Questo metodo ha una variante personalizzata per le promise disponibile utilizzando timersPromises.setImmediate().

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

[Cronologia]

Versione	Modifiche
v18.0.0	Passare un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v0.0.1	Aggiunto in: v0.0.1

• callback <Funzione> La funzione da chiamare quando il timer scade.
• delay <numero> Il numero di millisecondi da attendere prima di chiamare il callback. Predefinito: 1.
• ...args <qualsiasi> Argomenti opzionali da passare quando viene chiamato il callback.
• Restituisce: <Timeout> da utilizzare con clearInterval()

Pianifica l'esecuzione ripetuta di callback ogni delay millisecondi.

Quando delay è maggiore di 2147483647 o minore di 1 o NaN, delay verrà impostato su 1. I ritardi non interi vengono troncati a un numero intero.

Se callback non è una funzione, verrà generato un TypeError.

Questo metodo ha una variante personalizzata per le promise disponibile utilizzando timersPromises.setInterval().

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

[Cronologia]

Versione	Modifiche
v18.0.0	Il passaggio di un callback non valido all'argomento callback ora genera ERR_INVALID_ARG_TYPE invece di ERR_INVALID_CALLBACK.
v0.0.1	Aggiunto in: v0.0.1

• callback <Funzione> La funzione da chiamare quando il timer scade.
• delay <numero> Il numero di millisecondi da attendere prima di chiamare il callback. Predefinito: 1.
• ...args <qualsiasi> Argomenti opzionali da passare quando viene chiamato il callback.
• Restituisce: <Timeout> da utilizzare con clearTimeout()

Pianifica l'esecuzione di un callback una tantum dopo delay millisecondi.

È probabile che il callback non venga invocato esattamente dopo delay millisecondi. Node.js non fornisce garanzie sulla tempistica esatta di quando i callback verranno attivati, né sul loro ordine. Il callback verrà chiamato il più vicino possibile al tempo specificato.

Quando delay è maggiore di 2147483647 o minore di 1 o NaN, delay verrà impostato su 1. I ritardi non interi vengono troncati a un intero.

Se callback non è una funzione, verrà generato un TypeError.

Questo metodo ha una variante personalizzata per le promise che è disponibile utilizzando timersPromises.setTimeout().

Annullamento dei timer

I metodi setImmediate(), setInterval() e setTimeout() restituiscono ciascuno oggetti che rappresentano i timer pianificati. Questi possono essere utilizzati per annullare il timer e impedirne l'attivazione.

Per le varianti promissificate di setImmediate() e setTimeout(), è possibile utilizzare un AbortController per annullare il timer. Quando annullate, le Promise restituite verranno rifiutate con un 'AbortError'.

Per setImmediate():

ESM

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

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

// Non aspettiamo la promise, quindi `ac.abort()` viene chiamato concorrentemente.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error("L'immediato è stato annullato")
  })

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("L'immediato è stato annullato")
  })

ac.abort()

Per setTimeout():

ESM

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

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

// Non aspettiamo la promise, quindi `ac.abort()` viene chiamato concorrentemente.
setTimeoutPromise(1000, 'foobar', { signal })
  .then(console.log)
  .catch(err => {
    if (err.name === 'AbortError') console.error('Il timeout è stato annullato')
  })

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('Il timeout è stato annullato')
  })

ac.abort()

clearImmediate(immediate)

Aggiunto in: v0.9.1

• immediate <Immediate> Un oggetto Immediate come restituito da setImmediate().

Annulla un oggetto Immediate creato da setImmediate().

clearInterval(timeout)

Aggiunto in: v0.0.1

• timeout <Timeout> | <string> | <number> Un oggetto Timeout come restituito da setInterval() o il primitivo dell'oggetto Timeout come stringa o numero.

Annulla un oggetto Timeout creato da setInterval().

clearTimeout(timeout)

Aggiunto in: v0.0.1

• timeout <Timeout> | <string> | <number> Un oggetto Timeout come restituito da setTimeout() o il primitivo dell'oggetto Timeout come stringa o numero.

Annulla un oggetto Timeout creato da setTimeout().

API delle Promise dei Timer

[Cronologia]

Versione	Modifiche
v16.0.0	Passato dalla fase sperimentale.
v15.0.0	Aggiunto in: v15.0.0

L'API timers/promises fornisce un set alternativo di funzioni timer che restituiscono oggetti Promise. L'API è accessibile tramite require('node:timers/promises').

ESM

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

CJS

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

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

Aggiunto in: v15.0.0

• delay <number> Il numero di millisecondi da attendere prima di risolvere la promise. Default: 1.
• value <any> Un valore con cui la promise viene risolta.
• options <Object>
  • ref <boolean> Impostato su false per indicare che il Timeout pianificato non richiede che il loop degli eventi di Node.js rimanga attivo. Default: true.
  • signal <AbortSignal> Un AbortSignal opzionale che può essere utilizzato per annullare il Timeout pianificato.

ESM

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

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

console.log(res) // Stampa 'result'

CJS

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

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

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

Aggiunto in: v15.0.0

• value <any> Un valore con cui la promise viene risolta.
• options <Object>
  • ref <boolean> Impostato su false per indicare che l'Immediate pianificato non richiede che il loop degli eventi di Node.js rimanga attivo. Default: true.
  • signal <AbortSignal> Un AbortSignal opzionale che può essere utilizzato per annullare l'Immediate pianificato.

ESM

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

const res = await setImmediate('result')

console.log(res) // Stampa 'result'

CJS

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

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

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

Aggiunto in: v15.9.0

Restituisce un iteratore asincrono che genera valori a intervalli di delay ms. Se ref è true, è necessario chiamare next() dell'iteratore asincrono esplicitamente o implicitamente per mantenere attivo il loop dell'event loop.

• delay <number> Il numero di millisecondi da attendere tra le iterazioni. Default: 1.
• value <any> Un valore con cui l'iteratore restituisce.
• options <Object>
  • ref <boolean> Impostato su false per indicare che il Timeout pianificato tra le iterazioni non richiede che il loop degli eventi di Node.js rimanga attivo. Default: true.
  • signal <AbortSignal> Un AbortSignal opzionale che può essere utilizzato per annullare il Timeout pianificato tra le operazioni.

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

Aggiunto in: v17.3.0, v16.14.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• delay <number> Il numero di millisecondi da attendere prima di risolvere la promise.

• options <Object>

  • ref <boolean> Impostato su false per indicare che il Timeout pianificato non richiede che il loop degli eventi di Node.js rimanga attivo. Default: true.
  • signal <AbortSignal> Un AbortSignal opzionale che può essere utilizzato per annullare l'attesa.

• Restituisce: <Promise>

Un'API sperimentale definita dalla bozza di specifica Scheduling APIs in fase di sviluppo come API standard della piattaforma Web.

Chiamare timersPromises.scheduler.wait(delay, options) è equivalente a chiamare timersPromises.setTimeout(delay, undefined, options).

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

await scheduler.wait(1000) // Attendi un secondo prima di continuare

timersPromises.scheduler.yield()

Aggiunto in: v17.3.0, v16.14.0

[Stabile: 1 - Sperimentale]

Stabile: 1 Stabilità: 1 - Sperimentale

• Restituisce: <Promise>

Un'API sperimentale definita dalla bozza di specifica delle API di pianificazione in fase di sviluppo come API standard della piattaforma Web.

Chiamare timersPromises.scheduler.yield() è equivalente a chiamare timersPromises.setImmediate() senza argomenti.