Struct PrefetchExecutionState 

pub struct PrefetchExecutionState<E> { /* private fields */ }

Backend-neutral bounded prefetch admission and execution lifecycle.

The backend owns workers, buffers, I/O, and completion primitives. This value is the sole owner of FIFO ordering, bounded admission, duplicate coalescing, exact operation generations, cancellation fencing, failure retention and recovery, and lifecycle telemetry.

Implementations

impl<E> PrefetchExecutionState<E>

pub fn new(queue_capacity: usize) -> Result<Self, PrefetchStateError>

Creates an empty executor state with a finite, nonzero queue capacity.

pub fn admit(&mut self, id: OffloadUnitId, resident: bool) -> PrefetchAdmission

Admits a missing unit, coalesces existing work, or reports backpressure.

resident is supplied by the backend after checking its concrete storage. A completed logical result that is no longer resident is counted as evicted-before-use and is eligible for a new attempt.

pub fn rollback_admission( &mut self, work: &PrefetchWork, ) -> Result<(), PrefetchStateError>

Rolls back one admitted operation whose backend notification failed.

pub fn begin_next(&mut self) -> Option<PrefetchWork>

Selects the oldest admitted operation for backend submission.

pub fn complete( &mut self, work: PrefetchWork, result: Result<(), E>, ) -> Result<PrefetchCompletion, PrefetchStateError>

Applies one exact backend completion.

pub fn observe_demand( &mut self, id: &OffloadUnitId, ) -> PrefetchDemandObservation

Observes current background ownership when demand first arrives.

pub fn is_pending(&self, id: &OffloadUnitId) -> bool

Whether an admitted or submitted operation still owns this unit.

pub fn resolve_demand( &mut self, id: &OffloadUnitId, waited: Option<Duration>, ) -> Result<PrefetchDemandResolution<E>, PrefetchStateError>

Consumes the terminal background result for one demand acquisition.

pub fn begin_backpressure(&mut self)

Records a submission when it first encounters bounded admission capacity.

pub fn finish_backpressure(&mut self, duration: Duration)

Records how long one backpressured submission waited before resolving.

pub fn cancel_all(&mut self) -> Result<(), PrefetchStateError>

Cancels all queued work immediately and fences exact in-flight work.

In-flight backend resources remain owned until Self::complete sees their exact operation. Queued work needs no backend cancellation and is discarded synchronously.

pub fn finish_cancellation( &mut self, ) -> Result<Option<(OffloadUnitId, E)>, PrefetchStateError>

Finishes cancellation after every exact in-flight operation resolved.

Completed prefetches are abandoned. The first retained backend failure is returned in deterministic logical-unit order.

pub fn is_idle(&self) -> bool

Whether no admitted or backend-submitted operation remains.

pub const fn generation(&self) -> u64

Current cancellation generation.

pub const fn report(&self) -> BackgroundPrefetchReport

Immutable telemetry snapshot.

Trait Implementations

impl<E: Debug> Debug for PrefetchExecutionState<E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.