fhelium.residency.controller
Choose residency transitions from working-set requests and manager state.
A controller produces a placement decision for one manager state version. The associated ResidencyManager validates and executes transfers, accounting changes, and protected lifetimes.
ResidencyController
class View source
ResidencyController(manager: ResidencyManager, *, policy: ResidencyPolicy | None=None, search_state_limit: int=100000)Choose placement and eviction actions for one residency manager.
The controller tracks policy metadata and logical access epochs. Each call produces a decision tied to the observed manager state. Protected materializations are ineligible for eviction; stale decisions and failed actions are reported to the caller for a new decision. The manager executes the selected transitions, retaining any actions completed before a failure.
manager
property
manager: ResidencyManagerThe sole state and materialization authority used by this controller.
policy
property
policy: ResidencyPolicyPure policy used to rank invariant-filtered candidates.
set_policy_metadata
method
def set_policy_metadata(handle: ResidencyHandle[Any], *, priority: int=0, stable_key: str | None=None) -> None: ...Set controller-local eviction metadata for one known handle.
decide
method
def decide(request: ResidencyRequest) -> ResidencyDecision: ...Derive an inspectable decision without executing residency actions.
scope
method
def scope(decision: ResidencyDecision, *, transfer_streams: TransferStreams | None=None) -> ResidencyScope: ...Return a scope that version-checks and commits decision on entry.
use
method
def use(request: ResidencyRequest, *, consumer_streams: ConsumerStreams | None=None, transfer_streams: TransferStreams | None=None) -> ResidencyUse: ...Return a context that derives, admits, and borrows one decision.
Values remain cached after the use scope. Later admission may reclaim them under policy. No exit eviction, hidden synchronization, or background work is performed.
ResidencyDecision
class View source
ResidencyDecision(manager_id: str, expected_state_version: int, explored_states: int, request: ResidencyRequest, plan: ResidencyPlan, policy_name: str, policy_config: tuple[tuple[str, object], ...], evictions: tuple[ResidencyEviction, ...], explanation: ResidencyPlanExplanation)Immutable result tied to its issuing manager and state version.
A decision is valid only for the issuing manager at expected_state_version. It is process-local evidence, not a serialized or distributed execution artifact. Entering the associated manager scope atomically rechecks the version before any reclaim action or reservation.
Attributes
| Name | Type | Default/value |
|---|---|---|
manager_id | str | |
expected_state_version | int | |
explored_states | int | |
request | ResidencyRequest | |
plan | ResidencyPlan | |
policy_name | str | |
policy_config | tuple[tuple[str, object], ...] | |
evictions | tuple[ResidencyEviction, ...] | |
explanation | ResidencyPlanExplanation |
ResidencyEviction
class View source
ResidencyEviction(action: DropResident[TensorResident] | MoveResident[TensorResident], rank: int, released_location: ResidencyLocation, released_nbytes: int, reason: str)One controller-selected reclaim action and its policy evidence.
Attributes
| Name | Type | Default/value |
|---|---|---|
action | DropResident[TensorResident] | MoveResident[TensorResident] | |
rank | int | |
released_location | ResidencyLocation | |
released_nbytes | int | |
reason | str |
ResidencyUse
class View source
ResidencyUse(*, controller: ResidencyController, request: ResidencyRequest, consumer_streams: ConsumerStreams | None, transfer_streams: TransferStreams | None)Single-use automatic admission, borrow, and reservation lifetime.
decision
property
decision: ResidencyDecisionState-versioned decision after successful context entry.
values
property
values: Mapping[ResidencyRequirement, TensorResident]Borrowed values keyed by requirement during this context.
value
method
def value(handle: ResidencyHandle[Any], *, at: ResidencyLocation) -> TensorResident: ...Return the borrow for one (handle, location) endpoint.
report
property
report: ResidencyPlanReport | NoneCompleted plan report after successful scope close.
exit_error
property
exit_error: BaseException | NoneStructured plan cleanup failure retained by the underlying scope.