Trait ringbuf::ring_buffer::RbBase

source ·

pub trait RbBase<T> {
    // Required methods
    unsafe fn slices(
        &self,
        head: usize,
        tail: usize
    ) -> (&mut [MaybeUninit<T>], &mut [MaybeUninit<T>]);
    fn capacity_nonzero(&self) -> NonZeroUsize;
    fn head(&self) -> usize;
    fn tail(&self) -> usize;

    // Provided methods
    fn modulus(&self) -> NonZeroUsize { ... }
    fn occupied_len(&self) -> usize { ... }
    fn vacant_len(&self) -> usize { ... }
    fn is_empty(&self) -> bool { ... }
    fn is_full(&self) -> bool { ... }
}

Expand description

Basic ring buffer functionality.

Provides an access to raw underlying memory and head/tail counters.

It is recommended not to use this trait directly. Use Producer and Consumer instead.

Details

The ring buffer consists of an array (of capacity size) and two counters: head and tail. When an item is extracted from the ring buffer it is taken from the head position and after that head is incremented. New item is appended to the tail position and tail is incremented after that.

The head and tail counters are modulo 2 * capacity (not just capacity). It allows us to distinguish situations when the buffer is empty (head == tail) and when the buffer is full (tail - head modulo 2 * capacity equals to capacity) without using the space for an extra element in container. And obviously we cannot store more than capacity items in the buffer, so tail - head modulo 2 * capacity is not allowed to be greater than capacity.