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