time_sleep_until()

Функция PHP time_sleep_until() приостанавливает выполнение скрипта до абсолютного момента времени, заданного в виде Unix-временно́й метки. В отличие от sleep(), которая ждёт определённую продолжительность («подождать 10 секунд»), эта функция ждёт наступления конкретного момента («ждать до 14:30:00»). В статье рассматриваются синтаксис, возвращаемое значение, граничные случаи и ситуации, когда уместно её применять.

Синтаксис

time_sleep_until(float $timestamp): bool

• $timestamp — Unix-временна́я метка (секунды с начала эпохи), при достижении которой скрипт должен возобновить работу. Поскольку параметр имеет тип float, можно передавать дробные секунды для субсекундной точности (например, time() + 2.5).
• Возвращаемое значение — возвращает true при успехе и false при ошибке.

Если переданная временна́я метка уже в прошлом, функция возвращает управление немедленно, не засыпая. В PHP 8 она возвращает false и выдаёт предупреждение; в PHP 7 также возвращала false. В любом случае скрипт не блокируется — поэтому не рассчитывайте на то, что вызов «подождёт», если целевое время уже истекло.

Как использовать функцию time_sleep_until()

Вызовите функцию и передайте временну́ю метку, при наступлении которой скрипт должен продолжить выполнение. Наиболее распространённый шаблон — прибавить смещение к текущему времени, возвращаемому функцией time():

Здесь time() + 10 — абсолютная Unix-метка через десять секунд. time_sleep_until() блокирует выполнение до тех пор, пока системные часы не достигнут этого значения, после чего выполнение продолжается и выводится итоговое сообщение.

Ожидание до начала следующей минуты

Поскольку передаётся абсолютное время, time_sleep_until() идеально подходит для выравнивания задач по границе часов — например, для запуска задачи точно в момент начала следующей минуты:

<?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";
?>

Выражение $now - ($now % 60) + 60 убирает секунды из текущей метки и прибавляет 60, получая временну́ю метку наступающей минуты. Это точнее, чем sleep(60), который смещается, если скрипт стартовал в середине минуты.

Субсекундная точность

Передача дробной временно́й метки задерживает выполнение на долю секунды:

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

Для паузы по продолжительности, а не до абсолютного момента, предпочтите usleep() (микросекунды) или time_nanosleep() (наносекунды).

time_sleep_until() vs sleep()

Используйте time_sleep_until(), когда точно знаете, в какой момент хотите возобновить выполнение; используйте sleep()/usleep(), когда важна только продолжительность паузы. Целевую временну́ю метку можно вычислить с помощью вспомогательных функций time() или microtime().

Производительность

time_sleep_until() блокирует текущий процесс до наступления целевого времени. В режиме ожидания она потребляет минимум CPU, однако заблокированный процесс по-прежнему простаивает: в веб-запросе длительный сон может исчерпать лимит max_execution_time или тайм-аут веб-сервера и породить ошибку 504. Поэтому функция лучше всего подходит для CLI-скриптов, cron-задач и рабочих процессов, а не для пользовательских запросов. Избегайте вызова в критичных по производительности местах и держите время ожидания коротким в любом HTTP-контексте.

Заключение

time_sleep_until() приостанавливает скрипт до абсолютной Unix-временно́й метки, что делает её подходящим инструментом для задержек, привязанных к часам, там, где sleep() позволяет задать лишь продолжительность. Помните: функция возвращает true/false, не блокируется при прошедшей метке, принимает дробные секунды и удерживает весь процесс во время ожидания — поэтому используйте её в CLI и фоновых процессах, а не в веб-запросах.

Практика