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}