Struct SpeedGate 

pub struct SpeedGate { /* private fields */ }

Whether a wall-clock ratio measured in this build is about the SHIPPED codegen.

It is not the optimisation level: [profile.test] already carries opt-level = 2. It is codegen LAYOUT. [profile.test.package.gam-models] sets codegen-units = 16 and the test profile carries no LTO, while [profile.release] is codegen-units = 1 plus thin-LTO, and the whole margin of a compiled-vs-hand row kernel can be cross-CGU inlining. A ratio taken in the test profile therefore measures a different program than the one that ships, and a debug build measures fixed per-call overhead and nothing else. Every speed gate in this workspace opens only there.

That decision is made by the TEST that opens the gate, never by this module: test code may query its own build configuration, library code may not (build.rs bans cfg!(debug_assertions) outside test modules, because a library branch that only runs in one build configuration silently means something else in the other). A gate opened in the dev lane would assert about the wrong program, so the test returns before opening it:

if cfg!(debug_assertions) {
    return; // dev lane: the codegen is not the shipped one
}
let mut gate = SpeedGate::open("RIGID-BERNOULLI-VGH-932");

One speed gate: a named set of paired cells, each printed as it is measured and all asserted together at the end.

This is the ONE shape a wall-clock contract takes in this workspace, and its call site is the marker the release lane derives the gate population from: scripts/speed_gates.py walks the crates for every #[test] whose body calls SpeedGate::open, resolves each to an exact test path in the compiled release binary, runs exactly that set, and refuses a run in which any derived gate did not execute. A gate therefore cannot be forgotten by a name-prefix filter, cannot print ok having asserted nothing, and cannot assert in a lane whose codegen is not the shipped one.

Shape of a gate

// parity pins run in EVERY build, before the gate opens
if cfg!(debug_assertions) {
    return; // dev lane: skip the measurement, its verdict is about the wrong program
}
let mut gate = SpeedGate::open("RIGID-BERNOULLI-VGH-932");
let timing = paired_interleaved(15, 300_000, seed, production_arm, hand_arm);
gate.faster("y=1", &timing, "production", "hand");
gate.finish();

The profile check is the test’s, not the gate’s (see the module documentation above): a gate that is opened always asserts, and the dev lane does not pay for millions of timed iterations whose result it could not use because the test never opens one there.

Two contracts, no third

• SpeedGate::faster — the #932 contract: A (the compiled lowering) must be strictly faster than B (the strongest hand path or the generic tower it specialises). Loss when median_ratio() <= 1.
• SpeedGate::not_slower — for a cell whose two arms do the same work by construction and where no speed claim is made: A must not be measurably slower than B, where “measurably” is the measurement’s OWN resolution, PairedTiming::ratio_resolution. Loss when median_ratio() + ratio_resolution() < 1. There is no chosen tolerance here: the instrument reports its noise floor, and that is the only denominator a parity bar can honestly be stated in.

A gate that is opened and dropped without SpeedGate::finish panics, and a gate finished with no cells panics: both are gates that verified nothing.

Implementations

impl SpeedGate

pub fn open(token: &'static str) -> Self

Open a gate. It always asserts; the test decides whether this build is one whose verdict is meaningful before calling (see the type docs).

token is the stable, grep-able prefix every cell line of this gate is printed under (for example RIGID-BERNOULLI-VGH-932).

Examples found in repository

examples/paired_timing_report.rs (line 113)

fn main() {
    let input: [f64; 17] = std::array::from_fn(|index| 0.35 + 0.07 * (index as f64 + 1.0).sin());
    for (compiled, canonical) in compiled_bundle4(input).iter().zip(canonical_bundle4(input).iter()) {
        assert!((compiled - canonical).abs() <= 1e-12 * canonical.abs().max(1.0));
    }
    let timing = paired_interleaved(
        15,
        2_000,
        0x9320_AB,
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            compiled_bundle4(x).iter().sum()
        }),
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            canonical_bundle4(x).iter().sum()
        }),
    );
    println!("{}", timing.summary("compiled_bundle4", "nine_top_channels"));
    // The two contracts a gate can carry, printed the way a gate prints them.
    let mut gate = SpeedGate::open("PAIRED-TIMING-REPORT");
    gate.faster("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.not_slower("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.finish();
}

pub fn faster(&mut self, cell: &str, timing: &PairedTiming, a: &str, b: &str)

Record a cell whose contract is “A is strictly faster than B”.

Examples found in repository

examples/paired_timing_report.rs (line 114)

fn main() {
    let input: [f64; 17] = std::array::from_fn(|index| 0.35 + 0.07 * (index as f64 + 1.0).sin());
    for (compiled, canonical) in compiled_bundle4(input).iter().zip(canonical_bundle4(input).iter()) {
        assert!((compiled - canonical).abs() <= 1e-12 * canonical.abs().max(1.0));
    }
    let timing = paired_interleaved(
        15,
        2_000,
        0x9320_AB,
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            compiled_bundle4(x).iter().sum()
        }),
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            canonical_bundle4(x).iter().sum()
        }),
    );
    println!("{}", timing.summary("compiled_bundle4", "nine_top_channels"));
    // The two contracts a gate can carry, printed the way a gate prints them.
    let mut gate = SpeedGate::open("PAIRED-TIMING-REPORT");
    gate.faster("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.not_slower("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.finish();
}

pub fn not_slower( &mut self, cell: &str, timing: &PairedTiming, a: &str, b: &str, )

Record a cell whose contract is “A is not measurably slower than B”, measurable meaning beyond the paired measurement’s own resolution.

Examples found in repository

examples/paired_timing_report.rs (line 115)

fn main() {
    let input: [f64; 17] = std::array::from_fn(|index| 0.35 + 0.07 * (index as f64 + 1.0).sin());
    for (compiled, canonical) in compiled_bundle4(input).iter().zip(canonical_bundle4(input).iter()) {
        assert!((compiled - canonical).abs() <= 1e-12 * canonical.abs().max(1.0));
    }
    let timing = paired_interleaved(
        15,
        2_000,
        0x9320_AB,
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            compiled_bundle4(x).iter().sum()
        }),
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            canonical_bundle4(x).iter().sum()
        }),
    );
    println!("{}", timing.summary("compiled_bundle4", "nine_top_channels"));
    // The two contracts a gate can carry, printed the way a gate prints them.
    let mut gate = SpeedGate::open("PAIRED-TIMING-REPORT");
    gate.faster("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.not_slower("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.finish();
}

pub fn finish(self)

Assert that every recorded cell met its contract, naming all that did not. Consumes the gate.

Examples found in repository

examples/paired_timing_report.rs (line 116)

fn main() {
    let input: [f64; 17] = std::array::from_fn(|index| 0.35 + 0.07 * (index as f64 + 1.0).sin());
    for (compiled, canonical) in compiled_bundle4(input).iter().zip(canonical_bundle4(input).iter()) {
        assert!((compiled - canonical).abs() <= 1e-12 * canonical.abs().max(1.0));
    }
    let timing = paired_interleaved(
        15,
        2_000,
        0x9320_AB,
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            compiled_bundle4(x).iter().sum()
        }),
        batched(64, |nudge| {
            let mut x = input;
            x[4] += nudge;
            canonical_bundle4(x).iter().sum()
        }),
    );
    println!("{}", timing.summary("compiled_bundle4", "nine_top_channels"));
    // The two contracts a gate can carry, printed the way a gate prints them.
    let mut gate = SpeedGate::open("PAIRED-TIMING-REPORT");
    gate.faster("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.not_slower("order=4 bundle", &timing, "compiled_bundle4", "nine_top_channels");
    gate.finish();
}

Trait Implementations

impl Drop for SpeedGate

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.