warmpool 0.1.1__tar.gz

warmpool-0.1.1/PKG-INFO

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: warmpool
+Version: 0.1.1
+Summary: Process pool with hard-kill timeouts and import warming
+Keywords: subprocess,pool,timeout,multiprocessing
+Author: Michael Dawson-Haggerty
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: psutil>=5.9
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/slopden/warmpool
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="static/logo.svg" alt="warmpool" width="480">
+</p>
+
+<p align="center">
+  <strong>A single-worker subprocess pool that can actually kill C extensions.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/warmpool/"><img alt="PyPI" src="https://img.shields.io/pypi/v/warmpool?color=ff6b35"></a>
+  <a href="https://github.com/slopden/warmpool/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/slopden/warmpool?color=ff3d00"></a>
+  <img alt="Python" src="https://img.shields.io/pypi/pyversions/warmpool?color=1a1a2e">
+</p>
+
+---
+
+A "ProcessPool-like-executor" with hard-kill timeouts and import warming. The basic problem is that if you freeze up deep in a C-extension Python timeout-handling stuff doesn't work. `warmpool` runs functions in a spawned subprocess, and if they exceed their timeout it SIGTERM+SIGKILL the process and all children if the C extension has spawned anything.
+
+- It calls a "warming function" in each new process, so you can have it keep a process warmed with `import scipy, numpy, etc` which can easily be 2+ seconds.
+- The timeouts actually work regardless of what happens in the function.
+- It has an option to keep a spare process warm in the background so it can rotate cleanly without eating an import period.
+- It sends logs back to the parent through a pipe.
+
+```python
+import time
+from warmpool import WarmPool
+
+def warm_imports():
+    import numpy
+    import scipy.linalg
+
+def eigh_huge(n=5000):
+    """Stuck in LAPACK C code — only SIGKILL works."""
+    import numpy as np
+    from scipy import linalg
+    a = np.random.rand(n, n)
+    a = a + a.T
+    return linalg.eigh(a)
+
+def add(a=0, b=0):
+    return a + b
+
+pool = WarmPool(warming=warm_imports)
+
+# numpy+scipy are already imported — no 2s wait
+start = time.perf_counter()
+try:
+    pool.run(eigh_huge, timeout=0.5, n=5000)
+except TimeoutError:
+    print(f"killed after {time.perf_counter() - start:.2f}s")
+
+# pool recovered via spare
+result = pool.run(add, timeout=5.0, a=2, b=3)
+print(f"recovered: add(2, 3) = {result}")
+pool.shutdown()
+```
+
+```
+killed after 0.53s
+recovered: add(2, 3) = 5
+```

warmpool-0.1.1/README.md

@@ -0,0 +1,61 @@
+<p align="center">
+  <img src="static/logo.svg" alt="warmpool" width="480">
+</p>
+
+<p align="center">
+  <strong>A single-worker subprocess pool that can actually kill C extensions.</strong>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/warmpool/"><img alt="PyPI" src="https://img.shields.io/pypi/v/warmpool?color=ff6b35"></a>
+  <a href="https://github.com/slopden/warmpool/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/github/license/slopden/warmpool?color=ff3d00"></a>
+  <img alt="Python" src="https://img.shields.io/pypi/pyversions/warmpool?color=1a1a2e">
+</p>
+
+---
+
+A "ProcessPool-like-executor" with hard-kill timeouts and import warming. The basic problem is that if you freeze up deep in a C-extension Python timeout-handling stuff doesn't work. `warmpool` runs functions in a spawned subprocess, and if they exceed their timeout it SIGTERM+SIGKILL the process and all children if the C extension has spawned anything.
+
+- It calls a "warming function" in each new process, so you can have it keep a process warmed with `import scipy, numpy, etc` which can easily be 2+ seconds.
+- The timeouts actually work regardless of what happens in the function.
+- It has an option to keep a spare process warm in the background so it can rotate cleanly without eating an import period.
+- It sends logs back to the parent through a pipe.
+
+```python
+import time
+from warmpool import WarmPool
+
+def warm_imports():
+    import numpy
+    import scipy.linalg
+
+def eigh_huge(n=5000):
+    """Stuck in LAPACK C code — only SIGKILL works."""
+    import numpy as np
+    from scipy import linalg
+    a = np.random.rand(n, n)
+    a = a + a.T
+    return linalg.eigh(a)
+
+def add(a=0, b=0):
+    return a + b
+
+pool = WarmPool(warming=warm_imports)
+
+# numpy+scipy are already imported — no 2s wait
+start = time.perf_counter()
+try:
+    pool.run(eigh_huge, timeout=0.5, n=5000)
+except TimeoutError:
+    print(f"killed after {time.perf_counter() - start:.2f}s")
+
+# pool recovered via spare
+result = pool.run(add, timeout=5.0, a=2, b=3)
+print(f"recovered: add(2, 3) = {result}")
+pool.shutdown()
+```
+
+```
+killed after 0.53s
+recovered: add(2, 3) = 5
+```

warmpool-0.1.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "warmpool"
+version = "0.1.1"
+description = "Process pool with hard-kill timeouts and import warming"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["psutil>=5.9"]
+authors = [{name = "Michael Dawson-Haggerty"}]
+keywords = ["subprocess", "pool", "timeout", "multiprocessing"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+
+[project.urls]
+Repository = "https://github.com/slopden/warmpool"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "scipy>=1.15.3",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

warmpool-0.1.1/src/warmpool/__init__.py

@@ -0,0 +1,20 @@
+"""warmpool — single-worker subprocess pool with hard-kill timeouts.
+
+Usage
+-----
+>>> from warmpool import WarmPool, PoolStatus
+>>> pool = WarmPool(max_tasks=100, keep_spare=True)
+>>> result = pool.run(my_func, timeout=10.0, x=42)
+>>> pool.status is PoolStatus.READY
+True
+>>> pool.shutdown()
+
+Memory-based rotation:
+
+>>> pool = WarmPool(max_memory=500 * 1024 * 1024)
+"""
+
+from ._exceptions import ProcessPoolExhausted
+from .pool import PoolStatus, WarmPool
+
+__all__ = ["PoolStatus", "WarmPool", "ProcessPoolExhausted"]

warmpool-0.1.1/src/warmpool/_exceptions.py

@@ -0,0 +1,21 @@
+"""Exception types for the warmpool package."""
+
+
+class ProcessPoolExhausted(Exception):
+    """The worker process is dead or has hit its task limit.
+
+    When ``keep_spare=False``, the caller must create a new
+    :class:`~warmpool.WarmPool` instance to continue.
+
+    Parameters
+    ----------
+    message
+        Human-readable description of why the pool is exhausted.
+    exit_code
+        The worker's exit code, if it died.  ``None`` when the pool
+        was shut down explicitly or the code is unavailable.
+    """
+
+    def __init__(self, message: str, exit_code: int | None = None):
+        super().__init__(message)
+        self.exit_code = exit_code

warmpool-0.1.1/src/warmpool/_logging.py

@@ -0,0 +1,80 @@
+"""Pipe-based logging for worker subprocesses.
+
+Provides :class:`PipeHandler` (installed in workers) and
+:func:`forward_subprocess_log` (called in the parent) so that log
+records cross the process boundary as structured dicts.
+"""
+
+from __future__ import annotations
+
+import logging
+import traceback
+from multiprocessing.connection import Connection
+from typing import Any
+
+
+class PipeHandler(logging.Handler):
+    """Logging handler that serializes records and sends them through a
+    multiprocessing pipe as structured dicts (JSON-ready).
+
+    Installed in the **worker** subprocess so that all log output is
+    forwarded to the parent process over the pipe.
+
+    Parameters
+    ----------
+    connection
+        The child-side :class:`~multiprocessing.connection.Connection`.
+    """
+
+    def __init__(self, connection: Connection):
+        super().__init__()
+        self.connection = connection
+
+    def emit(self, record: logging.LogRecord) -> None:
+        """Serialize *record* to a dict and send it over the pipe.
+
+        Parameters
+        ----------
+        record
+            The log record to forward.
+        """
+        try:
+            entry: dict = {
+                "timestamp": record.created,
+                "level": record.levelname,
+                "message": record.getMessage(),
+                "logger": record.name,
+                "process_id": record.process,
+            }
+            if record.exc_info and record.exc_info[1] is not None:
+                entry["exception"] = "".join(
+                    traceback.format_exception(*record.exc_info)
+                )
+            self.connection.send(("log", entry, {}))
+        except Exception:
+            pass
+
+
+def forward_subprocess_log(
+    payload: dict[str, Any],
+    logger: logging.Logger | None = None,
+) -> None:
+    """Re-emit a subprocess log record via the parent's logging system.
+
+    Parameters
+    ----------
+    payload
+        The structured dict received from :class:`PipeHandler`.
+    logger
+        Logger to emit on.  Defaults to ``warmpool.subprocess``.
+    """
+    if logger is None:
+        logger = logging.getLogger("warmpool.subprocess")
+    level = getattr(logging, payload.get("level", "INFO"), logging.INFO)
+    message = payload.get("message", "")
+    extra = {
+        k: v
+        for k, v in payload.items()
+        if k not in ("level", "message", "levelname", "levelno")
+    }
+    logger.log(level, message, extra=extra)

warmpool-0.1.1/src/warmpool/_worker.py

@@ -0,0 +1,76 @@
+"""Worker subprocess entry point.
+
+This module is imported by the spawned child process.  It sets up
+pipe-based logging, runs the optional warming callable, then enters a
+receive-execute-send loop until the parent sends a shutdown sentinel
+(``func is None``) or the pipe breaks.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from multiprocessing.connection import Connection
+from typing import Callable
+
+from ._logging import PipeHandler
+
+
+def _worker_process(
+    connection: Connection,
+    log_level: int = logging.DEBUG,
+    warming: Callable | None = None,
+) -> None:
+    """Entry point for the worker subprocess.
+
+    Parameters
+    ----------
+    connection
+        Child-side pipe connection shared with the parent.
+    warming
+        Optional callable invoked once on startup (e.g. to pre-import
+        modules).  Its return value is sent to the parent.
+
+    Notes
+    -----
+    1. Replaces all root-logger handlers with a :class:`PipeHandler` so
+       every log record is forwarded to the parent as a structured dict.
+    2. Calls *warming* if provided.
+    3. Sends a ``("ready", init_result, {})`` message, then enters the task loop.
+    """
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(PipeHandler(connection))
+    root.setLevel(log_level)
+
+    init_result = warming() if warming is not None else None
+    connection.send(("ready", init_result, {}))
+
+    try:
+        while True:
+            if not connection.poll(timeout=None):
+                continue
+
+            try:
+                function, args, kwargs = connection.recv()
+                if function is None:  # shutdown sentinel
+                    break
+
+                start = time.perf_counter()
+                result = function(*args, **kwargs)
+                elapsed_ms = int((time.perf_counter() - start) * 1000)
+
+                connection.send(("success", result, {"elapsed_ms": elapsed_ms}))
+            except Exception as error:
+                # Guard against unpicklable exceptions (common with
+                # C-API wrappers).  If the exception can't be pickled
+                # the parent would see a silent worker death instead
+                # of a useful error message.
+                try:
+                    connection.send(("error", error, {}))
+                except Exception:
+                    connection.send(("error", RuntimeError(repr(error)), {}))
+    except (EOFError, BrokenPipeError):
+        pass
+    finally:
+        connection.close()

warmpool-0.1.1/src/warmpool/pool.py

@@ -0,0 +1,642 @@
+"""Single-worker subprocess pool with hard-kill timeouts.
+
+Runs callables in a spawned subprocess that can be SIGKILLed when
+C-API code (OpenCASCADE, etc.) ignores Python signals.  An optional
+spare worker is pre-warmed in the background so that rotation after
+task-limit exhaustion or crash is near-instant.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import atexit
+import enum
+import logging
+import multiprocessing
+import time
+import weakref
+from dataclasses import dataclass, field
+from multiprocessing import Pipe, Process
+from multiprocessing.connection import Connection
+from typing import Any, Callable, NoReturn
+
+import psutil
+
+from ._exceptions import ProcessPoolExhausted
+from ._logging import forward_subprocess_log
+from ._worker import _worker_process
+
+log = logging.getLogger(__name__)
+
+# Seconds to wait when polling a pipe for data.
+_POLL_TIMEOUT = 0.1
+# Seconds to wait for a worker to join after a graceful shutdown signal.
+_JOIN_TIMEOUT = 0.5
+# Seconds to wait for a process tree to die after SIGKILL.
+_KILL_WAIT = 1.0
+
+_active_pools: weakref.WeakSet[WarmPool] = weakref.WeakSet()
+
+
+def _cleanup_all_pools() -> None:
+    """Shut down every live pool at interpreter exit."""
+    for pool in list(_active_pools):
+        try:
+            pool.shutdown()
+        except Exception:
+            pass
+
+
+atexit.register(_cleanup_all_pools)
+
+
+class PoolStatus(enum.Enum):
+    """The pool's readiness state.
+
+    Returned by :attr:`WarmPool.status`.  Every decision point
+    in the pool dispatches on this enum with :func:`_assert_never` in
+    the ``else`` branch so that mypy proves exhaustive handling.
+
+    Attributes
+    ----------
+    READY
+        Active worker is alive and under the task limit.
+    NEEDS_ROTATION
+        Active worker is spent or dead, but a spare can take over.
+    EXHAUSTED
+        No workers available and no spare to promote.
+    SHUTDOWN
+        The pool has been explicitly shut down.
+    """
+
+    READY = "ready"
+    NEEDS_ROTATION = "rotation"
+    EXHAUSTED = "exhausted"
+    SHUTDOWN = "shutdown"
+
+
+def _assert_never(value: NoReturn) -> NoReturn:
+    """Statically assert all enum cases are handled.
+
+    Mypy narrows the type through each ``if``/``elif`` branch.  If all
+    :class:`PoolStatus` members are covered, the remaining type at the
+    ``else`` is ``Never``/``NoReturn`` and this call type-checks.
+    Adding a new enum member without a matching branch causes a mypy
+    error.
+    """
+    raise AssertionError(f"Unhandled status: {value!r}")
+
+
+@dataclass
+class WorkerHandle:
+    """Bookkeeping for a single worker subprocess.
+
+    Parameters
+    ----------
+    process
+        The :class:`multiprocessing.Process` instance.
+    connection
+        Parent-side pipe connection.
+    child_connection
+        Child-side pipe connection (kept open so we can close it on
+        cleanup).
+    ready
+        ``True`` once the worker has sent its ``"ready"`` message.
+    task_count
+        Number of tasks dispatched to this worker.
+    last_metadata
+        Metadata dict from the most recent completed task.
+    """
+
+    process: multiprocessing.Process
+    connection: Connection
+    child_connection: Connection
+    ready: bool = False
+    task_count: int = 0
+    last_metadata: dict[str, Any] = field(default_factory=dict)
+    init_result: Any = None
+
+
+class WarmPool:
+    """Single-worker subprocess pool with hard-kill timeouts.
+
+    Runs functions in a spawned subprocess that can be SIGKILLed when
+    C-API code (OpenCASCADE, etc.) ignores Python signals.
+
+    .. note::
+        This class is **not** thread-safe.  Do not call :meth:`run` from
+        multiple threads concurrently.
+
+    Parameters
+    ----------
+    warming
+        Optional callable invoked once per worker on startup (e.g. to
+        pre-import modules).  Its return value is available via
+        :attr:`init_result`.
+    max_tasks
+        Maximum tasks a single worker may handle before rotation.
+    keep_spare
+        If ``True``, a spare worker is pre-warmed in the background so
+        rotation is near-instant.
+    ready_timeout
+        Seconds to wait for a worker to send its ``"ready"`` signal.
+    max_memory
+        Maximum RSS in bytes before the worker is rotated.
+    max_memory_percent
+        Maximum RSS as a fraction of total system memory (0.0–1.0)
+        before the worker is rotated.
+    """
+
+    def __init__(
+        self,
+        max_tasks: int = 50,
+        keep_spare: bool = True,
+        ready_timeout: float = 30.0,
+        max_memory: int | None = None,
+        max_memory_percent: float | None = 0.35,
+        warming: Callable | None = None,
+        init_retries: int = 1,
+    ) -> None:
+        self._max_tasks = max_tasks
+        self._keep_spare = keep_spare
+        self._ready_timeout = ready_timeout
+        self._warming = warming
+        self._max_memory = max_memory
+        self._init_retries = init_retries
+        # Pre-compute absolute byte limit from percentage (avoid per-task psutil call).
+        if max_memory_percent is not None:
+            clamped = max(0.0, min(1.0, max_memory_percent))
+            self._max_memory_percent_bytes: int | None = int(
+                clamped * psutil.virtual_memory().total
+            )
+        else:
+            self._max_memory_percent_bytes = None
+
+        self._active: WorkerHandle | None = None
+        self._spare: WorkerHandle | None = None
+        self._shutdown = False
+        # Pool-level cache so elapsed_ms survives rotation.
+        self._last_elapsed_ms: int | None = None
+        self._last_memory_rss: int | None = None
+
+        _active_pools.add(self)
+
+        # Start primary worker (blocking), with retry.
+        for attempt in range(1 + self._init_retries):
+            try:
+                self._active = self._start_worker(block_ready=True)
+                break
+            except RuntimeError:
+                if attempt < self._init_retries:
+                    log.warning(
+                        "Primary worker failed to become ready, "
+                        f"retrying ({attempt + 1}/{self._init_retries})..."
+                    )
+                    time.sleep(5)
+                else:
+                    raise
+
+        # Start spare (non-blocking) if requested.
+        if self._keep_spare:
+            self._spare = self._start_worker(block_ready=False)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def status(self) -> PoolStatus:
+        """The pool's current readiness state.
+
+        Returns
+        -------
+        PoolStatus
+            Pure query — no side effects, no mutations.
+        """
+        if self._shutdown:
+            return PoolStatus.SHUTDOWN
+        if (
+            self._active is not None
+            and self._active.process.is_alive()
+            and self._active.task_count < self._max_tasks
+        ):
+            return PoolStatus.READY
+        if self._keep_spare:
+            return PoolStatus.NEEDS_ROTATION
+        return PoolStatus.EXHAUSTED
+
+    @property
+    def init_result(self) -> Any:
+        """Return value of ``warming`` from the active worker, or ``None``."""
+        return self._active.init_result if self._active else None
+
+    @property
+    def last_elapsed_ms(self) -> int | None:
+        """Wall-clock milliseconds the last completed task took.
+
+        Returns
+        -------
+        int or None
+            ``None`` if no task has completed yet.
+        """
+        return self._last_elapsed_ms
+
+    @property
+    def last_memory_rss(self) -> int | None:
+        """RSS in bytes of the worker after the last completed task.
+
+        Returns ``None`` if no task has completed or memory checking is disabled.
+        """
+        return self._last_memory_rss
+
+    def run(self, function: Callable, timeout: float, **kwargs: Any) -> Any:
+        """Run *function* in the worker subprocess (blocking).
+
+        Parameters
+        ----------
+        function
+            A picklable callable to execute in the worker.
+        timeout
+            Hard timeout in seconds; the worker is SIGKILLed if it
+            exceeds this.
+        **kwargs
+            Keyword arguments forwarded to *function*.
+
+        Returns
+        -------
+        Any
+            Whatever *function* returns.
+
+        Raises
+        ------
+        TimeoutError
+            If the worker exceeds *timeout*.
+        ProcessPoolExhausted
+            If the pool has no available workers.
+        """
+        status = self.status
+        if status is PoolStatus.READY:
+            pass
+        elif status is PoolStatus.NEEDS_ROTATION:
+            self._rotate_worker()
+        elif status is PoolStatus.EXHAUSTED:
+            # Capture diagnostics *before* cleanup.
+            task_count = self._active.task_count if self._active else 0
+            exit_code = self._active.process.exitcode if self._active else None
+            if self._active is not None:
+                self._shutdown_worker(self._active)
+                self._active = None
+            raise ProcessPoolExhausted(
+                f"tasks={task_count}/{self._max_tasks}",
+                exit_code=exit_code,
+            )
+        elif status is PoolStatus.SHUTDOWN:
+            raise ProcessPoolExhausted("Pool is shut down")
+        else:
+            _assert_never(status)
+
+        # At this point self._active is guaranteed non-None.
+        handle = self._active
+        assert handle is not None  # narrowing for mypy
+
+        # Send the task.
+        handle.connection.send((function, (), kwargs))
+        handle.task_count += 1
+
+        # Wait for result.
+        try:
+            result = self._wait_for_result(handle, function, timeout)
+        except (TimeoutError, ProcessPoolExhausted):
+            self._kill_worker(handle)
+            self._active = None
+            if self._keep_spare:
+                try:
+                    self._promote_spare()
+                except Exception:
+                    log.warning("Failed to promote spare after error", exc_info=True)
+            raise
+
+        # Persist elapsed_ms at pool level so it survives rotation.
+        self._last_elapsed_ms = handle.last_metadata.get("elapsed_ms")
+
+        # Rotate after the final allowed task or memory limit exceeded.
+        memory_exceeded = self._exceeds_memory_limit(handle)
+        if handle.task_count >= self._max_tasks or memory_exceeded:
+            self._shutdown_worker(handle)
+            self._active = None
+            if self._keep_spare:
+                try:
+                    self._promote_spare()
+                except Exception:
+                    log.warning("Failed to promote spare after rotation", exc_info=True)
+
+        return result
+
+    async def arun(self, function: Callable, timeout: float, **kwargs: Any) -> Any:
+        """Async wrapper around :meth:`run`.
+
+        Parameters
+        ----------
+        function
+            A picklable callable.
+        timeout
+            Hard timeout in seconds.
+        **kwargs
+            Forwarded to *function*.
+
+        Returns
+        -------
+        Any
+            Whatever *function* returns.
+        """
+        loop = asyncio.get_running_loop()
+        return await loop.run_in_executor(
+            None, lambda: self.run(function, timeout, **kwargs)
+        )
+
+    def shutdown(self) -> None:
+        """Shut down all workers and mark the pool as dead."""
+        self._shutdown = True
+        if self._active is not None:
+            self._shutdown_worker(self._active)
+            self._active = None
+        if self._spare is not None:
+            self._shutdown_worker(self._spare)
+            self._spare = None
+
+    # ------------------------------------------------------------------
+    # Worker lifecycle
+    # ------------------------------------------------------------------
+
+    def _start_worker(self, block_ready: bool = True) -> WorkerHandle:
+        """Spawn a new worker subprocess.
+
+        Parameters
+        ----------
+        block_ready
+            If ``True``, block until the worker sends ``"ready"``.
+
+        Returns
+        -------
+        WorkerHandle
+        """
+        parent_connection, child_connection = Pipe()
+        log_level = logging.getLogger().getEffectiveLevel()
+        try:
+            context = multiprocessing.get_context("spawn")
+            process = context.Process(
+                target=_worker_process,
+                args=(child_connection, log_level, self._warming),
+            )
+        except RuntimeError:
+            process = Process(
+                target=_worker_process,
+                args=(child_connection, log_level, self._warming),
+            )
+
+        process.start()
+        handle = WorkerHandle(
+            process=process,
+            connection=parent_connection,
+            child_connection=child_connection,
+        )
+        log.info(f"Started worker pid={process.pid}")
+
+        if block_ready:
+            if not self._wait_for_ready(handle):
+                self._kill_worker(handle)
+                raise RuntimeError(
+                    f"Worker pid={handle.process.pid} failed to become ready "
+                    f"within {self._ready_timeout}s"
+                )
+
+        return handle
+
+    def _wait_for_ready(self, handle: WorkerHandle) -> bool:
+        """Block until *handle* sends ``"ready"`` or the timeout expires.
+
+        Parameters
+        ----------
+        handle
+            The worker to wait on.
+
+        Returns
+        -------
+        bool
+            ``True`` if the worker became ready, ``False`` on timeout or error.
+        """
+        deadline = time.perf_counter() + self._ready_timeout
+        while time.perf_counter() < deadline:
+            remaining = max(0.01, deadline - time.perf_counter())
+            if not handle.connection.poll(timeout=remaining):
+                break
+            try:
+                status, payload, _ = handle.connection.recv()
+                if status == "log":
+                    forward_subprocess_log(payload)
+                    continue
+                if status == "ready":
+                    handle.ready = True
+                    handle.init_result = payload
+                    return True
+                log.warning(f"Expected 'ready', got: {status}")
+                return False
+            except Exception as error:
+                log.warning(f"Failed to receive ready signal: {error}")
+                return False
+        log.warning("Worker didn't send ready signal within timeout")
+        return False
+
+    def _wait_for_result(
+        self, handle: WorkerHandle, function: Callable, timeout: float
+    ) -> Any:
+        """Poll *handle* for the task result, forwarding log messages.
+
+        Parameters
+        ----------
+        handle
+            The active worker handle.
+        function
+            The function that was dispatched (used for error messages).
+        timeout
+            Hard timeout in seconds.
+
+        Returns
+        -------
+        Any
+            The return value of *function*.
+
+        Raises
+        ------
+        TimeoutError
+            If *timeout* is exceeded.
+        ProcessPoolExhausted
+            If the worker dies mid-task.
+        """
+        start = time.perf_counter()
+        while time.perf_counter() - start < timeout:
+            if handle.connection.poll(timeout=_POLL_TIMEOUT):
+                try:
+                    status, payload, metadata = handle.connection.recv()
+                except (EOFError, BrokenPipeError):
+                    exit_code = handle.process.exitcode
+                    raise ProcessPoolExhausted(
+                        f"Subprocess died during `{function.__name__}`",
+                        exit_code=exit_code,
+                    )
+
+                if status == "log":
+                    forward_subprocess_log(payload)
+                    continue
+
+                handle.last_metadata = metadata
+
+                if status == "success":
+                    return payload
+                if status == "error":
+                    raise payload
+
+            if not handle.process.is_alive():
+                exit_code = handle.process.exitcode
+                raise ProcessPoolExhausted(
+                    f"Subprocess died during `{function.__name__}`",
+                    exit_code=exit_code,
+                )
+
+        raise TimeoutError(f"`{function.__name__}` timed out after {timeout}s")
+
+    def _exceeds_memory_limit(self, handle: WorkerHandle) -> bool:
+        if self._max_memory is None and self._max_memory_percent_bytes is None:
+            return False
+        try:
+            rss = psutil.Process(handle.process.pid).memory_info().rss
+        except (psutil.NoSuchProcess, psutil.AccessDenied, ProcessLookupError):
+            return False
+        self._last_memory_rss = rss
+        if self._max_memory is not None and rss > self._max_memory:
+            log.info(
+                f"Worker pid={handle.process.pid} RSS {rss:,}B exceeds max_memory={self._max_memory:,}B, rotating"
+            )
+            return True
+        if (
+            self._max_memory_percent_bytes is not None
+            and rss > self._max_memory_percent_bytes
+        ):
+            log.info(
+                f"Worker pid={handle.process.pid} RSS {rss:,}B exceeds percent limit ({self._max_memory_percent_bytes:,}B), rotating"
+            )
+            return True
+        return False
+
+    def _rotate_worker(self) -> None:
+        """Shut down the spent active worker and promote the spare.
+
+        Called when :attr:`status` is :attr:`PoolStatus.NEEDS_ROTATION`.
+        """
+        if self._active is not None:
+            self._shutdown_worker(self._active)
+            self._active = None
+        self._promote_spare()
+
+    def _promote_spare(self) -> None:
+        """Make the spare worker active and replenish the spare.
+
+        If the spare has died or never became ready (e.g. deadlocked
+        during warming), it is killed and a fresh worker is
+        cold-started instead.
+        """
+        if self._spare is not None:
+            if self._spare.process.is_alive():
+                if not self._spare.ready:
+                    self._wait_for_ready(self._spare)
+                if self._spare.ready:
+                    self._active = self._spare
+                    self._spare = None
+                else:
+                    # Spare is alive but never became ready — kill it.
+                    log.warning(
+                        f"Spare pid={self._spare.process.pid} never became ready, killing"
+                    )
+                    self._kill_worker(self._spare)
+                    self._spare = None
+                    self._active = self._start_worker(block_ready=True)
+            else:
+                # Spare died — clean up and cold-start.
+                self._close_worker(self._spare)
+                self._spare = None
+                self._active = self._start_worker(block_ready=True)
+        else:
+            self._active = self._start_worker(block_ready=True)
+
+        # Replenish spare.
+        try:
+            self._spare = self._start_worker(block_ready=False)
+        except Exception:
+            log.warning("Failed to start spare worker", exc_info=True)
+            self._spare = None
+
+    def _shutdown_worker(self, handle: WorkerHandle) -> None:
+        """Gracefully shut down *handle*; escalate to kill if needed.
+
+        Parameters
+        ----------
+        handle
+            The worker to shut down.
+        """
+        if handle.process.is_alive():
+            try:
+                handle.connection.send((None, (), {}))
+            except (BrokenPipeError, OSError):
+                pass
+            handle.process.join(timeout=_JOIN_TIMEOUT)
+            if handle.process.is_alive():
+                self._kill_worker(handle)
+                return
+        self._close_worker(handle)
+
+    def _kill_worker(self, handle: WorkerHandle) -> None:
+        """SIGTERM then SIGKILL the worker and its entire process tree.
+
+        Parameters
+        ----------
+        handle
+            The worker to kill.
+        """
+        if not handle.process.is_alive():
+            self._close_worker(handle)
+            return
+        try:
+            worker = psutil.Process(handle.process.pid)
+            children = worker.children(recursive=True)
+            for child in children:
+                child.terminate()
+            worker.terminate()
+            gone, alive = psutil.wait_procs(children + [worker], timeout=0.1)
+            for remaining in alive:
+                remaining.kill()
+            psutil.wait_procs(alive, timeout=_KILL_WAIT)
+        except (psutil.NoSuchProcess, ProcessLookupError):
+            pass
+        except psutil.TimeoutExpired:
+            log.warning("Process tree still alive after SIGKILL")
+        except Exception:
+            log.error("Error killing process tree", exc_info=True)
+        self._close_worker(handle)
+
+    def _close_worker(self, handle: WorkerHandle) -> None:
+        """Join the process and close both pipe endpoints.
+
+        Parameters
+        ----------
+        handle
+            The worker whose resources should be freed.
+        """
+        handle.process.join(timeout=_POLL_TIMEOUT)
+        try:
+            handle.connection.close()
+        except Exception:
+            pass
+        try:
+            handle.child_connection.close()
+        except Exception:
+            pass