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;
24// Composites at the crate root, not under `stream` or `file`: a composite crosses the
25// boundary identically on both surfaces, and either home would have been half wrong.
26pub mod composite;
27pub mod descriptor;
28pub mod field;
29pub mod file;
30pub mod item;
31pub(crate) mod panic;
32pub mod status;
33pub mod stream;
34pub mod sync;
35// A tensor handle at the crate root, not under `stream`: every path produces one — a
36// stream read, a file read, and a native-protocol capsule (ADR-043) — so no surface owns it.
37pub mod tensor;
38
39// ── Re-exports ────────────────────────────────────────────────────────────────
40
41pub use buffer::{hurray_buffer_from_ptr, HurrayBuffer, HurrayReleaseCallback};
42pub use buffer_list::{hurray_buffer_list_new, HurrayBufferList};
43pub use composite::HurrayCompositeNode;
44pub use descriptor::{hurray_descriptor_decode, HurrayDescriptor};
45pub use field::{
46    hurray_descriptor_field_f64, hurray_descriptor_field_i64, hurray_descriptor_field_i64_array,
47    hurray_descriptor_field_u64, hurray_descriptor_field_u64_array, HurrayDescriptorField,
48};
49pub use file::{
50    hurray_file_reader_destroy, hurray_file_reader_kv_count, hurray_file_reader_kv_entry,
51    hurray_file_reader_new, hurray_file_reader_read_composite, hurray_file_reader_read_descriptor,
52    hurray_file_reader_read_tensor, hurray_file_reader_tensor_count,
53    hurray_file_reader_tensor_name, hurray_file_writer_destroy, hurray_file_writer_finish,
54    hurray_file_writer_new, hurray_file_writer_write_composite, hurray_file_writer_write_tensor,
55    HurrayFileReader, HurrayFileWriter, HurrayFileWriterOptions, HurrayKvEntry, HurrayKvValue,
56    HURRAY_KV_ARRAY, HURRAY_KV_BOOL, HURRAY_KV_BYTES, HURRAY_KV_FLOAT64, HURRAY_KV_INT64,
57    HURRAY_KV_STRING, HURRAY_KV_UINT64,
58};
59pub use item::{
60    hurray_item_destroy, hurray_item_kind, hurray_item_node, hurray_item_node_count, HurrayItem,
61    HurrayItemNode, HURRAY_ITEM_COMPOSITE, HURRAY_ITEM_TENSOR,
62};
63pub use status::{
64    HurrayStatus, HURRAY_END_OF_STREAM, HURRAY_ERR_BUFFER_TOO_SMALL, HURRAY_ERR_CORE_UNUSABLE,
65    HURRAY_ERR_FIELD_NOT_APPLICABLE, HURRAY_ERR_FIELD_NOT_PRESENT, HURRAY_ERR_INDEX_OUT_OF_BOUNDS,
66    HURRAY_ERR_INTERNAL, HURRAY_ERR_INTERNAL_PANIC, HURRAY_ERR_INVALID_FILE,
67    HURRAY_ERR_INVALID_LAYOUT, HURRAY_ERR_INVALID_MAGIC, HURRAY_ERR_INVALID_STREAM,
68    HURRAY_ERR_INVALID_SYNC_MODE, HURRAY_ERR_INVALID_TYPE, HURRAY_ERR_LIMIT_EXCEEDED,
69    HURRAY_ERR_NOT_COMPOSITE, HURRAY_ERR_NOT_FOUND, HURRAY_ERR_NULL_POINTER,
70    HURRAY_ERR_SINK_CLOSED, HURRAY_ERR_SYNC_MODE_MISMATCH, HURRAY_ERR_TRANSPORT,
71    HURRAY_ERR_UNEXPECTED_EOF, HURRAY_ERR_VERSION_MISMATCH, HURRAY_OK,
72};
73pub use stream::{
74    hurray_reader_destroy, hurray_reader_new, hurray_reader_next_item, hurray_reader_next_tensor,
75    hurray_writer_destroy, hurray_writer_new, hurray_writer_write_composite,
76    hurray_writer_write_tensor, HurrayIoSlice, HurrayReader, HurrayReaderOptions, HurrayTransport,
77    HurrayTransportReadAtFn, HurrayTransportReadFn, HurrayTransportReleaseFn,
78    HurrayTransportSizeFn, HurrayTransportWriteFn, HurrayWriter, HurrayWriterOptions,
79};
80pub use sync::{HurrayEventReleaseFn, HurraySyncConsumerStreamPayload, HurraySyncEventPayload};
81pub use tensor::{
82    hurray_tensor_abi_version, hurray_tensor_buffers, hurray_tensor_descriptor,
83    hurray_tensor_destroy, hurray_tensor_new, HurrayOwnerReleaseFn, HurrayTensor,
84};
85
86// ── ABI version ───────────────────────────────────────────────────────────────
87
88/// The integer version of the Hurray C ABI exposed by this build.
89///
90/// Callers SHOULD retrieve this at runtime via [`hurray_c_abi_version`] and
91/// compare it to the version they were compiled against.
92///
93/// # Examples
94///
95/// ```
96/// use hurray_ffi::HURRAY_C_ABI_VERSION;
97///
98/// assert_eq!(HURRAY_C_ABI_VERSION, 10);
99/// ```
100pub const HURRAY_C_ABI_VERSION: u32 = 10;
101
102/// Returns the [`HURRAY_C_ABI_VERSION`] constant.
103///
104/// This function is infallible and requires no panic barrier.
105///
106/// # Examples
107///
108/// ```
109/// assert_eq!(unsafe { hurray_ffi::hurray_c_abi_version() }, 10);
110/// ```
111#[no_mangle]
112pub extern "C" fn hurray_c_abi_version() -> u32 {
113    HURRAY_C_ABI_VERSION
114}
hurray_ffi/lib.rs

hurray_ffi/
lib.rs
