doom_fish_utils/
lib.rs

1//! # doom-fish-utils
2//!
3//! Framework-agnostic FFI utilities shared by the doom-fish family of safe
4//! Rust bindings to Apple SDKs.
5//!
6//! ## Modules
7//!
8//! | Module | Purpose |
9//! |--------|---------|
10//! | [`callback_context`] | Reference-counted callback contexts: `RETAIN`/`RELEASE` trampolines for the foreign owner, a deactivation flag checked before every call, and panic containment |
11//! | [`completion`] | Sync and async completion handlers for FFI callbacks |
12//! | [`ffi_callbacks`] | Common unsafe `extern "C"` callback type aliases shared across bridge crates |
13//! | [`ffi_string`] | Owned-string helpers around heap-allocated C strings |
14//! | [`four_char_code`] | `FourCharCode` wrapper (used by pixel formats, `OSType` codes, etc.) |
15//! | [`panic_safe`] | Contains supported callback and panic-payload failures, with explicit cleanup before best-effort destruction |
16//! | [`spsc`] | Lock-free single-producer single-consumer rings for real-time callback → async-consumer handoff |
17//! | [`stream`] | Executor-agnostic bounded async streams (waker + `VecDeque` + lossy oldest-drop policy) |
18//!
19//! ## Design tenets
20//!
21//! - **Executor-agnostic.** No tokio / async-std / smol dependencies; works
22//!   anywhere `std::future::Future` works.
23//! - **Defence in depth.** Completion contexts are exact-live and one-shot.
24//!   Their atomic consumed flags only reject duplicates while the backing
25//!   allocation remains live; they do not validate dangling raw pointers.
26//! - **Panic-safe.** `extern "C"` callbacks pass through [`panic_safe`]
27//!   wrappers. Explicit cleanup runs before opaque destruction; multiple
28//!   destructor panics within one aggregate remain outside the contract.
29//!
30//! ## Stability
31//!
32//! This crate is the foundation of every doom-fish Apple-SDK binding crate.
33//! Breaking changes ship as major version bumps; minor versions add modules
34//! or non-breaking helpers.
35
36#![doc(html_root_url = "https://docs.rs/doom-fish-utils/0.4.1")]
37#![cfg_attr(docsrs, feature(doc_cfg))]
38
39pub mod callback_context;
40pub mod completion;
41pub mod ffi_callbacks;
42pub mod ffi_string;
43pub mod four_char_code;
44pub mod panic_safe;
45pub mod spsc;
46pub mod stream;
47
48pub use four_char_code::FourCharCode;
doom_fish_utils/lib.rs

doom_fish_utils/
lib.rs
