hurray_ffi/
status.rs

1//! Status codes and error mapping for the Hurray C ABI.
2//!
3//! All exported `extern "C"` functions return a [`HurrayStatus`] integer. Zero
4//! indicates success; negative values indicate a specific error condition.
5//! Callers MUST check the return value of every function before using output
6//! pointer arguments.
7
8use hurray_core::Error;
9
10// ── Status code type ─────────────────────────────────────────────────────────
11
12/// Integer status code returned by every Hurray C ABI function.
13///
14/// Zero (`HURRAY_OK`) indicates success. All negative values indicate errors.
15/// Positive values are reserved for future use.
16///
17/// # Examples
18///
19/// ```
20/// use hurray_ffi::{HurrayStatus, HURRAY_OK};
21///
22/// fn check(s: HurrayStatus) {
23///     assert_eq!(s, HURRAY_OK);
24/// }
25/// check(HURRAY_OK);
26/// ```
27pub type HurrayStatus = i32;
28
29/// Operation completed successfully.
30pub const HURRAY_OK: HurrayStatus = 0;
31
32/// The descriptor magic bytes were not `"HRRY"` (`0x48 0x52 0x52 0x59`).
33pub const HURRAY_ERR_INVALID_MAGIC: HurrayStatus = -1;
34
35/// The descriptor version is not supported by this implementation.
36pub const HURRAY_ERR_VERSION_MISMATCH: HurrayStatus = -2;
37
38/// A layout descriptor field or tag is invalid.
39pub const HURRAY_ERR_INVALID_LAYOUT: HurrayStatus = -3;
40
41/// A type tag, device tag, or memory class is invalid.
42pub const HURRAY_ERR_INVALID_TYPE: HurrayStatus = -4;
43
44/// An output buffer is too small to hold the result.
45pub const HURRAY_ERR_BUFFER_TOO_SMALL: HurrayStatus = -5;
46
47/// A required pointer argument is null.
48pub const HURRAY_ERR_NULL_POINTER: HurrayStatus = -6;
49
50/// The function panicked internally; the handle MUST NOT be reused.
51pub const HURRAY_ERR_INTERNAL_PANIC: HurrayStatus = -7;
52
53/// The sync mode byte is not a recognized value.
54pub const HURRAY_ERR_INVALID_SYNC_MODE: HurrayStatus = -8;
55
56/// A sync-mode handoff payload does not match the buffer's declared sync mode.
57pub const HURRAY_ERR_SYNC_MODE_MISMATCH: HurrayStatus = -9;
58
59/// An unclassified internal error occurred.
60pub const HURRAY_ERR_INTERNAL: HurrayStatus = -10;
61
62/// An index argument is outside the valid range for the collection.
63pub const HURRAY_ERR_INDEX_OUT_OF_BOUNDS: HurrayStatus = -11;
64
65// ── Error mapping ─────────────────────────────────────────────────────────────
66
67/// Maps a [`hurray_core::Error`] to the closest [`HurrayStatus`] error code.
68///
69/// This function is exhaustive over all known variants and falls back to
70/// [`HURRAY_ERR_INTERNAL`] for variants added in future crate versions
71/// (the `Error` enum is `#[non_exhaustive]`).
72pub(crate) fn status_from_core_error(e: &Error) -> HurrayStatus {
73    match e {
74        Error::InvalidMagic { .. } => HURRAY_ERR_INVALID_MAGIC,
75
76        Error::UnsupportedDescriptorVersion { .. } => HURRAY_ERR_VERSION_MISMATCH,
77
78        // Layout-structural errors
79        Error::DescriptorTooShort { .. }
80        | Error::DescriptorTruncated { .. }
81        | Error::DescriptorLengthMismatch { .. }
82        | Error::ReservedDescriptorFlagBitsSet { .. }
83        | Error::ReservedBytesNonZero { .. }
84        | Error::EmptyBufferTable
85        | Error::RankExceedsMaximum { .. }
86        | Error::InvalidLayout(_)
87        | Error::InvalidLayoutTag(_)
88        | Error::ReservedLayoutTag(_)
89        | Error::PrivateLayoutTag(_)
90        | Error::UnknownLayoutTag(_)
91        | Error::ExtensionTypeFlagMismatch { .. }
92        | Error::ExtensionTypePackingInvalid { .. }
93        | Error::ShardOutOfBounds { .. }
94        | Error::StatisticsReservedMaskBitsSet { .. }
95        | Error::AlignmentNotPowerOfTwo { .. }
96        | Error::AlignmentBelowMinimum { .. }
97        | Error::AlignmentError { .. }
98        | Error::InvalidShape(_) => HURRAY_ERR_INVALID_LAYOUT,
99
100        // Type / device / memory class errors
101        Error::InvalidTypeTag(_)
102        | Error::ReservedTypeTag(_)
103        | Error::UnknownTypeTag(_)
104        | Error::UnsupportedElementType(_)
105        | Error::InvalidDeviceTag(_)
106        | Error::ReservedDeviceTag(_)
107        | Error::InvalidMemoryClass(_)
108        | Error::ReservedMemoryClass(_) => HURRAY_ERR_INVALID_TYPE,
109
110        Error::InvalidSyncMode(_) => HURRAY_ERR_INVALID_SYNC_MODE,
111
112        // Everything else (including future non_exhaustive variants)
113        _ => HURRAY_ERR_INTERNAL,
114    }
115}
hurray_ffi/status.rs

hurray_ffi/
status.rs
