[13.x] Resume sleeping when Sleep is interrupted by a signal

[dhrupo]

Fixes #56647

The problem

Calling Sleep inside a queued job can wake up early. For example:

public function handle(): void
{
    Log::debug('Should sleep for 60 seconds');

    Sleep::for(60)->seconds();

    Log::debug('Should be awake now'); // logged well before 60s have elapsed
}

The job logs "Should be awake now" before the full 60 seconds have passed. The same code sleeps correctly outside of a queue worker.

Root cause

Sleep::goodnight() performs the actual sleeping:

if ($seconds > 0) {
    sleep($seconds);

    $remaining = $remaining->subSeconds($seconds);
}

PHP's sleep() returns the number of seconds left to sleep if the call is interrupted by a signal (otherwise it returns 0). Queue workers — Horizon in the reported case — routinely deliver pcntl signals (timeout alarms, restart/termination signals, etc.). When one arrives mid-sleep, sleep() returns early, but goodnight() ignores the return value and assumes the whole duration was slept, so the remaining time is silently skipped.

This is straightforward to reproduce: an alarm scheduled with pcntl_alarm(1) interrupts sleep(3), which then returns 2 and elapses only one second.

The fix

Keep sleeping with the seconds that sleep() reports as remaining until the full duration has actually elapsed:

$secondsToSleep = $seconds;

while ($secondsToSleep > 0) {
    $secondsToSleep = sleep($secondsToSleep);
}

sleep() returns 0 on success and false on error — both end the loop — so an uninterrupted sleep behaves exactly as before. Only the interrupted case changes: it now resumes instead of returning early.

Tests

Added testItKeepsSleepingWhenInterruptedBySignal, which schedules a signal to interrupt a two-second sleep after one second and asserts the total elapsed time is still at least two seconds. It fails before this change (wakes after ~1s) and passes after it. The test skips automatically when the pcntl extension is unavailable.

The full tests/Support suite passes.

[taylorotwell]

What is the behavior if it receives a SIGTERM?

[dhrupo]

That's the weak spot here. The worker's SIGTERM handler only sets $shouldQuit and returns instead of exiting, so with this change the process would finish the leftover sleep before control gets back to the loop that checks the flag — delaying a graceful shutdown by up to the remaining duration, which is worse than waking early like it does today.

So resuming on every signal is wrong for termination signals specifically. It really needs to bail on SIGTERM/SIGINT (and the job timeout SIGALRM) and only resume on the benign ones, rather than the blanket loop I have here. I'll rework it that way if you think it's worth pursuing, otherwise happy to close it.

[rodrigopedra]

https://www.php.net/manual/en/function.sleep.php#refsect1-function.sleep-returnvalues

If the call was interrupted by a signal, sleep() returns a non-zero value. On Windows, this value will always be 192 (the value of the WAIT_IO_COMPLETION constant within the Windows API). On other platforms, the return value will be the number of seconds left to sleep.

I guess we should handle the Windows-specific return so a call to sleep won't sleep for an additional 192 seconds on every interrupt.