Module

_subinterpreter_bootstrap

Subinterpreter worker bootstrap.

This module providesbootstrap(), the entry point executed inside each subinterpreter worker. The supervisor injects IIC-safe values via interp.prepare_main()and then runs::

from pounce._subinterpreter_bootstrap import bootstrap
bootstrap(ctrl_queue, status_queue, config_json,
          app_import_path, sock_fd, worker_id, parent_sys_path)

Design

Rather than duplicating Worker internals, the bootstrap:

  1. ReconstructsServerConfigfrom JSON
  2. Imports the ASGI app by module path
  3. Reconstructs the socket from a dup'd file descriptor
  4. Creates a standardWorker with shutdown_event=None
  5. Monkey-patchesWorker._serveto inject an IIC shutdown bridge that pollsctrl_queue and sets _async_shutdownwhen commanded

This keeps Worker as the single source of truth for request handling.

8Functions

Functions

bootstrap 10 None ▼
Bootstrap a Worker inside a subinterpreter. All arguments are IIC-safe types i…
def bootstrap(ctrl_queue: Any, status_queue: Any, config_json: str, lifespan_state_json: str, app_import_path: str, sock_fd: int, sock_family: int, worker_id: int, generation: int, parent_sys_path: tuple[str, ...]) -> None

Bootstrap a Worker inside a subinterpreter.

All arguments are IIC-safe types injected by the supervisor via interp.prepare_main(). sock_familyis the parent socket's address family (AF_INET / AF_INET6 / AF_UNIX, as an int) so the reconstructed socket matches the bound listener.

Parameters
Name Type Description
ctrl_queue Any
status_queue Any
config_json str
lifespan_state_json str
app_import_path str
sock_fd int
sock_family int
worker_id int
generation int
parent_sys_path tuple[str, ...]
_run_worker_with_iic 3 None ▼
Run Worker._serve() with an IIC-based shutdown bridge. This replicates the set…
async
async def _run_worker_with_iic(worker: Any, ctrl_queue: Any, status_queue: Any) -> None

Run Worker._serve() with an IIC-based shutdown bridge.

This replicates the setup that Worker._serve() does, then injects an IIC polling task alongside the normal accept loop.

Parameters
Name Type Description
worker Any
ctrl_queue Any
status_queue Any
_iic_bridge 4 None ▼
Poll the IIC ctrl_queue and translate commands to Worker state changes. A sing…
async
async def _iic_bridge(worker: Any, ctrl_queue: Any, status_queue: Any, server: Any | None = None) -> None

Poll the IIC ctrl_queue and translate commands to Worker state changes.

A single bounded poll loop (issue #103). The supervisor queues ('drain',) then ('shutdown',)back-to-back on SIGTERM, so the bridge must keep reading the queue while draining — it can never block inside awhile not worker.is_idle() spin or the queued shutdown becomes unreachable and the subinterpreter thread wedges forever.

Behaviour per tick (everypoll_interval):

  • CMD_SHUTDOWN -> set _async_shutdownand return immediately.
  • CMD_DRAIN-> mark the worker draining and arm a deadline of config.shutdown_timeoutfrom now; keep polling.
  • CMD_RELOAD_DRAIN-> first close this generation's accept socket, then follow the same bounded drain protocol. A replacement generation is already serving before the supervisor sends this command.
  • while draining and idle -> emitSTATUS_IDLEonce so the supervisor's reload poll can observe it, then keep polling for the explicit shutdown.
  • while draining and past the deadline -> emit a finalSTATUS_IDLEand set_async_shutdownso the worker proceeds to its finally-block drain rather than spinning forever on a long-lived connection.
Parameters
Name Type Description
worker Any
ctrl_queue Any
status_queue Any
server Any | None Default:None
_run_worker_draining_hook 2 None ▼
Notify a subinterpreter app before its streams are force-closed.
async
async def _run_worker_draining_hook(worker: Any, reason: str) -> None
Parameters
Name Type Description
worker Any
reason str
_import_app 1 Any ▼
Import an ASGI app by dotted path (e.g. ``'myapp.main:app'``). Supports factor…
def _import_app(app_path: str) -> Any

Import an ASGI app by dotted path (e.g.'myapp.main:app').

Supports factory syntax:'myapp.main:create_app()'.

Parameters
Name Type Description
app_path str
Returns
Any
_try_get 1 tuple[Any, ...] | None ▼
Non-blocking get from an IIC queue. Returns None if empty.
def _try_get(queue: Any) -> tuple[Any, ...] | None
Parameters
Name Type Description
queue Any
Returns
tuple[Any, ...] | None
_noop_receive 0 dict[str, str] ▼
Noop receive for lifecycle hooks.
async
async def _noop_receive() -> dict[str, str]
Returns
dict[str, str]
_noop_send 1 None ▼
Noop send for lifecycle hooks.
async
async def _noop_send(message: dict[str, Any]) -> None
Parameters
Name Type Description
message dict[str, Any]