Crate indexbus_blocking 

Blocking (Tier B) adapters over indexbus-core using indexbus-wake.

This crate keeps indexbus-core bytes-first and nonblocking, and provides optional std-only blocking wrappers that use the appended wake sections in the v1 ABI.

Feature requirements

• This crate is std-only (std is the default and only meaningful feature).
• Blocking semantics require layouts/mappings that include wake sections.

Contracts

• Blocking operations park the current thread (directly or indirectly) until progress is possible, and are intended for Tier B integrations.
• Wake-backed adapters must not busy-spin while idle; they rely on indexbus-wake.
• On wake-capable mappings, blocking send/recv are expected to be fair with respect to other waiters.

Error semantics

• Constructor helpers return Error::MissingBlockingCapability when wake sections are required but not present.
• Layout validation failures from indexbus-core are propagated.

When wake sections are absent

Blocking adapters require both:

• INDEXBUS_CAP_SUPPORTS_BLOCKING in the layout header, and
• an appended wake section at the next 64B boundary (as validated by indexbus-core).

If either requirement is not met, constructors like split_spsc_blocking and fanout_handles_blocking return an error (Error::MissingBlockingCapability or a core layout validation error).

Fallback: use the nonblocking handles from indexbus-core (and/or indexbus-route) and drive progress via a polling loop appropriate to your application (e.g. route_once_with_stats plus std::thread::yield_now()/sleep/backoff).

Minimal usage (compile-only)

Blocking adapters require a mapping that includes a v1 wake section. Transports like indexbus-transport-shm can create such regions.

use indexbus_abi::{caps, layouts::SharedLayout};
use indexbus_blocking::split_spsc_blocking;
use indexbus_core::init_shared_layout_with_layout_bytes;

// SharedLayout is large; allocate it on the heap.
let mut shared: Box<SharedLayout> = Box::new(unsafe { core::mem::zeroed() });

// In a real mapping, `layout_bytes` must include the appended wake section bytes.
init_shared_layout_with_layout_bytes(
    &mut shared,
    caps::INDEXBUS_CAP_SUPPORTS_EVENTS | caps::INDEXBUS_CAP_SUPPORTS_BLOCKING,
    core::mem::size_of::<SharedLayout>() as u32,
);

let _blocking = split_spsc_blocking(&mut shared);

Structs

BlockingFanoutConsumer

Blocking wrapper over an indexbus-core fanout consumer.

BlockingFanoutProducer

Blocking wrapper over an indexbus-core fanout producer.

BlockingFanoutRouter

Blocking wrapper over an indexbus-core fanout router.

BlockingFanoutRouterRef

Blocking view over an existing FanoutRouter reference.

BlockingMpscConsumer

Blocking wrapper over an indexbus-core MPSC consumer.

BlockingMpscProducer

Blocking wrapper over an indexbus-core MPSC producer.

BlockingSpscReceiver

Blocking wrapper over an indexbus-core SPSC receiver.

BlockingSpscSender

Blocking wrapper over an indexbus-core SPSC sender.

Enums

Error

Errors returned by blocking adapters.

Functions

fanout_handles_blocking

Create wake-backed blocking wrappers for a fanout region.

fanout_router_ref_blocking

Create a wake-backed blocking view over an existing FanoutRouter.

split_mpsc_blocking

Create wake-backed blocking wrappers for MPSC over a SharedLayout.

split_spsc_blocking

Create wake-backed blocking wrappers for SPSC over a SharedLayout.

Type Aliases

Result

Convenience Result type for blocking adapters.