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//! | [`completion`] | Sync and async completion handlers for FFI callbacks |
11//! | [`ffi_callbacks`] | Common `extern "C"` callback type aliases shared across bridge crates |
12//! | [`ffi_string`] | Owned-string helpers around heap-allocated C strings |
13//! | [`four_char_code`] | `FourCharCode` wrapper (used by pixel formats, `OSType` codes, etc.) |
14//! | [`panic_safe`] | Catches panics inside `extern "C"` callbacks so they don't unwind across the FFI boundary |
15//! | [`stream`] | Executor-agnostic bounded async streams (waker + `VecDeque` + lossy oldest-drop policy) |
16//!
17//! ## Design tenets
18//!
19//! - **Executor-agnostic.** No tokio / async-std / smol dependencies; works
20//!   anywhere `std::future::Future` works.
21//! - **Defence in depth.** The async completion path uses an `AtomicBool`
22//!   `consumed` flag to prevent double-fire UAF in the face of misbehaving
23//!   Swift callbacks.
24//! - **Panic-safe.** `extern "C"` callbacks pass through [`panic_safe`]
25//!   wrappers so an unexpected Rust panic logs and returns rather than
26//!   unwinding into Swift / C code.
27//!
28//! ## Stability
29//!
30//! This crate is the foundation of every doom-fish Apple-SDK binding crate.
31//! Breaking changes ship as major version bumps; minor versions add modules
32//! or non-breaking helpers.
33
34#![doc(html_root_url = "https://docs.rs/doom-fish-utils/0.2.0")]
35#![cfg_attr(docsrs, feature(doc_cfg))]
36
37pub mod completion;
38pub mod ffi_callbacks;
39pub mod ffi_string;
40pub mod four_char_code;
41pub mod panic_safe;
42pub mod stream;
43
44pub use four_char_code::FourCharCode;
doom_fish_utils/lib.rs

doom_fish_utils/
lib.rs
