Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Core Concepts

ktstr tests compose from three layers:

Scenarios

The condition the test creates: cgroups, CPU partitioning, workloads, and mid-run changes.

Work types

What each worker process does, with variants aimed at specific scheduler paths.

Checking

How results are judged: worker progress, spread, stuck gaps, monitor thresholds, and temporal patterns.

One test, all three layers visible:

#[ktstr_test(
    scheduler = MY_SCHED,             // scheduler under test
    llcs = 2, cores = 4, threads = 1, // topology the VM boots with
    not_stuck = true,               // checking: every worker progressed
    max_spread_pct = 20.0,            // checking: fairness bound
)]
fn steady_two_cells(ctx: &Ctx) -> Result<AssertResult> {
    scenarios::steady(ctx)  // scenario: 2 cgroups of CPU-spin workers
                            // (work type: the default SpinWait)
}

The layers compose orthogonally: the same scenario body runs across every topology a gauntlet sweep declares, and the checks apply uniformly to every variant.

Five more concepts round out the picture:

Ops, Steps, and Backdrop

The lower-level API behind scenarios, used when state changes mid-run.

Topology

The NUMA/LLC/core/thread layout a test declares and the VM actually boots.

MemPolicy

Per-worker NUMA memory placement for locality-sensitive tests.

Performance Mode

Host-side isolation for noise-sensitive measurements.

Resource Budget

How concurrent VMs and kernel builds share host CPUs safely.

Read Scenarios, Work types, and Checking first — every test touches all three. Ops matters once a canned scenario stops being enough, and Topology once placement behavior is under test. Performance Mode and Resource Budget are operational: read them when measurements get noisy or hosts get shared.