hurray_ffi/
lib.rs

1//! # hurray-ffi
2//!
3//! C ABI layer for hurray language bindings.
4//!
5//! This crate exposes opaque handles, a function table, and buffer release
6//! callbacks via a stable C ABI. It is the foundation for all non-Rust language
7//! bindings.
8//!
9//! ## Safety contract
10//!
11//! - No panics may propagate across the FFI boundary. All `extern "C"` functions
12//!   wrap their bodies in `std::panic::catch_unwind`.
13//! - All `unsafe` blocks carry a `// SAFETY:` comment explaining soundness.
14//! - Buffer pointers MUST be aligned to at least 64 bytes.
15//!
16//! ## C ABI version
17//!
18//! The C ABI version is exposed via [`HURRAY_C_ABI_VERSION`] and the function
19//! [`hurray_c_abi_version`]. Callers SHOULD check this at startup to detect
20//! incompatible library versions.
21
22pub mod buffer;
23pub mod buffer_list;
24pub mod descriptor;
25pub(crate) mod panic;
26pub mod status;
27pub mod sync;
28pub mod tensor_context;
29
30// ── Re-exports ────────────────────────────────────────────────────────────────
31
32pub use buffer::{hurray_buffer_from_ptr, HurrayBuffer, HurrayReleaseCallback};
33pub use buffer_list::{hurray_buffer_list_new, HurrayBufferList};
34pub use descriptor::{hurray_descriptor_decode, HurrayDescriptor};
35pub use status::{
36    HurrayStatus, HURRAY_ERR_BUFFER_TOO_SMALL, HURRAY_ERR_INDEX_OUT_OF_BOUNDS, HURRAY_ERR_INTERNAL,
37    HURRAY_ERR_INTERNAL_PANIC, HURRAY_ERR_INVALID_LAYOUT, HURRAY_ERR_INVALID_MAGIC,
38    HURRAY_ERR_INVALID_SYNC_MODE, HURRAY_ERR_INVALID_TYPE, HURRAY_ERR_NULL_POINTER,
39    HURRAY_ERR_SYNC_MODE_MISMATCH, HURRAY_ERR_VERSION_MISMATCH, HURRAY_OK,
40};
41pub use sync::{HurrayEventReleaseFn, HurraySyncConsumerStreamPayload, HurraySyncEventPayload};
42pub use tensor_context::{hurray_tensor_context_new, HurrayOwnerReleaseFn, HurrayTensorContext};
43
44// ── ABI version ───────────────────────────────────────────────────────────────
45
46/// The integer version of the Hurray C ABI exposed by this build.
47///
48/// Callers SHOULD retrieve this at runtime via [`hurray_c_abi_version`] and
49/// compare it to the version they were compiled against.
50///
51/// # Examples
52///
53/// ```
54/// use hurray_ffi::HURRAY_C_ABI_VERSION;
55///
56/// assert_eq!(HURRAY_C_ABI_VERSION, 4);
57/// ```
58pub const HURRAY_C_ABI_VERSION: u32 = 4;
59
60/// Returns the [`HURRAY_C_ABI_VERSION`] constant.
61///
62/// This function is infallible and requires no panic barrier.
63///
64/// # Examples
65///
66/// ```
67/// assert_eq!(unsafe { hurray_ffi::hurray_c_abi_version() }, 4);
68/// ```
69#[no_mangle]
70pub extern "C" fn hurray_c_abi_version() -> u32 {
71    HURRAY_C_ABI_VERSION
72}
73
74// ── Forward declarations for future async bridge ──────────────────────────────
75
76/// Opaque handle to an async streaming reader (full implementation deferred).
77///
78/// A reader bridges `hurray-io`'s async streaming layer into the C ABI.
79/// The async-to-sync bridging strategy (e.g., blocking executor, channel
80/// hand-off) is deferred; this stub allows cbindgen to emit the type
81/// declaration in the generated header.
82pub struct HurrayReader;
83
84/// Opaque handle to an async streaming writer (full implementation deferred).
85///
86/// Symmetric to [`HurrayReader`]. Deferred pending the async bridge design.
87pub struct HurrayWriter;
hurray_ffi/lib.rs

hurray_ffi/
lib.rs
