Struct RingBuffer 

pub struct RingBuffer { /* private fields */ }

Thread-safe, in-process circular buffer for streaming binary frames.

Frames are variable-length byte slices stored with a u32 LE length prefix. The buffer enforces a byte budget; when a push would exceed the budget the oldest frames are silently dropped (lossy back-pressure).

Thread safety

All public methods take &self and synchronize via an internal Mutex. Contention is expected to be low: typically one producer thread and one consumer (the custom protocol handler draining on a fetch call).

Implementations

impl RingBuffer

pub fn new(capacity: usize) -> Self

Create a ring buffer with the given byte capacity.

Panics

Panics if capacity is less than DRAIN_FRAME_OVERHEAD + 1 (5 bytes), since at least a 1-byte frame must be storable.

pub fn with_default_capacity() -> Self

Create a ring buffer with the default capacity (64 KB).

pub fn push(&self, frame: &[u8]) -> usize

Push a frame into the buffer.

If the frame (plus its 4-byte length prefix) would exceed the byte budget, the oldest frames are dropped until there is room. Returns the number of frames that were dropped to make space.

If the frame itself is larger than the total capacity it is silently discarded and the return value is 0.

pub fn push_checked(&self, frame: &[u8]) -> PushOutcome

Push a frame with a richer outcome report.

Like push, but returns PushOutcome::TooLarge when the frame can never fit, instead of silently returning 0.

pub fn drain_all(&self) -> Vec<u8>

Drain all buffered frames into a single binary blob and clear the buffer.

Wire format

[u32 LE frame_count]
[u32 LE len_1][bytes_1]
[u32 LE len_2][bytes_2]
...

Returns an empty Vec if the buffer is empty.

pub fn try_pop(&self) -> Option<Vec<u8>>

Read one frame from the front of the buffer (FIFO).

Returns None if the buffer is empty.

pub fn frame_count(&self) -> usize

Number of frames currently buffered.

pub fn bytes_used(&self) -> usize

Number of bytes currently used (including per-frame length prefixes).

pub fn capacity(&self) -> usize

Total byte capacity of the buffer.

pub fn clear(&self)

Clear all buffered frames.

Trait Implementations

impl Debug for RingBuffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.