pub struct ResidencyController { /* private fields */ }Expand description
Validated backend-neutral declarations paired with residency control state.
Concrete backends own their native values separately and mirror every publication or eviction through this controller’s ledger. Keeping the declarations here ensures checkpoint shape policy and plan identity are validated before any backend allocation begins.
Implementations§
Source§impl ResidencyController
impl ResidencyController
Sourcepub fn new<C: RecipeCatalog + ?Sized>(
catalog: &C,
plan: OffloadPlan,
units: impl IntoIterator<Item = OffloadUnit>,
) -> Result<Self, ResidencyControllerError>
pub fn new<C: RecipeCatalog + ?Sized>( catalog: &C, plan: OffloadPlan, units: impl IntoIterator<Item = OffloadUnit>, ) -> Result<Self, ResidencyControllerError>
Validates declarations against checkpoint metadata and an explicit plan.
Sourcepub fn unit(&self, id: &OffloadUnitId) -> Option<&OffloadUnit>
pub fn unit(&self, id: &OffloadUnitId) -> Option<&OffloadUnit>
Returns the validated declaration for one planned unit.
Sourcepub fn units(&self) -> impl ExactSizeIterator<Item = &OffloadUnit>
pub fn units(&self) -> impl ExactSizeIterator<Item = &OffloadUnit>
Returns declarations in stable unit-identifier order.
Sourcepub fn binding_owner(
&self,
unit: &OffloadUnitId,
binding: &WeightBinding,
) -> Option<(&OffloadUnitId, &WeightBinding)>
pub fn binding_owner( &self, unit: &OffloadUnitId, binding: &WeightBinding, ) -> Option<(&OffloadUnitId, &WeightBinding)>
Resolves a logical alias to its canonical owner unit and binding.
Returns the canonical owner location when a binding participates in a shared alias family, including the canonical owner itself.
Sourcepub const fn ledger(&self) -> &ResidencyLedger
pub const fn ledger(&self) -> &ResidencyLedger
Returns immutable ownership, capacity, and telemetry state.
Sourcepub fn ledger_mut(&mut self) -> &mut ResidencyLedger
pub fn ledger_mut(&mut self) -> &mut ResidencyLedger
Returns mutable ownership, capacity, and telemetry state.
Sourcepub fn plan_acquisition(
&mut self,
ids: &[OffloadUnitId],
tier: MemoryTier,
) -> Result<ResidencyAcquisition, ResidencyLedgerError>
pub fn plan_acquisition( &mut self, ids: &[OffloadUnitId], tier: MemoryTier, ) -> Result<ResidencyAcquisition, ResidencyLedgerError>
Validates one batch and snapshots which requested copies need realization.
Sourcepub fn plan_initialization_acquisition(
&mut self,
ids: &[OffloadUnitId],
tier: MemoryTier,
) -> Result<ResidencyAcquisition, ResidencyLedgerError>
pub fn plan_initialization_acquisition( &mut self, ids: &[OffloadUnitId], tier: MemoryTier, ) -> Result<ResidencyAcquisition, ResidencyLedgerError>
Validates a batch while the manager is realizing its initial planned tiers.
Sourcepub fn reserve_acquisition(
&mut self,
acquisition: &ResidencyAcquisition,
reservations: &[(OffloadUnitId, u64)],
tier: MemoryTier,
) -> Result<Vec<EvictedResidencyCopy>, ResidencyLedgerError>
pub fn reserve_acquisition( &mut self, acquisition: &ResidencyAcquisition, reservations: &[(OffloadUnitId, u64)], tier: MemoryTier, ) -> Result<Vec<EvictedResidencyCopy>, ResidencyLedgerError>
Reserves backend-supplied physical capacities while protecting the complete batch.
Sourcepub fn touch_acquisition_hits(
&mut self,
acquisition: &ResidencyAcquisition,
tier: MemoryTier,
) -> Result<(), ResidencyLedgerError>
pub fn touch_acquisition_hits( &mut self, acquisition: &ResidencyAcquisition, tier: MemoryTier, ) -> Result<(), ResidencyLedgerError>
Updates recency for copies which were hits when the batch began.
Sourcepub fn rollback_acquisition(
&mut self,
acquisition: &ResidencyAcquisition,
tier: MemoryTier,
) -> Result<(), ResidencyLedgerError>
pub fn rollback_acquisition( &mut self, acquisition: &ResidencyAcquisition, tier: MemoryTier, ) -> Result<(), ResidencyLedgerError>
Rolls back every missing copy which remains an unpublished reservation.
Sourcepub fn publish_acquisition_copy(
&mut self,
id: &OffloadUnitId,
tier: MemoryTier,
actual_bytes: u64,
transferred_bytes: u64,
transfer_generation: Option<u64>,
direction: TransferDirection,
duration: Duration,
) -> Result<(), ResidencyLedgerError>
pub fn publish_acquisition_copy( &mut self, id: &OffloadUnitId, tier: MemoryTier, actual_bytes: u64, transferred_bytes: u64, transfer_generation: Option<u64>, direction: TransferDirection, duration: Duration, ) -> Result<(), ResidencyLedgerError>
Publishes one realized copy and records its backend transfer observation.
Sourcepub fn begin_prefetch(
&mut self,
id: &OffloadUnitId,
tier: MemoryTier,
) -> Result<PrefetchOutcome, ResidencyLedgerError>
pub fn begin_prefetch( &mut self, id: &OffloadUnitId, tier: MemoryTier, ) -> Result<PrefetchOutcome, ResidencyLedgerError>
Records a prefetch hit or miss before backend realization begins.
Sourcepub fn resolve_transfer(
&mut self,
ids: &[OffloadUnitId],
tier: MemoryTier,
generation: u64,
succeeded: bool,
) -> Result<Vec<EvictedResidencyCopy>, ResidencyLedgerError>
pub fn resolve_transfer( &mut self, ids: &[OffloadUnitId], tier: MemoryTier, generation: u64, succeeded: bool, ) -> Result<Vec<EvictedResidencyCopy>, ResidencyLedgerError>
Resolves one exact transfer and returns backend copies invalidated by failure.
Sourcepub fn commit_group_window(
&mut self,
group: &str,
active: &[OffloadUnitId],
upcoming: &[OffloadUnitId],
tier: MemoryTier,
) -> Result<Vec<OffloadUnitId>, ResidencyLedgerError>
pub fn commit_group_window( &mut self, group: &str, active: &[OffloadUnitId], upcoming: &[OffloadUnitId], tier: MemoryTier, ) -> Result<Vec<OffloadUnitId>, ResidencyLedgerError>
Replaces one protected window and selects unique bounded lookahead in caller order.
A concrete backend calls this after any in-flight copies touching the requested units have reached a stable state.
Sourcepub fn protect_group_window(
&mut self,
group: &str,
active: &[OffloadUnitId],
tier: MemoryTier,
) -> Result<(), ResidencyLedgerError>
pub fn protect_group_window( &mut self, group: &str, active: &[OffloadUnitId], tier: MemoryTier, ) -> Result<(), ResidencyLedgerError>
Replaces one protected window without selecting or materializing lookahead.