indexbus_kit/lib.rs
1//! `indexbus-kit` is the **final, application-facing** ergonomics layer for IndexBus.
2//!
3//! It exists to make it easy to assemble *correct* applications from the substrate crates
4//! (`indexbus-abi`, `indexbus-core`, transports, routing, codecs) without hiding what is
5//! actually happening.
6//!
7//! ## Design constraints
8//!
9//! - Keep substrate crates explicit and stable (`indexbus-abi`, `indexbus-core`, transports).
10//! - Put ergonomics here: thin wrappers, safe constructors, curated re-exports.
11//! - Prefer feature-gated optional integrations (blocking, runtimes, UDP, etc.).
12//!
13//! ## Kit contract (stability vs convenience)
14//!
15//! `indexbus-kit` is intentionally a **kit**, not a substrate layer. That means it provides
16//! convenience APIs for apps while remaining conservative about what it promises to keep
17//! stable.
18//!
19//! **Stable-by-intent (contract surface):**
20//! - Feature flags behave as documented in the crate's `Cargo.toml` (e.g. `no_std` requires
21//! `alloc`, `std` enables host-side helpers).
22//! - Error behavior: helpers return [`crate::errors::Result`] and do not silently swallow
23//! substrate errors.
24//! - `embedded`, `msg`, and `typed` modules aim to remain source-compatible and are the
25//! preferred surface for “library-like” reuse inside an application.
26//!
27//! **Convenience (may change as patterns evolve):**
28//! - [`crate::prelude`] contents and re-exports.
29//! - `lanes::*` orchestration helpers (thread spawning, region open helpers, defaults).
30//! - `shm` temp-path helpers and small wiring shims.
31//!
32//! This crate is intended to be the **clear onboarding story** for IndexBus: if you're building
33//! an application (not a new transport or ABI/layout), start here.
34//!
35//! Module map (discoverability-first):
36//!
37//! - `lanes`: named lanes (`routing`, `sequencer`, `journal`) for host-side flows.
38//! - `embedded`: static-memory/no-heap building blocks intended to be `no_std` friendly.
39//! - `typed`: typed message helpers (codec selection + constructors).
40//! - `msg`: envelope/header helpers.
41//! - `runtime`/`blocking`/`transport`/`shm`: host integrations (std-only).
42//!
43//! ## Minimal embedded-style SPSC
44//!
45//! ```
46//! use indexbus_kit::embedded::static_spsc;
47//! use indexbus_kit::errors::Result;
48//!
49//! // `static_spsc()` is single-use (it returns handles into a single static region).
50//! let (tx, rx) = static_spsc().unwrap();
51//! tx.publish(b"hi").unwrap();
52//!
53//! let mut out = [0u8; 64];
54//! let n = rx.try_recv_into(&mut out).unwrap().unwrap();
55//! assert_eq!(&out[..n], b"hi");
56//! ```
57
58#![cfg_attr(not(feature = "std"), no_std)]
59#![deny(missing_docs)]
60
61#[cfg(feature = "alloc")]
62extern crate alloc;
63
64#[cfg(all(not(feature = "std"), not(feature = "alloc")))]
65compile_error!("indexbus-kit in no_std mode requires the `alloc` feature");
66
67pub mod prelude;
68
69/// Error type and `Result` alias used throughout `indexbus-kit`.
70pub mod errors;
71pub mod msg;
72pub mod typed;
73
74pub mod embedded;
75pub mod lanes;
76
77#[cfg(feature = "std")]
78pub mod shm;
79
80#[cfg(feature = "std")]
81pub mod transport;
82
83#[cfg(feature = "std")]
84pub mod runtime;
85
86#[cfg(feature = "blocking")]
87pub mod blocking;
88
89#[cfg(feature = "std")]
90mod internal;