net_io/
handoff.rs

1//! Listener hand-off between processes.
2//!
3//! The functions arrive in `0.4.0` (Unix) and `0.5.0` (Windows); the error type
4//! exists in every build.
5
6use std::fmt;
7use std::io;
8
9/// Why a listener hand-off failed. Nothing is adopted on any error.
10///
11/// ```
12/// assert_eq!(net_io::HandoffError::BadChecksum.to_string(), "the hand-off manifest checksum does not match");
13/// ```
14#[non_exhaustive]
15#[derive(Debug)]
16pub enum HandoffError {
17    /// The sender is not the expected process or user.
18    PeerMismatch,
19    /// The control message was truncated.
20    Truncated,
21    /// The descriptor count does not match the manifest.
22    CountMismatch,
23    /// The manifest does not start with the expected magic.
24    BadMagic,
25    /// The manifest version is unknown.
26    BadVersion,
27    /// The manifest checksum does not match.
28    BadChecksum,
29    /// More listeners than one hand-off carries.
30    TooMany {
31        /// The maximum.
32        max: u8,
33    },
34    /// A received socket failed verification.
35    VerifyFailed {
36        /// Its position in the manifest.
37        index: u8,
38        /// Which check failed.
39        why: &'static str,
40    },
41    /// The hand-off did not finish in time.
42    Timeout,
43    /// An OS call failed.
44    Os(io::Error),
45}
46
47impl fmt::Display for HandoffError {
48    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
49        match self {
50            HandoffError::PeerMismatch => {
51                f.write_str("the hand-off sender is not the expected process or user")
52            }
53            HandoffError::Truncated => f.write_str("the hand-off message was truncated"),
54            HandoffError::CountMismatch => {
55                f.write_str("the descriptor count does not match the manifest")
56            }
57            HandoffError::BadMagic => f.write_str("not a hand-off manifest"),
58            HandoffError::BadVersion => f.write_str("unknown hand-off manifest version"),
59            HandoffError::BadChecksum => {
60                f.write_str("the hand-off manifest checksum does not match")
61            }
62            HandoffError::TooMany { max } => write!(f, "more than {max} listeners in one hand-off"),
63            HandoffError::VerifyFailed { index, why } => {
64                write!(f, "received listener {index} failed: {why}")
65            }
66            HandoffError::Timeout => f.write_str("the hand-off did not finish in time"),
67            HandoffError::Os(e) => write!(f, "{e}"),
68        }
69    }
70}
71
72impl std::error::Error for HandoffError {
73    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
74        match self {
75            HandoffError::Os(e) => Some(e),
76            _ => None,
77        }
78    }
79}
net_io/handoff.rs

net_io/
handoff.rs
