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(¬ice);
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 ¬ice,
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}