Module payload_run 

Runtime builder for launching a Payload from a test body.

ctx.payload(&X) returns a PayloadRun whose chainable methods configure args, checks, and cgroup placement before the terminal .run() (foreground) or .spawn() (background) executes the binary inside the guest VM.

.run() blocks until the child exits and returns Result<(AssertResult, PayloadMetrics)>. The builder is a pure guest-side std::process::Child wrapper — no cross-VM proxy.

PayloadKind::Scheduler payloads are rejected at .run(): schedulers are launched by the framework at test start, not by test-body invocation. Only PayloadKind::Binary payloads are runnable via this builder.

Args composition:

1. payload.default_args unless .clear_args() was called.
2. Plus any runtime .arg(...) / .args(...) appends.

Checks composition is identical in shape.

Stdout-primary, stderr-fallback metric extraction

The extraction pipeline runs extract_metrics against stdout first. When that returns an empty metric set AND stderr is non-empty, the extractor retries against stderr. This preserves the stdout-primary contract for well-behaved binaries (noisy stderr never corrupts the metric stream) while still handling payloads that emit their structured output only on stderr — e.g. schbench’s default percentile tables via show_latencies → fprintf(stderr, ...). The two streams are never merged: concurrent drain threads for stdout/stderr provide no ordering guarantee, so interleaving would corrupt any document whose bytes span both streams.

Stderr is still forwarded verbatim into the exit-code-mismatch detail produced by MetricCheck::ExitCodeEq (see the format_exit_mismatch path) so failing binaries surface their error output directly.

Structs

PayloadHandle

Handle to a background payload spawned via PayloadRun::spawn. Wraps a guest-local std::process::Child; wait / kill both consume the handle and return the collected metrics + assertion verdict.

PayloadRun

Builder returned by Ctx::payload.