Skip to main content

unityrs_testkit/
stack.rs

1//! Stack probes: how a test finds the least stack a path needs, and tells a
2//! stack overflow from every other way a run can fail.
3//!
4//! A thread that overflows its stack takes its whole process with it, so a
5//! test that bisects for the least stack runs the path once per size in a
6//! child process: this test binary again, running one ignored probe test,
7//! with the size in an environment variable ([`fits`], [`least`]). Only a
8//! stack overflow says a size is too small. Rust's runtime catches the
9//! fault on a thread's guard page, prints `thread '…' has overflowed its
10//! stack` and aborts the process (`SIGABRT`). Anything else a child does is
11//! no measurement, and fails the test with what happened: a panic (exit
12//! code 101), an abort with no overflow report (an allocation that failed),
13//! another signal (a `SIGSEGV` the runtime did not report, so not on a
14//! guard page), or a probe that did not run (libtest passes a filter that
15//! matches nothing). (Review round 5: three tests read every unsuccessful
16//! child as an overflow, so a child killed under memory pressure moved a
17//! measurement, and a check made from one could fail, or pass, on a wrong
18//! figure.)
19//!
20//! A child killed by `SIGKILL` did not end the probe itself: the OOM killer
21//! (or a person) ended it from outside, whatever the probe would have come
22//! to. Its run is no measurement, but the probe is the same on the next
23//! run, so [`run`] runs it again, up to [`KILLED_RUNS`] runs in all, and a
24//! probe killed on every one of them fails the test, saying so: the rule
25//! every test's child keeps ([`crate::child`]). A test then measures what
26//! it measures whatever memory the machine has free (review round 7: one
27//! kill under memory pressure failed the test).
28//!
29//! Owner: package B.
30
31use std::process::{Command, ExitStatus, Output};
32
33pub use crate::child::KILLED_RUNS;
34
35/// What Rust's runtime prints when a thread's stack overflows.
36pub const OVERFLOW_REPORT: &str = "has overflowed its stack";
37
38/// What one run of a probe came to.
39#[derive(Clone, Copy, Debug, PartialEq, Eq)]
40pub enum Probe {
41    /// The probe ran and passed.
42    Fits,
43    /// A thread overflowed its stack.
44    Overflows,
45}
46
47/// What a child that exited with `status`, printing `stdout` and `stderr`,
48/// came to, or what else happened to it.
49///
50/// # Errors
51/// Every outcome but a passed probe and a stack overflow, described.
52pub fn classify(status: ExitStatus, stdout: &[u8], stderr: &[u8]) -> Result<Probe, String> {
53    let out = String::from_utf8_lossy(stdout);
54    let err = String::from_utf8_lossy(stderr);
55    let tail = || format!("\n--- stdout\n{}\n--- stderr\n{}", last(&out), last(&err));
56    if status.success() {
57        return if out.contains("test result: ok. 1 passed;") {
58            Ok(Probe::Fits)
59        } else {
60            Err(format!("the probe did not run (no test matched){}", tail()))
61        };
62    }
63    let reported = err.contains(OVERFLOW_REPORT);
64    match (signal(status), status.code()) {
65        (Some(ABORT), _) if reported => Ok(Probe::Overflows),
66        (Some(ABORT), _) => Err(format!(
67            "the probe aborted with no stack overflow reported (an allocation that failed \
68             prints \"memory allocation of N bytes failed\"){}",
69            tail()
70        )),
71        (Some(KILL), _) => Err(format!(
72            "the probe was killed (SIGKILL: the OOM killer, or a person){}",
73            tail()
74        )),
75        (Some(s), _) => Err(format!(
76            "the probe died of signal {s}, with{} a stack overflow reported{}",
77            if reported { "" } else { "out" },
78            tail()
79        )),
80        (None, Some(101)) => Err(format!("the probe panicked{}", tail())),
81        (None, code) => Err(format!("the probe exited with {code:?}{}", tail())),
82    }
83}
84
85const ABORT: i32 = 6;
86const KILL: i32 = 9;
87
88#[cfg(unix)]
89fn signal(status: ExitStatus) -> Option<i32> {
90    std::os::unix::process::ExitStatusExt::signal(&status)
91}
92
93#[cfg(not(unix))]
94fn signal(_: ExitStatus) -> Option<i32> {
95    None
96}
97
98/// The last lines of `text`, enough to say what a child did.
99fn last(text: &str) -> String {
100    crate::child::tail(text.as_bytes())
101}
102
103/// Runs this test binary's ignored test `probe` (its whole path, as
104/// `--exact` matches it) in a child process with `var` set to `value`. A
105/// child killed by `SIGKILL` is no measurement, and the probe is run again,
106/// up to [`KILLED_RUNS`] runs in all ([`crate::child::output`]).
107///
108/// # Panics
109/// When the child can not start, comes to anything but [`Probe`]
110/// ([`classify`]), or is killed by `SIGKILL` on every run: the message says
111/// what, and ends with the last child's last lines of output.
112#[track_caller]
113#[must_use]
114pub fn run(probe: &str, var: &str, value: &str) -> Probe {
115    let exe = std::env::current_exe().expect("the test binary's path");
116    let Output {
117        status,
118        stdout,
119        stderr,
120    } = crate::child::output(
121        Command::new(exe)
122            .args(["--exact", probe, "--ignored", "--test-threads=1"])
123            .env(var, value),
124    )
125    .unwrap_or_else(|e| panic!("cannot start probe {probe}: {e}"));
126    classify(status, &stdout, &stderr)
127        .unwrap_or_else(|e| panic!("probe {probe} with {var}={value:?}: {e}"))
128}
129
130/// Whether `probe` passes with `var` set to `value`, and not whether it
131/// overflowed a stack ([`run`]).
132///
133/// # Panics
134/// As [`run`].
135#[track_caller]
136#[must_use]
137pub fn fits(probe: &str, var: &str, value: &str) -> bool {
138    run(probe, var, value) == Probe::Fits
139}
140
141/// The least stack, to 4 KiB, of those up to `hi` on which `fits` holds,
142/// by bisection: `fits` is false only for a stack overflow ([`fits`]).
143///
144/// # Panics
145/// When `hi` itself does not fit, naming `what`.
146#[track_caller]
147pub fn least(hi: usize, what: &str, mut fits: impl FnMut(usize) -> bool) -> usize {
148    assert!(fits(hi), "{what} overflows {hi} bytes");
149    let (mut lo, mut hi) = (0, hi);
150    while hi - lo > 4 << 10 {
151        let mid = usize::midpoint(lo, hi) / 4096 * 4096;
152        if fits(mid) {
153            hi = mid;
154        } else {
155            lo = mid;
156        }
157    }
158    hi
159}
160
161#[cfg(test)]
162mod tests {
163    use super::{Probe, classify, least, run};
164    use crate::child::Marks;
165
166    const VAR: &str = "UNITYRS_TESTKIT_STACK_PROBE";
167
168    /// Run by the tests below: on a thread of 256 KiB, `recurse` recurses
169    /// without end, `panic` panics, `alloc` fails an allocation, and `pass`
170    /// returns; `killed:N:DIR` is killed by `SIGKILL` (as the OOM killer
171    /// kills a child) on each of its first `N` runs, counted in `DIR`, then
172    /// passes.
173    #[test]
174    #[ignore = "run by the stack probe tests"]
175    fn probe() {
176        let Ok(what) = std::env::var(VAR) else {
177            return;
178        };
179        if let Some(spec) = what.strip_prefix("killed:") {
180            crate::child::kill_self_while(spec);
181        }
182        let t = std::thread::Builder::new().stack_size(256 << 10);
183        t.spawn(move || match what.as_str() {
184            "recurse" => {
185                std::hint::black_box(recurse(0));
186            }
187            "panic" => panic!("the probe's own panic"),
188            "alloc" => {
189                std::alloc::handle_alloc_error(
190                    std::alloc::Layout::from_size_align(1 << 40, 8).unwrap(),
191                );
192            }
193            _ => {}
194        })
195        .unwrap()
196        .join()
197        .unwrap();
198    }
199
200    fn recurse(n: u64) -> u64 {
201        if std::hint::black_box(n) == u64::MAX {
202            return 0;
203        }
204        let pad = std::hint::black_box([n; 64]);
205        recurse(n + 1).wrapping_add(pad[0])
206    }
207
208    const PROBE: &str = "stack::tests::probe";
209
210    fn refused(what: &str) -> String {
211        let r = std::panic::catch_unwind(|| run(PROBE, VAR, what));
212        let p = r.expect_err(what);
213        p.downcast_ref::<String>().cloned().unwrap_or_default()
214    }
215
216    /// A run that passes fits; one that recurses without end overflows.
217    #[test]
218    fn a_pass_fits_and_a_stack_overflow_overflows() {
219        assert_eq!(run(PROBE, VAR, "pass"), Probe::Fits);
220        assert_eq!(run(PROBE, VAR, "recurse"), Probe::Overflows);
221    }
222
223    /// A panic, a failed allocation and a probe that did not run are no
224    /// measurement: each fails the test, naming what happened, where a
225    /// child's failure alone read them as overflows (review round 5).
226    #[test]
227    fn every_other_failure_is_no_measurement() {
228        let m = refused("panic");
229        assert!(m.contains("the probe panicked"), "{m}");
230        assert!(m.contains("the probe's own panic"), "{m}");
231        let m = refused("alloc");
232        assert!(m.contains("aborted with no stack overflow reported"), "{m}");
233        assert!(m.contains("memory allocation of"), "{m}");
234        let r = std::panic::catch_unwind(|| run("stack::tests::no_such_probe", VAR, "pass"));
235        let m = r.expect_err("no such probe");
236        let m = m.downcast_ref::<String>().cloned().unwrap_or_default();
237        assert!(m.contains("the probe did not run"), "{m}");
238    }
239
240    /// The other signals, and an overflow reported under one: SIGKILL (the
241    /// OOM killer) and SIGSEGV off a guard page are failures; only SIGABRT
242    /// with the runtime's report is an overflow.
243    #[cfg(unix)]
244    #[test]
245    fn only_an_abort_with_the_overflow_report_is_an_overflow() {
246        use std::os::unix::process::ExitStatusExt;
247        let report =
248            b"\nthread 'w' has overflowed its stack\nfatal runtime error: stack overflow\n";
249        let of = |raw: i32, err: &[u8]| classify(ExitStatusExt::from_raw(raw), b"", err);
250        assert_eq!(of(6, report), Ok(Probe::Overflows));
251        assert!(
252            of(6, b"")
253                .unwrap_err()
254                .contains("no stack overflow reported")
255        );
256        assert!(of(9, report).unwrap_err().contains("SIGKILL"));
257        assert!(of(11, b"").unwrap_err().contains("signal 11"));
258        assert!(of(101 << 8, report).unwrap_err().contains("panicked"));
259        assert!(of(0, b"").unwrap_err().contains("did not run"));
260        let passed = b"test result: ok. 1 passed; 0 failed; 0 ignored";
261        assert_eq!(
262            classify(ExitStatusExt::from_raw(0), passed, b""),
263            Ok(Probe::Fits)
264        );
265    }
266
267    /// A child the OOM killer ends (`SIGKILL`) is no measurement and is run
268    /// again: killed on each of its first `KILLED_RUNS - 1` runs, the probe
269    /// still measures (review round 7: one kill failed the test).
270    #[cfg(unix)]
271    #[test]
272    fn a_child_killed_from_outside_is_run_again() {
273        let marks = Marks::new("stack-again");
274        let spec = format!("killed:{}:{}", super::KILLED_RUNS - 1, marks.0.display());
275        assert_eq!(run(PROBE, VAR, &spec), Probe::Fits);
276        assert_eq!(
277            marks.runs(),
278            usize::try_from(super::KILLED_RUNS - 1).unwrap()
279        );
280    }
281
282    /// A child killed on every run fails the test, saying so and how often.
283    #[cfg(unix)]
284    #[test]
285    fn a_child_killed_on_every_run_fails_saying_so() {
286        let marks = Marks::new("stack-always");
287        let spec = format!("killed:{}:{}", super::KILLED_RUNS, marks.0.display());
288        let m = refused(&spec);
289        assert_eq!(marks.runs(), usize::try_from(super::KILLED_RUNS).unwrap());
290        let want = format!(
291            "killed by SIGKILL on each of its {} runs",
292            super::KILLED_RUNS
293        );
294        assert!(m.contains(&want), "{m}");
295        assert!(m.contains("the OOM killer"), "{m}");
296    }
297
298    /// [`least`] finds the least size that fits, to 4 KiB.
299    #[test]
300    fn least_bisects_to_four_kib() {
301        let need = 1_234_567;
302        let got = least(8 << 20, "a model", |s| s >= need);
303        assert!(got >= need && got - need < 4 << 10, "{got}");
304    }
305}