Crate nexus_logbuf 

High-performance lock-free ring buffers for variable-length messages.

This crate provides bounded SPSC and MPSC byte ring buffers optimized for getting data off the hot path without disturbing it. No allocation, no formatting, no syscalls on the producer side.

Modules

• queue: Low-level ring buffer primitives. No blocking, maximum control.
• channel: Ergonomic channel API with backoff and parking for receivers.

Design

• Flat byte buffer with free-running offsets, power-of-2 capacity
• len-as-commit: Record’s len field is the commit marker (non-zero = ready)
• Skip markers: High bit of len distinguishes padding/aborted claims
• Consumer zeroing: Consumer zeros records before releasing space
• Claim-based API: WriteClaim/ReadClaim with RAII semantics

Channel Philosophy

Senders are never slowed down. They use brief backoff (spin + yield) but never syscall. If the buffer is full, they return an error immediately.

Receivers can block. They use park_timeout to wait for messages without burning CPU, but always with a timeout to check for disconnection.

Example (Queue API)

use nexus_logbuf::queue::spsc;

let (mut producer, mut consumer) = spsc::new(4096);

// Producer (hot path)
let payload = b"hello world";
if let Ok(mut claim) = producer.try_claim(payload.len()) {
    claim.copy_from_slice(payload);
    claim.commit();
}

// Consumer (background thread)
if let Some(record) = consumer.try_claim() {
    assert_eq!(&*record, b"hello world");
    // record dropped here -> zeros region, advances head
}

Re-exports

pub use queue::mpsc;

pub use queue::spsc;

Modules

channel

Channel API with parking for receivers.

queue

Low-level ring buffer primitives.

Enums

TryClaimError

Error returned from queue try_claim operations.