Skip to main content

crumbkit_process/
run.rs

1//! The one-shot run: start a child, write its input, read its output within
2//! limits and a deadline, stop it when needed, and reap it.
3
4use std::fmt;
5use std::fs::File;
6use std::io;
7use std::panic::{AssertUnwindSafe, catch_unwind};
8use std::process::{Command, Stdio};
9use std::sync::Arc;
10use std::thread::{Builder, Scope as Threads, ScopedJoinHandle};
11use std::time::{Duration, Instant};
12
13use zeroize::Zeroizing;
14
15use crate::notice::Notice;
16use crate::overdue::Report;
17use crate::{Cancel, Escalation, Group, Outcome, Overdue, Scope, Signal, Status, StopReason, sys};
18
19mod finished;
20mod output;
21mod pipes;
22mod spawn;
23
24#[cfg(test)]
25mod tests;
26
27pub use self::finished::{ChildFinished, RunError};
28pub use self::output::{Capture, Captured, LineCapture, LongLine, OverLimit, WholeCapture};
29use self::output::{Keeper, OutputCopy};
30use self::pipes::{Ends, Kept};
31use self::spawn::AroundSpawn;
32pub use self::spawn::{Spawn, Spawned};
33
34/// How long a run keeps reading the child's pipes after it reaps the
35/// child. A descendant outside the child's scope that holds a pipe open
36/// holds the run no longer than this.
37pub const DRAIN_GRACE: Duration = Duration::from_secs(1);
38
39/// How long after the child exits a run on Unix waits for the child's group
40/// to be empty. On macOS the run also kills the group again while a live
41/// process is left. A process of the group that outlasts it is left behind
42/// and the run goes on to read the pipes: one that waits for a parent that
43/// never reaps it, or a live one that the tool may not signal, such as a
44/// setuid program.
45pub const REAP_GRACE: Duration = Duration::from_secs(1);
46
47/// What the child reads on its standard input.
48#[derive(Clone, Default)]
49#[non_exhaustive]
50pub enum Input {
51    /// The null device, so the child reads the end of its input at once.
52    #[default]
53    Null,
54    /// These bytes, which a thread of the run writes and then closes. The
55    /// thread stops early when the child closes its input.
56    ///
57    /// The buffer is cleared when it drops, so a secret given to a child
58    /// does not stay in the tool's memory after the settings are gone.
59    /// Each clone of the settings holds and clears its own copy. The
60    /// clearing covers this buffer only: it misses copies that the caller
61    /// made before and the pipe's buffer in the kernel. `Debug` prints the
62    /// length alone.
63    Bytes(Zeroizing<Vec<u8>>),
64    /// The tool's own standard input. On Unix a child in a group of its own
65    /// that reads a terminal is stopped by SIGTTIN, so a terminal suits
66    /// only [`Scope::Child`].
67    Inherit,
68    /// A file or the read end of a pipe, which a pipe becomes with
69    /// `File::from(OwnedFd::from(reader))` on Unix and
70    /// `File::from(OwnedHandle::from(reader))` on Windows. The child gets a duplicate that
71    /// shares the file's position, so it reads from the current position
72    /// and moves the position that the caller and any later run see. The
73    /// caller's `File` stays open.
74    File(Arc<File>),
75}
76
77impl fmt::Debug for Input {
78    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
79        match self {
80            Self::Null => f.write_str("Null"),
81            Self::Bytes(bytes) => f
82                .debug_tuple("Bytes")
83                .field(&format_args!("{} bytes", bytes.len()))
84                .finish(),
85            Self::Inherit => f.write_str("Inherit"),
86            Self::File(file) => f.debug_tuple("File").field(file).finish(),
87        }
88    }
89}
90
91/// The settings of one [`run`]: the child's input, what it keeps of each
92/// output stream, when and how it stops the child, and the child's scope.
93///
94/// A `RunOptions` value that delivers a stream as lines serves one run,
95/// because the run ends the line queue when it returns.
96///
97/// The default reads nothing, keeps nothing, has no deadline and no cancel,
98/// kills at once when it stops the child, and starts the child in a group
99/// of its own.
100#[derive(Clone, Debug, Default)]
101pub struct RunOptions {
102    stdin: Input,
103    stdout: Capture,
104    stderr: Capture,
105    deadline: Option<Instant>,
106    overdue: Option<Report>,
107    cancel: Option<Cancel>,
108    escalation: Escalation,
109    scope: Scope,
110    around_spawn: Option<AroundSpawn>,
111    stdout_copy: Option<OutputCopy>,
112    stderr_copy: Option<OutputCopy>,
113    report_survivors: bool,
114}
115
116impl RunOptions {
117    /// Returns the default settings.
118    #[must_use]
119    pub fn new() -> Self {
120        Self::default()
121    }
122
123    /// Sets what the child reads on its standard input.
124    #[must_use]
125    pub fn stdin(mut self, input: Input) -> Self {
126        self.stdin = input;
127        self
128    }
129
130    /// Sets what the run keeps of the child's standard output.
131    #[must_use]
132    pub fn stdout(mut self, capture: impl Into<Capture>) -> Self {
133        self.stdout = capture.into();
134        self
135    }
136
137    /// Sets what the run keeps of the child's standard error.
138    #[must_use]
139    pub fn stderr(mut self, capture: impl Into<Capture>) -> Self {
140        self.stderr = capture.into();
141        self
142    }
143
144    /// Sets the time at which the run stops a child that has not exited,
145    /// which then ends as [`Outcome::TimedOut`].
146    #[must_use]
147    pub const fn deadline(mut self, deadline: Instant) -> Self {
148        self.deadline = Some(deadline);
149        self
150    }
151
152    /// Makes the run call `report` once when `at` passes while the child
153    /// still runs, and then wait on as before. The run never signals the
154    /// child because `at` passed, so a tool that must not stop a child that
155    /// outlives a time limit reports it here and lets it go on.
156    ///
157    /// The run calls `report` on its own thread, and it does nothing else
158    /// while `report` runs: it does not act on a cancel, an over-limit
159    /// stream or the [`deadline`](Self::deadline) until `report` returns, so
160    /// `report` should return quickly. [`Overdue::id`] names the child,
161    /// which stays unreaped until the run ends. After `report` the run
162    /// still obeys its cancel, its limits and its deadline, and it ends
163    /// as it would have, with [`ChildFinished::was_overdue`] true. A child
164    /// that exits by itself then gives [`Outcome::Ended`].
165    ///
166    /// `report` never runs when the child has exited by `at`, when `at` is
167    /// at or after the deadline, or when the run stops the child first.
168    /// When `report` panics, the run kills the child's scope, reaps the
169    /// child and returns [`RunError::Run`].
170    #[must_use]
171    pub fn overdue(
172        mut self,
173        at: Instant,
174        report: impl Fn(Overdue) + Send + Sync + 'static,
175    ) -> Self {
176        self.overdue = Some(Report::new(at, report));
177        self
178    }
179
180    /// Makes the run watch `cancel`, so [`Cancel::cancel`] stops it.
181    #[must_use]
182    pub fn cancel(mut self, cancel: &Cancel) -> Self {
183        self.cancel = Some(cancel.clone());
184        self
185    }
186
187    /// Sets the steps that stop the child.
188    #[must_use]
189    pub fn escalation(mut self, escalation: Escalation) -> Self {
190        self.escalation = escalation;
191        self
192    }
193
194    /// Sets which processes the run holds and signals.
195    #[must_use]
196    pub const fn scope(mut self, scope: Scope) -> Self {
197        self.scope = scope;
198        self
199    }
200
201    /// Makes `hook` start the child, so the caller can hold a lock or change
202    /// process-wide state for exactly the length of the start.
203    ///
204    /// The run calls `hook` once, on the thread that called [`run`], and
205    /// never when its cancel was already cancelled. The hook does its work
206    /// before the start, calls [`Spawn::start`], does its work after the
207    /// start, and returns the [`Spawned`] that the start gave. The hook
208    /// surrounds the whole start, including the `forward` feature's lock.
209    ///
210    /// A hook that returns an error ends the run with [`RunError::Start`].
211    /// When the child had started, dropping its [`Spawned`] kills the child
212    /// and every process in its scope and reaps the child. A panic in the
213    /// hook does the same as it unwinds.
214    ///
215    /// The time the hook takes counts towards the deadline, and it is not
216    /// part of the time bound that [`run`] states. Time that the hook spends
217    /// after the start counts towards
218    /// [`first_stdout`](ChildFinished::first_stdout), because the run reads
219    /// the child's output only once the hook returns. A hook that waits for a
220    /// lock can check the deadline itself and return an error. With the
221    /// `forward` feature, a start waits forever once the tool has received
222    /// a signal, so a clean-up must not wait for a lock that the hook holds.
223    ///
224    /// ```no_run
225    /// use std::io;
226    /// use std::process::Command;
227    /// use std::sync::Mutex;
228    ///
229    /// use crumbkit_process::{RunOptions, run};
230    ///
231    /// static FORK_GATE: Mutex<()> = Mutex::new(());
232    ///
233    /// fn inherit(descriptors: bool) -> io::Result<()> {
234    ///     // Clears or sets CLOEXEC on the descriptors the child inherits.
235    ///     # let _ = descriptors;
236    ///     Ok(())
237    /// }
238    ///
239    /// let options = RunOptions::new().around_spawn(|spawn| {
240    ///     let _gate = FORK_GATE.lock().map_err(|_| io::Error::other("poisoned"))?;
241    ///     inherit(true)?;
242    ///     let spawned = spawn.start();
243    ///     inherit(false)?;
244    ///     spawned
245    /// });
246    /// # let _ = run(Command::new("true"), &options);
247    /// ```
248    #[must_use]
249    pub fn around_spawn(
250        mut self,
251        hook: impl Fn(Spawn) -> io::Result<Spawned> + Send + Sync + 'static,
252    ) -> Self {
253        self.around_spawn = Some(AroundSpawn::new(hook));
254        self
255    }
256
257    /// Calls `copy` with each chunk of standard output as the run reads it,
258    /// whatever the capture keeps, so a tool can show the output while the
259    /// run keeps a bounded copy. See [`RunOptions::stderr_copy`].
260    #[must_use]
261    pub fn stdout_copy(mut self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self {
262        self.stdout_copy = Some(OutputCopy::new(copy));
263        self
264    }
265
266    /// Calls `copy` with each chunk of standard error as the run reads it,
267    /// whatever the capture keeps.
268    ///
269    /// A chunk can end in the middle of a line or of a UTF-8 character. The
270    /// run does not read a stream with [`Capture::inherit`], so its function
271    /// receives nothing.
272    /// Each stream's function runs on that stream's reader thread, so the
273    /// two streams can interleave. A function that blocks holds the reader:
274    /// the child then waits on its full pipe, and the run waits for the
275    /// function past the time bound that [`run`] states. A function that
276    /// panics gets no more chunks, the run reads the rest of the stream so
277    /// the child runs on, and the run ends with [`RunError::Run`].
278    #[must_use]
279    pub fn stderr_copy(mut self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self {
280        self.stderr_copy = Some(OutputCopy::new(copy));
281        self
282    }
283
284    /// Makes the run check, when the child ends by itself and before the run
285    /// kills what is left of the group, whether any other process in the
286    /// group still runs. [`ChildFinished::survivors`] gives the answer. The
287    /// run kills those processes as it always does.
288    ///
289    /// The check is off by default because on Linux it reads every process
290    /// in `/proc`. It reports on [`Scope::Group`] on Linux and macOS alone.
291    #[must_use]
292    pub const fn report_survivors(mut self) -> Self {
293        self.report_survivors = true;
294        self
295    }
296
297    /// Tells the queue of each stream delivered as lines that the run began
298    /// to stop its child.
299    fn stopping(&self) {
300        self.stdout.stopping();
301        self.stderr.stopping();
302    }
303
304    /// Tells the queue of each stream delivered as lines that the child has
305    /// exited, so a full queue drops lines once `deadline` has passed.
306    fn drain_until(&self, deadline: Instant) {
307        self.stdout.drain_until(deadline);
308        self.stderr.drain_until(deadline);
309    }
310}
311
312/// Runs `command` with the settings in `options` and returns how it ended and
313/// what it printed.
314///
315/// The run sets the command's standard streams, starts it in the scope of
316/// [`RunOptions::scope`], and waits until the child exits, the deadline passes,
317/// the cancel is cancelled, or a stream whose policy stops the child passes
318/// its limit. In the last three cases it stops the child with the
319/// [`Escalation`]. Once the child has exited, the run kills what is left of
320/// its group, reaps it, waits on Unix until the group is empty for at most
321/// [`REAP_GRACE`] after the exit, and reads its pipes for at most
322/// [`DRAIN_GRACE`] more. A run whose deadline passes after the child exited gives the
323/// child's own exit.
324///
325/// On Unix, for a child that the tool may signal, a run takes at most the
326/// time to its deadline, plus the graces of its escalation, plus
327/// [`REAP_GRACE`], plus [`DRAIN_GRACE`], plus the time that a hook of
328/// [`RunOptions::around_spawn`] takes, plus the time that a function of
329/// [`RunOptions::stdout_copy`] or [`RunOptions::stderr_copy`] blocks, plus
330/// the time that the report of [`RunOptions::overdue`] takes. Every
331/// thread that it starts is joined before it returns. On Windows a stop ends the job at once, and a reader waits for
332/// its pipe to close, which ending the job causes for every process in the
333/// job, so a process outside the job that holds a pipe holds the run.
334///
335/// A stream delivered as lines waits for the caller while its queue is
336/// full, and the child then waits on its full pipe. Once the run begins to
337/// stop the child, a full queue drops each line instead. After the child
338/// exits by itself, a full queue waits for the caller until the drain
339/// deadline, half of [`DRAIN_GRACE`] after the reap, and then drops each
340/// line while the reader goes on reading the pipe until [`DRAIN_GRACE`]
341/// after the reap. [`Lines::lost`](crate::Lines::lost) says which line a
342/// caller can rely on. The run ends each line queue when it returns, on
343/// every path.
344///
345/// # Errors
346///
347/// Returns [`RunError::Start`] when the program cannot be started, a hook
348/// of [`RunOptions::around_spawn`] fails, or an [`Input::File`] cannot be
349/// duplicated, and
350/// [`RunError::Run`] when waiting for, reaping or reading the child fails
351/// a copy function panics, or the report of [`RunOptions::overdue`] panics.
352/// The child is stopped and reaped on every path.
353pub fn run(mut command: Command, options: &RunOptions) -> Result<ChildFinished, RunError> {
354    let _end = EndLines(options);
355    if options.cancel.as_ref().is_some_and(Cancel::is_cancelled) {
356        return Ok(ChildFinished {
357            outcome: Outcome::Stopped(StopReason::Cancelled),
358            status: None,
359            stdout: Captured::default(),
360            stderr: Captured::default(),
361            first_stdout: None,
362            survivors: false,
363            overdue: false,
364        });
365    }
366    let input = match &options.stdin {
367        Input::Null => Stdio::null(),
368        Input::Inherit => Stdio::inherit(),
369        Input::Bytes(_) => Stdio::piped(),
370        Input::File(file) => Stdio::from(file.try_clone().map_err(RunError::Start)?),
371    };
372    command
373        .stdin(input)
374        .stdout(output_stdio(&options.stdout, options.stdout_copy.as_ref()))
375        .stderr(output_stdio(&options.stderr, options.stderr_copy.as_ref()));
376    let spawned = spawn::start(command, options.scope, options.around_spawn.as_ref())
377        .map_err(RunError::Start)?;
378    let (mut group, started) = spawned.into_parts();
379    let notice = Arc::new(Notice::default());
380    if let Some(cancel) = &options.cancel {
381        cancel.watch(&notice);
382    }
383    let ends = Ends::default();
384    let followed = std::thread::scope(|threads| {
385        let unwind = Unwind {
386            group: &mut group,
387            ends: &ends,
388            options,
389        };
390        follow(
391            threads,
392            &mut *unwind.group,
393            &notice,
394            &ends,
395            options,
396            started,
397        )
398    });
399    let (outcome, status, stdout, stderr, survivors, overdue) = followed.map_err(RunError::Run)?;
400    Ok(ChildFinished {
401        outcome,
402        status: Some(status),
403        first_stdout: stdout.first.map(|first| first - started),
404        survivors,
405        overdue,
406        stdout: stdout.captured,
407        stderr: stderr.captured,
408    })
409}
410
411/// Returns the standard stream for an output with `capture` and `copy`. A
412/// copy needs a pipe even when the capture keeps nothing. An inherited
413/// stream stays the tool's own, so a copy of it receives nothing.
414fn output_stdio(capture: &Capture, copy: Option<&OutputCopy>) -> Stdio {
415    if copy.is_some() && !capture.inherits() {
416        Stdio::piped()
417    } else {
418        capture.stdio()
419    }
420}
421
422/// Ends the line queues of a run when the run returns, on every path.
423struct EndLines<'run>(&'run RunOptions);
424
425impl Drop for EndLines<'_> {
426    fn drop(&mut self) {
427        self.0.stdout.end();
428        self.0.stderr.end();
429    }
430}
431
432/// Ends the threads of a run when [`follow`] returns, which matters when it
433/// panics: it kills the child unless the group has been reaped, makes the
434/// readers and the writer stop waiting on their pipes, and makes each line
435/// queue drop instead of waiting. The scope then joins every thread, and
436/// the group's drop reaps the child. On a normal return each of these has
437/// already happened or does nothing.
438struct Unwind<'a> {
439    group: &'a mut Group,
440    ends: &'a Ends,
441    options: &'a RunOptions,
442}
443
444impl Drop for Unwind<'_> {
445    fn drop(&mut self) {
446        // A reaped group refuses the signal, so the kill never reaches a
447        // process id that another process may have taken.
448        let _ = self.group.signal(Signal::Kill);
449        self.ends.set(Instant::now());
450        self.options.stopping();
451    }
452}
453
454/// The threads of one run: the waiter, the readers and the writer.
455struct Started<'scope> {
456    waiter: ScopedJoinHandle<'scope, io::Result<()>>,
457    stdout: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
458    stderr: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
459    stdin: Option<ScopedJoinHandle<'scope, ()>>,
460}
461
462/// Follows the child of `group` to its end within `threads`, and returns
463/// its exit, its reaped status and what the readers kept.
464fn follow<'scope>(
465    threads: &'scope Threads<'scope, '_>,
466    group: &mut Group,
467    notice: &'scope Notice,
468    ends: &'scope Ends,
469    options: &'scope RunOptions,
470    started_at: Instant,
471) -> io::Result<(Outcome, Status, Kept, Kept, bool, bool)> {
472    let pipes = (group.take_stdin(), group.take_stdout(), group.take_stderr());
473    let exit = group.waiter();
474    let waiter = match Builder::new().spawn_scoped(threads, move || {
475        let waited = exit.wait();
476        notice.set(|flags| flags.exited = true);
477        waited
478    }) {
479        Ok(waiter) => waiter,
480        Err(error) => {
481            let _ = group.signal(Signal::Kill);
482            let _ = group.reap();
483            return Err(error);
484        }
485    };
486    let mut started = Started {
487        waiter,
488        stdout: None,
489        stderr: None,
490        stdin: None,
491    };
492    let mut failure = start_pipes(threads, &mut started, pipes, notice, ends, options).err();
493    let mut overdue = false;
494    let stopped = if failure.is_some() {
495        stop(group, notice, &Escalation::default(), options);
496        None
497    } else {
498        match control(group, notice, options, started_at) {
499            Ok(controlled) => {
500                overdue = controlled.overdue;
501                controlled.stopped
502            }
503            Err(error) => {
504                failure = Some(error);
505                None
506            }
507        }
508    };
509    let survivors =
510        options.report_survivors && failure.is_none() && stopped.is_none() && group.others_alive();
511    let status = group.reap();
512    // The child is gone. The queues drop lines from the middle of the drain,
513    // so the reader still has time to read the rest of the pipe and `lost`
514    // can be the stream's last line.
515    let reaped = Instant::now();
516    let after = |grace: Duration| reaped.checked_add(grace).unwrap_or(reaped);
517    ends.set(after(DRAIN_GRACE));
518    options.drain_until(after(DRAIN_GRACE / 2));
519    let exited = joined(started.waiter.join());
520    let stdout = started.stdout.map(|reader| joined(reader.join()));
521    let stderr = started.stderr.map(|reader| joined(reader.join()));
522    if let Some(writer) = started.stdin {
523        let _ = writer.join();
524    }
525    if let Some(failure) = failure.take() {
526        return Err(failure);
527    }
528    exited?;
529    let status = sys::status_of(status?);
530    let exit = stopped.unwrap_or(Outcome::Ended(status));
531    let unread = || Kept {
532        captured: Captured::default(),
533        first: None,
534    };
535    Ok((
536        exit,
537        status,
538        stdout.transpose()?.unwrap_or_else(unread),
539        stderr.transpose()?.unwrap_or_else(unread),
540        survivors,
541        overdue,
542    ))
543}
544
545/// Starts the readers of the child's output pipes and the writer of its
546/// input, and records each in `started`.
547fn start_pipes<'scope>(
548    threads: &'scope Threads<'scope, '_>,
549    started: &mut Started<'scope>,
550    (stdin, stdout, stderr): (
551        Option<std::process::ChildStdin>,
552        Option<std::process::ChildStdout>,
553        Option<std::process::ChildStderr>,
554    ),
555    notice: &'scope Notice,
556    ends: &'scope Ends,
557    options: &'scope RunOptions,
558) -> io::Result<()> {
559    let over = || notice.set(|flags| flags.over_limit = true);
560    if let Some(stdout) = stdout {
561        let keeper = Keeper::new(&options.stdout);
562        let copy = options.stdout_copy.as_ref();
563        started.stdout = Some(Builder::new().spawn_scoped(threads, move || {
564            pipes::read(stdout, ends, keeper, copy, over)
565        })?);
566    }
567    if let Some(stderr) = stderr {
568        let keeper = Keeper::new(&options.stderr);
569        let copy = options.stderr_copy.as_ref();
570        started.stderr = Some(Builder::new().spawn_scoped(threads, move || {
571            pipes::read(stderr, ends, keeper, copy, over)
572        })?);
573    }
574    if let (Some(stdin), Input::Bytes(bytes)) = (stdin, &options.stdin) {
575        started.stdin =
576            Some(Builder::new().spawn_scoped(threads, move || pipes::write(stdin, bytes, ends))?);
577    }
578    Ok(())
579}
580
581/// How [`control`] ended: the exit that a stop gave, or `None` when the
582/// child ended on its own, and whether the overdue report ran.
583struct Controlled {
584    stopped: Option<Outcome>,
585    overdue: bool,
586}
587
588/// Waits until the child exits or the run must stop it, stops it then, and
589/// returns the exit that the stop gives, or `None` when the child ended on
590/// its own. The child has exited when it returns, and is unreaped. On the
591/// way it calls the overdue report once, when its time passes while the
592/// child runs.
593///
594/// # Errors
595///
596/// Returns an error when the overdue report panicked. The child has been
597/// stopped then.
598fn control(
599    group: &Group,
600    notice: &Notice,
601    options: &RunOptions,
602    started: Instant,
603) -> io::Result<Controlled> {
604    // The overdue report waits for its time only while it comes before the
605    // deadline, and fires once.
606    let mut pending = options
607        .overdue
608        .as_ref()
609        .filter(|report| options.deadline.is_none_or(|deadline| report.at < deadline));
610    let mut reported = false;
611    loop {
612        let until = match (pending, options.deadline) {
613            (Some(report), Some(deadline)) => Some(report.at.min(deadline)),
614            (Some(report), None) => Some(report.at),
615            (None, deadline) => deadline,
616        };
617        let flags = notice.wait(until, |flags| {
618            flags.exited || flags.cancelled || flags.over_limit
619        });
620        let exit = if flags.exited {
621            return Ok(Controlled {
622                stopped: None,
623                overdue: reported,
624            });
625        } else if flags.cancelled {
626            Outcome::Stopped(StopReason::Cancelled)
627        } else if flags.over_limit {
628            Outcome::Stopped(StopReason::OverLimit)
629        } else if group.has_exited().unwrap_or(false) {
630            // The deadline or the overdue time passed after the child
631            // exited and before the waiter said so, so the child's own exit
632            // stands and the report does not run.
633            notice.wait(None, |flags| flags.exited);
634            return Ok(Controlled {
635                stopped: None,
636                overdue: reported,
637            });
638        } else if let Some(report) = pending.filter(|report| report.at <= Instant::now()) {
639            pending = None;
640            let overdue = Overdue::new(group.id(), started.elapsed());
641            if catch_unwind(AssertUnwindSafe(|| report.call(overdue))).is_err() {
642                stop(group, notice, &Escalation::default(), options);
643                return Err(io::Error::other("the overdue report panicked"));
644            }
645            reported = true;
646            continue;
647        } else {
648            Outcome::TimedOut
649        };
650        stop(group, notice, &options.escalation, options);
651        return Ok(Controlled {
652            stopped: Some(exit),
653            overdue: reported,
654        });
655    }
656}
657
658/// Stops the child with `escalation`, and returns once the child has exited.
659/// First it tells each line queue of `run` that the run is stopping.
660///
661/// A signal that the operating system refuses is skipped, because the next
662/// step, and in the end the kill, still applies. A grace too long for an
663/// `Instant` waits without a limit.
664///
665/// RUST-10: the stop waits for the child's exit after the kill without a
666/// limit. That handles every child that the tool may signal, and it misses
667/// a child that the kill cannot reach, such as a setuid program that
668/// refuses the tool's signals with `EPERM`, which holds the run until it
669/// exits. A run that gives up on such a child and reports it replaces this
670/// when a caller needs one.
671fn stop(group: &Group, notice: &Notice, escalation: &Escalation, options: &RunOptions) {
672    options.stopping();
673    if sys::GRACEFUL {
674        for (signal, grace) in escalation.steps() {
675            let _ = group.signal(signal);
676            if notice
677                .wait(Instant::now().checked_add(grace), |flags| flags.exited)
678                .exited
679            {
680                return;
681            }
682        }
683    }
684    let _ = group.signal(Signal::Kill);
685    notice.wait(None, |flags| flags.exited);
686}
687
688/// Returns a thread's result, or an error when the thread panicked, which
689/// only a broken invariant in the crate can cause.
690fn joined<T>(result: std::thread::Result<io::Result<T>>) -> io::Result<T> {
691    result.unwrap_or_else(|_| Err(io::Error::other("a thread of the run stopped")))
692}