gdt_cpus/
error.rs

1//! Defines the error types and `Result` alias used throughout the `gdt-cpus` crate.
2//!
3//! This module provides a centralized way to handle errors that can occur during
4//! CPU information detection, thread affinity management, or other operations.
5//! The primary error type is [`Error`], and the standard `Result` type is aliased
6//! as [`Result<T>`] for convenience.
7
8use std::fmt;
9
10/// A specialized `Result` type for `gdt-cpus` operations.
11///
12/// This type alias uses [`crate::error::Error`] as its error type.
13/// All functions in this crate that can fail will return this `Result` type.
14pub type Result<T> = std::result::Result<T, Error>;
15
16/// The primary error enum for all operations within the `gdt-cpus` crate.
17///
18/// This enum consolidates various error conditions that can arise,
19/// such as issues with CPU detection, platform incompatibilities,
20/// permission problems, I/O errors, and invalid parameters.
21/// It implements `std::error::Error` for interoperability with other Rust error handling mechanisms.
22#[derive(Debug, Clone)]
23#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
24pub enum Error {
25    /// An error occurred during the process of detecting CPU information.
26    /// This could be due to parsing issues, unexpected system responses, or
27    /// platform-specific problems.
28    /// Contains a descriptive message about the detection failure.
29    Detection(String),
30
31    /// An invalid core ID was provided to a function.
32    /// Core IDs are typically 0-indexed and should correspond to actual logical processors.
33    /// Contains the invalid ID that was used.
34    InvalidCoreId(usize),
35
36    /// No CPU core of the requested type (e.g., Performance or Efficiency) could be found.
37    /// This can happen on systems without hybrid architectures or if the specified
38    /// type doesn't exist or isn't distinguishable on the current platform.
39    /// Contains a string describing the requested core type.
40    NoCoreOfType(String),
41
42    /// An error occurred during thread affinity operations.
43    /// This could involve issues setting or getting thread affinity, such as
44    /// the specified core ID being invalid for affinity operations or OS-level restrictions.
45    /// Contains a descriptive message about the affinity failure.
46    Affinity(String),
47
48    /// The requested operation is not supported on the current operating system
49    /// or hardware platform.
50    /// Contains a message explaining why the operation is unsupported.
51    Unsupported(String),
52
53    /// The operation could not be completed due to insufficient permissions.
54    /// For example, setting thread priority or affinity might require
55    /// administrator/root privileges on the operating system.
56    /// Contains a message detailing the permission issue.
57    PermissionDenied(String),
58
59    /// An underlying Input/Output error occurred.
60    /// This often wraps `std::io::Error` and is used for file operations or
61    /// interactions with system devices that result in I/O failures.
62    /// Contains a descriptive message about the I/O failure.
63    Io(String),
64
65    /// An error occurred during a system call.
66    /// This is often used for platform-specific API call failures not covered
67    /// by `std::io::Error`, such as issues with `sysctl` on macOS/BSD or
68    /// other low-level OS interactions.
69    /// Contains a descriptive message about the system call failure.
70    SystemCall(String),
71
72    /// A requested resource or item was not found.
73    /// For example, trying to access a non-existent configuration file, registry key,
74    /// or a specific piece of information that the system doesn't provide.
75    /// Contains a message describing what was not found.
76    NotFound(String),
77
78    /// An invalid parameter was supplied to a function.
79    /// This is a general error for cases where input validation fails and the
80    /// parameter does not fit other more specific error categories.
81    /// Contains a message explaining which parameter was invalid and why.
82    InvalidParameter(String),
83
84    /// The requested feature or operation is not yet implemented in this version
85    /// of the crate.
86    /// This is a placeholder for future development or for features that are
87    /// planned but not yet available.
88    NotImplemented,
89}
90
91impl fmt::Display for Error {
92    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
93        match self {
94            Error::Detection(msg) => write!(f, "CPU detection error: {}", msg),
95            Error::InvalidCoreId(id) => write!(f, "Invalid core ID: {}", id),
96            Error::NoCoreOfType(ty) => write!(f, "No core of type {} found", ty),
97            Error::Affinity(msg) => write!(f, "Thread affinity error: {}", msg),
98            Error::Unsupported(msg) => write!(f, "Unsupported operation: {}", msg),
99            Error::PermissionDenied(msg) => write!(f, "Permission denied: {}", msg),
100            Error::Io(msg) => write!(f, "I/O error: {}", msg),
101            Error::SystemCall(msg) => write!(f, "System call error: {}", msg),
102            Error::NotFound(msg) => write!(f, "Not found: {}", msg),
103            Error::InvalidParameter(msg) => write!(f, "Invalid parameter: {}", msg),
104            Error::NotImplemented => write!(f, "Operation not implemented"),
105        }
106    }
107}
108
109impl std::error::Error for Error {}
110
111// Implementations of From for common error conversions
112impl From<std::io::Error> for Error {
113    fn from(err: std::io::Error) -> Self {
114        Error::Io(err.to_string())
115    }
116}
gdt_cpus/error.rs

gdt_cpus/
error.rs
