supervisor

Wait for a replacement generation without changing global state.

Initial startup failures abort the server through _raise_startup_failure(). A reload is different: the old generation is still healthy, so a replacement failure must be reported to the caller without setting the supervisor shutdown event.

Mark async workers as draining (503 new connections) during shutdown.

Thread-mode workers expose a Worker / SyncWorker instance; process workers do not (handle.worker is None). Subinterpreter workers receive drain commands via IIC queue.

Build and start a fresh AsyncPool bound to the currentself._app.

Returns the pool and its thread handle without mutatingselfso the caller can repointself._async_pooland retire the old one in the order it chooses (issue #102).

Build and start a fresh AcceptDistributor for shared-socket sync mode.

Returns(conn_queue, handle, drain_event) (all Nonewhen a distributor does not apply) without mutatingself.

Return a worker-owned socket handle.

Thread workers always receive a duplicated handle so one generation can close its asyncio server without invalidating the canonical listener kept inself._socketsfor the next reload generation.

This applies both when workers share one listener object (macOS / Windows fallback) and when each worker has its ownSO_REUSEPORT socket (Linux): without a dup, an old worker closing its asyncio server would close the supervisor-owned socket and leave reload withEBADF.

Create and start a worker inside a subinterpreter (PEP 734).

Each worker runs in a dedicated thread that hosts a subinterpreter. Communication uses IIC queues (tagged tuples) instead of direct method calls or threading.Events.

The supervisor passes config as JSON, the app as an import path, and the socket as a dup'd file descriptor — all IIC-safe types.

Restart a crashed worker if within restart budget.

Serialized with restart_workers/graceful_reload via _lifecycle_lock. Skips if a reload is in progress (avoids overlapping restarts).

Wait for all workers to finish draining connections, then clean up.

Signals shutdown to all workers, waits for them to finish processing active connections (seeshutdown_timeout on ServerConfig), then force-terminates process workers that haven't stopped.

Workers will reject new connections but finish existing ones for clean shutdown (important for Kubernetes graceful termination).

Close a subinterpreter worker's dup'd listener FD, if still recorded.

Subinterpreter workers run as daemon threads the parent cannot force kill (see _force_stop()). When such a worker stops abnormally — a crash/respawn, or a force-stop of an old generation that never drained — its bootstrap finally-block may not have closed the dup'd listener FD. Each abnormal cycle would then leak one FD until the process exhausts its descriptor budget (issue #106). The parent recorded the FD on sock_fd, so it can reclaim it here.

The generated bootstrap wrapper acknowledges its worker-side close with a parent-owned Event before the host thread exits. In that case this method only clears the record: calling os.close on the old numeric value could close an unrelated resource if the OS already reused it. Without an acknowledgement, the parent still owns abnormal cleanup.

Force-terminate a worker that did not drain in time.

Process workers receive SIGTERM then SIGKILL. Thread workers cannot be terminated from Python; they are daemon threads and may outlive this join.

Install SIGINT/SIGTERM handlers to trigger graceful shutdown.

Only effective when the supervisor runs on the main thread (e.g., direct testing). In production the supervisor runs inside a run_in_executor thread, so signal.signal()will fail silently. Server installs asyncio signal handlers that call supervisor.shutdown()instead.