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::io;
6use std::process::{Command, Stdio};
7use std::sync::Arc;
8use std::thread::{Builder, Scope as Threads, ScopedJoinHandle};
9use std::time::{Duration, Instant};
10
11use crate::notice::Notice;
12use crate::{Cancel, Escalation, Group, Outcome, Scope, Signal, Status, StopReason, sys};
13
14mod output;
15mod pipes;
16
17#[cfg(test)]
18mod tests;
19
20use self::output::Keeper;
21pub use self::output::{Capture, Captured, OverLimit};
22use self::pipes::{Ends, Kept};
23
24/// How long a run keeps reading the child's pipes after it reaps the
25/// child. A descendant outside the child's scope that holds a pipe open
26/// holds the run no longer than this.
27pub const DRAIN_GRACE: Duration = Duration::from_secs(1);
28
29/// What the child reads on its standard input.
30#[derive(Clone, Debug, Default, PartialEq, Eq)]
31#[non_exhaustive]
32pub enum Input {
33    /// The null device, so the child reads the end of its input at once.
34    #[default]
35    Null,
36    /// These bytes, which a thread of the run writes and then closes. The
37    /// thread stops early when the child closes its input.
38    Bytes(Vec<u8>),
39    /// The tool's own standard input. On Unix a child in a group of its own
40    /// that reads a terminal is stopped by SIGTTIN, so a terminal suits
41    /// only [`Scope::Child`].
42    Inherit,
43}
44
45/// The settings of one [`run`]: the child's input, what it keeps of each
46/// output stream, when and how it stops the child, and the child's scope.
47///
48/// A `RunOptions` value that delivers a stream as lines serves one run,
49/// because the run ends the line queue when it returns.
50///
51/// The default reads nothing, keeps nothing, has no deadline and no cancel,
52/// kills at once when it stops the child, and starts the child in a group
53/// of its own.
54#[derive(Clone, Debug, Default)]
55pub struct RunOptions {
56    stdin: Input,
57    stdout: Capture,
58    stderr: Capture,
59    deadline: Option<Instant>,
60    cancel: Option<Cancel>,
61    escalation: Escalation,
62    scope: Scope,
63}
64
65impl RunOptions {
66    /// Returns the default settings.
67    #[must_use]
68    pub fn new() -> Self {
69        Self::default()
70    }
71
72    /// Sets what the child reads on its standard input.
73    #[must_use]
74    pub fn stdin(mut self, input: Input) -> Self {
75        self.stdin = input;
76        self
77    }
78
79    /// Sets what the run keeps of the child's standard output.
80    #[must_use]
81    pub fn stdout(mut self, capture: Capture) -> Self {
82        self.stdout = capture;
83        self
84    }
85
86    /// Sets what the run keeps of the child's standard error.
87    #[must_use]
88    pub fn stderr(mut self, capture: Capture) -> Self {
89        self.stderr = capture;
90        self
91    }
92
93    /// Sets the time at which the run stops a child that has not exited,
94    /// which then ends as [`Outcome::TimedOut`].
95    #[must_use]
96    pub const fn deadline(mut self, deadline: Instant) -> Self {
97        self.deadline = Some(deadline);
98        self
99    }
100
101    /// Makes the run watch `cancel`, so [`Cancel::cancel`] stops it.
102    #[must_use]
103    pub fn cancel(mut self, cancel: &Cancel) -> Self {
104        self.cancel = Some(cancel.clone());
105        self
106    }
107
108    /// Sets the steps that stop the child.
109    #[must_use]
110    pub fn escalation(mut self, escalation: Escalation) -> Self {
111        self.escalation = escalation;
112        self
113    }
114
115    /// Sets which processes the run holds and signals.
116    #[must_use]
117    pub const fn scope(mut self, scope: Scope) -> Self {
118        self.scope = scope;
119        self
120    }
121
122    /// Tells the queue of each stream delivered as lines that the run began
123    /// to stop its child.
124    fn stopping(&self) {
125        self.stdout.stopping();
126        self.stderr.stopping();
127    }
128
129    /// Tells the queue of each stream delivered as lines that the child has
130    /// exited, so a full queue drops lines once `deadline` has passed.
131    fn drain_until(&self, deadline: Instant) {
132        self.stdout.drain_until(deadline);
133        self.stderr.drain_until(deadline);
134    }
135}
136
137/// How a run's child ended and what the run kept of its output.
138#[derive(Clone, Debug, PartialEq, Eq)]
139pub struct ChildFinished {
140    outcome: Outcome,
141    status: Option<Status>,
142    stdout: Captured,
143    stderr: Captured,
144    first_stdout: Option<Duration>,
145}
146
147impl ChildFinished {
148    /// Returns how the child ended.
149    #[must_use]
150    pub const fn outcome(&self) -> Outcome {
151        self.outcome
152    }
153
154    /// Returns the child's own status as the run reaped it, or `None` when
155    /// the run started no child because its cancel was already cancelled.
156    ///
157    /// The status tells how the child ended even when the run stopped it.
158    /// A run whose cancel stopped a child that SIGINT ended gives
159    /// `Outcome::Stopped(StopReason::Cancelled)` and the status `Status::Signal(2)`,
160    /// whose [`Status::shell_code`] is 130. A child that handles the signal
161    /// and exits with a code of its own gives that code.
162    #[must_use]
163    pub const fn status(&self) -> Option<Status> {
164        self.status
165    }
166
167    /// Returns what the run kept of standard output.
168    #[must_use]
169    pub const fn stdout(&self) -> &Captured {
170        &self.stdout
171    }
172
173    /// Returns what the run kept of standard error.
174    #[must_use]
175    pub const fn stderr(&self) -> &Captured {
176        &self.stderr
177    }
178
179    /// Returns what the run kept of standard output and standard error.
180    #[must_use]
181    pub fn into_output(self) -> (Captured, Captured) {
182        (self.stdout, self.stderr)
183    }
184
185    /// Returns the time from the child's start to the first byte of its
186    /// standard output, or `None` when it printed none or the run discarded
187    /// standard output.
188    #[must_use]
189    pub const fn first_stdout(&self) -> Option<Duration> {
190        self.first_stdout
191    }
192}
193
194/// A run that could not start its child or follow it to its end.
195#[derive(Debug)]
196#[non_exhaustive]
197pub enum RunError {
198    /// The program does not exist or cannot be started.
199    Start(io::Error),
200    /// Waiting for the child, reaping it, reading its output or starting a
201    /// thread failed after it started. The child was stopped and reaped.
202    Run(io::Error),
203}
204
205impl fmt::Display for RunError {
206    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
207        f.write_str(match self {
208            Self::Start(_) => "cannot start the program",
209            Self::Run(_) => "cannot follow the program to its end",
210        })
211    }
212}
213
214impl std::error::Error for RunError {
215    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
216        match self {
217            Self::Start(error) | Self::Run(error) => Some(error),
218        }
219    }
220}
221
222/// Runs `command` with the settings in `options` and returns how it ended and
223/// what it printed.
224///
225/// The run sets the command's standard streams, starts it in the scope of
226/// [`RunOptions::scope`], and waits until the child exits, the deadline passes,
227/// the cancel is cancelled, or a stream whose policy stops the child passes
228/// its limit. In the last three cases it stops the child with the
229/// [`Escalation`]. Once the child has exited, the run kills what is left of
230/// its group, reaps it, and reads its pipes for at most [`DRAIN_GRACE`]
231/// more. A run whose deadline passes after the child exited gives the
232/// child's own exit.
233///
234/// On Unix, for a child that the tool may signal, a run takes at most the
235/// time to its deadline, plus the graces of its escalation, plus
236/// [`DRAIN_GRACE`]. Every thread that it starts is joined before it
237/// returns. On Windows a stop ends the job at once, and a reader waits for
238/// its pipe to close, which ending the job causes for every process in the
239/// job, so a process outside the job that holds a pipe holds the run.
240///
241/// A stream delivered as lines waits for the caller while its queue is
242/// full, and the child then waits on its full pipe. Once the run begins to
243/// stop the child, a full queue drops each line instead. After the child
244/// exits by itself, a full queue waits for the caller until the drain
245/// deadline, half of [`DRAIN_GRACE`] after the reap, and then drops each
246/// line while the reader goes on reading the pipe until [`DRAIN_GRACE`]
247/// after the reap. [`Lines::lost`](crate::Lines::lost) says which line a
248/// caller can rely on. The run ends each line queue when it returns, on
249/// every path.
250///
251/// # Errors
252///
253/// Returns [`RunError::Start`] when the program cannot be started, and
254/// [`RunError::Run`] when waiting for, reaping or reading the child fails.
255/// The child is stopped and reaped on every path.
256pub fn run(mut command: Command, options: &RunOptions) -> Result<ChildFinished, RunError> {
257    let _end = EndLines(options);
258    if options.cancel.as_ref().is_some_and(Cancel::is_cancelled) {
259        return Ok(ChildFinished {
260            outcome: Outcome::Stopped(StopReason::Cancelled),
261            status: None,
262            stdout: Captured::default(),
263            stderr: Captured::default(),
264            first_stdout: None,
265        });
266    }
267    let input = match &options.stdin {
268        Input::Null => Stdio::null(),
269        Input::Inherit => Stdio::inherit(),
270        Input::Bytes(_) => Stdio::piped(),
271    };
272    command
273        .stdin(input)
274        .stdout(options.stdout.stdio())
275        .stderr(options.stderr.stdio());
276    let started = Instant::now();
277    let mut group = Group::start(command, options.scope).map_err(RunError::Start)?;
278    let notice = Arc::new(Notice::default());
279    if let Some(cancel) = &options.cancel {
280        cancel.watch(&notice);
281    }
282    let ends = Ends::default();
283    let followed = std::thread::scope(|threads| {
284        let unwind = Unwind {
285            group: &mut group,
286            ends: &ends,
287            options,
288        };
289        follow(threads, &mut *unwind.group, &notice, &ends, options)
290    });
291    let (outcome, status, stdout, stderr) = followed.map_err(RunError::Run)?;
292    Ok(ChildFinished {
293        outcome,
294        status: Some(status),
295        first_stdout: stdout.first.map(|first| first - started),
296        stdout: stdout.captured,
297        stderr: stderr.captured,
298    })
299}
300
301/// Ends the line queues of a run when the run returns, on every path.
302struct EndLines<'run>(&'run RunOptions);
303
304impl Drop for EndLines<'_> {
305    fn drop(&mut self) {
306        self.0.stdout.end();
307        self.0.stderr.end();
308    }
309}
310
311/// Ends the threads of a run when [`follow`] returns, which matters when it
312/// panics: it kills the child unless the group has been reaped, makes the
313/// readers and the writer stop waiting on their pipes, and makes each line
314/// queue drop instead of waiting. The scope then joins every thread, and
315/// the group's drop reaps the child. On a normal return each of these has
316/// already happened or does nothing.
317struct Unwind<'a> {
318    group: &'a mut Group,
319    ends: &'a Ends,
320    options: &'a RunOptions,
321}
322
323impl Drop for Unwind<'_> {
324    fn drop(&mut self) {
325        // A reaped group refuses the signal, so the kill never reaches a
326        // process id that another process may have taken.
327        let _ = self.group.signal(Signal::Kill);
328        self.ends.set(Instant::now());
329        self.options.stopping();
330    }
331}
332
333/// The threads of one run: the waiter, the readers and the writer.
334struct Started<'scope> {
335    waiter: ScopedJoinHandle<'scope, io::Result<()>>,
336    stdout: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
337    stderr: Option<ScopedJoinHandle<'scope, io::Result<Kept>>>,
338    stdin: Option<ScopedJoinHandle<'scope, ()>>,
339}
340
341/// Follows the child of `group` to its end within `threads`, and returns
342/// its exit, its reaped status and what the readers kept.
343fn follow<'scope>(
344    threads: &'scope Threads<'scope, '_>,
345    group: &mut Group,
346    notice: &'scope Notice,
347    ends: &'scope Ends,
348    options: &'scope RunOptions,
349) -> io::Result<(Outcome, Status, Kept, Kept)> {
350    let pipes = (group.take_stdin(), group.take_stdout(), group.take_stderr());
351    let exit = group.waiter();
352    let waiter = match Builder::new().spawn_scoped(threads, move || {
353        let waited = exit.wait();
354        notice.set(|flags| flags.exited = true);
355        waited
356    }) {
357        Ok(waiter) => waiter,
358        Err(error) => {
359            let _ = group.signal(Signal::Kill);
360            let _ = group.reap();
361            return Err(error);
362        }
363    };
364    let mut started = Started {
365        waiter,
366        stdout: None,
367        stderr: None,
368        stdin: None,
369    };
370    let mut failure = start_pipes(threads, &mut started, pipes, notice, ends, options).err();
371    let stopped = if failure.is_some() {
372        stop(group, notice, &Escalation::default(), options);
373        None
374    } else {
375        control(group, notice, options)
376    };
377    let status = group.reap();
378    // The child is gone. The queues drop lines from the middle of the drain,
379    // so the reader still has time to read the rest of the pipe and `lost`
380    // can be the stream's last line.
381    let reaped = Instant::now();
382    let after = |grace: Duration| reaped.checked_add(grace).unwrap_or(reaped);
383    ends.set(after(DRAIN_GRACE));
384    options.drain_until(after(DRAIN_GRACE / 2));
385    let exited = joined(started.waiter.join());
386    let stdout = started.stdout.map(|reader| joined(reader.join()));
387    let stderr = started.stderr.map(|reader| joined(reader.join()));
388    if let Some(writer) = started.stdin {
389        let _ = writer.join();
390    }
391    if let Some(failure) = failure.take() {
392        return Err(failure);
393    }
394    exited?;
395    let status = sys::status_of(status?);
396    let exit = stopped.unwrap_or(Outcome::Ended(status));
397    let unread = || Kept {
398        captured: Captured::default(),
399        first: None,
400    };
401    Ok((
402        exit,
403        status,
404        stdout.transpose()?.unwrap_or_else(unread),
405        stderr.transpose()?.unwrap_or_else(unread),
406    ))
407}
408
409/// Starts the readers of the child's output pipes and the writer of its
410/// input, and records each in `started`.
411fn start_pipes<'scope>(
412    threads: &'scope Threads<'scope, '_>,
413    started: &mut Started<'scope>,
414    (stdin, stdout, stderr): (
415        Option<std::process::ChildStdin>,
416        Option<std::process::ChildStdout>,
417        Option<std::process::ChildStderr>,
418    ),
419    notice: &'scope Notice,
420    ends: &'scope Ends,
421    options: &'scope RunOptions,
422) -> io::Result<()> {
423    let over = || notice.set(|flags| flags.over_limit = true);
424    if let Some(stdout) = stdout {
425        let keeper = Keeper::new(&options.stdout);
426        started.stdout = Some(
427            Builder::new()
428                .spawn_scoped(threads, move || pipes::read(stdout, ends, keeper, over))?,
429        );
430    }
431    if let Some(stderr) = stderr {
432        let keeper = Keeper::new(&options.stderr);
433        started.stderr = Some(
434            Builder::new()
435                .spawn_scoped(threads, move || pipes::read(stderr, ends, keeper, over))?,
436        );
437    }
438    if let (Some(stdin), Input::Bytes(bytes)) = (stdin, &options.stdin) {
439        started.stdin =
440            Some(Builder::new().spawn_scoped(threads, move || pipes::write(stdin, bytes, ends))?);
441    }
442    Ok(())
443}
444
445/// Waits until the child exits or the run must stop it, stops it then, and
446/// returns the exit that the stop gives, or `None` when the child ended on
447/// its own. The child has exited when it returns, and is unreaped.
448fn control(group: &Group, notice: &Notice, options: &RunOptions) -> Option<Outcome> {
449    let flags = notice.wait(options.deadline, |flags| {
450        flags.exited || flags.cancelled || flags.over_limit
451    });
452    let exit = if flags.exited {
453        return None;
454    } else if flags.cancelled {
455        Outcome::Stopped(StopReason::Cancelled)
456    } else if flags.over_limit {
457        Outcome::Stopped(StopReason::OverLimit)
458    } else if group.has_exited().unwrap_or(false) {
459        // The deadline passed after the child exited and before the waiter
460        // said so, so the child's own exit stands.
461        notice.wait(None, |flags| flags.exited);
462        return None;
463    } else {
464        Outcome::TimedOut
465    };
466    stop(group, notice, &options.escalation, options);
467    Some(exit)
468}
469
470/// Stops the child with `escalation`, and returns once the child has exited.
471/// First it tells each line queue of `run` that the run is stopping.
472///
473/// A signal that the operating system refuses is skipped, because the next
474/// step, and in the end the kill, still applies. A grace too long for an
475/// `Instant` waits without a limit.
476///
477/// RUST-10: the stop waits for the child's exit after the kill without a
478/// limit. That handles every child that the tool may signal, and it misses
479/// a child that the kill cannot reach, such as a setuid program that
480/// refuses the tool's signals with `EPERM`, which holds the run until it
481/// exits. A run that gives up on such a child and reports it replaces this
482/// when a caller needs one.
483fn stop(group: &Group, notice: &Notice, escalation: &Escalation, options: &RunOptions) {
484    options.stopping();
485    if sys::GRACEFUL {
486        for (signal, grace) in escalation.steps() {
487            let _ = group.signal(signal);
488            if notice
489                .wait(Instant::now().checked_add(grace), |flags| flags.exited)
490                .exited
491            {
492                return;
493            }
494        }
495    }
496    let _ = group.signal(Signal::Kill);
497    notice.wait(None, |flags| flags.exited);
498}
499
500/// Returns a thread's result, or an error when the thread panicked, which
501/// only a broken invariant in the crate can cause.
502fn joined<T>(result: std::thread::Result<io::Result<T>>) -> io::Result<T> {
503    result.unwrap_or_else(|_| Err(io::Error::other("a thread of the run stopped")))
504}