fhelium.residency.plan

Inspectable low-level plans for residency transitions.

A residency plan is an immutable intermediate representation (IR). It records ordered reclaim, entry, and exit transition requests plus temporary accounting reservations. A manager resolves any omitted move source against current state and reports each completed transition separately.

DiscardValue

class View source

DiscardValue(handle: ResidencyHandle[ValueT_co])

Bases: Generic[ValueT_co]

End a managed value and remove all of its materializations.

Attributes

Name	Type	Default/value
handle	ResidencyHandle[ValueT_co]

DropResident

class View source

DropResident(handle: ResidencyHandle[ValueT_co], location: ResidencyLocation)

Bases: Generic[ValueT_co]

Remove one materialization without ending the managed value.

Attributes

Name	Type	Default/value
handle	ResidencyHandle[ValueT_co]
location	ResidencyLocation

EnsureResident

class View source

EnsureResident(handle: ResidencyHandle[ValueT_co], location: ResidencyLocation)

Bases: Generic[ValueT_co]

Require a managed value to be resident at location.

Attributes

Name	Type	Default/value
handle	ResidencyHandle[ValueT_co]
location	ResidencyLocation

MemoryReservation

class View source

MemoryReservation(location: ResidencyLocation, nbytes: int, label: str)

Named accounting headroom held for the lifetime of a plan scope.

Reservations account for future storage but do not allocate tensors or imply any value placement.

Attributes

Name	Type	Default/value
location	ResidencyLocation
nbytes	int
label	str

MoveResident

class View source

MoveResident(handle: ResidencyHandle[ValueT_co], to: ResidencyLocation, from_location: ResidencyLocation | None = None)

Bases: Generic[ValueT_co]

Move a managed value to to from an optional explicit source.

from_location=None delegates source resolution to the manager while preserving move semantics: successful completion does not retain the selected source materialization.

Attributes

Name	Type	Default/value
handle	ResidencyHandle[ValueT_co]
to	ResidencyLocation
from_location	ResidencyLocation | None	None

ResidencyAction

data View source

ResidencyAction: TypeAlias = EnsureResident[TensorResident] | MoveResident[TensorResident] | DropResident[TensorResident] | DiscardValue[TensorResident]

ResidencyPlan

class View source

ResidencyPlan(name: str, enter: tuple[ResidencyAction, ...] = (), exit: tuple[ResidencyAction, ...] = (), reservations: tuple[MemoryReservation, ...] = (), reclaim: tuple[ResidencyAction, ...] = ())

Immutable ordered residency plan executed at scope entry and exit.

reclaim actions execute first and may free capacity needed by the scope. Reservations are admitted only after reclaim completes, then enter actions execute in tuple order. exit actions execute in tuple order when the plan scope closes. The tuples are normalized at construction so callers cannot mutate a plan by retaining an input list. Each action remains a manager request.

Parameters

• name: Non-empty diagnostic plan identity.
• reclaim: Ordered actions that establish capacity before reservations.
• enter: Ordered actions for plan-scope entry.
• exit: Ordered actions for plan-scope exit.
• reservations: Capacity reservations held across the plan scope.

Attributes

Name	Type	Default/value
name	str
enter	tuple[ResidencyAction, ...]	()
exit	tuple[ResidencyAction, ...]	()
reservations	tuple[MemoryReservation, ...]	()
reclaim	tuple[ResidencyAction, ...]	()