time_sleep_until()

La función time_sleep_until() de PHP pausa un script hasta un punto absoluto en el tiempo, expresado como una marca de tiempo Unix. A diferencia de sleep(), que espera una duración ("dormir 10 segundos"), esta función espera hasta un momento ("dormir hasta las 14:30:00"). Este artículo explica su sintaxis, valor de retorno, casos límite y cuándo usarla.

Sintaxis

time_sleep_until(float $timestamp): bool

• $timestamp — la marca de tiempo Unix (segundos desde la época) en la que el script debe reanudarse. Como el parámetro es un float, se pueden pasar segundos fraccionarios para precisión de subsegundos (por ejemplo, time() + 2.5).
• Valor de retorno — devuelve true en caso de éxito y false en caso de error.

Si la marca de tiempo proporcionada ya está en el pasado, la función retorna inmediatamente sin dormir. En PHP 8 devuelve false y emite una advertencia; en PHP 7 también devolvía false. En cualquier caso, el script no se bloquea, así que no confíes en que la llamada "espere" cuando el tiempo objetivo ya ha transcurrido.

Cómo usar la función time_sleep_until()

Llama a la función y pasa la marca de tiempo en la que el script debe reanudarse. El patrón más común es añadir un desplazamiento al tiempo actual devuelto por time():

Aquí time() + 10 es una marca de tiempo Unix absoluta diez segundos en el futuro. time_sleep_until() se bloquea hasta que el reloj del sistema alcanza ese valor, luego continúa la ejecución e imprime el mensaje final.

Esperar al próximo minuto completo

Como se pasa un tiempo absoluto, time_sleep_until() es ideal para alinear el trabajo con un límite de reloj — por ejemplo, ejecutar una tarea exactamente cuando comienza el próximo 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";
?>

La expresión $now - ($now % 60) + 60 elimina los segundos de la marca de tiempo actual y suma 60, dando la marca de tiempo del próximo minuto. Esto es más preciso que sleep(60), que podría desviarse si el script comenzó a mitad de un minuto.

Precisión de subsegundos

Pasar una marca de tiempo fraccionaria genera un retraso de una fracción de segundo:

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

Para pausar por una duración en lugar de hasta un momento absoluto, prefiere usleep() (microsegundos) o time_nanosleep() (nanosegundos).

time_sleep_until() vs sleep()

Elige time_sleep_until() cuando conozcas la hora exacta del reloj en la que deseas reanudar; elige sleep()/usleep() cuando solo importa cuánto tiempo pausar. Puedes construir la marca de tiempo objetivo con ayudantes como time() o microtime().

Consideraciones de rendimiento

time_sleep_until() bloquea el proceso actual hasta que se alcanza el tiempo objetivo. Utiliza muy poca CPU mientras espera, pero un proceso bloqueado sigue siendo uno detenido: en una solicitud web, una pausa prolongada puede alcanzar el límite de max_execution_time o el tiempo de espera de solicitud del servidor web y producir un error 504. Por ello, es más adecuada para scripts CLI, tareas cron y procesos trabajadores que para solicitudes orientadas al usuario. Evita llamarla en rutas críticas de rendimiento y mantén la espera corta en cualquier contexto HTTP.

Conclusión

time_sleep_until() pausa un script hasta una marca de tiempo Unix absoluta, lo que la convierte en la herramienta adecuada para retrasos alineados al reloj donde sleep() solo permitiría especificar una duración. Recuerda que devuelve true/false, nunca bloquea para una marca de tiempo en el pasado, acepta segundos fraccionarios y ocupa todo el proceso mientras espera — así que resérvala para código CLI y de trabajadores, no para solicitudes web.

Práctica