Expand description
Child processes a test runs to their end, and the one rule every such test keeps: a child the system kills from outside is no result.
A child killed by SIGKILL did not end itself: nothing a program does
raises SIGKILL but a kill of it, and a test that runs a child to its
end sends none, so the OOM killer (or a person) ended it from outside,
whatever the child would have come to. Its run says nothing about the
code under test, but the child is the same on the next run, so
output and status run it again, up to KILLED_RUNS runs in
all, and a child killed on every one of them fails the test, saying the
system killed it. Every other ending is the child’s own and comes back
at once, after one run: an exit status, an abort (SIGABRT: the code
under test’s own abort, or Rust’s report of a stack overflow), any other
signal. Live scenes use scene and live; their explicit
Scene::kill marks a deliberate kill, which is never retried. All other
outside kills restart the entire closure, including its services and FIFOs.
Every Rust test in the workspace that runs a child process runs it
through here: crate::stack’s and crate::address_space’s probes,
the counting allocator’s tally-panic probe, the unityrs binary’s
tests, the tests that run Python, cargo, rustc, git and sh.
(Review round 7 gave the rule to crate::stack::run alone; review
round 8 found the rest failing on one kill under memory pressure.) A
source scan keeps it so (direct_runs). The Python suites and tools
(tools/, scripts/) keep the same rule through tools/parity/child.py
(review round 9), which its own scan keeps.
Each run of a child also gets a scratch folder this process owns and
removes when the run ends, however it ends, named in the child’s
crate::scratch::VAR, so what the child writes there is gone even
when it aborts or is killed (crate::scratch). A caller that sets the
variable on its command (Command::env) or removes it
(Command::env_remove) keeps what it chose.
Owner: package B.
Structs§
- Fifo
- A fresh scene-local FIFO opened before engine spawn. Its dedicated reader drains continuously, preserving partial lines; no stale file can satisfy a later scene’s wait. Drop ends the reader without waiting for engine exit.
- Live
- Scene
Constants§
- DIRECT
- What runs a child process other than through this module:
Command’s own runs, by method (.output(),.spawn()) or by path. - KILLED_
RUNS - The most runs
outputandstatusmake of a child that is killed bySIGKILL(module docs) before they fail the test.
Functions§
- direct_
runs - Every place under
root(its.rsfiles,targetdirectories left out, this file too) that runs a child process other than throughoutputorstatus: each line outside a//comment that names one ofDIRECT(a thread’sspawntakes its closure, so.spawn()is a process’s), and each file that makes more commands (Command::new() than it runs through this module (child::output(,child::status(), which is how a.status()on a command shows (a dump error’s.status()is its exit code). Live children usechild::live; directChild::killis refused too, preserving deliberate-kill bookkeeping. - drain
- Continuously drain a pipe before waiting for the next protocol event.
- killed
- Whether a child that ended with
statuswas killed bySIGKILL. - live
- Spawn an engine or service in the current scene. Use
service=trueonly for a process intentionally retained until scene cleanup. All streams must be drained by the caller when piped;drainsupplies a continuous reader. - output
cmd.output(), run again while aSIGKILLfrom outside ends it, up toKILLED_RUNSruns in all (module docs). Every other outcome is the first run’s, returned asCommand::outputreturns it.- scene
- Rebuild the complete scene after outside kills. Cleanup also runs on panic.
- status
cmd.status()(the child’s streams are this process’s), run again while aSIGKILLfrom outside ends it, asoutput.