Crate nodedb_bridge 

nodedb-bridge

Lock-free, capacity-bounded SPSC ring buffer bridging a Tokio Control Plane (Send + Sync) and a Thread-per-Core Data Plane (!Send).

This crate is the single most critical infrastructure component in NodeDB. If this bridge fails under load, the entire database fails.

Design constraints

• No locks, no atomics in the hot path beyond the two cache-line-padded head/tail counters (one written by producer, one by consumer).
• Bounded capacity: the ring buffer has a fixed power-of-two slot count. When full, the producer must yield — this is the backpressure mechanism.
• Cross-runtime waker integration: when the queue transitions from full→not-full or empty→not-empty, the sleeping side must be woken without requiring Send on the waker itself.
• Zero-copy where possible: payloads are Arc<[u8]> or slab handles; the ring buffer moves lightweight envelopes, not bulk data.

Validation target

Pump 50 GB of dummy data Tokio→TPC→Tokio. Memory must stay flat. Throughput must exceed 5 GB/s on a modern x86_64 machine.

Re-exports

pub use async_bridge::BridgeChannel;

pub use async_bridge::ControlHandle;

pub use async_bridge::DataHandle;

pub use async_bridge::PinnedDataHandle;

pub use backpressure::BackpressureConfig;

pub use backpressure::BackpressureController;

pub use backpressure::PressureState;

pub use buffer::Consumer;

pub use buffer::Producer;

pub use buffer::RingBuffer;

pub use envelope::Request;

pub use envelope::Response;

pub use error::BridgeError;

pub use error::Result;

pub use eventfd::EventFd;

pub use eventfd::WakePair;

pub use metrics::BridgeMetrics;

pub use wfq::WeightedFairQueue;

pub use wfq::priority_weight;

pub use wfq_metrics::VirtualQueueMetrics;

Modules

async_bridge

Async wrappers for the SPSC bridge.

backpressure

Adaptive backpressure controller.

buffer

Lock-free SPSC ring buffer.

envelope

error

eventfd

Cross-runtime wake signaling via Linux eventfd.

metrics

Bridge throughput and backpressure metrics.

telemetry

Lock-free per-core telemetry buffer.

waker

Cross-runtime waker integration.

wfq

Weighted-fair queue for per-database SPSC bridge dispatch.

wfq_metrics

Per-virtual-queue depth and backpressure counters.