Crate shm_primitives 

shm-primitives

Lock-free primitives for shared memory IPC.

This crate provides lock-free data structures designed for use in shared memory contexts where you work with raw pointers to memory-mapped regions.

Primitives

• SpscRing / SpscRingRaw: Single-producer single-consumer ring buffer with wait-free operations
• TreiberSlab / TreiberSlabRaw: Treiber stack-based slab allocator with generation counting for ABA protection

Raw vs Region APIs

Each primitive has two variants:

• Raw (SpscRingRaw, TreiberSlabRaw): Work with raw pointers, suitable for shared memory where you have *mut pointers from mmap. Caller manages memory lifetime.

• Region (SpscRing, TreiberSlab): Convenience wrappers that own their backing memory via a Region. These delegate to the Raw implementations internally.

Features

• loom - Enables loom-based concurrency testing

Loom Testing

All algorithms are tested under loom to verify correctness across all possible thread interleavings:

cargo test -p shm-primitives --features loom

Example

use shm_primitives::{SpscRing, HeapRegion, PushResult};

// Create a ring buffer with capacity 16
let region = HeapRegion::new_zeroed(SpscRing::<u64>::required_size(16));
let ring = SpscRing::<u64>::init(region.region(), 16);

// Split into producer and consumer
let (mut producer, mut consumer) = ring.split();

// Push some values
assert!(matches!(producer.push(42), PushResult::Ok));
assert!(matches!(producer.push(43), PushResult::Ok));

// Pop them back
assert_eq!(consumer.pop(), Some(42));
assert_eq!(consumer.pop(), Some(43));
assert_eq!(consumer.pop(), None);

License

MIT OR Apache-2.0

Re-exports

pub use region::HeapRegion;

pub use region::Region;

pub use slot::SlotMeta;

pub use slot::SlotState;

pub use slot::VarSlotMeta;

pub use spsc::PushResult;

pub use spsc::RingFull;

pub use spsc::SpscConsumer;

pub use spsc::SpscProducer;

pub use spsc::SpscRing;

pub use spsc::SpscRingHeader;

pub use spsc::SpscRingRaw;

pub use treiber::AllocResult;

pub use treiber::FreeError;

pub use treiber::SlotError;

pub use treiber::SlotHandle;

pub use treiber::TreiberSlab;

pub use treiber::TreiberSlabHeader;

pub use treiber::TreiberSlabRaw;

Modules

doorbell

Socketpair doorbell for cross-process wakeup.

mmap

File-backed memory-mapped regions for cross-process shared memory.

region

slot

spsc

sync

treiber

Structs

Doorbell

A doorbell for cross-process wakeup.

DoorbellHandle

Opaque handle for passing doorbell endpoints between processes.

MmapRegion

File-backed memory-mapped region for cross-process shared memory.

Enums

FileCleanup

Cleanup behavior for memory-mapped files.

SignalResult

Result of a doorbell signal attempt.

Functions

clear_cloexec

Clear the close-on-exec flag so the fd is inherited by children.

close_peer_fd

Close the peer end of a socketpair (host side, after spawning plugin).

set_nonblocking

Set a file descriptor to non-blocking mode.

validate_fd

Validate that a file descriptor is valid and open.