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