fhelium.residency.snapshot

Immutable observations and reports for managed residency state.

Snapshots expose logical identities, materialization protection, and strict per-location accounting without retaining tensor-bearing values or mutable manager internals. Explanation records describe a dry-run decision, while transition and plan reports describe completed synchronous manager work.

MaterializationSnapshot

class View source

MaterializationSnapshot(location: ResidencyLocation, logical_nbytes: int, storage_nbytes: int, charged_nbytes: int, use_count: int, hold_count: int, pending_event_count: int)

Protection and byte state of one value at one residency location.

storage_nbytes is the current materialization's actual unique backing storage. charged_nbytes is the fixed conservative admission charge and can be larger after functional movement compacts a view-backed allocation. pending_event_count records completed lease closures whose CUDA work has not yet reached its recorded event. Such a materialization can have use_count == 0 while remaining protected from removal.

Attributes

Name	Type	Default/value
location	ResidencyLocation
logical_nbytes	int
storage_nbytes	int
charged_nbytes	int
use_count	int
hold_count	int
pending_event_count	int

ResidencyActionExplanation

class View source

ResidencyActionExplanation(action: ResidencyAction, executable: bool, no_op: bool, source: ResidencyLocation | None, destination: ResidencyLocation | None, logical_nbytes: int, storage_nbytes: int, reason: str | None = None)

Dry-run explanation of how one requested action would be resolved.

Attributes

Name	Type	Default/value
action	ResidencyAction
executable	bool
no_op	bool
source	ResidencyLocation | None
destination	ResidencyLocation | None
logical_nbytes	int
storage_nbytes	int
reason	str | None	None

ResidencyLocationSnapshot

class View source

ResidencyLocationSnapshot(location: ResidencyLocation, budget_bytes: int | None, used_bytes: int, reserved_bytes: int, remaining_budget_bytes: int | None, peak_used_bytes: int, peak_charged_bytes: int, value_count: int, reservation_count: int, use_count: int, hold_count: int, pending_event_count: int, allocator_allocated_bytes: int | None, allocator_reserved_bytes: int | None)

Budget, usage, and protection accounting for one location.

budget_bytes and remaining_budget_bytes are both None when the manager applies no admission limit at this location. With a budget, remaining_budget_bytes equals the budget minus current materialization and reservation charges. peak_used_bytes is the maximum materialization charge observed by the manager and excludes reservations; peak_charged_bytes includes MemoryReservation and temporary charges. CUDA locations additionally report process-wide PyTorch allocator allocated and reserved bytes at capture time; those metrics include storage outside this manager. Counts are aggregates over current materializations and named reservations at this location.

Attributes

Name	Type	Default/value
location	ResidencyLocation
budget_bytes	int | None
used_bytes	int
reserved_bytes	int
remaining_budget_bytes	int | None
peak_used_bytes	int
peak_charged_bytes	int
value_count	int
reservation_count	int
use_count	int
hold_count	int
pending_event_count	int
allocator_allocated_bytes	int | None
allocator_reserved_bytes	int | None

ResidencyPlanExplanation

class View source

ResidencyPlanExplanation(plan_name: str, actions: tuple[ResidencyActionExplanation, ...], reservations: tuple[MemoryReservation, ...], predicted_peak_bytes: tuple[tuple[ResidencyLocation, int], ...], feasible: bool, reason: str | None = None)

Immutable dry-run feasibility and predicted peak for one plan.

predicted_peak_bytes starts with the manager's tracked locations, then appends locations first referenced by the plan in reservation/action order. It represents the predicted peak of managed backing storage, MemoryReservation plan charges, and temporary source loading without mutating manager state. It is not CUDA caching-allocator reservation.

Attributes

Name	Type	Default/value
plan_name	str
actions	tuple[ResidencyActionExplanation, ...]
reservations	tuple[MemoryReservation, ...]
predicted_peak_bytes	tuple[tuple[ResidencyLocation, int], ...]
feasible	bool
reason	str | None	None

ResidencyPlanReport

class View source

ResidencyPlanReport(plan_name: str, transitions: tuple[ResidencyTransitionReport, ...], started_at_ns: int, completed_at_ns: int)

Completed transition sequence for one plan operation.

A successful execute_actions call or closed scope returns its complete report. A ResidencyPlanExecutionError carries a partial report containing only transitions committed before the runtime failure.

Attributes

Name	Type	Default/value
plan_name	str
transitions	tuple[ResidencyTransitionReport, ...]
started_at_ns	int
completed_at_ns	int

ResidencyReservationSnapshot

class View source

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

One active named accounting reservation without an allocated tensor.

Attributes

Name	Type	Default/value
location	ResidencyLocation
nbytes	int
label	str

ResidencySnapshot

class View source

ResidencySnapshot(manager_id: str, state_version: int, values: tuple[ResidencyValueSnapshot[ValueT_co], ...], locations: tuple[ResidencyLocationSnapshot, ...], reservations: tuple[ResidencyReservationSnapshot, ...], captured_at_ns: int)

Bases: Generic[ValueT_co]

Hierarchical tensor-free observation of one manager at one instant.

state_version is the manager's monotonic mutation version at capture. captured_at_ns is a Unix timestamp in nanoseconds recorded while the manager holds the state lock used to construct both value and location observations.

Attributes

Name	Type	Default/value
manager_id	str
state_version	int
values	tuple[ResidencyValueSnapshot[ValueT_co], ...]
locations	tuple[ResidencyLocationSnapshot, ...]
reservations	tuple[ResidencyReservationSnapshot, ...]
captured_at_ns	int

ResidencyTransitionReport

class View source

ResidencyTransitionReport(action: ResidencyAction, no_op: bool, source: ResidencyLocation | None, destination: ResidencyLocation | None, logical_nbytes: int, storage_nbytes: int, started_at_ns: int, completed_at_ns: int, allocator_device: torch.device | None = None, allocator_allocated_bytes_before: int | None = None, allocator_reserved_bytes_before: int | None = None, allocator_allocated_bytes_after: int | None = None, allocator_reserved_bytes_after: int | None = None, reason: str | None = None)

Measured result of one completed residency action.

action is the exact requested action. source records the resolved source when an action left it implicit, and destination records the target when applicable. CUDA allocator metrics are optional because host transitions and managers without allocator instrumentation cannot provide them. allocator_device identifies the optional allocator sample; a cross-device move samples its destination. Timestamps are Unix nanoseconds.

Attributes

Name	Type	Default/value
action	ResidencyAction
no_op	bool
source	ResidencyLocation | None
destination	ResidencyLocation | None
logical_nbytes	int
storage_nbytes	int
started_at_ns	int
completed_at_ns	int
allocator_device	torch.device | None	None
allocator_allocated_bytes_before	int | None	None
allocator_reserved_bytes_before	int | None	None
allocator_allocated_bytes_after	int | None	None
allocator_reserved_bytes_after	int | None	None
reason	str | None	None

ResidencyValueSnapshot

class View source

ResidencyValueSnapshot(handle: ResidencyHandle[ValueT_co], spec: ResidencyValueSpec[ValueT_co], materializations: tuple[MaterializationSnapshot, ...], has_source: bool, source_location: ResidencyLocation | None, discarded: bool)

Bases: Generic[ValueT_co]

Public state of one registered or discarded managed value.

source_location identifies reconstruction placement when has_source is true. Discarded handles remain visible so diagnostics can explain why they are rejected; they have no source or live materializations.

Attributes

Name	Type	Default/value
handle	ResidencyHandle[ValueT_co]
spec	ResidencyValueSpec[ValueT_co]
materializations	tuple[MaterializationSnapshot, ...]
has_source	bool
source_location	ResidencyLocation | None
discarded	bool