feat: grace period and force-kill for background worker shutdown

On restart/shutdown, background workers receive "stop\n" on the
signaling stream and have 5 seconds to exit gracefully.

After the grace period, stuck threads get a best-effort force-kill
by arming PHP's own max_execution_time timer cross-thread (Linux ZTS
only, via timer_settime on EG(max_execution_timer_timer)). This
triggers a "Maximum execution time exceeded" fatal error on the
stuck thread. On other platforms, stuck threads are abandoned and
exit when the blocking call eventually returns.

Author: nicolas-grekas

docs/background-workers.md

@@ -36,15 +36,15 @@ example.com {
 
 - `num` and `max_threads` are accepted but capped at 1 for now (pooling is a future feature). Values > 1 are rejected with a clear error.
 - `max_threads` on catch-all workers sets a safety cap for lazy-started instances (defaults to 16).
-- `max_consecutive_failures` defaults to -1 (never panic on boot failures).
+- `max_consecutive_failures` defaults to 6 (same as HTTP workers).
 - `env` and `watch` work the same as HTTP workers.
 
 ### Thread reservation
 
 Background workers get dedicated thread slots outside the global `max_threads` budget.
 They don't compete with HTTP auto-scaling. For catch-all workers, `max_threads` determines
-the reservation (default 16). Named workers with `num 0` (default) are lazy-started and
-don't reserve threads.
+the reservation (default 16). Named workers with `num 0` (default) are lazy-started but
+still reserve 1 thread (`max_threads` defaults to `max(num, 1)`).
 
 Each `php_server` block has its own isolated background worker scope.
 
@@ -199,7 +199,8 @@ if (function_exists('frankenphp_worker_get_vars')) {
 - Background workers also get `$_SERVER['argv']` = `[entrypoint, name]` for CLI compatibility
 - Crash recovery: automatic restart with exponential backoff
 - Graceful shutdown via `frankenphp_worker_get_signaling_stream()` and `stream_select()`
-- Worker restarts stop running background workers; the next `get_vars()` call starts them again
+- Grace period: on restart/shutdown, background workers receive `"stop\n"` on the signaling stream and have 5 seconds to exit gracefully. Workers still blocked after 5 seconds are abandoned (their threads exit when the blocking call returns).
+- Worker restarts stop and immediately restart background workers (same as HTTP workers)
 - Use `error_log()` or `frankenphp_log()` for logging - avoid `echo`
 
 For advanced use cases (amphp, ReactPHP), the signaling stream can be registered directly

frankenphp.c

@@ -93,6 +93,101 @@ __thread int worker_stop_fds[2] = {-1, -1};
 __thread php_stream *worker_signaling_stream = NULL;
 __thread HashTable *sandboxed_env = NULL;
 
+/* Best-effort force-kill for stuck background workers after grace period.
+ * - Linux 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 blocking call returns) */
+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;
+}
+
 /* Per-thread cache for get_vars results.
  * Maps worker name (string) -> {version, cached_zval}.
  * When the version matches, the cached zval is returned with a refcount bump,
@@ -1673,6 +1768,9 @@ static void *php_thread(void *arg) {
 #endif
 #endif
 
+  /* Save PHP's timer handle for best-effort force-kill after grace period */
+  frankenphp_save_php_timer(thread_index);
+
   // loop until Go signals to stop
   char *scriptName = NULL;
   while ((scriptName = go_frankenphp_before_script_execution(thread_index))) {

frankenphp.h

@@ -195,4 +195,9 @@ int frankenphp_get_current_memory_limit();
 
 void register_extensions(zend_module_entry **m, int len);
 
+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);
+
 #endif

phpmainthread.go

@@ -54,6 +54,9 @@ func initPHPThreads(numThreads int, numMaxThreads int, phpIni map[string]string)
 		return nil, err
 	}
 
+	// initialize force-kill support for stuck background workers
+	C.frankenphp_init_force_kill(C.int(mainThread.maxThreads))
+
 	// initialize all other threads
 	phpThreads = make([]*phpThread, mainThread.maxThreads)
 	phpThreads[0] = initialThread
@@ -95,6 +98,7 @@ func drainPHPThreads() {
 	}
 
 	doneWG.Wait()
+	C.frankenphp_destroy_force_kill()
 	mainThread.state.Set(state.Done)
 	mainThread.state.WaitFor(state.Reserved)
 	phpThreads = nil

worker.go

@@ -16,6 +16,10 @@ import (
 	"github.com/dunglas/frankenphp/internal/state"
 )
 
+// backgroundWorkerGracePeriod is the time background workers have to stop
+// gracefully after receiving the stop signal before being force-killed.
+const backgroundWorkerGracePeriod = 5 * time.Second
+
 // represents a worker script and can have many threads assigned to it
 type worker struct {
 	mercureContext
@@ -183,9 +187,10 @@ func DrainWorkers() {
 
 func drainWorkerThreads() []*phpThread {
 	var (
-		ready                    sync.WaitGroup
-		drainedThreads           []*phpThread
-		stoppedBackgroundWorkers []*worker
+		ready          sync.WaitGroup
+		drainedThreads []*phpThread
+		bgThreads      []*phpThread
+		bgWorkers      []*worker
 	)
 
 	for _, worker := range workers {
@@ -195,14 +200,20 @@ func drainWorkerThreads() []*phpThread {
 
 		for _, thread := range threads {
 			if worker.isBackgroundWorker {
-				thread.shutdown()
-				stoppedBackgroundWorkers = append(stoppedBackgroundWorkers, worker)
+				// Signal background workers to stop via the signaling stream
+				if !thread.state.RequestSafeStateChange(state.ShuttingDown) {
+					continue
+				}
+				if fd := worker.backgroundStopFdWrite.Load(); fd >= 0 {
+					C.frankenphp_worker_write_stop_fd(C.int(fd))
+				}
+				close(thread.drainChan)
+				bgThreads = append(bgThreads, thread)
+				bgWorkers = append(bgWorkers, worker)
 				continue
 			}
 
 			if !thread.state.RequestSafeStateChange(state.Restarting) {
-				// no state change allowed == thread is shutting down
-				// we'll proceed to restart all other threads anyway
 				continue
 			}
 
@@ -219,9 +230,39 @@ func drainWorkerThreads() []*phpThread {
 
 	ready.Wait()
 
-	if len(stoppedBackgroundWorkers) > 0 {
-		stopped := make(map[*worker]struct{}, len(stoppedBackgroundWorkers))
-		for _, w := range stoppedBackgroundWorkers {
+	// Wait for background workers with a grace period.
+	// Well-written workers check the signaling stream and stop promptly.
+	// Stuck workers (e.g., blocking C calls) are abandoned after the timeout;
+	// new threads are created on restart, and the old thread exits when the
+	// blocking call eventually returns.
+	if len(bgThreads) > 0 {
+		bgDone := make(chan struct{})
+		go func() {
+			for _, thread := range bgThreads {
+				thread.state.WaitFor(state.Done)
+			}
+			close(bgDone)
+		}()
+
+		select {
+		case <-bgDone:
+			// all stopped gracefully
+		case <-time.After(backgroundWorkerGracePeriod):
+			// Best-effort force-kill: arm PHP's max_execution_time timer on
+			// stuck threads. Linux ZTS: arms PHP's timer. Windows: interrupts
+			// I/O and alertable waits. Other platforms: no-op.
+			// Safe because after 5s, stuck threads are guaranteed to be in C code.
+			for _, thread := range bgThreads {
+				if !thread.state.Is(state.Done) {
+					C.frankenphp_force_kill_thread(C.uintptr_t(thread.threadIndex))
+				}
+			}
+			globalLogger.Warn("background workers did not stop within grace period, force-killing stuck threads")
+		}
+
+		// Clean up registry entries for stopped workers
+		stopped := make(map[*worker]struct{}, len(bgWorkers))
+		for _, w := range bgWorkers {
 			if w.backgroundRegistry != nil && w.backgroundWorker != nil {
 				w.backgroundRegistry.remove(w.name, w.backgroundWorker)
 			}
@@ -234,6 +275,14 @@ func drainWorkerThreads() []*phpThread {
 			}
 		}
 		workers = filtered
+
+		// Reset drained background threads for restart
+		for _, thread := range bgThreads {
+			thread.drainChan = make(chan struct{})
+			if mainThread.state.Is(state.Ready) {
+				thread.state.Set(state.Reserved)
+			}
+		}
 	}
 
 	return drainedThreads