Struct FreshnessController 

pub struct FreshnessController<P: FreshnessPolicy, C: FreshnessClock> { /* private fields */ }

Drives the optimistic verify-and-rerun loop over an EvmCache.

Holds the freshness FreshnessRegistry, the shared SlotObservationTracker, a FreshnessPolicy, a FreshnessClock, and the pending-corrections queue. The tracker and the pending queue are Arc<Mutex<…>> so the background validator can update them without touching the !Send cache. Adaptive thresholds (FreshnessParams) live on the policy that uses them (ObservationDriven), not on the controller.

Runtime requirement

run spawns a background task and the (synchronous) fetcher uses block_in_place internally, so a multi-thread tokio runtime is required (#[tokio::main(flavor = "multi_thread")] or Builder::new_multi_thread()), mirroring the EvmCache constructor note.

Implementations

impl<P: FreshnessPolicy> FreshnessController<P, BlockClock>

pub fn new(registry: FreshnessRegistry, policy: P) -> Self

Build a controller with the default BlockClock (starting at block 0).

Starts with a fresh, empty SlotObservationTracker and an empty pending-corrections queue. Use with_tracker to share a persisted tracker, or with_clock for a non-default clock such as WallClock.

impl<P: FreshnessPolicy, C: FreshnessClock> FreshnessController<P, C>

pub fn with_clock(registry: FreshnessRegistry, policy: P, clock: C) -> Self

Build a controller with an explicit clock.

Starts with a fresh, empty SlotObservationTracker and an empty pending-corrections queue. The clock’s units must match those the policy’s FreshnessParams were tuned for (block numbers for BlockClock, unix seconds for WallClock).

pub fn with_tracker(self, tracker: Arc<Mutex<SlotObservationTracker>>) -> Self

Use an existing shared observation tracker (e.g. a persisted one).

Builder-style override that replaces the fresh tracker installed by new / with_clock with the given shared handle, so change-frequency history survives across runs or is shared with other components. The background validator updates this same tracker under its Mutex.

pub fn tracker(&self) -> &Arc<Mutex<SlotObservationTracker>>

The shared observation tracker.

pub fn registry(&self) -> &FreshnessRegistry

The freshness registry.

pub fn registry_mut(&mut self) -> &mut FreshnessRegistry

Mutable access to the freshness registry.

pub fn pending_len(&self) -> usize

Number of corrections waiting to be drained into the cache on the next run.

pub fn rerun_count(&self) -> usize

Cumulative number of background re-runs performed by the validator across all run calls so far.

Incremented once per sim that the reconcile step actually re-executes (i.e. whose read set intersected a changed slot). A Corrected verdict over n requests where only one slot changed advances this by the number of affected sims, not by n — making the selective-re-run behavior directly observable.

pub fn on_new_block(&mut self, block: u64)

Advance to a new block.

Advances the clock to block (a no-op for WallClock, a set_block for BlockClock) and then notifies the policy. Advancing the clock is what ages Validity::ValidThrough slots into Validity::Volatile and progresses the observation-tracker reuse window through the natural API.

pub fn run( &mut self, cache: &mut EvmCache, requests: Vec<SimRequest>, ) -> Result<SpeculativeSim>

Run the optimistic loop for a batch of requests.

1. Drain queued corrections from prior cycles into the cache.
2. Snapshot the cache and grab the batch fetcher.
3. Run each request optimistically against the snapshot, capturing its actual volatile read set.
4. Compute the predicted volatile candidates and ask the policy which to verify.
5. Spawn the background validator (Send data only) and return a SpeculativeSim immediately.

Panics

Must be called from within a tokio runtime: it calls tokio::spawn to launch the background validator, which panics (there is no reactor running) if no runtime is active. The spawned (synchronous) fetcher additionally uses tokio::task::block_in_place internally, so the runtime must be multi-thread (#[tokio::main(flavor = "multi_thread")] or Builder::new_multi_thread()); on a current-thread runtime block_in_place panics, mirroring the EvmCache constructor note.

Errors

Returns an error if any optimistic simulation fails to execute against the freshly-created snapshot (propagated from EvmOverlay::call_raw_with_access_list).