Struct CtxBuilder 

pub struct CtxBuilder<'a> { /* private fields */ }

Fluent builder for Ctx.

Scenario unit tests reach for a Ctx with sane defaults so they can exercise scenario logic without booting a VM. The direct struct-literal construction at ~14 call sites forces every test to repeat the full 12-field init and keeps diverging defaults in sync by hand; this builder centralises those defaults and keeps required fields (borrowed cgroups/topo) in their types.

Defaults:

• duration: 1 s — matches the scenario::basic test helper (scenario::stress uses 2 s and sets it explicitly)
• workers_per_cgroup: 1
• sched_pid: None — run_scenario short-circuits the liveness checks when sched_pid.is_none().
• settle: 0 ms — tests do not need to wait for scheduler stabilisation
• work_type_override: None
• assert: crate::assert::Assert::default_checks() — the same policy production paths merge through
• wait_for_map_write: false

Override any default via the corresponding method, then materialise the context with CtxBuilder::build.

Example

let cgroups = CgroupManager::new("/nonexistent");
let topo = TestTopology::synthetic(4, 1);
let ctx = Ctx::builder(&cgroups, &topo)
    .workers_per_cgroup(3)
    .duration(Duration::from_secs(2))
    .build();

Implementations

impl<'a> CtxBuilder<'a>

pub fn duration(self, d: Duration) -> Self

Wall-clock budget for the workload phase of the scenario.

pub fn workers_per_cgroup(self, n: usize) -> Self

Number of worker threads started per cgroup by the default workload.

pub fn sched_pid(self, pid: Option<pid_t>) -> Self

PID of the scheduler process; None disables the liveness checks in run_scenario.

pub fn settle(self, s: Duration) -> Self

Time to wait after cgroup creation for scheduler stabilisation.

pub fn work_type_override(self, wt: Option<WorkType>) -> Self

Override the default work type for scenarios that would otherwise use SpinWait.

pub fn assert(self, a: Assert) -> Self

Merged assertion config. Callers that want the production layering should pass Assert::default_checks().merge(&...); tests that pin a specific policy can pass crate::assert::Assert::NO_OVERRIDES directly.

pub fn wait_for_map_write(self, v: bool) -> Self

When true, execute_steps blocks on the bpf_map_write_done latch (set on the host’s SIGNAL_BPF_WRITE_DONE over virtio-console RX) after writing the scenario start marker. See the field doc on Ctx::wait_for_map_write.

pub fn current_step(self, cs: Arc<AtomicU16>) -> Self

Inject a caller-owned per-VM step-index publisher. The default Ctx::builder already constructs a fresh Arc<AtomicU16> initialised to 0, so most callers do not need this setter; it exists so the host-side VM runner can hand the same Arc to both the scenario driver Ctx and the freeze-coordinator thread, giving both halves a single per-VM source of truth for the current phase.

pub fn entry_name(self, name: &'static str) -> Self

Drift-safe path derivation. Stamp the &'static str name of the KtstrTestEntry the dispatched test body was registered as. Drives the body-side path-derivation methods on Ctx (failure_dump_path, wprof_pb_path, repro_wprof_pb_path) so test authors get the drift-safe per-test sidecar path without re-hardcoding the test fn name in the body — a future test rename surfaces a deterministic Result<PathBuf> bail rather than a runtime ENOENT against a stale literal.

The framework’s macro-stamped dispatch path (maybe_dispatch_vm_test_with_args + the host-only dispatcher) calls this with the entry name at Ctx construction time, before the test body runs. Ad-hoc scenario unit tests that build Ctx without the dispatch path skip this setter, and the path-derivation methods bail with an actionable diagnostic — see Ctx::failure_dump_path for the None-case bail shape.

pub fn variant_hash(self, hash: u64) -> Self

Stamp the run’s variant hash (see variant_hash_from_parts) so the body-side failure_dump_path / wprof_pb_path derivations embed it as the -{16-hex} filename suffix. Set at the macro dispatch site alongside Self::entry_name; ad-hoc fixtures leave it 0.

pub fn build(self) -> Ctx<'a>

Materialise the configured Ctx.