Struct StackTuner 

pub struct StackTuner { /* private fields */ }

No state mutex is held while running a candidate, validator, profile, or disk operation. Contenders use the declared reference instead of waiting (also avoids nested-tuning deadlocks).

Implementations

impl StackTuner

pub fn new( policy: StackPolicy, cache_directory: Option<PathBuf>, ) -> Result<Self, TuneFailure>

Validate policy and create an independent controller. None disables disk storage. Construction performs no disk I/O and does not install this instance as the global runtime controller.

pub fn policy(&self) -> &StackPolicy

Borrow the immutable policy; runtime reconfiguration is not supported.

pub fn stats(&self) -> Stats

Snapshot this instance’s counters without launching device work.

pub fn lower_level_fingerprint(&self) -> String

Conservative dependency snapshot for complete pipelines. It includes all currently cached lower-level decisions in this controller, including other workloads/devices. That may over-invalidate a pipeline but never hides a changed lower-level choice.

pub fn reports(&self) -> Vec<TuneReport>

Clone retained search diagnostics, oldest first, bounded by min(capacity, 128). Cache hits are counters, not new search reports.

pub fn select( &self, problem: &Problem, candidates: &[Candidate], reference: usize, runner: &mut impl TrialRunner, ) -> Result<Decision, TuneFailure>

Reuse or select an eligible implementation for one exact workload. Candidate names must be unique/nonempty, count 1..=4096, and the reference index must exist and fit policy. Empty operation/environment/workload or an oversized key return InvalidInput. Trials may synchronize; memory hits do not. A returned decision does not execute the caller’s live request.

pub fn invalidate(&self, decision: &Decision, ban_candidate: bool)

Invalidate future selections; NEVER re-run the current stateful request after a failure. ban_candidate=true additionally bans a non-reference name for this key. Removes the persistent record when possible; disk failures increment cache warnings.

pub fn record_comparison( &self, decision: &Decision, reference: Duration, selected: Duration, correctness_checked: bool, ) -> Result<bool, TuneFailure>

Feed paired observations from a controlled replay of the SAME workload and load regime. Ordinary production request latency is NOT a comparable baseline measurement. Returns true only when the accumulated ratio window invalidates this decision. Missing records or changed winner names return false; zero or unchecked timings return InvalidInput. This observation does not revalidate TTL.