Expand description
Race probes: env-gated perturbation points on Hermit’s own host-timed edges, for reproducing rare races in Hermit itself (docs/RACE_PROBES.md).
Off unless RACE_PROBE_ENV is set to a non-empty list of
point=LO[-HI][@P] items. At point, with probability P (default 1), a
visit is perturbed: an async point waits a uniform LO..=HI milliseconds,
and a synchronous point takes its perturbed branch (its numbers ignored).
RACE_PROBE_SEED_ENV fixes the choices; without it a seed is drawn from
the host clock. Either way the configuration and seed are printed once to
stderr, so a failing run names its seed.
point=hold makes every visit to an async point wait, without a time
limit, until a file named after the point exists in
RACE_PROBE_HOLD_DIR_ENV: a test can then act on a task while it is
known to be at the point, and release it after. A held visit prints one
line to stderr naming the file it waits for.
Unset, every point is one read of an initialized OnceLock and a branch;
nothing is logged, and no tracing event is emitted.
A probe only moves host timing that Hermit already treats as nondeterministic input (when a backgrounded call returns, and when the scheduler samples that it has), so an outcome reached under a probe is one host timing alone could produce. Decisions are drawn in visit order from one process-wide counter, so a seed replays exactly only when the number of visits before the deciding one does not itself depend on host timing.
Constants§
- RACE_
PROBE_ ENV - The variable that enables race probes and lists their settings.
- RACE_
PROBE_ HOLD_ DIR_ ENV - The directory whose files release held points (
point=hold). - RACE_
PROBE_ SEED_ ENV - The variable that fixes the seed of the race probes’ choices.