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}