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 momento futuro. Poiché le funzioni del timer sono globali, non è necessario chiamare require('node:timers') per utilizzare l'API.

Le funzioni del timer all'interno di Node.js implementano un'API simile all'API dei timer fornita dai browser Web, ma utilizzano un'implementazione interna diversa che è costruita attorno al Ciclo di eventi 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 immediate, il ciclo di eventi di Node.js continuerà a essere eseguito finché l'immediate è attivo. L'oggetto Immediate restituito da setImmediate() esporta entrambe le funzioni immediate.ref() e immediate.unref() che possono essere utilizzate per controllare questo comportamento predefinito.

immediate.hasRef()

Aggiunto in: v11.0.0

• Restituisce: <boolean>

Se true, l'oggetto Immediate manterrà attivo il ciclo di eventi di Node.js.

immediate.ref()

Aggiunto in: v9.7.0

• Restituisce: <Immediate> un riferimento a immediate

Quando viene chiamata, richiede che il ciclo di eventi di Node.js non si chiuda fintanto che l'Immediate è attivo. Chiamare immediate.ref() più volte non avrà alcun effetto.

Per impostazione predefinita, tutti gli oggetti Immediate sono "ref'ed", rendendo normalmente non necessario 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 ciclo di eventi di Node.js rimanga attivo. Se non ci sono altre attività che mantengono in esecuzione il ciclo di eventi, il processo potrebbe terminare prima che venga invocato il callback dell'oggetto Immediate. Chiamare immediate.unref() più volte non avrà alcun effetto.

immediate[Symbol.dispose]()

Aggiunto in: v20.5.0, v18.18.0

[Stable: 1 - Experimental]

Stable: 1 Stabilità: 1 - Sperimentale

Annulla l'immediate. Questo è simile alla chiamata a 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 utilizzando setTimeout() o setInterval(), il ciclo di eventi di Node.js continuerà a essere eseguito 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

[Stable: 3 - Legacy]

Stable: 3 Stabilità: 3 - Legacy: Utilizzare invece clearTimeout().

• 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 ciclo di eventi di Node.js.

timeout.ref()

Aggiunto in: v0.9.1

• Restituisce: <Timeout> un riferimento a timeout

Quando chiamata, richiede che il ciclo di eventi di Node.js non si chiuda fintanto che il Timeout è attivo. Chiamare timeout.ref() più volte non avrà alcun effetto.

Per impostazione predefinita, tutti gli oggetti Timeout sono "ref'ed", rendendo normalmente non necessario 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 all'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.

Usare questo 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 chiamato, l'oggetto Timeout attivo non richiederà che il ciclo di eventi di Node.js rimanga attivo. Se non ci sono altre attività che mantengono attivo il ciclo di eventi, il processo potrebbe terminare prima che venga richiamata 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: <integer> un numero che può essere usato per fare riferimento a questo timeout

Forza 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 usarlo attraverso 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 è un costrutto interno che chiama una determinata funzione dopo un certo periodo di tempo. Il momento in cui viene chiamata la funzione di un timer varia a seconda del metodo utilizzato per creare il timer e del lavoro svolto dal ciclo di eventi di Node.js.

setImmediate(callback[, ...args])

[Cronologia]

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

• callback <Function> La funzione da chiamare alla fine di questo turno del Ciclo di eventi di Node.js
• ...args <any> Argomenti opzionali da passare quando viene chiamata la callback.
• Restituisce: <Immediate> per l'utilizzo con clearImmediate()

Pianifica l'esecuzione "immediata" della callback dopo le callback degli eventi I/O.

Quando vengono effettuate più chiamate a setImmediate(), le funzioni callback vengono accodate per l'esecuzione nell'ordine in cui vengono create. L'intera coda di callback viene elaborata a ogni iterazione del ciclo di eventi. Se un timer immediato viene accodato dall'interno di una callback in esecuzione, quel timer non verrà attivato fino alla successiva iterazione del ciclo di eventi.

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

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

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

[Cronologia]

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

• callback <Function> La funzione da chiamare quando il timer scade.
• delay <number> Il numero di millisecondi da attendere prima di chiamare la callback. Predefinito: 1.
• ...args <any> Argomenti opzionali da passare quando viene chiamata la callback.
• Restituisce: <Timeout> per l'utilizzo con clearInterval()

Pianifica l'esecuzione ripetuta di callback ogni delay millisecondi.

Quando delay è maggiore di 2147483647 o inferiore a 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.setInterval().

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

[Cronologia]

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

• callback <Function> La funzione da chiamare quando il timer scade.
• delay <number> Il numero di millisecondi da attendere prima di chiamare la callback. Predefinito: 1.
• ...args <any> Argomenti opzionali da passare quando viene chiamata la callback.
• Restituisce: <Timeout> per l'uso con clearTimeout()

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

È probabile che la callback non venga richiamata esattamente dopo delay millisecondi. Node.js non fornisce garanzie sui tempi esatti di attivazione delle callback, né sul loro ordine. La callback verrà chiamata il più vicino possibile all'ora specificata.

Quando delay è maggiore di 2147483647 o inferiore a 1 o NaN, il 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 disponibile tramite 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 promesse di setImmediate() e setTimeout(), è possibile utilizzare un AbortController per annullare il timer. Quando viene annullato, 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 `await` la promise, quindi `ac.abort()` viene chiamato contemporaneamente.
setImmediatePromise('foobar', { signal })
  .then(console.log)
  .catch((err) => {
    if (err.name === 'AbortError')
      console.error('L'immediate è stato interrotto');
  });

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'immediate è stato interrotto');
  });

ac.abort();

Per setTimeout():

ESM

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

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

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

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 interrotto');
  });

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 Timer basate su Promise

[Cronologia]

Versione	Modifiche
v16.0.0	Uscito 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 soddisfare la promise. Predefinito: 1.
• value <any> Un valore con cui la promise viene soddisfatta.
• options <Object>
  • ref <boolean> Imposta su false per indicare che il Timeout pianificato non dovrebbe richiedere che il ciclo di eventi di Node.js rimanga attivo. Predefinito: 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 soddisfatta.
• options <Object>
  • ref <boolean> Imposta su false per indicare che l'Immediate pianificato non dovrebbe richiedere che il ciclo di eventi di Node.js rimanga attivo. Predefinito: 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 in un intervallo di delay ms. Se ref è true, è necessario chiamare next() dell'iteratore asincrono esplicitamente o implicitamente per mantenere attivo il ciclo di eventi.

• delay <number> Il numero di millisecondi da attendere tra le iterazioni. Predefinito: 1.
• value <any> Un valore con cui l'iteratore restituisce.
• options <Object>
  • ref <boolean> Imposta su false per indicare che il Timeout pianificato tra le iterazioni non dovrebbe richiedere che il ciclo di eventi di Node.js rimanga attivo. Predefinito: 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> Imposta su false per indicare che il Timeout pianificato non dovrebbe richiedere che il ciclo di eventi di Node.js rimanga attivo. Predefinito: true.
  • signal <AbortSignal> Un AbortSignal opzionale che può essere utilizzato per annullare l'attesa.

• Restituisce: <Promise>

Un'API sperimentale definita dalla bozza di 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 Scheduling APIs in fase di sviluppo come API standard della piattaforma Web.

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