Trait RingBuffer 

pub trait RingBuffer {
    type Item;

    // Required methods
    fn cap(&self) -> usize;
    fn len(&self) -> usize;
    fn get(&self, off: usize) -> Option<&Self::Item>;
    unsafe fn get_disjoint_mut(&self, off: usize) -> &mut Self::Item;
    fn enqueue(&mut self, item: Self::Item) -> Option<Self::Item>;
    fn dequeue(&mut self) -> Option<Self::Item>;

    // Provided methods
    fn is_empty(&self) -> bool { ... }
    fn is_full(&self) -> bool { ... }
    fn get_mut(&mut self, off: usize) -> Option<&mut Self::Item> { ... }
    fn iter(&self) -> Iter<'_, Self>  { ... }
    fn iter_mut(&mut self) -> IterMut<'_, Self>  { ... }
    fn skip_one(&mut self) { ... }
    fn skip(&mut self, num: usize) { ... }
    fn clear(&mut self) { ... }
    fn drain(&mut self) -> Drain<'_, Self>  { ... }
}

A ring buffer.

Ring buffers are double-ended fixed-capacity queues. New items can be added and the oldest-added items can be retrieved. Ring buffers have a capacity that determines the maximum number of items they can hold at any time; once they hit this limit, adding a new item will remove the oldest-added item. They can be seen as VecDeques with a maximum size.

This trait is object-safe; it can be used even when the implementing type is not known at compile-time (as &dyn RingBuffer).

Required Associated Types

type Item

The type of the items stored by the buffer.

Required Methods

fn cap(&self) -> usize

The capacity of the buffer.

This returns the maximum number of items the ring buffer can hold at any time. The capacity of a ring buffer cannot be changed, and it is at least one (as a zero-capacity ring buffer can never hold items).

fn len(&self) -> usize

The length of the buffer.

This returns the number of items the ring buffer is currently holding (this is less than or equal to the capacity of the buffer).

fn get(&self, off: usize) -> Option<&Self::Item>

Get a shared reference to the item at the given offset.

Considering the buffer from the oldest-added to newest-added item, the item at the given index/offset is selected, if it exists, and a shared reference to it is returned; None is returned if the offset was too large and no item could be found.

unsafe fn get_disjoint_mut(&self, off: usize) -> &mut Self::Item

Get a unique reference to the item at the given offset, assuming that no other reference to this item does or will exist.

This function is unsafe; it can only be called if its invariants are satisfied, as otherwise undefined behaviour will occur. Specifically, while the given lifetime exists:

• The given offset must be valid (in the range 0 .. len).
• The ring buffer must exist, at the same location, without moving.
• No new items can be enqueued or dequeued.
• This method cannot be called with the same index again.

If these conditions are satisfied, a unique reference to the item at the given offset is returned, as in get_mut(), but for a shared reference to self. This can be used to hold multiple unique references to different items at once, but it must be handled very carefully.

fn enqueue(&mut self, item: Self::Item) -> Option<Self::Item>

Enqueue an item.

If the buffer is full, the oldest item in the buffer will be removed and returned. Otherwise, None is returned.

fn dequeue(&mut self) -> Option<Self::Item>

Dequeue an item.

The oldest-added item in the buffer will be removed and returned. If the buffer is empty, None is returned.

Provided Methods

fn is_empty(&self) -> bool

Whether the buffer is empty.

fn is_full(&self) -> bool

Whether the buffer is full.

The buffer is full if its length is equal to its capacity; in this case, adding a new item will drop the oldest item.

fn get_mut(&mut self, off: usize) -> Option<&mut Self::Item>

Get a unique reference to the item at the given offset.

Considering the buffer from the oldest-added to newest-added item, the item at the given index/offset is selected, if it exists, and a unique reference to it is returned; None is returned if the offset was too large and no item could be found.

By default, this is implemented in terms of get_disjoint_mut(); but if it is re-implemented without, its body will likely be fairly similar to that of get().

fn iter(&self) -> Iter<'_, Self>

Iterate over shared references to the items in the queue.

The referenced items are not modified or removed from the queue; this is simply an inspection of the items, akin to calling get() for each item. For unique references, see iter_mut().

fn iter_mut(&mut self) -> IterMut<'_, Self>

Iterate over unique references to the items in the queue.

The referenced items are not modified or removed from the queue; this is simply an inspection of the items, akin to calling get_mut() for each item. For shared references, see iter().

fn skip_one(&mut self)

Skip the next item.

The oldest-added item in the buffer, if any, will be removed. This is akin to dequeueing the item and dropping it immediately.

fn skip(&mut self, num: usize)

Skip the given number of item.

This is equivalent to dequeueing this number of items (if they exist) and dropping them immediately. If the buffer contains fewer items, they are all dropped, and the buffer is cleared.

fn clear(&mut self)

Clear the buffer.

All the items in the buffer will be removed and dropped.

fn drain(&mut self) -> Drain<'_, Self>

Drain the items of the iterator.

An iterator is returned which removes and returns individual items from this ring buffer. Once the iterator is dropped, any remaining items can be accessed from the ring buffer; no items are lost outright. This is akin to calling dequeue() on the buffer repeatedly.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementations on Foreign Types

impl<RB: RingBuffer> RingBuffer for &mut RB

type Item = <RB as RingBuffer>::Item

fn cap(&self) -> usize

fn len(&self) -> usize

fn get(&self, off: usize) -> Option<&Self::Item>

fn get_mut(&mut self, off: usize) -> Option<&mut Self::Item>

unsafe fn get_disjoint_mut(&self, off: usize) -> &mut Self::Item

fn enqueue(&mut self, item: Self::Item) -> Option<Self::Item>

fn dequeue(&mut self) -> Option<Self::Item>

fn skip(&mut self, num: usize)

fn clear(&mut self)

Implementors

impl<S: Storage + ?Sized> RingBuffer for MaskingBuffer<S>

type Item = <S as Storage>::Item