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,143 @@ 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 registers pointers to its own executor_globals'
+ * vm_interrupt and timed_out atomic bools at boot; force_kill_thread
+ * stores true into both from any goroutine, which wakes the VM at the
+ * next opcode boundary and unwinds 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. */
+#if !defined(PHP_WIN32) && defined(SIGRTMIN)
+#define FRANKENPHP_HAS_KILL_SIGNAL 1
+#define FRANKENPHP_KILL_SIGNAL (SIGRTMIN + 3)
+
+/* 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; }
+#endif
+
+#ifdef PHP_WIN32
+static void CALLBACK frankenphp_noop_apc(ULONG_PTR param) { (void)param; }
+#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;
+
+static int force_kill_num_threads = 0;
+static force_kill_slot *thread_slots = NULL;
+
+void frankenphp_init_force_kill(int num_threads) {
+  thread_slots = calloc((size_t)num_threads, sizeof(force_kill_slot));
+  if (thread_slots == NULL) {
+    /* Out of memory at startup: leave force-kill disabled rather than crash
+     * later in register/kill. Graceful drain still works via the yielding
+     * path. */
+    force_kill_num_threads = 0;
+    return;
+  }
+
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  /* 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
+
+  force_kill_num_threads = num_threads;
+}
+
+/* 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. The pointers stay
+ * valid for the thread's lifetime. */
+void frankenphp_register_thread_for_kill(uintptr_t idx) {
+  if (thread_slots == NULL || idx >= (uintptr_t)force_kill_num_threads) {
+    return;
+  }
+  thread_slots[idx].vm_interrupt = &EG(vm_interrupt);
+  thread_slots[idx].timed_out = &EG(timed_out);
+#ifdef FRANKENPHP_HAS_KILL_SIGNAL
+  thread_slots[idx].tid = pthread_self();
+#elif defined(PHP_WIN32)
+  if (!DuplicateHandle(GetCurrentProcess(), GetCurrentThread(),
+                       GetCurrentProcess(), &thread_slots[idx].thread_handle, 0,
+                       FALSE, DUPLICATE_SAME_ACCESS)) {
+    /* DuplicateHandle can fail under resource pressure; leave the slot's
+     * handle NULL so force_kill_thread falls back to the atomic-bool path
+     * only and does not dereference an uninitialized handle. */
+    thread_slots[idx].thread_handle = NULL;
+  }
+#endif
+}
+
+void frankenphp_force_kill_thread(uintptr_t idx) {
+  if (thread_slots == NULL || idx >= (uintptr_t)force_kill_num_threads) {
+    return;
+  }
+  force_kill_slot slot = thread_slots[idx];
+  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
+}
+
+void frankenphp_destroy_force_kill(void) {
+#ifdef PHP_WIN32
+  if (thread_slots != NULL) {
+    for (int i = 0; i < force_kill_num_threads; i++) {
+      if (thread_slots[i].thread_handle != NULL) {
+        CloseHandle(thread_slots[i].thread_handle);
+      }
+    }
+  }
+#endif
+  free(thread_slots);
+  thread_slots = NULL;
+  force_kill_num_threads = 0;
+}
+
 void frankenphp_update_local_thread_context(bool is_worker) {
   is_worker_thread = is_worker;
 
@@ -1073,6 +1210,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

@@ -193,6 +193,13 @@ 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. Interrupt the Zend VM at the next
+ * opcode boundary; blocking syscalls are not woken. */
+void frankenphp_init_force_kill(int num_threads);
+void frankenphp_register_thread_for_kill(uintptr_t thread_index);
+void frankenphp_force_kill_thread(uintptr_t thread_index);
+void frankenphp_destroy_force_kill(void);
+
 void register_extensions(zend_module_entry **m, int len);
 
 #endif

phpmainthread.go

@@ -56,6 +56,12 @@ func initPHPThreads(numThreads int, numMaxThreads int, phpIni map[string]string)
 
 	C.frankenphp_init_thread_metrics(C.int(mainThread.maxThreads))
 
+	// initialize force-kill support: allocates per-thread slots that each PHP
+	// thread fills in at boot (frankenphp_register_thread_for_kill) so a
+	// thread stuck in a busy PHP loop can be interrupted after the
+	// graceful-drain grace period.
+	C.frankenphp_init_force_kill(C.int(mainThread.maxThreads))
+
 	// initialize all other threads
 	phpThreads = make([]*phpThread, mainThread.maxThreads)
 	phpThreads[0] = initialThread
@@ -97,6 +103,7 @@ func drainPHPThreads() {
 	}
 
 	doneWG.Wait()
+	C.frankenphp_destroy_force_kill()
 	mainThread.state.Set(state.Done)
 	mainThread.state.WaitFor(state.Reserved)
 	C.frankenphp_destroy_thread_metrics()

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(C.uintptr_t(thread.threadIndex))
+			}
+		}
+		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)