nodedb_bridge/lib.rs
1//! # nodedb-bridge
2//!
3//! Lock-free, capacity-bounded SPSC ring buffer bridging a **Tokio Control Plane**
4//! (`Send + Sync`) and a **Thread-per-Core Data Plane** (`!Send`).
5//!
6//! This crate is the single most critical infrastructure component in NodeDB.
7//! If this bridge fails under load, the entire database fails.
8//!
9//! ## Design constraints
10//!
11//! - **No locks, no atomics in the hot path** beyond the two cache-line-padded
12//! head/tail counters (one written by producer, one by consumer).
13//! - **Bounded capacity**: the ring buffer has a fixed power-of-two slot count.
14//! When full, the producer must yield — this is the backpressure mechanism.
15//! - **Cross-runtime waker integration**: when the queue transitions from
16//! full→not-full or empty→not-empty, the sleeping side must be woken
17//! *without* requiring `Send` on the waker itself.
18//! - **Zero-copy where possible**: payloads are `Arc<[u8]>` or slab handles;
19//! the ring buffer moves lightweight envelopes, not bulk data.
20//!
21//! ## Validation target
22//!
23//! Pump 50 GB of dummy data Tokio→TPC→Tokio. Memory must stay flat.
24//! Throughput must exceed 5 GB/s on a modern x86_64 machine.
25
26pub mod async_bridge;
27pub mod backpressure;
28pub mod buffer;
29pub mod envelope;
30pub mod error;
31pub mod eventfd;
32pub mod metrics;
33pub mod telemetry;
34#[cfg(feature = "tokio")]
35pub mod tokio_fd;
36pub mod waker;
37
38pub use async_bridge::{BridgeChannel, ControlHandle, DataHandle, PinnedDataHandle};
39pub use backpressure::{BackpressureConfig, BackpressureController, PressureState};
40pub use buffer::{Consumer, Producer, RingBuffer};
41pub use envelope::{Request, Response};
42pub use error::{BridgeError, Result};
43pub use eventfd::{EventFd, WakePair};
44pub use metrics::BridgeMetrics;
45#[cfg(feature = "tokio")]
46pub use tokio_fd::AsyncControlHandle;