ProcessPoolBackend

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class ProcessPoolBackend(workers: int = 1, *, subject_timeout_sec: float | None = 900.0, subject_spawn_timeout_sec: float | None = 120.0, graceful_shutdown_sec: float = 15.0, on_subject_failure: str = 'continue', oom_backoff: bool = True, oom_reduce_workers_by: int = 1, cap_workers_to_gpu_pool: bool = False, parallel_mode: str = 'persistent', auto_retry_rounds: int = 2, resume: bool = True, retry_failed_subjects: bool = False, force_rerun_subjects: Tuple[str, ...] = (), clear_checkpoint_on_success: bool = False, persistent_worker_max_consecutive_failures: int = 1, persistent_worker_recycle_after_tasks: int = 0)[source]

Bases: object

Execute subject-level work across child processes.

This backend ports the v0.1 individual-level parallel machinery – timeouts, graceful shutdown, failure isolation, OOM backoff, resume – behind the ExecutionBackend protocol, so no algorithm ever manages a process pool itself.

Parameters:

  • workers – Parallel worker processes; 1 still runs the work in a child (the process boundary is the point of this backend).

  • subject_timeout_sec – Wall-clock seconds per subject; None disables the per-subject timeout.

  • subject_spawn_timeout_sec – Seconds allowed for an isolated child to start; None disables it. Only meaningful in isolated mode (persistent workers start once per round, not per subject).

  • graceful_shutdown_sec – Seconds between terminate() and kill() when a process must be stopped.

  • on_subject_failure – "continue" isolates a subject failure in its result slot; "fail_fast" aborts the run.

  • oom_backoff – Reduce the effective worker count after a fatal memory error.

  • oom_reduce_workers_by – Workers subtracted per OOM event; the effective count never drops below one.

  • cap_workers_to_gpu_pool – Clamp workers to the detected GPU pool; no-op when no pool is detectable.

  • parallel_mode – "persistent" keeps one long-lived worker per slot; "isolated" spawns one child process per subject.

  • auto_retry_rounds – Extra dispatch rounds for failed subjects within one run; 0 disables.

  • resume – Reuse checkpointed successes and honour recorded failures.

  • retry_failed_subjects – Re-run subjects whose checkpoint records a failure instead of skipping them.

  • force_rerun_subjects – Subject ids reprocessed even when a checkpoint success exists.

  • clear_checkpoint_on_success – Clear the checkpoint store after a run with zero failures.

  • persistent_worker_max_consecutive_failures – Restart a persistent slot after this many consecutive fatal-class failures.

  • persistent_worker_recycle_after_tasks – Restart a persistent worker after this many successes (0 disables).

__init__(workers: int = 1, *, subject_timeout_sec: float | None = 900.0, subject_spawn_timeout_sec: float | None = 120.0, graceful_shutdown_sec: float = 15.0, on_subject_failure: str = 'continue', oom_backoff: bool = True, oom_reduce_workers_by: int = 1, cap_workers_to_gpu_pool: bool = False, parallel_mode: str = 'persistent', auto_retry_rounds: int = 2, resume: bool = True, retry_failed_subjects: bool = False, force_rerun_subjects: Tuple[str, ...] = (), clear_checkpoint_on_success: bool = False, persistent_worker_max_consecutive_failures: int = 1, persistent_worker_recycle_after_tasks: int = 0) → None[source]
classmethod from_policy(policy: RunPolicy) → ProcessPoolBackend[source]

Build a backend from its declarative snapshot.

Parameters:

policy – The run policy to transcribe; every field maps onto the constructor parameter of the same name.

Returns:

The configured backend.

reuse_workers() → Iterator[ProcessPoolBackend][source]

Keep persistent workers alive across successive map() calls.

Nested enters are reference-counted. Isolated mode is a no-op (each subject already owns a short-lived child). Recipes use this to avoid paying Windows spawn/import twice for two_step units + labels.

property policy: RunPolicy

Return the validated policy snapshot behind this backend.

property workers: int

Return the effective worker count (after any GPU capping).

map(op: SubjectOperator[TIn, TOut], items: Iterable[TIn], *, checkpoint: CheckpointStore | None = None, progress: Callable[[int, int], None] | None = None) → Iterator[SubjectResult[TOut]][source]

Apply op across items with checkpoint-aware resume.

Results stream out in COMPLETION order (successes immediately, terminal failures after their retry rounds are exhausted); each SubjectResult names its subject so callers restore the canonical order, per the backend protocol.

Parameters:

  • op – The subject-level operation to run.

  • items – Subject-scoped inputs.

  • checkpoint – Optional store for resume and persistence.

  • progress – Optional callback receiving (completed, total).

Yields:

One SubjectResult per item, exactly once.

Raises:

BaseException – The first subject failure under on_subject_failure="fail_fast".

Examples using habit.execution.ProcessPoolBackend

Running the same study on each backend

Running the same study on each backend