Module

_runtime

Runtime detection utilities.

Detects GIL state and determines the appropriate worker mode for the current Python interpreter. Used by the supervisor to decide between thread-based (nogil) and process-based (GIL) worker spawning.

2Classes8Functions

Classes

WorkerMode 0 ▼
Worker spawning strategy.
Bases: StrEnum

Worker spawning strategy.

WorkerExecutionMode 0 ▼
Worker execution model.
Bases: StrEnum

Worker execution model.

Functions

is_gil_enabled 0 bool ▼
Check whether the GIL is active in the current interpreter. Returns the runtim…
def is_gil_enabled() -> bool

Check whether the GIL is active in the current interpreter.

Returns the runtime state, which can beTrueon either a standard build or a free-threaded build started with its GIL enabled. Falls back to True on Python < 3.13 where sys._is_gil_enableddoes not exist.

Returns
bool
is_free_threaded_build 0 bool ▼
Return whether this interpreter was compiled with free-threading support. This…
def is_free_threaded_build() -> bool

Return whether this interpreter was compiled with free-threading support.

This is distinct from is_gil_enabled(): a free-threaded build can still start with its GIL enabled, while a standard build cannot disable it.

Returns
bool
has_subinterpreters 0 bool ▼
Check whether ``concurrent.interpreters`` is available (Python 3.14+).
def has_subinterpreters() -> bool
Returns
bool
detect_worker_mode 0 WorkerMode ▼
Choose the worker spawning strategy based on GIL state.
def detect_worker_mode() -> WorkerMode
Returns
WorkerMode
default_worker_count 0 int ▼
Return a sensible default worker count based on available CPUs. Returns ``os.c…
def default_worker_count() -> int

Return a sensible default worker count based on available CPUs.

Returnsos.cpu_count() or 1when the CPU count cannot be determined.

Returns
int
resolve_worker_execution_mode 1 WorkerExecutionMode ▼
Resolve the effective worker execution mode.
def resolve_worker_execution_mode(worker_mode: str) -> WorkerExecutionMode
Parameters
Name Type Description
worker_mode str

Config value ("auto", "sync", "async", "subinterpreter").
Returns
WorkerExecutionMode
resolve_worker_model 2 str ▼
Return the actual spawning and execution model for this runtime. A single work…
def resolve_worker_model(worker_mode: str, worker_count: int) -> str

Return the actual spawning and execution model for this runtime.

A single worker uses the direct async server path. Multi-workerauto uses sync thread workers on a free-threaded build and async process workers on a GIL build. Explicit subinterpreter mode always uses isolated async workers, including when the configured worker count is one.

Parameters
Name Type Description
worker_mode str
worker_count int
Returns
str
validate_subinterpreter_app_path 2 None ▼
Fail at the embedding boundary when isolated workers cannot import the app.
def validate_subinterpreter_app_path(worker_mode: str, app_path: str | None) -> None
Parameters
Name Type Description
worker_mode str
app_path str | None