Crate indexbus_core 

Core IndexBus algorithms built on top of the v1 ABI layouts.

This crate provides safe(ish) APIs for initializing and operating on the shared-memory layouts defined in indexbus-abi.

• Layout structs live in indexbus-abi (Rust source of truth; C headers generated).
• This crate provides algorithms and handles (SPSC/MPSC events, fanout router, state stream).

Safety model

Handles in this crate are thin wrappers around raw pointers to ABI layouts (typically memory-mapped shared memory). They are “safe” to call in the Rust sense only if you uphold the contracts documented on each type:

• The mapped layout must outlive all handles derived from it.
• You must not concurrently call APIs that require single-threaded access (most handles are intentionally not Sync).
• Mappings should be validated with validate_shared_layout, validate_fanout_layout, validate_state_layout, etc. before use (especially across process boundaries).

Minimal SPSC example

use indexbus_core::{init_shared_layout, split_spsc, SharedLayoutCell};
use indexbus_abi::layouts::SharedLayout;

// SharedLayout is large; allocate it on the heap to avoid huge stack frames.
let mut shared: Box<SharedLayout> = Box::new(unsafe { core::mem::zeroed() });
init_shared_layout(&mut shared);
let cell = SharedLayoutCell::from_mut(&mut shared);
let (tx, rx) = split_spsc(cell).unwrap();

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

Re-exports

pub use state::StateLayoutCell;

pub use state::StatePublisher;

pub use state::StateReader;

pub use validate::validate_fanout_layout;

pub use validate::validate_journal_layout4;

pub use validate::validate_sequencer_layout;

pub use validate::validate_shared_layout;

pub use validate::validate_state_layout;

Modules

prelude

Curated prelude for downstream users.

state

State-stream publisher/reader algorithms.

validate

Runtime layout validation helpers.

Structs

ChainMpscConsumer

MPSC consumer handle over an explicit (pool, queue) pair.

ChainMpscProducer

MPSC producer handle over an explicit (pool, queue) pair.

ChainSpscReceiver

SPSC receiver handle over an explicit (pool, queue) pair.

ChainSpscSender

SPSC sender handle over an explicit (pool, queue) pair.

EventsSlot

Owned handle to an Events slot (slot index + pool pointer).

FanoutConsumer

Consumer handle for a fanout events region.

FanoutMpscProducer

Multi-producer handle for publishing into a fanout layout.

FanoutProducer

SPSC producer handle for a fanout events region.

FanoutRouter

Fanout router handle.

MpscConsumer

MPSC consumer handle for a SharedLayout events region.

MpscProducer

MPSC producer handle for a SharedLayout events region.

PublishSlotError

Error returned by publish_slot APIs when the slot cannot be forwarded.

RouteOnceResult

Result of a single FanoutRouter routing step.

SharedFanoutLayoutCell

SharedFanoutLayout<N> wrapper that explicitly opts into interior mutability.

SharedLayoutCell

SharedLayout wrapper that explicitly opts into interior mutability.

SpinWait

no_std-friendly spin-only wait strategy.

SpscReceiver

SPSC consumer handle for a SharedLayout events region.

SpscSender

SPSC producer handle for a SharedLayout events region.

StdBackoff

std-only: spin, then yield, then sleep with capped exponential backoff.

YieldWait

std-only: cooperative yield-only wait strategy.

Enums

Error

Core error type returned by the low-level region handles.

PublishWithError

Error returned by publish_with APIs.

RecvWithError

Error returned by try_recv_with APIs.

RouterMode

Routing policy for a single message.

RouterSource

Selects which producer queue the router drains from.

Constants

INDEXBUS_EMPTY_FREE_U32

Re-export ABI constants for convenience. Free-list empty sentinel.

INDEXBUS_FANOUT_CONSUMERS_DEFAULT

Re-export ABI constants for convenience. Default fanout consumer count used by examples.

INDEXBUS_QUEUE_CAPACITY

Re-export ABI constants for convenience. Ring queue capacity (MUST be power-of-two).

INDEXBUS_SLOTS_CAPACITY

Re-export ABI constants for convenience. Number of slots in the shared pool.

INDEXBUS_SLOT_DATA_SIZE

Re-export ABI constants for convenience. v1 constants (must match generated C headers). Fixed bytes available per slot payload.

Traits

WaitStrategy

Progressive backoff when polling.

Functions

cpu_relax

Hint to the processor that we are in a spin-wait loop.

fanout_handles

Create handles over a fanout layout.

fanout_mpsc_producer

Create an MPSC producer handle over a fanout layout.

init_shared_fanout_layout

Initialize a shared fanout events layout in-place with default v1 capabilities.

init_shared_fanout_layout_with_layout_bytes

Initialize a shared fanout events layout in-place.

init_shared_layout

Initialize a shared events layout in-place with default v1 capabilities.

init_shared_layout_with_layout_bytes

Initialize a shared events layout in-place.

split_chain_mpsc^⚠

Create MPSC producer/consumer handles over a shared slot pool and a specific MPSC queue.

split_chain_spsc^⚠

Create SPSC sender/receiver handles over a shared slot pool and a specific queue.

split_mpsc

Create MPSC producer/consumer handles over a shared layout.

split_spsc

Create SPSC sender/receiver handles over a shared layout.