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,108 @@ static bool is_forked_child = false;
 static void frankenphp_fork_child(void) { is_forked_child = true; }
 #endif
 
+/* Best-effort force-kill for PHP threads stuck in blocking calls after the
+ * graceful-drain grace period. Cross-platform primitives with no dependency
+ * on any specific worker type; the Go side decides when to arm them.
+ * - Linux/FreeBSD ZTS: arm PHP's per-thread timer -> "max execution time" fatal
+ * - Windows: CancelSynchronousIo + QueueUserAPC -> interrupts I/O and sleeps
+ * - macOS/other: no-op (threads abandoned, exit when the blocking call returns)
+ *
+ * The timer/handle is captured by the thread itself at boot (see
+ * frankenphp_save_php_timer at the top of the PHP thread loop) so
+ * force_kill_thread can fire from any goroutine without touching per-thread
+ * PHP state directly. */
+static int force_kill_num_threads = 0;
+#ifdef ZEND_MAX_EXECUTION_TIMERS
+static timer_t *thread_php_timers = NULL;
+static bool *thread_php_timer_saved = NULL;
+#elif defined(PHP_WIN32)
+static HANDLE *thread_handles = NULL;
+static bool *thread_handle_saved = NULL;
+static void CALLBACK frankenphp_noop_apc(ULONG_PTR param) { (void)param; }
+#endif
+
+void frankenphp_init_force_kill(int num_threads) {
+  force_kill_num_threads = num_threads;
+#ifdef ZEND_MAX_EXECUTION_TIMERS
+  thread_php_timers = calloc(num_threads, sizeof(timer_t));
+  thread_php_timer_saved = calloc(num_threads, sizeof(bool));
+#elif defined(PHP_WIN32)
+  thread_handles = calloc(num_threads, sizeof(HANDLE));
+  thread_handle_saved = calloc(num_threads, sizeof(bool));
+#endif
+}
+
+void frankenphp_save_php_timer(uintptr_t idx) {
+  if (idx >= (uintptr_t)force_kill_num_threads) {
+    return;
+  }
+#ifdef ZEND_MAX_EXECUTION_TIMERS
+  if (thread_php_timers && EG(pid)) {
+    thread_php_timers[idx] = EG(max_execution_timer_timer);
+    thread_php_timer_saved[idx] = true;
+  }
+#elif defined(PHP_WIN32)
+  if (thread_handles) {
+    DuplicateHandle(GetCurrentProcess(), GetCurrentThread(),
+                    GetCurrentProcess(), &thread_handles[idx], 0, FALSE,
+                    DUPLICATE_SAME_ACCESS);
+    thread_handle_saved[idx] = true;
+  }
+#endif
+  (void)idx;
+}
+
+void frankenphp_force_kill_thread(uintptr_t idx) {
+  if (idx >= (uintptr_t)force_kill_num_threads) {
+    return;
+  }
+#ifdef ZEND_MAX_EXECUTION_TIMERS
+  if (thread_php_timers && thread_php_timer_saved[idx]) {
+    struct itimerspec its;
+    its.it_value.tv_sec = 0;
+    its.it_value.tv_nsec = 1;
+    its.it_interval.tv_sec = 0;
+    its.it_interval.tv_nsec = 0;
+    timer_settime(thread_php_timers[idx], 0, &its, NULL);
+  }
+#elif defined(PHP_WIN32)
+  if (thread_handles && thread_handle_saved[idx]) {
+    CancelSynchronousIo(thread_handles[idx]);
+    QueueUserAPC((PAPCFUNC)frankenphp_noop_apc, thread_handles[idx], 0);
+  }
+#endif
+  (void)idx;
+}
+
+void frankenphp_destroy_force_kill(void) {
+#ifdef ZEND_MAX_EXECUTION_TIMERS
+  if (thread_php_timers) {
+    free(thread_php_timers);
+    thread_php_timers = NULL;
+  }
+  if (thread_php_timer_saved) {
+    free(thread_php_timer_saved);
+    thread_php_timer_saved = NULL;
+  }
+#elif defined(PHP_WIN32)
+  if (thread_handles) {
+    for (int i = 0; i < force_kill_num_threads; i++) {
+      if (thread_handle_saved && thread_handle_saved[i]) {
+        CloseHandle(thread_handles[i]);
+      }
+    }
+    free(thread_handles);
+    thread_handles = NULL;
+  }
+  if (thread_handle_saved) {
+    free(thread_handle_saved);
+    thread_handle_saved = NULL;
+  }
+#endif
+  force_kill_num_threads = 0;
+}
+
 void frankenphp_update_local_thread_context(bool is_worker) {
   is_worker_thread = is_worker;
 
@@ -1073,6 +1175,10 @@ static void *php_thread(void *arg) {
 #endif
 #endif
 
+  /* Capture this thread's PHP timer / OS handle so the Go side can force-kill
+   * the thread after a grace period if it gets stuck in a blocking call. */
+  frankenphp_save_php_timer(thread_index);
+
   bool thread_is_healthy = true;
   bool has_attempted_shutdown = false;
 

frankenphp.h

@@ -193,6 +193,12 @@ 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 for threads stuck in blocking calls. */
+void frankenphp_init_force_kill(int num_threads);
+void frankenphp_save_php_timer(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,11 @@ 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 the PHP
+	// threads fill in at boot (frankenphp_save_php_timer) so a stuck thread
+	// can be unblocked 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 +102,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,55 @@ 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 must arm PHP's max_execution_time timer
+// (Linux/FreeBSD ZTS) or the equivalent Windows primitive after the grace
+// period so the thread unblocks. macOS and other platforms without these
+// primitives would hang; skip there.
+func TestRestartWorkersForceKillsStuckThread(t *testing.T) {
+	if runtime.GOOS != "linux" && runtime.GOOS != "freebsd" && runtime.GOOS != "windows" {
+		t.Skipf("force-kill primitive not available 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)