wireshift_core/
error.rs

1//! Error types for `wireshift`.
2
3use std::borrow::Cow;
4use std::io;
5
6use thiserror::Error;
7
8/// Convenience result alias used throughout the crate.
9pub type Result<T> = std::result::Result<T, Error>;
10
11/// Errors produced by ring setup, submission, and completion handling.
12///
13/// ```rust
14/// use wireshift::Error;
15///
16/// let err = Error::invalid_config("queue_depth must be non-zero");
17/// assert!(err.to_string().contains("Fix:"));
18/// ```
19#[derive(Debug, Error)]
20#[non_exhaustive]
21pub enum Error {
22    /// The supplied configuration is invalid.
23    #[error("{message}. Fix: {fix}")]
24    InvalidConfig {
25        /// Error summary.
26        message: Cow<'static, str>,
27        /// Suggested remediation.
28        fix: Cow<'static, str>,
29    },
30    /// The selected backend is unavailable.
31    #[error("{message}. Fix: {fix}")]
32    BackendUnavailable {
33        /// Error summary.
34        message: Cow<'static, str>,
35        /// Suggested remediation.
36        fix: Cow<'static, str>,
37    },
38    /// Submission could not be accepted.
39    #[error("{message}. Fix: {fix}")]
40    Submission {
41        /// Error summary.
42        message: Cow<'static, str>,
43        /// Suggested remediation.
44        fix: Cow<'static, str>,
45    },
46    /// Completion routing failed internally.
47    #[error("{message}. Fix: {fix}")]
48    Completion {
49        /// Error summary.
50        message: Cow<'static, str>,
51        /// Suggested remediation.
52        fix: Cow<'static, str>,
53    },
54    /// Resource exhaustion was hit.
55    #[error("{message}. Fix: {fix}")]
56    ResourceExhausted {
57        /// Error summary.
58        message: Cow<'static, str>,
59        /// Suggested remediation.
60        fix: Cow<'static, str>,
61    },
62    /// The caller attempted an unsupported operation.
63    #[error("{message}. Fix: {fix}")]
64    Unsupported {
65        /// Error summary.
66        message: Cow<'static, str>,
67        /// Suggested remediation.
68        fix: Cow<'static, str>,
69    },
70    /// A cancellation request succeeded.
71    #[error("{message}. Fix: {fix}")]
72    Canceled {
73        /// Error summary.
74        message: Cow<'static, str>,
75        /// Suggested remediation.
76        fix: Cow<'static, str>,
77    },
78    /// The operation timed out.
79    #[error("{message}. Fix: {fix}")]
80    Timeout {
81        /// Error summary.
82        message: Cow<'static, str>,
83        /// Suggested remediation.
84        fix: Cow<'static, str>,
85    },
86    /// Input validation failed.
87    #[error("{message}. Fix: {fix}")]
88    Validation {
89        /// Error summary.
90        message: Cow<'static, str>,
91        /// Suggested remediation.
92        fix: Cow<'static, str>,
93    },
94    /// The current process state is incompatible with the backend.
95    #[error("{message}. Fix: {fix}")]
96    ProcessState {
97        /// Error summary.
98        message: Cow<'static, str>,
99        /// Suggested remediation.
100        fix: Cow<'static, str>,
101    },
102    /// A wrapped I/O error.
103    #[error("{message}: {source}. Fix: {fix}")]
104    Io {
105        /// Human-readable context.
106        message: Cow<'static, str>,
107        /// Source I/O error.
108        #[source]
109        source: io::Error,
110        /// Suggested remediation.
111        fix: Cow<'static, str>,
112    },
113}
114
115impl Error {
116    /// Creates an invalid configuration error with a standard fix hint.
117    #[must_use]
118    pub fn invalid_config(message: impl Into<Cow<'static, str>>) -> Self {
119        Self::InvalidConfig {
120            message: message.into(),
121            fix: Cow::Borrowed("provide a non-zero queue depth and sensible batch sizes"),
122        }
123    }
124
125    /// Creates an I/O-flavoured error.
126    #[must_use]
127    pub fn io(
128        message: impl Into<Cow<'static, str>>,
129        source: io::Error,
130        fix: impl Into<Cow<'static, str>>,
131    ) -> Self {
132        Self::Io {
133            message: message.into(),
134            source,
135            fix: fix.into(),
136        }
137    }
138
139    /// Creates a validation error.
140    #[must_use]
141    pub fn validation(
142        message: impl Into<Cow<'static, str>>,
143        fix: impl Into<Cow<'static, str>>,
144    ) -> Self {
145        Self::Validation {
146            message: message.into(),
147            fix: fix.into(),
148        }
149    }
150
151    /// Creates a submission error.
152    #[must_use]
153    pub fn submission(
154        message: impl Into<Cow<'static, str>>,
155        fix: impl Into<Cow<'static, str>>,
156    ) -> Self {
157        Self::Submission {
158            message: message.into(),
159            fix: fix.into(),
160        }
161    }
162
163    /// Creates a completion error.
164    #[must_use]
165    pub fn completion(
166        message: impl Into<Cow<'static, str>>,
167        fix: impl Into<Cow<'static, str>>,
168    ) -> Self {
169        Self::Completion {
170            message: message.into(),
171            fix: fix.into(),
172        }
173    }
174
175    /// Creates a resource exhaustion error.
176    #[must_use]
177    pub fn resource_exhausted(
178        message: impl Into<Cow<'static, str>>,
179        fix: impl Into<Cow<'static, str>>,
180    ) -> Self {
181        Self::ResourceExhausted {
182            message: message.into(),
183            fix: fix.into(),
184        }
185    }
186
187    /// Creates a backend unavailable error.
188    #[must_use]
189    pub fn backend_unavailable(
190        message: impl Into<Cow<'static, str>>,
191        fix: impl Into<Cow<'static, str>>,
192    ) -> Self {
193        Self::BackendUnavailable {
194            message: message.into(),
195            fix: fix.into(),
196        }
197    }
198
199    /// Creates a cancellation error.
200    #[must_use]
201    pub fn canceled(
202        message: impl Into<Cow<'static, str>>,
203        fix: impl Into<Cow<'static, str>>,
204    ) -> Self {
205        Self::Canceled {
206            message: message.into(),
207            fix: fix.into(),
208        }
209    }
210
211    /// Creates an unsupported-operation error.
212    #[must_use]
213    pub fn unsupported(message: impl Into<Cow<'static, str>>) -> Self {
214        Self::Unsupported {
215            message: message.into(),
216            fix: Cow::Borrowed("use a supported backend, platform, or operation mode"),
217        }
218    }
219
220    /// Creates a timeout error.
221    #[must_use]
222    pub fn timeout(
223        message: impl Into<Cow<'static, str>>,
224        fix: impl Into<Cow<'static, str>>,
225    ) -> Self {
226        Self::Timeout {
227            message: message.into(),
228            fix: fix.into(),
229        }
230    }
231}
wireshift_core/error.rs

wireshift_core/
error.rs
