Struct RingBuffer

pub struct RingBuffer<'a, T: 'a> { /* private fields */ }

A ring buffer.

This ring buffer implementation provides many ways to interact with it:

• Enqueueing or dequeueing one element from corresponding side of the buffer;
• Enqueueing or dequeueing a slice of elements from corresponding side of the buffer;
• Accessing allocated and unallocated areas directly.

It is also zero-copy; all methods provide references into the buffer’s storage. Note that all references are mutable; it is considered more important to allow in-place processing than to protect from accidental mutation.

This implementation is suitable for both simple uses such as a FIFO queue of UDP packets, and advanced ones such as a TCP reassembly buffer.

Implementations

impl<'a, T: 'a> RingBuffer<'a, T>

pub fn new<S>(storage: S) -> RingBuffer<'a, T>

where S: Into<ManagedSlice<'a, T>>,

Create a ring buffer with the given storage.

During creation, every element in storage is reset.

pub fn clear(&mut self)

Clear the ring buffer.

pub fn capacity(&self) -> usize

Return the maximum number of elements in the ring buffer.

pub fn reset(&mut self)

where T: Resettable,

Clear the ring buffer, and reset every element.

pub fn len(&self) -> usize

Return the current number of elements in the ring buffer.

pub fn window(&self) -> usize

Return the number of elements that can be added to the ring buffer.

pub fn contiguous_window(&self) -> usize

Return the largest number of elements that can be added to the buffer without wrapping around (i.e. in a single enqueue_many call).

pub fn is_empty(&self) -> bool

Query whether the buffer is empty.

pub fn is_full(&self) -> bool

Query whether the buffer is full.

impl<'a, T: 'a> RingBuffer<'a, T>

This is the “discrete” ring buffer interface: it operates with single elements, and boundary conditions (empty/full) are errors.

pub fn enqueue_one_with<'b, R, E, F>( &'b mut self, f: F, ) -> Result<Result<R, E>, Full>

where F: FnOnce(&'b mut T) -> Result<R, E>,

Call f with a single buffer element, and enqueue the element if f returns successfully, or return Err(Full) if the buffer is full.

pub fn enqueue_one(&mut self) -> Result<&mut T, Full>

Enqueue a single element into the buffer, and return a reference to it, or return Err(Full) if the buffer is full.

This function is a shortcut for ring_buf.enqueue_one_with(Ok).

pub fn dequeue_one_with<'b, R, E, F>( &'b mut self, f: F, ) -> Result<Result<R, E>, Empty>

where F: FnOnce(&'b mut T) -> Result<R, E>,

Call f with a single buffer element, and dequeue the element if f returns successfully, or return Err(Empty) if the buffer is empty.

pub fn dequeue_one(&mut self) -> Result<&mut T, Empty>

Dequeue an element from the buffer, and return a reference to it, or return Err(Empty) if the buffer is empty.

This function is a shortcut for ring_buf.dequeue_one_with(Ok).

impl<'a, T: 'a> RingBuffer<'a, T>

This is the “continuous” ring buffer interface: it operates with element slices, and boundary conditions (empty/full) simply result in empty slices.

pub fn enqueue_many_with<'b, R, F>(&'b mut self, f: F) -> (usize, R)

where F: FnOnce(&'b mut [T]) -> (usize, R),

Call f with the largest contiguous slice of unallocated buffer elements, and enqueue the amount of elements returned by f.

Panics

This function panics if the amount of elements returned by f is larger than the size of the slice passed into it.

pub fn enqueue_many(&mut self, size: usize) -> &mut [T]

Enqueue a slice of elements up to the given size into the buffer, and return a reference to them.

This function may return a slice smaller than the given size if the free space in the buffer is not contiguous.

pub fn enqueue_slice(&mut self, data: &[T]) -> usize

where T: Copy,

Enqueue as many elements from the given slice into the buffer as possible, and return the amount of elements that could fit.

pub fn dequeue_many_with<'b, R, F>(&'b mut self, f: F) -> (usize, R)

where F: FnOnce(&'b mut [T]) -> (usize, R),

Call f with the largest contiguous slice of allocated buffer elements, and dequeue the amount of elements returned by f.

Panics

This function panics if the amount of elements returned by f is larger than the size of the slice passed into it.

pub fn dequeue_many(&mut self, size: usize) -> &mut [T]

Dequeue a slice of elements up to the given size from the buffer, and return a reference to them.

This function may return a slice smaller than the given size if the allocated space in the buffer is not contiguous.

pub fn dequeue_slice(&mut self, data: &mut [T]) -> usize

where T: Copy,

Dequeue as many elements from the buffer into the given slice as possible, and return the amount of elements that could fit.

impl<'a, T: 'a> RingBuffer<'a, T>

This is the “random access” ring buffer interface: it operates with element slices, and allows to access elements of the buffer that are not adjacent to its head or tail.

pub fn get_unallocated(&mut self, offset: usize, size: usize) -> &mut [T]

Return the largest contiguous slice of unallocated buffer elements starting at the given offset past the last allocated element, and up to the given size.

pub fn write_unallocated(&mut self, offset: usize, data: &[T]) -> usize

where T: Copy,

Write as many elements from the given slice into unallocated buffer elements starting at the given offset past the last allocated element, and return the amount written.

pub fn enqueue_unallocated(&mut self, count: usize)

Enqueue the given number of unallocated buffer elements.

Panics

Panics if the number of elements given exceeds the number of unallocated elements.

pub fn get_allocated(&self, offset: usize, size: usize) -> &[T]

Return the largest contiguous slice of allocated buffer elements starting at the given offset past the first allocated element, and up to the given size.

pub fn read_allocated(&mut self, offset: usize, data: &mut [T]) -> usize

where T: Copy,

Read as many elements from allocated buffer elements into the given slice starting at the given offset past the first allocated element, and return the amount read.

pub fn dequeue_allocated(&mut self, count: usize)

Dequeue the given number of allocated buffer elements.

Panics

Panics if the number of elements given exceeds the number of allocated elements.

Trait Implementations

impl<'a, T: Debug + 'a> Debug for RingBuffer<'a, T>

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

Formats the value using the given formatter.

impl<'a, T: 'a> From<ManagedSlice<'a, T>> for RingBuffer<'a, T>

fn from(slice: ManagedSlice<'a, T>) -> RingBuffer<'a, T>

Converts to this type from the input type.