feat: SentTaskHandle and ReceivedTaskHandle

[nicolas-grekas]

Stacked on #2617 and #2635, themselves on #2664: review the last six commits, from 00f32de.

The task half of #2319, rewritten on the background workers of #2617 and the shared vars of #2635. A request, an HTTP worker or another background worker hands work to a named background worker by constructing a FrankenPHP\SentTaskHandle(string $worker, array $payload, ?float $timeout = 30.0) and reads what comes back with read(): ?array; the worker dequeues a FrankenPHP\ReceivedTaskHandle with WorkerHandle::receive() and answers with update(array $data): void, complete(?array $data = null): void ending the task. One class per side, so each script only meets the one it uses and a wrong-end call cannot be written. Both are Io\Poll\Handle, like the worker handle of #2617, so a context follows several tasks without touching a stream. Names resolve like frankenphp_get_vars() does, payloads and updates follow the setVars() whitelist and travel as persistent tables through the Go side. Roughly 280 lines of Go and 330 of C.

The handle of #2617 is the only stream the worker needs: each task sent wakes a parked thread of the worker through it, so the loop of #2617 stays as it is, tick() consuming the wake-up and receive() dequeuing after it, EOF still meaning drain, and stream_select() users keep a single stream. A wake-up is not a count: in a pool the first thread back in its loop takes the task and the others get null from receive().

Constructing a SentTaskHandle blocks until a thread has picked the task up and throws on timeout, so a busy worker pushes back on its senders instead of queueing without bounds; null waits forever. Tasks queued while a thread restarts are signaled again on its next run, and the wait ends when the sender's own thread is drained for a restart or the shutdown, since the target's threads are drained too. Each handle exposes the stream of its side through getStream(), built on demand so a script waiting through a context allocates none, over a pair opened per task (the Windows php_select() rule of #2617), one byte per update and EOF at completion, so stream_select() bounds the wait or multiplexes tasks and a blocking read parks as well; abandon(), or dropping the handle, gives up on the task, which the worker's stream reports as EOF to stream_select() and feof(), and the worker's next update() throws. The receiver's handle completes the task when it is closed or dropped, unless that is the resource cleanup of request shutdown, which means the script ended with the task open: the sender's next read() throws instead of returning null. Past the end of a task, getStream() hands the stream back closed, the way the poll hooks report an invalid descriptor, so a context that still watches it reads the end from is_resource() rather than an exception; anything else throws, closing twice does not, and the payload outlives it. Sixteen updates are buffered per task, past that update() waits for the sender to read.

Waking threads is what a task costs, so wake-ups are kept to a minimum. A send wakes one parked thread of the worker, round-robin, through its handle; tick() parks the thread for the senders and, when tasks are already queued, makes the coming wait return at once, so no wake-up is lost whichever loop shape the script uses, and after 10ms without pickup every thread is woken as a fallback. The sender waits for the pickup in the kernel, on its end of the task's pair, rather than in a Go select: waking a PHP thread parked inside a cgo callback costs Go a P hand-off, a byte on a socket does not. The queue mutex is never held across a syscall and taken once per wake-up, since a thread inside a cgo callback that loses it parks the same expensive way. Benchmarked in the Docker builder image (the harness stayed out of the PR): a task went from 549 to 285µs with one thread, a pool of 8 from 1745 to 320µs, and 8 senders on 8 threads from 2k to 32k tasks/s.

Each side of a task waits on its own descriptor of the task's channel, an eventfd on Linux, a kqueue descriptor carrying a user event on macOS, one end of a socket pair elsewhere for Windows's php_select(): the streams carry no data, they are what stream_select() waits on and what fclose() ends, the Go side holds the state the functions report. The descriptors belong to the task until both sides closed, then the pair is drained and pooled, so a task costs no socketpair, fcntl or close: about 12 syscalls instead of 18, 13% off the latency and up to a third more throughput under load in the same measurement.

Tasks are referenced from the streams through cgo handles and freed once both sides closed, or by the sender when nobody picked the task up. The stop sockets of a worker's threads are now guarded by its task-queue mutex, since senders write to them.

Its metrics come with it, since the existing ones would otherwise report a background worker as idle while it works: frankenphp_busy_workers counts a thread holding a task, from pickup to the close of the task's stream, and frankenphp_worker_queue_depth the tasks waiting for a thread, the only queue a background worker has. Two counters break tasks down, frankenphp_worker_task_count{worker,server,outcome} with completed, aborted (the script ended with the task open), abandoned (the sender gave up first) and timeout (no thread picked the task up in time), settled by whichever side closes first so every task counts exactly once, and frankenphp_worker_task_time{worker,server}, the seconds spent on tasks. The /frankenphp/threads endpoint follows, a background thread being busy while it holds a task, and the ServerMetrics interface of #2617 gains StartWorkerTask, StopWorkerTask and WorkerTaskOutcome.

Compared to #2319: no queue ahead of pickup and no cancellation before it, no dedicated signaling stream, no global task table, no metrics yet.

[nicolas-grekas]

Pushed 23d3094 after benchmarking the task path in the Docker builder image (harness kept out of the PR). Three changes: a send wakes one parked thread instead of every thread of the pool; the sender waits for the pickup in the kernel, on the task's socket, instead of in a Go select (waking a thread parked inside a cgo callback costs the scheduler a P hand-off); and the queue mutex is no longer held across a syscall nor taken twice per wake-up. One thread: 549 to 285µs per task. A pool of 8: 1745 to 320µs. 8 senders on 8 threads: 2k to 32k tasks/s. Absolute numbers are that VM's, the ratios are the point.