feat: cross-platform force-kill primitive for stuck PHP threads

Introduces a small, self-contained primitive that unblocks a PHP thread
stuck in a blocking call (sleep, synchronous I/O, etc.) so the graceful
drain used by RestartWorkers and DrainWorkers can make progress instead
of waiting for the block to return on its own. The primitive is useful
on its own and gives follow-up graceful-shutdown work a reviewed
foundation to build on.

- frankenphp.c: add frankenphp_init_force_kill / frankenphp_save_php_timer
  / frankenphp_force_kill_thread / frankenphp_destroy_force_kill. The
  per-thread PHP timer handle (Linux/FreeBSD ZTS) or OS thread handle
  (Windows) is captured at thread boot and stored in a pre-sized array
  so the kill path can fire from any goroutine without touching
  per-thread PHP state. Linux/FreeBSD arm PHP's max_execution_time timer
  (delivers SIGALRM -> "Maximum execution time exceeded"); Windows uses
  CancelSynchronousIo + QueueUserAPC to interrupt I/O and alertable
  waits; macOS and other platforms are a safe no-op (the thread is
  abandoned and exits when the blocking call returns naturally).

- phpmainthread.go: wire frankenphp_init_force_kill into initPHPThreads
  (sized to maxThreads, matching the thread_metrics allocation) and
  frankenphp_destroy_force_kill into drainPHPThreads.

- worker.go: add a 5-second graceful-drain grace period to
  drainWorkerThreads. Once elapsed, arm the force-kill primitive on any
  thread still outside Yielding and keep waiting on ready.Wait(); the
  kill lets the thread return from its blocking call so the drain
  completes in bounded time instead of hanging.

- worker_test.go + testdata/worker-sleep.php: TestRestartWorkersForceKillsStuckThread
  drives the path end-to-end. A worker blocks inside sleep(60) below
  frankenphp_handle_request (so drainChan close can't reach it); the
  test asserts RestartWorkers returns within 8s (grace + slack). The
  test skips on platforms without the underlying primitive.

Author: nicolas-grekas

frankenphp.c

@@ -92,6 +92,115 @@ static bool is_forked_child = false;
 static void frankenphp_fork_child(void) { is_forked_child = true; }
 #endif
 
+/* Best-effort force-kill for PHP threads after the graceful-drain grace
+ * period. Each thread captures pointers to its own executor_globals'
+ * vm_interrupt and timed_out atomic bools at boot and hands them back to
+ * Go via go_frankenphp_store_force_kill_slot. From any goroutine, the
+ * Go side passes that slot back to frankenphp_force_kill_thread, which
+ * stores true into both bools, waking the VM at the next opcode boundary
+ * and unwinding the thread through zend_timeout().
+ *
+ * On platforms with POSIX realtime signals (Linux, FreeBSD), force-kill
+ * also delivers SIGRTMIN+3 to the target thread so any in-flight blocking
+ * syscall (select, sleep, nanosleep, blocking I/O without SA_RESTART)
+ * returns EINTR and the VM gets a chance to observe the atomic bools on
+ * the next opcode. On Windows, CancelSynchronousIo + QueueUserAPC does
+ * the equivalent for alertable I/O and SleepEx. Non-alertable Sleep()
+ * (including PHP's usleep on Windows) stays uninterruptible - the VM
+ * must wait for it to return naturally before bailing.
+ *
+ * macOS has no realtime signals exposed to user-space, so the atomic
+ * bool path is the only mechanism there: threads busy-looping in PHP
+ * are killed promptly, threads stuck in blocking syscalls wait to
+ * return on their own.
+ *
+ * The slot lives in the Go-side phpThread struct - there is no C-side
+ * array or init/destroy dance. Signal handler installation happens once
+ * via pthread_once the first time a thread registers. */
+#ifdef PHP_WIN32
+static void CALLBACK frankenphp_noop_apc(ULONG_PTR param) { (void)param; }
+#endif
+
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+/* No-op handler: signal delivery is sufficient on its own because it
+ * forces the in-flight syscall to return EINTR. The VM then observes
+ * vm_interrupt on the next opcode and unwinds via zend_timeout(). */
+static void frankenphp_kill_signal_handler(int sig) { (void)sig; }
+
+static pthread_once_t kill_signal_handler_installed = PTHREAD_ONCE_INIT;
+static void install_kill_signal_handler(void) {
+  /* Install the no-op handler process-wide with SA_RESTART cleared so
+   * blocking syscalls return EINTR when the signal is delivered rather
+   * than being transparently restarted by libc. */
+  struct sigaction sa;
+  memset(&sa, 0, sizeof(sa));
+  sa.sa_handler = frankenphp_kill_signal_handler;
+  sigemptyset(&sa.sa_mask);
+  sa.sa_flags = 0;
+  sigaction(FRANKENPHP_KILL_SIGNAL, &sa, NULL);
+}
+#endif
+
+/* Called by each PHP thread at boot, from its own TSRM context, so that
+ * the EG-backed addresses resolve to the thread's private executor_globals
+ * and the captured thread identity refers to itself. Hands the slot to
+ * the Go side via go_frankenphp_store_force_kill_slot; the slot's
+ * lifetime is the phpThread's. */
+void frankenphp_register_thread_for_kill(uintptr_t idx) {
+  force_kill_slot slot;
+  memset(&slot, 0, sizeof(slot));
+  slot.vm_interrupt = &EG(vm_interrupt);
+  slot.timed_out = &EG(timed_out);
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  slot.tid = pthread_self();
+  pthread_once(&kill_signal_handler_installed, install_kill_signal_handler);
+#elif defined(PHP_WIN32)
+  if (!DuplicateHandle(GetCurrentProcess(), GetCurrentThread(),
+                       GetCurrentProcess(), &slot.thread_handle, 0, FALSE,
+                       DUPLICATE_SAME_ACCESS)) {
+    /* DuplicateHandle can fail under resource pressure; leave the handle
+     * NULL so force_kill_thread falls back to the atomic-bool path only. */
+    slot.thread_handle = NULL;
+  }
+#endif
+  go_frankenphp_store_force_kill_slot(idx, slot);
+}
+
+void frankenphp_force_kill_thread(force_kill_slot slot) {
+  if (slot.vm_interrupt == NULL) {
+    /* Thread never reached register_thread_for_kill (aborted during boot). */
+    return;
+  }
+  /* Set the atomic bools first so that by the time the thread wakes up -
+   * whether from our signal/APC or naturally - the VM sees them and
+   * routes through zend_timeout() -> "Maximum execution time exceeded". */
+  zend_atomic_bool_store(slot.timed_out, true);
+  zend_atomic_bool_store(slot.vm_interrupt, true);
+
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  /* Return value intentionally ignored: ESRCH (thread already exited) and
+   * EINVAL are both benign - there is simply nothing to unblock. */
+  pthread_kill(slot.tid, FRANKENPHP_KILL_SIGNAL);
+#elif defined(PHP_WIN32)
+  if (slot.thread_handle != NULL) {
+    CancelSynchronousIo(slot.thread_handle);
+    QueueUserAPC((PAPCFUNC)frankenphp_noop_apc, slot.thread_handle, 0);
+  }
+#endif
+}
+
+/* Releases any OS resource tied to the slot (currently: CloseHandle on
+ * Windows). Called by the Go side when a phpThread is torn down. */
+void frankenphp_release_thread_for_kill(force_kill_slot slot) {
+#ifdef PHP_WIN32
+  if (slot.thread_handle != NULL) {
+    CloseHandle(slot.thread_handle);
+  }
+#else
+  (void)slot;
+#endif
+}
+
 void frankenphp_update_local_thread_context(bool is_worker) {
   is_worker_thread = is_worker;
 
@@ -1073,6 +1182,11 @@ static void *php_thread(void *arg) {
 #endif
 #endif
 
+  /* Register this thread's vm_interrupt/timed_out addresses so the Go side
+   * can force-kill it after the graceful-drain grace period if it gets stuck
+   * in a busy PHP loop. */
+  frankenphp_register_thread_for_kill(thread_index);
+
   bool thread_is_healthy = true;
   bool has_attempted_shutdown = false;
 

frankenphp.h

@@ -46,6 +46,28 @@ static inline HRESULT LongLongSub(LONGLONG llMinuend, LONGLONG llSubtrahend,
 #include <stdbool.h>
 #include <stdint.h>
 
+#ifndef PHP_WIN32
+#include <pthread.h>
+#include <signal.h>
+#endif
+
+/* Platform capabilities for the force-kill primitive; declared in the
+ * header so Go (via CGo) gets the correct struct layout too. */
+#if !defined(PHP_WIN32) && defined(SIGRTMIN)
+#define FRANKENPHP_HAS_KILL_SIGNAL 1
+#define FRANKENPHP_KILL_SIGNAL (SIGRTMIN + 3)
+#endif
+
+typedef struct {
+  zend_atomic_bool *vm_interrupt;
+  zend_atomic_bool *timed_out;
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  pthread_t tid;
+#elif defined(PHP_WIN32)
+  HANDLE thread_handle;
+#endif
+} force_kill_slot;
+
 #ifndef FRANKENPHP_VERSION
 #define FRANKENPHP_VERSION dev
 #endif
@@ -193,6 +215,18 @@ void frankenphp_init_thread_metrics(int max_threads);
 void frankenphp_destroy_thread_metrics(void);
 size_t frankenphp_get_thread_memory_usage(uintptr_t thread_index);
 
+/* Best-effort force-kill primitives. The slot is populated by each PHP
+ * thread at boot (frankenphp_register_thread_for_kill calls back into Go
+ * via go_frankenphp_store_force_kill_slot) and lives in the Go-side
+ * phpThread. force_kill_thread interrupts the Zend VM at the next opcode
+ * boundary; on POSIX it also delivers SIGRTMIN+3 to the target thread,
+ * on Windows it calls CancelSynchronousIo + QueueUserAPC. release_thread
+ * drops any OS-owned resource tied to the slot (currently the Windows
+ * thread handle). */
+void frankenphp_register_thread_for_kill(uintptr_t thread_index);
+void frankenphp_force_kill_thread(force_kill_slot slot);
+void frankenphp_release_thread_for_kill(force_kill_slot slot);
+
 void register_extensions(zend_module_entry **m, int len);
 
 #endif

phpmainthread.go

@@ -97,6 +97,9 @@ func drainPHPThreads() {
 	}
 
 	doneWG.Wait()
+	for _, thread := range phpThreads {
+		C.frankenphp_release_thread_for_kill(thread.forceKill)
+	}
 	mainThread.state.Set(state.Done)
 	mainThread.state.WaitFor(state.Reserved)
 	C.frankenphp_destroy_thread_metrics()

phpthread.go

@@ -25,6 +25,11 @@ type phpThread struct {
 	contextMu    sync.RWMutex
 	state        *state.ThreadState
 	requestCount atomic.Int64
+	// forceKill is populated by go_frankenphp_store_force_kill_slot from
+	// the PHP thread's own TSRM context at boot. Read by other goroutines
+	// via RestartWorkers/DrainWorkers; the write-before-Ready state
+	// transition provides the happens-before edge.
+	forceKill C.force_kill_slot
 }
 
 // threadHandler defines how the callbacks from the C thread should be handled
@@ -203,6 +208,15 @@ func go_frankenphp_after_script_execution(threadIndex C.uintptr_t, exitStatus C.
 	thread.Unpin()
 }
 
+//export go_frankenphp_store_force_kill_slot
+func go_frankenphp_store_force_kill_slot(threadIndex C.uintptr_t, slot C.force_kill_slot) {
+	// Release any resource (Windows thread HANDLE) tied to the previous
+	// slot: a phpThread can reboot (max_requests, unhealthy restart) and
+	// register a fresh DuplicateHandle each time.
+	C.frankenphp_release_thread_for_kill(phpThreads[threadIndex].forceKill)
+	phpThreads[threadIndex].forceKill = slot
+}
+
 //export go_frankenphp_on_thread_shutdown
 func go_frankenphp_on_thread_shutdown(threadIndex C.uintptr_t) {
 	thread := phpThreads[threadIndex]

testdata/worker-sleep.php

@@ -0,0 +1,21 @@
+<?php
+
+// Worker that sleeps inside the handler to simulate a stuck request blocking
+// drain. Used to test the force-kill grace period.
+//
+// Before sleeping we touch a marker file whose path is passed via the
+// SLEEP_MARKER header. The Go test polls for the file so it only arms
+// RestartWorkers once the worker is proven to be inside sleep(), removing
+// the fixed-time race of a bare time.Sleep on the caller side.
+$fn = static function () {
+    $marker = $_SERVER['HTTP_SLEEP_MARKER'] ?? '';
+    if ($marker !== '') {
+        @touch($marker);
+    }
+    sleep(60);
+    echo 'should not reach';
+};
+
+do {
+    $ret = \frankenphp_handle_request($fn);
+} while ($ret);

worker.go

@@ -4,6 +4,7 @@ package frankenphp
 import "C"
 import (
 	"fmt"
+	"log/slog"
 	"os"
 	"path/filepath"
 	"runtime"
@@ -165,16 +166,27 @@ func newWorker(o workerOpt) (*worker, error) {
 	return w, nil
 }
 
+// drainGracePeriod is the time a worker thread has to stop gracefully after
+// receiving the drain signal before the force-kill primitive is armed on it.
+// Well-behaved scripts return promptly on drainChan close; stuck ones (e.g.
+// blocking C calls inside the VM) would otherwise hang drainWorkerThreads
+// forever.
+const drainGracePeriod = 5 * time.Second
+
+// forceKillDeadline is how long drainWorkerThreads waits after arming the
+// force-kill primitive before giving up. Force-kill is best-effort: on
+// macOS (no realtime signals) and on Windows non-alertable Sleep() it
+// cannot interrupt the blocking syscall, so we abandon the thread rather
+// than hang the drain forever.
+const forceKillDeadline = 5 * time.Second
+
 // EXPERIMENTAL: DrainWorkers finishes all worker scripts before a graceful shutdown
 func DrainWorkers() {
-	_ = drainWorkerThreads()
+	_, _ = drainWorkerThreads()
 }
 
-func drainWorkerThreads() []*phpThread {
-	var (
-		ready          sync.WaitGroup
-		drainedThreads []*phpThread
-	)
+func drainWorkerThreads() (drainedThreads []*phpThread, abandoned []*phpThread) {
+	var ready sync.WaitGroup
 
 	for _, worker := range workers {
 		worker.threadMutex.RLock()
@@ -193,17 +205,71 @@ func drainWorkerThreads() []*phpThread {
 			drainedThreads = append(drainedThreads, thread)
 
 			go func(thread *phpThread) {
-				thread.state.WaitFor(state.Yielding)
+				// Accept any state that releases us: Yielding is the
+				// graceful-drain goal; Ready covers the abandon path
+				// where RestartWorkers resumes the thread without it
+				// having yielded; ShuttingDown/Done covers shutdown.
+				// Without these extras, threads that never yield would
+				// leak this goroutine permanently across repeated
+				// RestartWorkers calls.
+				thread.state.WaitFor(state.Yielding, state.Ready, state.ShuttingDown, state.Done)
 				ready.Done()
 			}(thread)
 		}
 
 		worker.threadMutex.RUnlock()
 	}
 
-	ready.Wait()
+	// Wait for graceful drain, then arm the force-kill primitive on any
+	// thread still stuck. On Linux/FreeBSD pthread_kill(SIGRTMIN+3) breaks
+	// out of blocking syscalls; on Windows CancelSynchronousIo covers
+	// alertable waits and I/O. Platforms/syscalls where force-kill can't
+	// actually unblock the thread (macOS, Windows non-alertable Sleep,
+	// PHP's usleep on Windows) get logged and abandoned rather than
+	// blocking the drain forever.
+	done := make(chan struct{})
+	go func() {
+		ready.Wait()
+		close(done)
+	}()
+
+	select {
+	case <-done:
+		// everyone yielded in time
+	case <-time.After(drainGracePeriod):
+		for _, thread := range drainedThreads {
+			if !thread.state.Is(state.Yielding) {
+				C.frankenphp_force_kill_thread(thread.forceKill)
+			}
+		}
+		if globalLogger.Enabled(globalCtx, slog.LevelWarn) {
+			globalLogger.LogAttrs(globalCtx, slog.LevelWarn, "worker threads did not yield within grace period, force-killing stuck threads")
+		}
+		// Give the kill signal a bounded window to land. If the thread
+		// was in a syscall force-kill can't interrupt, we abandon it
+		// here rather than hanging RestartWorkers/DrainWorkers/Shutdown.
+		select {
+		case <-done:
+		case <-time.After(forceKillDeadline):
+			if globalLogger.Enabled(globalCtx, slog.LevelWarn) {
+				globalLogger.LogAttrs(globalCtx, slog.LevelWarn, "worker threads did not yield after force-kill; abandoning to unblock drain")
+			}
+		}
+	}
+
+	// Split drained threads into those that actually yielded (will go
+	// through the proper restart / opcache-reset path on resume) and
+	// those still stuck in a blocking syscall. Callers like
+	// RestartWorkers surface the abandoned count so watcher / admin
+	// restarts don't silently report success for threads that never
+	// reloaded code.
+	for _, thread := range drainedThreads {
+		if !thread.state.Is(state.Yielding) {
+			abandoned = append(abandoned, thread)
+		}
+	}
 
-	return drainedThreads
+	return drainedThreads, abandoned
 }
 
 // RestartWorkers attempts to restart all workers gracefully
@@ -213,12 +279,24 @@ func RestartWorkers() {
 	scalingMu.Lock()
 	defer scalingMu.Unlock()
 
-	threadsToRestart := drainWorkerThreads()
+	threadsToRestart, abandoned := drainWorkerThreads()
 
 	for _, thread := range threadsToRestart {
 		thread.drainChan = make(chan struct{})
 		thread.state.Set(state.Ready)
 	}
+
+	// Abandoned threads did not reach Yielding, so they will resume
+	// without going through the drain branch in threadworker.go that
+	// clears opcache and re-executes the worker script. That means
+	// "restart" did not actually reload code for those threads. Log
+	// loudly so watcher / admin callers do not silently report success.
+	if len(abandoned) > 0 && globalLogger.Enabled(globalCtx, slog.LevelError) {
+		globalLogger.LogAttrs(globalCtx, slog.LevelError,
+			"workers restart incomplete: some threads were stuck in an uninterruptible blocking call and did not reload code",
+			slog.Int("abandoned", len(abandoned)),
+			slog.Int("restarted", len(threadsToRestart)-len(abandoned)))
+	}
 }
 
 func (worker *worker) attachThread(thread *phpThread) {