Module sample 

Unified periodic-sample bundle and series projection.

At every periodic boundary (see super::snapshot and the freeze coordinator’s periodic-capture loop), the framework captures a coupled FailureDumpReport + scx_stats JSON pair. Sample is the borrowed-view tuple over that pair plus the per-sample tag and elapsed-millisecond timestamp; SampleSeries is the ordered sequence of samples drained from a SnapshotBridge after VM exit.

Test authors do not construct samples manually — they call SampleSeries::from_drained on the periodic bundle the bridge surfaces via SnapshotBridge::drain_ordered_with_stats, then project the series along one of four orthogonal axes:

• bpf — kernel BPF state through SampleSeries::bpf / the typed SampleSeries::bpf_map helper.
• stats — userspace scx_stats JSON through SampleSeries::stats / the typed SampleSeries::stats_path helper.
• host — per-sample per-CPU host timeline through SampleSeries::host (sourced from FailureDumpReport::per_cpu_time).
• monitor — per-VM-run cross-CPU host monitor aggregate through SampleSeries::monitor (sourced from MonitorReport::summary).

Each projection yields a crate::assert::temporal::SeriesField that flows into the temporal-assertion patterns (nondecreasing, rate_within, steady_within, converges_to, always_true, ratio_within) defined in crate::assert::temporal.

Lifetime model

SampleSeries owns the drained Vec<SampleRow> (each row: tag, report, stats, elapsed_ms, boundary_offset_ms, step_index) so projection closures can borrow into the reports / stats without copying. Constructing a Sample only borrows; SampleSeries::iter_samples yields Sample<'_> bound by the series’ own lifetime.

Structs

BpfMapCpuProjector

Single-CPU view of a per-CPU BPF map, returned by BpfMapProjector::cpu. Its field_* read the chosen CPU’s slot of the map’s per-CPU value — the per-CPU SELECT counterpart to the cross-CPU BpfMapProjector::field_cpu_sum_u64 reductions.

BpfMapProjector

Auto-projector handle returned by SampleSeries::bpf_map. Lazily resolves the named map’s value at the requested entry index when Self::field is invoked.

HostView

Borrowed view over the per-sample per-CPU PerCpuTimeStats data that the host capture pipeline populates into each FailureDumpReport::per_cpu_time. Returned by SampleSeries::host; exposes a per-CPU timeline (rows sorted ascending by elapsed-ms, stable on ties) plus a closure-based projector that emits a SeriesField<u64> compatible with the temporal-assertion patterns in crate::assert::temporal.

MonitorView

Borrowed view over a per-VM-run MonitorReport. Returned by SampleSeries::monitor; provides typed access to the report’s summary statistics + the SCX event-counter deltas.

Sample

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.

SampleSeries

Ordered collection of Samples drained from a SnapshotBridge after a VM run completes. Owns the underlying tuples so projection closures can borrow into the reports / stats without copying.

ScxEventsView

Borrowed view over the ScxEventDeltas aggregated across the monitor’s first/last sample window. Returned by MonitorView::scx_events; exposes the 14 i64 counter totals via Self::total_pairs and the 2 f64 derived rates via Self::rates_pairs.

StatsPathProjector

Auto-projector handle returned by SampleSeries::stats_path. Walks a stats sub-tree per sample and exposes scalar / nested projections for the keys at that level.

StatsValue

Newtype carrier handed to the SampleSeries::stats closure. Wraps a borrowed serde_json::Value and exposes Self::get as a thin facade over stats_path so the closure body reads s.get("layers.batch.util").as_f64() without an explicit import. The .get(path) name mirrors crate::scenario::snapshot::SnapshotField::get and crate::scenario::snapshot::JsonField::get so test authors see one navigator vocabulary across every accessor surface.

Constants

ERROR_CLASS_NAMES

Default curated subset of ScxEventsView::total_pairs counter names that signal genuine scheduler-class errors when non-zero. Used to filter the full 14-entry total slice down to the entries that callers conventionally bound at zero with crate::assert::assert_scx_events_clean.