ringkernel_core/
error.rs

1//! Error types for RingKernel operations.
2
3use thiserror::Error;
4
5/// Result type alias for RingKernel operations.
6pub type Result<T> = std::result::Result<T, RingKernelError>;
7
8/// Comprehensive error type for RingKernel operations.
9#[derive(Error, Debug)]
10pub enum RingKernelError {
11    // ===== Kernel Lifecycle Errors =====
12    /// Kernel not found with the given ID.
13    #[error("kernel not found: {0}")]
14    KernelNotFound(String),
15
16    /// Kernel is already active.
17    #[error("kernel already active: {0}")]
18    KernelAlreadyActive(String),
19
20    /// Kernel is not active.
21    #[error("kernel not active: {0}")]
22    KernelNotActive(String),
23
24    /// Kernel has already terminated.
25    #[error("kernel already terminated: {0}")]
26    KernelTerminated(String),
27
28    /// Invalid kernel state transition.
29    #[error("invalid state transition from {from:?} to {to:?}")]
30    InvalidStateTransition {
31        /// Current state
32        from: String,
33        /// Attempted target state
34        to: String,
35    },
36
37    /// Invalid kernel state.
38    #[error("invalid state: expected {expected}, got {actual}")]
39    InvalidState {
40        /// Expected state
41        expected: String,
42        /// Actual state
43        actual: String,
44    },
45
46    /// Kernel launch failed.
47    #[error("kernel launch failed: {0}")]
48    LaunchFailed(String),
49
50    /// Kernel compilation failed (NVRTC, shader compilation, etc.).
51    #[error("kernel compilation failed: {0}")]
52    CompilationError(String),
53
54    // ===== Message Errors =====
55    /// Queue is full, message cannot be enqueued.
56    #[error("queue full: capacity {capacity}, attempted to enqueue message")]
57    QueueFull {
58        /// Queue capacity
59        capacity: usize,
60    },
61
62    /// Queue is empty, no message to dequeue.
63    #[error("queue empty")]
64    QueueEmpty,
65
66    /// Message serialization failed.
67    #[error("serialization error: {0}")]
68    SerializationError(String),
69
70    /// Message deserialization failed.
71    #[error("deserialization error: {0}")]
72    DeserializationError(String),
73
74    /// Message validation failed.
75    #[error("message validation failed: {0}")]
76    ValidationError(String),
77
78    /// Message too large.
79    #[error("message too large: {size} bytes (max: {max} bytes)")]
80    MessageTooLarge {
81        /// Actual message size
82        size: usize,
83        /// Maximum allowed size
84        max: usize,
85    },
86
87    /// Message timeout.
88    #[error("message timeout after {0:?}")]
89    Timeout(std::time::Duration),
90
91    // ===== Memory Errors =====
92    /// GPU memory allocation failed.
93    #[error("GPU memory allocation failed: {size} bytes - {reason}")]
94    AllocationFailed {
95        /// Requested size
96        size: usize,
97        /// Failure reason
98        reason: String,
99    },
100
101    /// Host memory allocation failed.
102    #[error("host memory allocation failed: {size} bytes")]
103    HostAllocationFailed {
104        /// Requested size
105        size: usize,
106    },
107
108    /// Memory transfer failed.
109    #[error("memory transfer failed: {0}")]
110    TransferFailed(String),
111
112    /// Invalid memory alignment.
113    #[error("invalid alignment: expected {expected}, got {actual}")]
114    InvalidAlignment {
115        /// Expected alignment
116        expected: usize,
117        /// Actual alignment
118        actual: usize,
119    },
120
121    /// Out of GPU memory.
122    #[error("out of GPU memory: requested {requested} bytes, available {available} bytes")]
123    OutOfMemory {
124        /// Requested size
125        requested: usize,
126        /// Available memory
127        available: usize,
128    },
129
130    /// Memory pool exhausted.
131    #[error("memory pool exhausted")]
132    PoolExhausted,
133
134    /// Invalid index (out of bounds).
135    #[error("invalid index: {0}")]
136    InvalidIndex(usize),
137
138    /// Generic memory error.
139    #[error("memory error: {0}")]
140    MemoryError(String),
141
142    // ===== Backend Errors =====
143    /// Backend not available.
144    #[error("backend not available: {0}")]
145    BackendUnavailable(String),
146
147    /// Backend initialization failed.
148    #[error("backend initialization failed: {0}")]
149    BackendInitFailed(String),
150
151    /// No suitable GPU device found.
152    #[error("no GPU device found")]
153    NoDeviceFound,
154
155    /// Device selection failed.
156    #[error("device selection failed: {0}")]
157    DeviceSelectionFailed(String),
158
159    /// Backend operation failed.
160    #[error("backend error: {0}")]
161    BackendError(String),
162
163    // ===== Synchronization Errors =====
164    /// Deadlock detected.
165    #[error("deadlock detected")]
166    DeadlockDetected,
167
168    /// Lock poisoned.
169    #[error("lock poisoned")]
170    LockPoisoned,
171
172    /// Channel closed.
173    #[error("channel closed")]
174    ChannelClosed,
175
176    // ===== HLC Errors =====
177    /// Clock skew too large.
178    #[error("clock skew too large: {skew_ms}ms (max: {max_ms}ms)")]
179    ClockSkew {
180        /// Detected skew in milliseconds
181        skew_ms: u64,
182        /// Maximum allowed skew
183        max_ms: u64,
184    },
185
186    /// Invalid timestamp.
187    #[error("invalid timestamp")]
188    InvalidTimestamp,
189
190    // ===== K2K Messaging Errors =====
191    /// K2K messaging error.
192    #[error("K2K error: {0}")]
193    K2KError(String),
194
195    /// K2K destination not found.
196    #[error("K2K destination not found: {0}")]
197    K2KDestinationNotFound(String),
198
199    /// K2K delivery failed.
200    #[error("K2K delivery failed: {0}")]
201    K2KDeliveryFailed(String),
202
203    // ===== Pub/Sub Errors =====
204    /// Pub/sub error.
205    #[error("pub/sub error: {0}")]
206    PubSubError(String),
207
208    /// Topic not found.
209    #[error("topic not found: {0}")]
210    TopicNotFound(String),
211
212    /// Subscription error.
213    #[error("subscription error: {0}")]
214    SubscriptionError(String),
215
216    // ===== Multi-GPU Errors =====
217    /// Multi-GPU coordination error.
218    #[error("multi-GPU error: {0}")]
219    MultiGpuError(String),
220
221    /// Device not available.
222    #[error("device not available: {0}")]
223    DeviceNotAvailable(String),
224
225    /// Cross-device transfer failed.
226    #[error("cross-device transfer failed: {0}")]
227    CrossDeviceTransferFailed(String),
228
229    // ===== Telemetry Errors =====
230    /// Telemetry error.
231    #[error("telemetry error: {0}")]
232    TelemetryError(String),
233
234    /// Metrics collection failed.
235    #[error("metrics collection failed: {0}")]
236    MetricsCollectionFailed(String),
237
238    // ===== Configuration Errors =====
239    /// Invalid configuration.
240    #[error("invalid configuration: {0}")]
241    InvalidConfig(String),
242
243    /// Missing required configuration.
244    #[error("missing configuration: {0}")]
245    MissingConfig(String),
246
247    // ===== I/O Errors =====
248    /// I/O error wrapper.
249    #[error("I/O error: {0}")]
250    IoError(#[from] std::io::Error),
251
252    // ===== Generic Errors =====
253    /// Internal error.
254    #[error("internal error: {0}")]
255    Internal(String),
256
257    /// Feature not supported.
258    #[error("feature not supported: {0}")]
259    NotSupported(String),
260
261    /// Operation cancelled.
262    #[error("operation cancelled")]
263    Cancelled,
264}
265
266impl RingKernelError {
267    /// Returns true if this error is recoverable.
268    pub fn is_recoverable(&self) -> bool {
269        matches!(
270            self,
271            RingKernelError::QueueFull { .. }
272                | RingKernelError::QueueEmpty
273                | RingKernelError::Timeout(_)
274                | RingKernelError::PoolExhausted
275        )
276    }
277
278    /// Returns true if this error indicates a resource issue.
279    pub fn is_resource_error(&self) -> bool {
280        matches!(
281            self,
282            RingKernelError::AllocationFailed { .. }
283                | RingKernelError::HostAllocationFailed { .. }
284                | RingKernelError::OutOfMemory { .. }
285                | RingKernelError::PoolExhausted
286        )
287    }
288
289    /// Returns true if this is a fatal error requiring restart.
290    pub fn is_fatal(&self) -> bool {
291        matches!(
292            self,
293            RingKernelError::BackendInitFailed(_)
294                | RingKernelError::NoDeviceFound
295                | RingKernelError::LockPoisoned
296                | RingKernelError::Internal(_)
297        )
298    }
299}
300
301#[cfg(test)]
302mod tests {
303    use super::*;
304
305    #[test]
306    fn test_error_display() {
307        let err = RingKernelError::KernelNotFound("test_kernel".to_string());
308        assert_eq!(format!("{}", err), "kernel not found: test_kernel");
309
310        let err = RingKernelError::QueueFull { capacity: 1024 };
311        assert!(format!("{}", err).contains("1024"));
312    }
313
314    #[test]
315    fn test_error_classification() {
316        assert!(RingKernelError::QueueFull { capacity: 1024 }.is_recoverable());
317        assert!(RingKernelError::OutOfMemory {
318            requested: 1000,
319            available: 100
320        }
321        .is_resource_error());
322        assert!(RingKernelError::LockPoisoned.is_fatal());
323    }
324}
ringkernel_core/error.rs

ringkernel_core/
error.rs
