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,11 @@ 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) {
+	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,12 @@
+<?php
+
+// Worker that sleeps inside the handler to simulate a stuck request blocking
+// drain. Used to test the force-kill grace period.
+$fn = static function () {
+    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,6 +166,13 @@ 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
+
 // EXPERIMENTAL: DrainWorkers finishes all worker scripts before a graceful shutdown
 func DrainWorkers() {
 	_ = drainWorkerThreads()
@@ -201,7 +209,31 @@ func drainWorkerThreads() []*phpThread {
 		worker.threadMutex.RUnlock()
 	}
 
-	ready.Wait()
+	// Wait for graceful drain, then arm the force-kill primitive on any
+	// thread still stuck. Linux/FreeBSD ZTS arms PHP's max_execution_time
+	// timer; Windows interrupts blocking I/O and alertable waits; other
+	// platforms leave the thread abandoned (it will exit when the blocking
+	// call returns).
+	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")
+		}
+		<-done
+	}
 
 	return drainedThreads
 }

worker_test.go

@@ -9,13 +9,17 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"net/url"
+	"os"
+	"runtime"
 	"strconv"
 	"strings"
 	"sync"
 	"testing"
+	"time"
 
 	"github.com/dunglas/frankenphp"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func TestWorker(t *testing.T) {
@@ -45,6 +49,56 @@ func TestWorker(t *testing.T) {
 	}, &testOptions{workerScript: "worker.php", nbWorkers: 1, nbParallelRequests: 1})
 }
 
+// TestRestartWorkersForceKillsStuckThread verifies that the drain path used
+// by RestartWorkers and DrainWorkers does not hang indefinitely when a
+// worker thread is stuck inside a blocking PHP call (sleep, synchronous
+// I/O, etc.). The force-kill primitive delivers a realtime signal to the
+// thread on Linux/FreeBSD (interrupts the syscall with EINTR) or calls
+// CancelSynchronousIo + QueueUserAPC on Windows. macOS has no realtime
+// signal exposed to user-space, so a thread stuck in sleep() cannot be
+// force-unblocked there; skip the test.
+func TestRestartWorkersForceKillsStuckThread(t *testing.T) {
+	if runtime.GOOS != "linux" && runtime.GOOS != "freebsd" && runtime.GOOS != "windows" {
+		t.Skipf("force-kill cannot interrupt blocking syscalls on %s", runtime.GOOS)
+	}
+
+	cwd, _ := os.Getwd()
+	testDataDir := cwd + "/testdata/"
+
+	require.NoError(t, frankenphp.Init(
+		frankenphp.WithWorkers("sleep-worker", testDataDir+"worker-sleep.php", 1),
+		frankenphp.WithNumThreads(2),
+	))
+	t.Cleanup(frankenphp.Shutdown)
+
+	// Fire a request the worker will handle and then block on (sleep 60s).
+	// When the drain runs, the worker script is inside the handler callback,
+	// below frankenphp_handle_request, so the drain signal on drainChan
+	// can't be observed until the blocking sleep returns.
+	go func() {
+		req := httptest.NewRequest("GET", "http://example.com/worker-sleep.php", nil)
+		fr, err := frankenphp.NewRequestWithContext(req, frankenphp.WithRequestDocumentRoot(testDataDir, false))
+		if err != nil {
+			return
+		}
+		_ = frankenphp.ServeHTTP(httptest.NewRecorder(), fr)
+	}()
+
+	// Give the request time to reach the handler and enter sleep().
+	time.Sleep(500 * time.Millisecond)
+
+	// RestartWorkers must complete within the grace period + a bit of slack.
+	// Without force-kill, it would wait for the 60s sleep to return.
+	start := time.Now()
+	frankenphp.RestartWorkers()
+	elapsed := time.Since(start)
+
+	// Grace period is 5s; allow margin for SIGALRM dispatch, PHP VM tick,
+	// and the drain's final ready.Wait() plus the restart loop.
+	const budget = 8 * time.Second
+	assert.Less(t, elapsed, budget, "drain must force-kill the stuck thread within the grace period")
+}
+
 func TestWorkerDie(t *testing.T) {
 	runTest(t, func(handler func(http.ResponseWriter, *http.Request), _ *httptest.Server, i int) {
 		req := httptest.NewRequest("GET", "http://example.com/die.php", nil)