kawauso-process 0.2.0

External programs for Kawauso applications
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90

//! The error of running a command

use thiserror::Error;

use crate::invocation::Invocation;

/// The error returned when a command does not run
///
/// The variants separate what happened to the command. A command that never
/// started needs a program that exists, a working directory that exists, and
/// the rights to start a program. A run that started and did not finish means
/// that the operating system stopped the crate from collecting the result,
/// which a caller reports and can try again.
///
/// A command that ran and ended without success is no failure of the run. The
/// result then carries the status, and the caller decides what it means.
///
/// The invocation travels in a box. A result carries its error by value, so
/// the size of the error reaches every function that returns one. The box
/// keeps the error small, and a caller that wraps it in an error of its own
/// needs no box for it.
///
/// A later release can add variants, and it can add fields to a variant.
/// Match with a wildcard arm, and bind the fields of a variant with `..`.
#[derive(Debug, Error)]
#[non_exhaustive]
pub enum RunCommandError {
    /// The command started and the run did not finish
    ///
    /// The program ran, and reading one of its streams or waiting for its end
    /// failed. Nothing of the run survives such a failure, so the crate
    /// reports it instead of a result with holes in it. The command itself
    /// can still have done its work.
    // process[impl run.error.message]
    #[error("failed to complete the run of the command `{invocation}`")]
    #[non_exhaustive]
    IncompleteRun {
        /// The command that did not finish
        invocation: Box<Invocation>,

        /// The cause of the failure
        source: std::io::Error,
    },

    /// The command did not start
    ///
    /// No program answers to the name, the working directory does not exist,
    /// or the operating system refused to start the program. Nothing ran, so
    /// there is no status and no output to report.
    // process[impl run.error]
    // process[impl run.error.message]
    #[error("failed to start the command `{invocation}`")]
    #[non_exhaustive]
    UnstartableCommand {
        /// The command that did not start
        invocation: Box<Invocation>,

        /// The cause of the failure
        source: std::io::Error,
    },
}

#[cfg(test)]
mod tests {
    // An assertion in a test panics by design. A `# Panics` section on every
    // test would repeat that and give the reader no information.
    #![allow(clippy::missing_panics_doc)]

    use super::*;

    // A caller sends the error between threads and keeps it in a report that
    // another thread reads. This test holds the error to the auto traits that
    // make this possible, because a private field of a later version could
    // take them away without a word from the compiler.
    #[test]
    fn run_command_error_is_send_and_sync() {
        fn assert_send_and_sync<T: Send + Sync>() {}

        assert_send_and_sync::<RunCommandError>();
    }

    // A result carries its error by value, and a consumer wraps the error in
    // an error of its own. An error that grows makes every such wrapper grow
    // with it, until the wrapper needs a box that the consumer writes. This
    // test holds the error to a size that leaves the consumer that room.
    #[test]
    fn run_command_error_stays_small() {
        assert!(size_of::<RunCommandError>() <= 4 * size_of::<usize>());
    }
}