Struct Config 

pub struct Config {

    pub pass_threshold: f64,
    pub fail_threshold: f64,
    pub time_budget: Duration,
    pub max_samples: usize,
    pub batch_size: usize,
    pub calibration_samples: usize,
    pub min_effect_of_concern_ns: f64,
    pub attacker_model: Option<AttackerModel>,
    pub effect_threshold_ns: Option<f64>,
    pub warmup: usize,
    pub outlier_percentile: f64,
    pub iterations_per_sample: IterationsPerSample,
    pub cpu_affinity: bool,
    pub thread_priority: bool,
    pub frequency_stabilization_ms: u64,
    pub prior_no_leak: f64,
    pub cov_bootstrap_iterations: usize,
    pub calibration_fraction: f32,
    pub max_duration_ms: Option<u64>,
    pub measurement_seed: Option<u64>,
    pub force_discrete_mode: bool,
}

Configuration options for TimingOracle.

The adaptive Bayesian oracle uses these settings to control the analysis behavior, thresholds, and resource limits.

See spec Section 4.2 (Configuration).

Fields

pass_threshold: f64

Threshold for declaring “Pass” (no leak detected).

If the posterior probability of a timing leak falls below this threshold, the test passes. Default: 0.05 (5%).

Lower values require more confidence to pass (more conservative).

fail_threshold: f64

Threshold for declaring “Fail” (leak detected).

If the posterior probability of a timing leak exceeds this threshold, the test fails. Default: 0.95 (95%).

Higher values require more confidence to fail (more conservative).

time_budget: Duration

Maximum time budget for the analysis.

The oracle will stop collecting samples and return Inconclusive if this time limit is reached. Default: 60 seconds.

max_samples: usize

Maximum number of samples to collect per class.

The oracle will stop and return Inconclusive if this limit is reached without achieving a conclusive result. Default: 1,000,000.

batch_size: usize

Number of samples to collect per batch during adaptive sampling.

Larger batches are more efficient but less responsive to early stopping. Default: 1,000.

calibration_samples: usize

Number of samples for initial calibration (covariance estimation).

This fixed number of samples is collected before the adaptive phase begins. Used to estimate the noise covariance matrix. Default: 5,000.

Note: This is a fixed overhead, not prominently configurable.

min_effect_of_concern_ns: f64

Minimum effect size we care about in nanoseconds.

Effects smaller than this won’t trigger high posterior probabilities even if statistically detectable. This encodes practical relevance.

Note: When attacker_model is set, this value may be overridden at runtime based on the attacker model’s threshold.

Default: 10.0 ns.

attacker_model: Option<AttackerModel>

Attacker model preset.

When set, the attacker model’s threshold is used instead of min_effect_of_concern_ns. The threshold is computed at runtime based on the timer’s resolution and CPU frequency.

See AttackerModel for available presets.

Default: None (uses min_effect_of_concern_ns).

effect_threshold_ns: Option<f64>

Optional hard effect threshold in nanoseconds for reporting/panic.

If the detected effect exceeds this threshold, the result is flagged prominently. Default: None.

warmup: usize

Warmup iterations before measurement.

These iterations warm CPU caches, stabilize frequency scaling, and trigger any JIT compilation before actual measurement begins. Default: 1,000.

outlier_percentile: f64

Percentile for outlier winsorization.

Samples beyond this percentile are capped (not dropped) to reduce the impact of extreme outliers while preserving information about tail-heavy distributions. Set to 1.0 to disable.

Default: 0.9999 (99.99th percentile).

iterations_per_sample: IterationsPerSample

Iterations per timing sample.

When set to Auto, the library detects timer resolution and automatically batches iterations when needed for coarse timers. Set to a specific value to override auto-detection.

Default: Auto.

cpu_affinity: bool

Pin the measurement thread to its current CPU core.

Reduces timing noise from thread migration between cores, which can cause cache invalidation and expose different core frequencies. Enabled by default.

• Linux: Enforced via sched_setaffinity (no privileges needed)
• macOS: Advisory hint via thread_policy_set (kernel may ignore)

Set to false if CPU pinning causes issues on your system.

Default: true.

thread_priority: bool

Elevate thread priority during measurement.

Attempts to reduce preemption by other processes by raising the measurement thread’s priority. This is best-effort and fails silently if privileges are insufficient.

• Linux: Lowers nice value and sets SCHED_BATCH policy
• macOS: Lowers nice value and sets thread precedence hint

Set to false if priority elevation causes issues on your system.

Default: true.

frequency_stabilization_ms: u64

Duration of frequency stabilization spin-wait in milliseconds.

Before measurement begins, a brief busy-wait loop runs to let the CPU frequency ramp up and stabilize. Many CPUs start in low-power mode and take several milliseconds to reach their turbo/boost frequency.

Set to 0 to disable frequency stabilization.

Default: 5 ms.

prior_no_leak: f64

Prior probability of no leak.

This is the prior belief that the code under test is constant-time. Higher values make the test more conservative (harder to fail).

Default: 0.75 (75% prior belief in no leak).

cov_bootstrap_iterations: usize

Bootstrap iterations for covariance estimation.

Used during the calibration phase to estimate the noise covariance matrix via block bootstrap. More iterations give better estimates but take longer.

Default: 2,000.

calibration_fraction: f32

Fraction of samples held out for calibration/preflight.

In non-adaptive mode, this fraction of samples is used for covariance estimation. In adaptive mode, this is less relevant since calibration is a fixed upfront cost.

Default: 0.3 (30% for calibration).

max_duration_ms: Option<u64>

👎Deprecated since 0.2.0: Use time_budget instead

Optional guardrail for max duration in milliseconds (legacy).

Prefer using time_budget instead. This is kept for backwards compatibility but will be removed in a future version.

measurement_seed: Option<u64>

Optional deterministic seed for measurement randomness.

When set, the measurement order (interleaving of classes) is deterministic, which can help with debugging and reproducibility.

Default: None (random seed).

force_discrete_mode: bool

Force discrete mode for testing.

When true, discrete mode (m-out-of-n bootstrap with mid-quantiles) is used regardless of timer resolution. This is primarily for testing the discrete mode code path on machines with high-resolution timers.

In production, discrete mode is triggered automatically when the minimum uniqueness ratio < 10% (per spec Section 2.4).

Default: false.

Implementations

impl Config

pub fn new() -> Self

Create a new configuration with default settings.

pub fn pass_threshold(self, threshold: f64) -> Self

Set the pass threshold.

pub fn fail_threshold(self, threshold: f64) -> Self

Set the fail threshold.

pub fn time_budget(self, budget: Duration) -> Self

Set the time budget.

pub fn time_budget_secs(self, secs: u64) -> Self

Set the time budget in seconds.

pub fn max_samples(self, max: usize) -> Self

Set the maximum number of samples.

pub fn batch_size(self, size: usize) -> Self

Set the batch size for adaptive sampling.

pub fn calibration_samples(self, samples: usize) -> Self

Set the number of calibration samples.

pub fn attacker_model(self, model: AttackerModel) -> Self

Set the attacker model.

pub fn warmup(self, iterations: usize) -> Self

Set the warmup iterations.

pub fn outlier_percentile(self, percentile: f64) -> Self

Set the outlier percentile.

pub fn iterations_per_sample(self, iterations: IterationsPerSample) -> Self

Set the iterations per sample.

pub fn cpu_affinity(self, enabled: bool) -> Self

Enable or disable CPU affinity pinning.

When enabled (default), the measurement thread is pinned to its current CPU to reduce noise from thread migration.

• Linux: Enforced via sched_setaffinity
• macOS: Advisory hint via thread_policy_set

pub fn thread_priority(self, enabled: bool) -> Self

Enable or disable thread priority elevation.

When enabled (default), attempts to raise thread priority to reduce preemption during measurement. Fails silently if insufficient privileges.

• Linux: Lowers nice value, sets SCHED_BATCH
• macOS: Lowers nice value, sets thread precedence hint

pub fn frequency_stabilization_ms(self, ms: u64) -> Self

Set the frequency stabilization duration in milliseconds.

A brief spin-wait loop runs before measurement to let the CPU frequency ramp up and stabilize. Set to 0 to disable.

Default: 5 ms.

pub fn prior_no_leak(self, prior: f64) -> Self

Set the prior probability of no leak.

pub fn cov_bootstrap_iterations(self, iterations: usize) -> Self

Set the covariance bootstrap iterations.

pub fn calibration_fraction(self, fraction: f32) -> Self

Set the calibration fraction.

pub fn seed(self, seed: u64) -> Self

Set a deterministic seed for measurement.

pub fn force_discrete_mode(self, force: bool) -> Self

Force discrete mode for testing.

pub fn resolve_min_effect_ns( &self, _cpu_freq_ghz: Option<f64>, _timer_resolution_ns: Option<f64>, ) -> f64

Resolve the minimum effect of concern in nanoseconds.

If an attacker model is set, returns its threshold in nanoseconds. Otherwise, returns the manually configured min_effect_of_concern_ns.

Arguments

• _cpu_freq_ghz - Deprecated, kept for API compatibility
• _timer_resolution_ns - Deprecated, kept for API compatibility

Returns

The resolved threshold in nanoseconds.

pub fn validate(&self) -> Result<(), String>

Check if the configuration is valid.

Returns an error message if the configuration is invalid.

Trait Implementations

impl Clone for Config

fn clone(&self) -> Config

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Config

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

Formats the value using the given formatter.

impl Default for Config

fn default() -> Self

Returns the “default value” for a type.