Struct SpeculationController 

pub struct SpeculationController { /* private fields */ }

Runtime-neutral owner of one volume generation’s two speculation engines.

The controller performs no I/O and spawns no work. It gives embedded, browser, daemon, and fleet adapters one atomic transition surface while execution remains pull-based through execute_residency and execute_promotion.

Implementations

impl SpeculationController

pub fn new( options: SpeculationOptions, volume_id: VolumeId, generation_id: GenerationId, ) -> Result<Self, SpeculationControllerError>

Creates both engines against the same exact volume generation.

Errors

Rejects an invalid policy without retaining either partial engine.

pub fn observe_hint( &mut self, operation_id: OperationId, volume_id: VolumeId, generation_id: GenerationId, foreground_bytes: u64, hint: ResidencyHint, ) -> Result<ResidencyAdmission, SpeculationControllerError>

Records foreground demand and evaluates its already-authenticated successor as one all-or-nothing transition.

Errors

Leaves foreground history and admission state unchanged on exact accounting failure.

pub fn plan_promotion( &mut self, permit: ResidencyPermit, accepted_tiers: Vec<StorageTier>, residency: &[ObjectResidency], destinations: &[PromotionDestination], ) -> Result<PromotionAdmission, SpeculationControllerError>

Converts an admitted local prediction into a bounded promotion plan.

Errors

Leaves promotion state unchanged on policy or accounting failure.

pub fn finish_residency( &mut self, operation_id: OperationId, useful: bool, ) -> Result<(), SpeculationControllerError>

Records terminal local-residency usefulness exactly once.

Errors

Rejects unknown identities or accounting overflow without mutation.

pub fn finish_promotion( &mut self, operation_id: OperationId, useful: bool, ) -> Result<(), SpeculationControllerError>

Records terminal promotion usefulness exactly once.

Errors

Rejects unknown identities or accounting overflow without mutation.

pub fn preempt_for_foreground( &mut self, foreground_bytes: u64, ) -> Result<SpeculationPreemption, SpeculationControllerError>

Preempts both engines before recording new foreground traffic.

Errors

Commits all cancellations and traffic together or changes neither engine.

pub fn replace_generation( &mut self, generation_id: GenerationId, ) -> Result<SpeculationPreemption, SpeculationControllerError>

Atomically fences both engines onto a new immutable generation.

Errors

Leaves both engines on the old generation if either transition fails.

pub const fn metrics(&self) -> SpeculationMetrics

Returns both exact metrics from one committed controller state.

pub const fn residency(&self) -> &ResidencySpeculator

Borrows the local residency engine for pull-based execution.

pub const fn promotion(&self) -> &PromotionSpeculator

Borrows the promotion engine for pull-based execution.

pub fn active_residency_permit( &self, operation_id: OperationId, ) -> Option<ResidencyPermit>

Returns one currently active local execution permit.

Trait Implementations

impl Clone for SpeculationController

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.