mlx_native/
error.rs

1//! Error types for the mlx-native crate.
2//!
3//! All public functions return `Result<T, MlxError>` — the crate never panics.
4
5/// Compile-time assertion that a type is Send + Sync.  Used internally.
6#[doc(hidden)]
7#[macro_export]
8macro_rules! static_assertions_send_sync {
9    ($t:ty) => {
10        const _: fn() = || {
11            fn assert_send<T: Send>() {}
12            fn assert_sync<T: Sync>() {}
13            assert_send::<$t>();
14            assert_sync::<$t>();
15        };
16    };
17}
18
19/// Unified error type for all Metal GPU operations.
20#[derive(Debug, thiserror::Error)]
21pub enum MlxError {
22    /// No Metal-capable GPU device was found on this system.
23    #[error("No Metal GPU device found — Apple Silicon required")]
24    DeviceNotFound,
25
26    /// A Metal command buffer completed with an error status.
27    #[error("Command buffer error: {0}")]
28    CommandBufferError(String),
29
30    /// An MSL shader failed to compile.
31    #[error("Shader compilation error for '{name}': {message}")]
32    ShaderCompilationError {
33        /// Name of the shader / kernel function that failed.
34        name: String,
35        /// Compiler diagnostic message.
36        message: String,
37    },
38
39    /// Metal buffer allocation failed (usually out of GPU memory).
40    #[error("Failed to allocate Metal buffer of {bytes} bytes")]
41    BufferAllocationError {
42        /// Requested allocation size in bytes.
43        bytes: usize,
44    },
45
46    /// A Metal residency set could not be created or updated.
47    #[error("Residency set error: {0}")]
48    ResidencySetError(String),
49
50    /// An argument to a public function was invalid.
51    #[error("Invalid argument: {0}")]
52    InvalidArgument(String),
53
54    /// A kernel function was not found in the compiled library.
55    #[error("Kernel not found: {0}")]
56    KernelNotFound(String),
57
58    /// An I/O error occurred (e.g. reading a safetensors file).
59    #[error("I/O error: {0}")]
60    IoError(String),
61
62    /// A safetensors file could not be parsed or contains invalid data.
63    #[error("Safetensors error: {0}")]
64    SafetensorsError(String),
65
66    /// A quantization config file could not be parsed.
67    #[error("Quantization config error: {0}")]
68    QuantConfigError(String),
69
70    /// An unsupported data type was encountered.
71    #[error("Unsupported dtype: {0}")]
72    UnsupportedDtype(String),
73
74    /// A GGUF file could not be parsed or contains invalid data.
75    #[error("GGUF parse error: {0}")]
76    GgufParseError(String),
77}
78
79/// Convenience alias used throughout the crate.
80pub type Result<T> = std::result::Result<T, MlxError>;
81
82/// Display implementation is handled by thiserror; this is a manual `Debug`
83/// helper for the shader variant to keep log output readable.
84impl MlxError {
85    /// Returns `true` if this is a transient error that *might* succeed on retry
86    /// (e.g. a command buffer timeout). Most errors are permanent.
87    pub fn is_transient(&self) -> bool {
88        matches!(self, MlxError::CommandBufferError(_))
89    }
90}
91
92// Ensure the error type itself is thread-safe.
93static_assertions_send_sync!(MlxError);
mlx_native/error.rs

mlx_native/
error.rs
