cayu.runtime.application_lifecycle

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.

ApplicationAdmission

from cayu import ApplicationAdmission

Seal-once gate for local entrances, counting operations still in flight.

Each operation counts once: a call it makes in its own task is part of it. Work an admitted operation starts while still running, including in a background task that outlives it, is not refused after sealing, and that task is counted so shutdown waits for it. Once the operation finished, its leftover tasks are refused like any other new work.

init (method)

ApplicationAdmission.__init__() -> None

sealed (property)

ApplicationAdmission.sealed() -> bool

in_flight (property)

ApplicationAdmission.in_flight() -> int

closed (property)

ApplicationAdmission.closed() -> bool

seal (method)

ApplicationAdmission.seal() -> None

Refuse new top-level operations; idempotent and never reopened.

close (method)

ApplicationAdmission.close() -> None

Refuse every operation from now on, including tracked ones.

The final transition before releasing what operations depend on: unlike seal, nothing is admitted or tracked afterwards.

acquire (method)

ApplicationAdmission.acquire() -> _AdmissionLease

Admit and count one operation, unless sealed and not started by admitted work.

track (method)

ApplicationAdmission.track() -> _AdmissionLease

Count one operation that stays allowed while the application drains.

release (method)

ApplicationAdmission.release(lease: _AdmissionLease) -> None

wait_idle (method)

async ApplicationAdmission.wait_idle(timeout_s: float) -> bool

Wait until no admitted operation remains, up to timeout_s.

Release source · Runtime guarantees · Capability guides

ApplicationAdmissionsSealed

from cayu import ApplicationAdmissionsSealed

A new local operation cannot start after the application began shutting down.

Bases: RuntimeError.

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

Release source · Runtime guarantees · Capability guides

ApplicationShutdown

from cayu import ApplicationShutdown

Run ordered shutdown stages under one deadline and report the outcome.

Repeated and concurrent calls share one attempt at a time. A settled outcome is final; after an incomplete or failed outcome, a later call runs a new attempt that first rejoins steps still running from the previous one. A caller’s cancellation propagates to that caller promptly while the attempt finishes within its own deadline.

init (method)

ApplicationShutdown.__init__(*, admission: ApplicationAdmission, stages: Callable[[], Sequence[ShutdownStage]], late_work: Callable[[], Mapping[str, ApplicationShutdownStepReason]]=dict, owned_resources: Iterable[SupportsAsyncClose]=()) -> None

state (property)

ApplicationShutdown.state() -> ApplicationLifecycleState

aclose (method)

async ApplicationShutdown.aclose(*, timeout_s: float) -> ApplicationShutdownOutcome

Release source · Runtime guarantees · Capability guides

ApplicationShutdownOutcome

from cayu import ApplicationShutdownOutcome

Truthful, process-local result of one application shutdown attempt.

settled means every step completed and no owned work remained. It says nothing about other processes sharing the same durable stores.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
status	ApplicationShutdownStatus	required
attempt	StrictInt	Field(ge=1)
timeout_seconds	float	Field(gt=0)
elapsed_seconds	float	Field(ge=0)
steps	tuple[ApplicationShutdownStep, ...]	required
open_operations	StrictInt	Field(ge=0)
owned_resources	OwnedResourcesStatus	required
scope	Literal['process_local']	'process_local'

settled (property)

ApplicationShutdownOutcome.settled() -> bool

step (method)

ApplicationShutdownOutcome.step(subsystem: str) -> ApplicationShutdownStep | None

unsettled (property)

ApplicationShutdownOutcome.unsettled() -> tuple[ApplicationShutdownStep, ...]

summary (method)

ApplicationShutdownOutcome.summary() -> str

One content-free line describing this attempt, for logs and terminals.

Release source · Runtime guarantees · Capability guides

ApplicationShutdownStep

from cayu import ApplicationShutdownStep

Content-free outcome of one shutdown step.

Bases: BaseModel.

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
subsystem	StrictStr	required
status	ApplicationShutdownStepStatus	required
budget_seconds	float	Field(ge=0)
elapsed_seconds	float	Field(ge=0)
reason	ApplicationShutdownStepReason | None	None
failure_type	StrictStr | None	None

Release source · Runtime guarantees · Capability guides

ShutdownBudget

from cayu import ShutdownBudget

One deadline shared by a sequence of bounded shutdown operations.

init (method)

ShutdownBudget.__init__(timeout_s: float) -> None

remaining (method)

ShutdownBudget.remaining() -> float

Seconds left before the shared deadline, never negative.

expired (method)

ShutdownBudget.expired() -> bool

elapsed (method)

ShutdownBudget.elapsed() -> float

step_budget (method)

ShutdownBudget.step_budget(*, floor_s: float=0.0) -> float

The remaining time, or floor_s when that is larger.

Release source · Runtime guarantees · Capability guides

ShutdownStepSpec

from cayu import ShutdownStepSpec

One bounded shutdown operation.

run receives its time budget and returns True/None when settled or False when work remains. floor_protected steps still run after the shared deadline is exhausted because their timeout path performs local cleanup. seal synchronously refuses the subsystem’s new work; it runs even when the deadline is exhausted and the drain itself is skipped.

Decorators: @dataclass(frozen=True).

Fields and attributes

Defaults below are source expressions; Field(...) includes schema/validation settings and default_factory creates a fresh value. Inherited declarations are included. Constructor behavior follows the model or dataclass shown in the bases/decorators.

Name	Type	Default
subsystem	str	required
run	Callable[[float], Awaitable[bool | None]]	required
floor_protected	bool	False
incomplete_reason	ApplicationShutdownStepReason	'still_draining'
seal	Callable[[], None] | None	None

Release source · Runtime guarantees · Capability guides

SupportsAsyncClose

from cayu import SupportsAsyncClose

A resource whose ownership was explicitly transferred to the application.

Bases: Protocol.

close (method)

async SupportsAsyncClose.close() -> None

Release source · Runtime guarantees · Capability guides