time_sleep_until()

La funzione PHP time_sleep_until() mette in pausa uno script fino a un punto assoluto nel tempo, espresso come timestamp Unix. A differenza di sleep(), che attende per una durata ("dormi 10 secondi"), questa funzione attende fino a un momento preciso ("dormi fino alle 14:30:00"). Questo articolo ne illustra la sintassi, il valore restituito, i casi limite e quando è opportuno utilizzarla.

Sintassi

time_sleep_until(float $timestamp): bool

• $timestamp — il timestamp Unix (secondi dall'epoca) al quale lo script deve riprendere l'esecuzione. Poiché il parametro è un float, è possibile passare secondi frazionari per una precisione inferiore al secondo (ad esempio time() + 2.5).
• Valore restituito — restituisce true in caso di successo e false in caso di errore.

Se il timestamp fornito è già nel passato, la funzione ritorna immediatamente senza attendere. In PHP 8 restituisce false ed emette un avviso; in PHP 7 restituiva anch'essa false. In ogni caso, lo script non si blocca — quindi non fare affidamento sulla chiamata per "attendere" quando il momento target è già trascorso.

Come usare la funzione time_sleep_until()

Chiama la funzione passando il timestamp al quale lo script deve riprendere. Il pattern più comune è aggiungere un offset al tempo corrente restituito da time():

Qui time() + 10 è un timestamp Unix assoluto dieci secondi nel futuro. time_sleep_until() si blocca finché l'orologio di sistema non raggiunge quel valore, dopodiché l'esecuzione continua e stampa il messaggio finale.

Attendere l'inizio del prossimo minuto intero

Poiché si passa un tempo assoluto, time_sleep_until() è ideale per allineare il lavoro a un confine di orologio — ad esempio, eseguire un'operazione esattamente all'inizio del prossimo minuto:

<?php
$now  = time();
$next = $now - ($now % 60) + 60; // round up to the next whole minute
echo "Now: " . date('H:i:s', $now) . "\n";
time_sleep_until($next);
echo "Resumed at: " . date('H:i:s', $next) . "\n";
?>

L'espressione $now - ($now % 60) + 60 elimina i secondi dal timestamp corrente e aggiunge 60, ottenendo il timestamp del minuto successivo. Questo approccio è più preciso di sleep(60), che potrebbe slittare se lo script è partito a metà minuto.

Precisione sub-secondaria

Passare un timestamp frazionario introduce un ritardo inferiore al secondo:

<?php
$start = microtime(true);
time_sleep_until(microtime(true) + 0.25); // wait 250 ms
echo "Waited " . round(microtime(true) - $start, 2) . " seconds\n";
?>

Per mettere in pausa per una durata piuttosto che fino a un momento assoluto, preferisci usleep() (microsecondi) o time_nanosleep() (nanosecondi).

time_sleep_until() vs sleep()

Scegli time_sleep_until() quando conosci l'ora esatta dell'orologio alla quale vuoi riprendere; scegli sleep()/usleep() quando ti interessa solo quanto tempo aspettare. Puoi costruire il timestamp target con funzioni ausiliarie come time() o microtime().

Considerazioni sulle prestazioni

time_sleep_until() blocca il processo corrente fino al raggiungimento del momento target. Utilizza CPU minima durante l'attesa, ma un processo bloccato rimane comunque fermo: in una richiesta web, un'attesa prolungata può superare il limite max_execution_time o il timeout del server web, generando un errore 504. È quindi più adatta a script CLI, cron job e processi worker piuttosto che a richieste utente. Evita di chiamarla in percorsi critici per le prestazioni e mantieni l'attesa breve in qualsiasi contesto HTTP.

Conclusione

time_sleep_until() mette in pausa uno script fino a un timestamp Unix assoluto, rendendola lo strumento giusto per ritardi allineati all'orologio dove sleep() permetterebbe solo di specificare una durata. Ricorda che restituisce true/false, non si blocca mai per un timestamp passato, accetta secondi frazionari e impegna l'intero processo durante l'attesa — quindi riservala al codice CLI e worker piuttosto che alle richieste web.

Esercizio