cayu.environments.warm_spares

Public Cayu API. Definitions are grouped by their public source module, and definitions from private implementation modules appear on their package’s page; adding a symbol does not move existing links. The import shown at each entry is a supported public namespace. Read the Python API overview and install the required extra.

WarmSpareBackend

from cayu.environments import WarmSpareBackend

The resource side of a WarmSparePool.

Every method may raise. The pool treats any Exception as “no spare”: it discards the spare it was handling and the caller falls back to its cold-start path.

Bases: Protocol[SpareT].

create_spare (method)

async WarmSpareBackend.create_spare(name: str) -> SpareT

Create one spare named name through the backend’s cold-start path.

Run the same admission probes a cold start runs, on this exact resource, and remove it before raising if they fail.

spare_is_alive (method)

async WarmSpareBackend.spare_is_alive(spare: SpareT) -> bool

Whether the idle spare can still be handed out.

claim_spare (method)

async WarmSpareBackend.claim_spare(spare: SpareT, name: str, requirements: ExecutionRequirements) -> SpareT

Make spare the consumer’s resource name and return what it uses.

Re-verify anything the consumer’s requirements add beyond what the spare was created with. Raise to refuse; the pool then discards it and returns None. Raise WarmSpareRequirementsUnsatisfied when the requirements themselves cannot be met by a spare.

discard_spare (method)

async WarmSpareBackend.discard_spare(spare: SpareT) -> None

Remove a spare that will never be handed out.

list_spare_names (method)

async WarmSpareBackend.list_spare_names(prefix: str) -> Sequence[str]

Names of every spare resource on this host that starts with prefix.

remove_spare_named (method)

async WarmSpareBackend.remove_spare_named(name: str) -> None

Remove the spare resource called name; absence is not an error.

Release source · Runtime guarantees · Capability guides

WarmSparePool

from cayu.environments import WarmSparePool

Keep up to size idle spares and hand each to exactly one consumer.

take never raises for a backend failure: it returns None and the caller cold-starts. Refill is single-flight, capped at size and backs off on backend errors. release_idle trims idle spares and lets a later use refill; close trims them for good.

Bases: Generic[SpareT].

init (method)

WarmSparePool.__init__(backend: WarmSpareBackend[SpareT], *, size: int, name_prefix: str, reap_interval_s: float=DEFAULT_WARM_SPARE_REAP_INTERVAL_S) -> None

size (property)

WarmSparePool.size() -> int

idle_count (property)

WarmSparePool.idle_count() -> int

closed (property)

WarmSparePool.closed() -> bool

name_prefix (property)

WarmSparePool.name_prefix() -> str

reap_stale (method)

async WarmSparePool.reap_stale() -> list[str]

Remove spares left by dead processes or closed pools on this host.

take (method)

async WarmSparePool.take(name: str, requirements: ExecutionRequirements) -> SpareT | None

Hand one live spare to name, or return None for a cold start.

Only a spare that is no longer alive makes take try the next one. A failed claim discards that spare and stops, so one bad claim cannot burn the whole pool; requirements a spare cannot satisfy are remembered for a while and go straight to a cold start.

schedule_refill (method)

WarmSparePool.schedule_refill() -> None

Start one background refill unless full, closed, released or backing off.

wait_for_refill (method)

async WarmSparePool.wait_for_refill() -> None

Wait for the in-flight refill, if any, to settle.

release_idle (method)

async WarmSparePool.release_idle() -> None

Remove every idle spare; the next take refills the pool.

close (method)

async WarmSparePool.close() -> None

Remove every idle spare and create no more. Later takes cold-start.

Release source · Runtime guarantees · Capability guides

WarmSpareRequirementsUnsatisfied

from cayu.environments import WarmSpareRequirementsUnsatisfied

Raised by claim_spare when a spare cannot meet the consumer’s requirements.

The pool then sends later claims with the same requirements straight to a cold start for a while, instead of spending a spare on each attempt.

Bases: RuntimeError.

This type’s implementation and inherited behavior are available in the linked release source.

Release source · Runtime guarantees · Capability guides