Shared-Memory Transport

IndexBus regions are file-backed shared memory (mmap). Multiple processes map the same file and communicate via atomic operations on the shared #[repr(C)] layout.

How SHM Regions Work

  Process A              /dev/shm/my_region              Process B
  ┌──────────┐          ┌──────────────────┐           ┌──────────┐
  │ Producer │──mmap───▶│  SharedFanout     │◀──mmap───│ Consumer │
  │          │          │  Layout (repr(C)) │           │          │
  └──────────┘          └──────────────────┘           └──────────┘

Lifecycle

Create — The creator opens or creates the SHM file and initializes the layout (initialized: 0→1→2).
Open — Other processes open the file and validate before use: magic, version, capabilities, layout_bytes, and initialized state.
Crash handling — The safest approach is to recreate the region rather than reattach to a potentially corrupted one.

Production Requirements

Requirement	Recommendation
Filesystem	`tmpfs` or `hugetlbfs` for SHM files
Permissions	Restrictive (owner-only or group-restricted)
Memory sizing	Ensure `mapped_bytes >= layout_bytes`; check at validation
Page locking	`mlockall` to avoid page faults on the hot path
Huge pages	Tested and supported; reduces TLB pressure for large regions
Core pinning	Pin router and critical consumers to dedicated cores
NUMA	Place region on same NUMA node as its participants

Security Considerations

IndexBus SHM is designed for same-host, trusted-participant IPC. It is NOT:

A network security boundary
A cryptographic secrecy or integrity mechanism
Safe for multi-tenant use without strong OS-level isolation

Risks and Mitigations

Risk	Mitigation
Unauthorized read	Restrictive file permissions and ownership
Unauthorized write	Restrict SHM paths; separate per-environment namespaces
Data lifetime	Bytes may remain after participants exit; clean up explicitly
Corruption	Validate before use; recreate on failed validation

Delivery Semantics Summary

Primitive	Delivery Guarantee	Ordering	Notes
SPSC events	At-most-once	FIFO	Nonblocking; loss by design
MPSC events	At-most-once	Per-producer FIFO	Cross-producer order not guaranteed
Fanout (Broadcast)	Best-effort per consumer	Per-producer FIFO	Partial delivery allowed
Fanout (WorkQueue)	Exactly-one consumer	Per-producer FIFO	Round-robin selection
State stream	Overwrite-latest	N/A (snapshot)	Even seq = stable; odd = in-progress
Sequencer + gating	Coordination-only	Strict monotonic	Wrap prevention bounds producer
Journal	Append-only	Append order	Overrun detection for slow subs

Cross-stream and cross-producer ordering is not guaranteed.

Memory visibility uses Acquire/Release atomics. Publication commit is the synchronization point.

Provenance

Need the canonical source?

Use the public hub to orient yourself, then jump to repo-owned docs or rustdoc when you need contract-level detail.

Source-of-truth model Repo docs index

#Shared-Memory Transport

#How SHM Regions Work

#Lifecycle

#Production Requirements

#Security Considerations

#Risks and Mitigations