Skip to main content

eggfetch_ffi/
lib.rs

1//! C ABI bindings for eggfetch-core.
2//!
3//! This crate exposes eggfetch-core as a C-compatible library for consumption
4//! by Node.js (N-API), Ruby (FFI), Zig, or any language that can call C ABI
5//! functions. All operations are blocking — the internal tokio runtime handles
6//! async I/O transparently.
7//!
8//! # Thread Safety
9//!
10//! - [`ClientHandle`] is `Send + Sync` and may be shared across threads.
11//! - [`RequestHandle`], [`ResponseHandle`], and [`ErrorHandle`] are
12//!   single-thread, single-use. Create, use, and free them on one thread.
13//! - [`StreamingResponseHandle`] holds thread-safe shared state
14//!   (`Arc<StreamState>`): `next` may block on one thread while another
15//!   thread cancels, but each stream is still single-use (consume or cancel,
16//!   then free).
17//! - All callback functions must be `extern "C"`.
18
19#![allow(
20    unsafe_code,
21    reason = "the C ABI boundary needs raw-pointer handling in every module; the crate-level allowance is what makes those blocks compile"
22)]
23
24/// Run an exported FFI operation without allowing a Rust panic to unwind
25/// across the C ABI. The operation's documented sentinel value is returned
26/// when a panic is caught.
27#[doc(hidden)]
28#[macro_export]
29macro_rules! ffi_guard {
30    ($fallback:expr, $body:block) => {{
31        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| $body)) {
32            Ok(value) => value,
33            Err(_) => $fallback,
34        }
35    }};
36}
37
38mod builder;
39mod client;
40mod error;
41mod ffi_response;
42mod handle;
43mod protocol;
44mod request;
45mod response;
46mod runtime;
47mod streaming;
48
49pub use builder::*;
50pub use client::*;
51pub use error::*;
52pub use ffi_response::*;
53pub use handle::*;
54pub use request::*;
55pub use response::*;
56pub use streaming::*;