Struct Sample 

#[non_exhaustive]
pub struct Sample<'a> {
    pub tag: &'a str,
    pub elapsed_ms: Option<u64>,
    pub snapshot: Snapshot<'a>,
    pub stats: Result<&'a Value, &'a MissingStatsReason>,
    pub step_index: Option<u16>,
    pub boundary_offset_ms: Option<u64>,
}

One captured periodic sample: a frozen BPF snapshot paired with the scx_stats JSON observed just before the freeze rendezvous, labelled with the periodic tag (periodic_000 … periodic_NNN) and tagged with the elapsed milliseconds since run_start.

Constructed by SampleSeries::iter_samples — test authors do not invoke Sample::new directly. The 'a lifetime ties the borrowed tag, snapshot, and stats references back to the owning SampleSeries.

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

tag: &'a str

Periodic tag the freeze coordinator stamped onto this sample. Always begins with "periodic_" followed by a zero-padded ordinal — see crate::vmm::freeze_coord::periodic_tag.

elapsed_ms: Option<u64>

Wall-clock elapsed milliseconds (pause-adjusted: the coordinator subtracts cumulative ScenarioPause/Resume pause time and any in-flight pause window) since the coordinator’s run_start instant at stats-request completion time, pre-freeze. The coordinator captures this timestamp AFTER the scx_stats request returns (or fails) and BEFORE entering the freeze rendezvous, so the value reflects when the running scheduler’s stats were observed. BPF state is observed up to FREEZE_RENDEZVOUS_TIMEOUT later than this anchor. None when the bridge could not record a timestamp (legacy stores without elapsed metadata, or non-periodic captures surfaced through the same drain) — distinct from a measured Some(0).

snapshot: Snapshot<'a>

Frozen BPF state captured at this boundary. The view is cheap to build — accessor methods walk the underlying FailureDumpReport in place.

stats: Result<&'a Value, &'a MissingStatsReason>

scx_stats JSON observed by a stats request issued just BEFORE the freeze rendezvous. Err(reason) when the stats client was not wired (scheduler_binary is absent) or the request failed — the carried MissingStatsReason identifies the specific failure mode (no scheduler, relay rejected, watchdog cancelled, scheduler errno, etc.). SampleSeries::stats surfaces this Err as a per-sample SnapshotError::MissingStats slot in the resulting SeriesField rather than vacuously skipping; temporal patterns handle that error per their own policy (gap-tolerant patterns like nondecreasing, rate_within, steady_within, converges_to, and ratio_within skip the sample with a rendered Note, while strict patterns like always_true and each fail the assertion so a stats-coverage gap can never silently slip past the call site).

step_index: Option<u16>

Scenario phase index the freeze coordinator stamped onto this sample at capture time. Encoded per the framework’s 1-indexed phase convention — 0 is the BASELINE settle window, 1..=N align with scenario Step ordinals. None for fixture-injected samples that took the unstamped legacy bridge paths (super::snapshot::SnapshotBridge::capture / super::snapshot::SnapshotBridge::store / super::snapshot::SnapshotBridge::store_with_stats); production captures via the periodic-fire path and the on-demand Op::CaptureSnapshot / Op::WatchSnapshot apply arms always carry Some(idx). Read by SampleSeries::by_stamped_phase (and as the offset-less fallback in SampleSeries::by_stimulus_phase) to bucket samples per scenario phase for the phase-aware aggregator.

boundary_offset_ms: Option<u64>

Workload-relative boundary offset (ms) this periodic capture was scheduled for (boundary_ns - scenario_anchor_ns), or None for non-periodic / on-demand captures. Distinct from elapsed_ms (run_start-relative fire time, ~uniform across a deferred-fire burst). Read by crate::assert::build_phase_buckets / crate::assert::build_phase_buckets_with_stimulus to attribute the capture to the guest step whose stimulus window contains this offset, and as the workload-relative bucket start/end. None falls back to elapsed_ms + the stored step_index (today’s behavior for on-demand captures).

Trait Implementations

impl<'a> Debug for Sample<'a>

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

Formats the value using the given formatter.