Struct Queue 

pub struct Queue { /* private fields */ }

Thread-safe, bounded FIFO queue with backpressure.

Unlike crate::RingBuffer, this queue never drops frames. When the byte budget would be exceeded, push returns Error::ChannelFull and the frame is rejected. A max_bytes of 0 means the queue is unbounded.

Thread safety

All public methods take &self and synchronize via an internal Mutex.

Implementations

impl Queue

pub fn new(max_bytes: usize) -> Self

Create a queue with the given byte limit.

A max_bytes of 0 means unbounded — pushes will never fail due to capacity.

Warning

When max_bytes is 0 the queue has no memory limit. If the producer pushes data faster than the consumer drains it, memory usage will grow without bound, eventually causing an out-of-memory (OOM) condition. Prefer a non-zero byte limit for production use and reserve 0 (or Queue::unbounded) for cases where unbounded growth is explicitly acceptable.

pub fn unbounded() -> Self

Create an unbounded queue.

Equivalent to Queue::new(0).

Warning

An unbounded queue has no memory limit. If the consumer cannot keep up with the producer, memory usage will grow without bound. Prefer Queue::new with a reasonable byte limit for production use.

pub fn push(&self, frame: &[u8]) -> Result<(), Error>

Push a frame into the queue.

Returns Ok(()) if the frame was accepted. Returns Err(Error::ChannelFull) if the frame (plus its 4-byte length prefix) would exceed max_bytes. When max_bytes is 0 (unbounded), pushes always succeed.

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

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

Returns None if the queue is empty.

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

Drain all queued frames into a single binary blob and clear the queue.

Wire format

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

Returns an empty Vec if the queue is empty.

pub fn frame_count(&self) -> usize

Number of frames currently queued.

pub fn bytes_used(&self) -> usize

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

pub fn max_bytes(&self) -> usize

Maximum byte budget (0 means unbounded).

pub fn clear(&self)

Clear all queued frames.

Trait Implementations

impl Debug for Queue

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

Formats the value using the given formatter.