Crate indexbus_transport_shm

Crate indexbus_transport_shm 

Source
Expand description

File-backed shared-memory transport for IndexBus layouts.

This crate is a std-only adapter that maps IndexBus v1 layouts into memory using memmap2 and provides safe(ish) helpers to initialize and validate those mappings.

§Feature flags

  • std (default): enables the transport (the public API is gated on std).

§Safety model

Region types (e.g., EventsRegion) own an mmap and provide typed access to ABI layouts. They expose raw pointers for advanced integrations; callers must ensure that any derived handles do not outlive the region mapping.

§Threading

Region wrapper types are marked Send/Sync via unsafe impl because they contain raw pointers into the mapping.

This is sound under the intended usage model:

  • The backing memory is a shared layout that is mutated using ABI-defined atomics.
  • The wrapper does not hand out Rust references to interior fields (only raw pointers or validated handle types).
  • Users must not create aliased &mut references into the mapping.

If you need stronger guarantees, build higher-level synchronization at the application layer.

§Minimal events region (file-backed)

use indexbus_transport_shm::EventsRegion;

// This will create/map the region file on first open.
let mut region = EventsRegion::open_path("/tmp/indexbus.events").unwrap();
let (tx, rx) = region.split_spsc().unwrap();

tx.publish(b"hi").unwrap();
let mut out = [0u8; 64];
let n = rx.try_recv_into(&mut out).unwrap().unwrap();
assert_eq!(&out[..n], b"hi");

Structs§

EventsRegion
File-backed shared events region (SPSC + MPSC).
FanoutRegion
File-backed shared fanout region.
JournalOpenOptions
Options for opening a mapped journal region.
JournalRegion4
File-backed journal region (concrete v1 layout).
OpenOptions
Options for opening a mapped region.
SequencerRegion
File-backed shared sequencer region.

Enums§

Error
Errors returned by the indexbus-transport-shm adapter.