Skip to main content

crumbkit_process/run/
finished.rs

1//! What a run gives back: how its child ended and what the run kept.
2
3use std::fmt;
4use std::io;
5use std::time::Duration;
6
7use super::Captured;
8use crate::{Outcome, Status};
9
10/// How a run's child ended and what the run kept of its output.
11#[derive(Clone, Debug, PartialEq, Eq)]
12pub struct ChildFinished {
13    pub(super) outcome: Outcome,
14    pub(super) status: Option<Status>,
15    pub(super) stdout: Captured,
16    pub(super) stderr: Captured,
17    pub(super) first_stdout: Option<Duration>,
18    pub(super) survivors: bool,
19}
20
21impl ChildFinished {
22    /// Returns how the child ended.
23    #[must_use]
24    pub const fn outcome(&self) -> Outcome {
25        self.outcome
26    }
27
28    /// Returns the child's own status as the run reaped it, or `None` when
29    /// the run started no child because its cancel was already cancelled.
30    ///
31    /// The status tells how the child ended even when the run stopped it.
32    /// A run whose cancel stopped a child that SIGINT ended gives
33    /// `Outcome::Stopped(StopReason::Cancelled)` and the status `Status::Signal(2)`,
34    /// whose [`Status::shell_code`] is 130. A child that handles the signal
35    /// and exits with a code of its own gives that code.
36    #[must_use]
37    pub const fn status(&self) -> Option<Status> {
38        self.status
39    }
40
41    /// Returns true when [`RunOptions::report_survivors`](crate::RunOptions::report_survivors) asked, the child
42    /// ended by itself, and another process in its group still ran then.
43    /// A run that stopped the child gives false.
44    ///
45    /// A process that left the group, such as one that called `setsid`, is
46    /// not in it, so it does not count.
47    #[must_use]
48    pub const fn survivors(&self) -> bool {
49        self.survivors
50    }
51
52    /// Returns what the run kept of standard output.
53    #[must_use]
54    pub const fn stdout(&self) -> &Captured {
55        &self.stdout
56    }
57
58    /// Returns what the run kept of standard error.
59    #[must_use]
60    pub const fn stderr(&self) -> &Captured {
61        &self.stderr
62    }
63
64    /// Returns what the run kept of standard output and standard error.
65    #[must_use]
66    pub fn into_output(self) -> (Captured, Captured) {
67        (self.stdout, self.stderr)
68    }
69
70    /// Returns the time from the child's start to the first byte of its
71    /// standard output, or `None` when it printed none, when the run inherited
72    /// standard output, or when the run discarded it and had no copy function.
73    #[must_use]
74    pub const fn first_stdout(&self) -> Option<Duration> {
75        self.first_stdout
76    }
77}
78
79/// A run that could not start its child or follow it to its end.
80#[derive(Debug)]
81#[non_exhaustive]
82pub enum RunError {
83    /// The program does not exist or cannot be started, or the hook of
84    /// [`RunOptions::around_spawn`](crate::RunOptions::around_spawn) returned
85    /// this error, or an [`Input::File`](crate::Input::File) could not be
86    /// duplicated. No child is left running.
87    Start(io::Error),
88    /// Waiting for the child, reaping it, reading its output or starting a
89    /// thread failed after it started, or a copy function panicked. The
90    /// child was stopped and reaped, or after a panic it ran to its end and
91    /// was reaped.
92    Run(io::Error),
93}
94
95impl fmt::Display for RunError {
96    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
97        f.write_str(match self {
98            Self::Start(_) => "cannot start the program",
99            Self::Run(_) => "cannot follow the program to its end",
100        })
101    }
102}
103
104impl std::error::Error for RunError {
105    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
106        match self {
107            Self::Start(error) | Self::Run(error) => Some(error),
108        }
109    }
110}