# _subinterpreter_bootstrap URL: /pounce/api/_subinterpreter_bootstrap/ Section: api Description: Subinterpreter worker bootstrap. This module provides `bootstrap`(), 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. Reconstructs ``ServerConfig`` from JSON 2. Imports the ASGI app by module path 3. Reconstructs the socket from a dup'd file descriptor 4. Creates a standard ``Worker`` with ``shutdown_event=None`` 5. Monkey-patches ``Worker._serve`` to inject an IIC shutdown bridge that polls ``ctrl_queue`` and sets ``_async_shutdown`` when commanded This keeps Worker as the single source of truth for request handling. --- > For a complete page index, fetch /pounce/llms.txt. Open LLM text (/pounce/api/_subinterpreter_bootstrap/index.txt) Share with AI Ask Claude (https://claude.ai/new?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_subinterpreter_bootstrap%2Findex.txt) Ask ChatGPT (https://chatgpt.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_subinterpreter_bootstrap%2Findex.txt) Ask Gemini (https://gemini.google.com/app?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_subinterpreter_bootstrap%2Findex.txt) Ask Copilot (https://copilot.microsoft.com/?q=Please%20help%20me%20understand%20this%20documentation%3A%20%2Fpounce%2Fapi%2F_subinterpreter_bootstrap%2Findex.txt) Module # `_subinterpreter_bootstrap` Subinterpreter worker bootstrap. This module provides`bootstrap`(), 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: - Reconstructs`ServerConfig`from JSON - Imports the ASGI app by module path - Reconstructs the socket from a dup'd file descriptor - Creates a standard`Worker` with `shutdown_event=None` - Monkey-patches`Worker._serve`to inject an IIC shutdown bridge that polls`ctrl_queue` and sets `_async_shutdown`when 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_family`is 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 a`while not worker.is_idle()` spin or the queued `shutdown` becomes unreachable and the subinterpreter thread wedges forever. Behaviour per tick (every`poll_interval`): - `CMD_SHUTDOWN` -> set `_async_shutdown`and return immediately. - `CMD_DRAIN`-> mark the worker draining and arm a deadline of `config.shutdown_timeout`from 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 -> emit`STATUS_IDLE`once so the supervisor's reload poll can observe it, then keep polling for the explicit shutdown. - while draining and past the deadline -> emit a final`STATUS_IDLE`and set`_async_shutdown`so 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]`