Struct PayloadRun 

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

Builder returned by Ctx::payload.

Configure the run via chainable methods, then invoke .run() (foreground, blocking) or .spawn() (background) to execute the payload’s binary inside the guest VM and receive the extracted crate::test_support::PayloadMetrics plus an AssertResult for any declared MetricChecks.

Implementations

impl<'a> PayloadRun<'a>

pub fn arg(self, arg: impl Into<String>) -> Self

Append one CLI argument to the effective argv.

pub fn args<I, S>(self, args: I) -> Self

where I: IntoIterator<Item = S>, S: Into<String>,

Append multiple CLI arguments to the effective argv.

pub fn clear_args(self) -> Self

Wipe ALL args (both payload.default_args and any prior .arg() calls). Subsequent .arg() calls start from empty.

pub fn check(self, c: MetricCheck) -> Self

Append a MetricCheck to the effective check list.

pub fn clear_checks(self) -> Self

Wipe ALL checks (both payload.default_checks and any prior .check() calls).

pub fn in_cgroup(self, name: impl Into<Cow<'static, str>>) -> Self

Place the spawned child in the named cgroup (a plain name, resolved relative to ctx.cgroups.parent_path()). When omitted, the child inherits the spawning process’s cgroup.

Accepts &'static str (zero-alloc, the common case of a const cgroup name) or any owned string type via Cow’s From impls.

The name is validated at .run()/.spawn() — leading / is stripped, .. and NUL bytes are rejected.

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

Bound .run()’s wait for the payload to exit. None (the default when .timeout is not called) waits indefinitely — suitable for payloads whose runtime is bounded internally (schbench -r 10, fio --runtime, …). Some(duration) arms a deadline watchdog inside .run() that SIGKILLs the payload’s whole process group if it has not exited by the deadline. Ignored by .spawn() — background handles manage their own timing.

The builder shape keeps .run() zero-arg so non-timeout call sites read naturally, and leaves room for future knobs (per-test environment, stdin, …) without another signature break.

pub fn run(self) -> Result<(AssertResult, PayloadMetrics)>

Blocking foreground run. Spawns the payload binary, waits for it to exit, extracts metrics from its output per the payload’s OutputFormat (stdout-primary with stderr fallback for Json; no extraction for ExitCode), and evaluates declared MetricChecks into an AssertResult. See the module-level # Stdout-primary, stderr-fallback metric extraction section for the full contract.

Runtime is bounded by the value set via timeout. When the deadline expires, kill_payload_process_group fires and the returned (AssertResult, PayloadMetrics) reflects the captured output plus the killed-child exit code; status.code() returns None for a SIGKILL’d child, which spawn_and_wait surfaces as exit_code = -1 in SpawnOutput. The timeout case is not an error — the caller can still inspect metrics collected before the kill. A post-kill drain failure is reported as Err (wraps the original I/O error with “drain after timeout of N”); the caller loses no output that was already captured because the partial reader-thread buffers have been consumed in the error path too.

Metrics are also recorded to the per-test sidecar via the SHM ring; the returned tuple is a convenience view of the same values.

Returns Err when the payload is not PayloadKind::Binary (schedulers are framework-launched, not test-body-launched), when the cgroup name fails validation, when the spawn itself fails, or when post-kill drain fails (see the timeout paragraph).

pub fn spawn(self) -> Result<PayloadHandle>

Spawn the payload binary in the background and return a PayloadHandle the caller can .wait(), .kill(), or .try_wait() on.

The child runs in the guest’s process namespace (all ktstr tests execute inside the VM); PayloadHandle is a thin wrapper over std::process::Child. No cross-VM proxy.

Dropping the handle without first calling one of the waiters emits a stderr warning and SIGKILLs the child — leaked handles would lose metrics and potentially outlive the test.

Returns Err when the payload is not PayloadKind::Binary or when the spawn itself fails.

Trait Implementations

impl Debug for PayloadRun<'_>

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

Formats the value using the given formatter.