indexbus_transport_shm/
lib.rs

1#![cfg_attr(not(feature = "std"), no_std)]
2#![deny(missing_docs)]
3
4//! File-backed shared-memory transport for IndexBus layouts.
5//!
6//! This crate is a **std-only adapter** that maps IndexBus v1 layouts into memory using `memmap2`
7//! and provides safe(ish) helpers to initialize and validate those mappings.
8//!
9//! ## Feature flags
10//!
11//! - `std` (default): enables the transport (the public API is gated on `std`).
12//!
13//! ## Safety model
14//!
15//! Region types (e.g., [`EventsRegion`]) own an `mmap` and provide typed access to ABI layouts.
16//! They expose raw pointers for advanced integrations; callers must ensure that any derived
17//! handles do not outlive the region mapping.
18//!
19//! ### Threading
20//!
21//! Region wrapper types are marked `Send`/`Sync` via `unsafe impl` because they contain raw
22//! pointers into the mapping.
23//!
24//! This is sound under the intended usage model:
25//! - The backing memory is a shared layout that is mutated using ABI-defined atomics.
26//! - The wrapper does not hand out Rust references to interior fields (only raw pointers or
27//!   validated handle types).
28//! - Users must not create aliased `&mut` references into the mapping.
29//!
30//! If you need stronger guarantees, build higher-level synchronization at the application layer.
31//!
32//! ## Minimal events region (file-backed)
33//!
34//! ```no_run
35//! use indexbus_transport_shm::EventsRegion;
36//!
37//! // This will create/map the region file on first open.
38//! let mut region = EventsRegion::open_path("/tmp/indexbus.events").unwrap();
39//! let (tx, rx) = region.split_spsc().unwrap();
40//!
41//! tx.publish(b"hi").unwrap();
42//! let mut out = [0u8; 64];
43//! let n = rx.try_recv_into(&mut out).unwrap().unwrap();
44//! assert_eq!(&out[..n], b"hi");
45//! ```
46
47#[cfg(feature = "std")]
48mod errors;
49#[cfg(feature = "std")]
50mod regions;
51
52#[cfg(feature = "std")]
53mod internal;
54
55#[cfg(feature = "std")]
56pub use errors::Error;
57#[cfg(feature = "std")]
58pub use regions::{
59    EventsRegion, FanoutRegion, JournalOpenOptions, JournalRegion4, OpenOptions, SequencerRegion,
60};
indexbus_transport_shm/lib.rs

indexbus_transport_shm/
lib.rs
