feat(preemption): bound the preempt drain and diagnose a coroutine that never cooperates

[lisachenko]

Closes #18, via Option 1 — bound the drain and report.

drainPreempted() resumed a preempt-suspended coroutine until it returned or parked — forever, for while (true) { $x++; }. Main returns, Go semantics say discard, and the process hung at shutdown with nothing to read.

The budget

64 resumes per coroutine per attempt, 1.0 s of wall clock per attempt, and at least one resume per coroutine whatever the clock says. Both halves are load-bearing: a resume is not itself time-bounded (S4 — one sort() over 4M ints defers the next slice ~2 s), and a clock alone could expire on a loaded machine before a coroutine was ever given a chance. The control run in the new S7 spike drains a 2M-iteration loop in six resumes, so 64 is an order of magnitude of headroom. Counts accumulate across attempts, and each attempt re-offers its budget to earlier stragglers.

Giving up is not letting go

A straggler moves to a set the scheduler holds for the rest of the process — the drain stopping is a decision about how long to keep resuming, never a decision to release the fiber. run() throws UndrainableCoroutineException naming each coroutine, the effort it was given, and the line that spawned it (already captured for the deadlock dump — zero new capture cost). A panic keeps precedence at run()'s boundary; the straggler is still reported at shutdown.

The ending — measured, not guessed

New spike S7 (spikes/s7_undrainable_fiber_exit.php, verdict in spikes/VERDICTS.md) measured every ending available with an undrainable fiber alive: letting the script end, uninstalling the hook first, and exit() all die at 255 on Throwing from FFI callbacks is not allowed — exit() included, because it still runs request shutdown, which is where the engine destroys the fiber. Holding the fiber in a static changes nothing. Only a self-directed signal ends the process without destroying it, keeping both output streams.

So the preemptor's shutdown backstop writes the diagnosis to STDERR and sends SIGKILL to itself — from a shutdown function registered during shutdown, so every application shutdown function still runs first (S7 --late-shutdown-function). SIGKILL rather than a politer signal because a handleable signal can be handled, and this one may not be declined: the only alternative is the fatal above. Without ext-posix the drain falls back to unbounded-but-diagnosed — the invariant outranks the hang. Criterion 3 holds throughout: the S6 fatal path is never reached.

One rule fell out and is now enforced: a drain may only resume while the slice timer is live — a resume returns because the next tick takes the CPU back, not because the coroutine hands it over. (The first working draft diagnosed correctly and then hung in the backstop for exactly this reason.)

A runaway now ends in ~1.3 s with the diagnosis on both streams instead of hanging forever; the exit status is 137 (by signal), with the STDERR diagnosis immediately preceding it.

Acceptance criteria from #18

• ☑ No hang; diagnosis names coroutine + spawn site — testACoroutineThatNeverCooperatesEndsTheRunWithADiagnosis.phpt, supervising the runaway in a child process with a deadline so a regression fails rather than hangs CI.
• ☑ A cooperating coroutine drains exactly as before — the existing drain tests, unchanged and green.
• ☑ No preempt-suspended fiber is ever released — testAnUndrainableCoroutineIsNeverLeftForTheEngineToDestroy.phpt asserts the absence of the FFI fatal, death by signal (not exit 255), the diagnosis on stderr, and that an earlier-registered application shutdown function still ran.

Verification

PHP 8.4.19, -d ffi.enable=1 -d opcache.jit=off: full suite OK (100 tests, 100 assertions), PHPStan level max clean, cs:check clean. PHP 8.5 is CI-only (local vendor resolves the 8.4 z-engine line); S7's 8.5 column is marked not-measured in VERDICTS.md rather than assumed.

Known trade-offs, stated rather than hidden: a coroutine needing >~0.64 s of CPU to reach its first safe point is reported alongside the truly hopeless (indistinguishable from here; the remedy is the same — give it a safe point); exit 137 is confusable with an OOM kill, mitigated by the immediately-preceding STDERR diagnosis; a runaway inside a worker surfaces at the parent as WorkerCrashedException (killed by signal 9) with the child's diagnosis on shared stderr.

🤖 Generated with Claude Code

https://claude.ai/code/session_01U5QRWPfmkZME7hDjU6i5EA

---

Generated by Claude Code