fhelium.residency.lease
Borrowed value, hold, and accounting-reservation lifetimes.
BorrowedValues
class View source
BorrowedValues(lease: ResidencyLease)Bases: Mapping[ResidencyHandle[Any], TensorResident]
Concrete immutable materializations borrowed through one active lease.
The mapping validates its lease on every lookup and iteration. Returned exact values remain ordinary Python objects; callers must not mutate them or retain aliases beyond the lease. Managed memory accounting is strong only for manager-owned aliases that obey these borrowing rules.
ResidencyHold
class View source
ResidencyHold(*, manager: ResidencyManager, token: object, handles: tuple[ResidencyHandle[Any], ...], location: ResidencyLocation)Long-lived retention protection that exposes no concrete value.
Attributes
| Name | Type | Default/value |
|---|---|---|
close | release |
active
property
active: boolWhether this hold still protects its materializations.
handles
property
handles: tuple[ResidencyHandle[Any], ...]Managed values retained by this hold.
location
property
location: ResidencyLocationLocation at which the materializations are retained.
release
method
def release() -> None: ...Release exactly this retention protection idempotently.
ResidencyLease
class View source
ResidencyLease(*, manager: ResidencyManager, token: object, handles: tuple[ResidencyHandle[Any], ...], location: ResidencyLocation, consumer_streams: Sequence[torch.cuda.Stream])Short read lifetime protected through CUDA consumer completion.
A lease is created only by ResidencyManager.acquire. CUDA consumer streams are registered rather than synchronized at Python scope exit. On release, the manager records one completion event per registered stream and retains every materialization until those events complete. CUDA acquisition requires one consumer stream; CPU leases release immediately.
Consumers using additional CUDA streams must call add_consumer_stream before release. Abandoning a lease synchronizes its registered streams before release; if that fails, a process-global strong root conservatively retains the manager and its storage.
Attributes
| Name | Type | Default/value |
|---|---|---|
close | release |
active
property
active: boolWhether the Python lease scope remains open.
handles
property
handles: tuple[ResidencyHandle[Any], ...]Managed values protected by this lease.
location
property
location: ResidencyLocationLocation of every borrowed materialization.
values
property
values: BorrowedValuesBorrowed mapping valid until this lease is released.
add_consumer_stream
method
def add_consumer_stream(stream: torch.cuda.Stream) -> None: ...Register another CUDA stream whose prior reads this lease protects.
release
method
def release(*, wait: bool=False) -> None: ...Close the borrow and protect CUDA reads until completion.
Parameters
wait: Synchronize recorded completion events before returning. WithFalse, the manager retains a pending protection and reaps it after the events report completion.
ResidencyReservation
class View source
ResidencyReservation(*, manager: ResidencyManager, token: object, location: ResidencyLocation, nbytes: int, label: str)Idempotently releasable accounting reservation at one location.
Attributes
| Name | Type | Default/value |
|---|---|---|
close | release |
active
property
active: boolWhether this reservation still charges its location budget.
release
method
def release() -> None: ...Return the reserved headroom to its location budget.