Struct heapless::ring_buffer::RingBuffer

pub struct RingBuffer<T, N, U = usize> where
    N: Add<U1> + Unsigned,
    Sum<N, U1>: ArrayLength<T>,
    U: Uxx,  { /* fields omitted */ }

A statically allocated ring buffer with a capacity of N

By default RingBuffer will use usize integers to hold the indices to its head and tail. For small ring buffers usize may be overkill. However, RingBuffer's index type is generic and can be changed to u8 or u16 to reduce its footprint. The easiest to construct a RingBuffer with a smaller index type is to use the u8 and u16 constructors.

Examples

use heapless::RingBuffer;
use heapless::consts::*;

let mut rb: RingBuffer<u8, U3> = RingBuffer::new();

assert!(rb.enqueue(0).is_ok());
assert!(rb.enqueue(1).is_ok());
assert!(rb.enqueue(2).is_ok());
assert!(rb.enqueue(3).is_err()); // full

assert_eq!(rb.dequeue(), Some(0));

Single producer single consumer mode

use heapless::RingBuffer;
use heapless::consts::*;

// static mut RB: RingBuffer<Event, U4> = RingBuffer::new(); // requires feature `const-fn`

static mut RB: Option<RingBuffer<Event, U4>>  = None;

enum Event { A, B }

fn main() {
    unsafe { RB = Some(RingBuffer::new()) };
    // NOTE(unsafe) beware of aliasing the `consumer` end point
    let mut consumer = unsafe { RB.as_mut().unwrap().split().1 };

    loop {
        // `dequeue` is a lockless operation
        match consumer.dequeue() {
            Some(Event::A) => { /* .. */ },
            Some(Event::B) => { /* .. */ },
            None => { /* sleep */},
        }
    }
}

// this is a different execution context that can preempt `main`
fn interrupt_handler() {
    // NOTE(unsafe) beware of aliasing the `producer` end point
    let mut producer = unsafe { RB.as_mut().unwrap().split().0 };

    // ..

    if condition {
        producer.enqueue(Event::A).ok().unwrap();
    } else {
        producer.enqueue(Event::B).ok().unwrap();
    }

    // ..
}

Methods

impl<T, N, U> RingBuffer<T, N, U> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,     U: Uxx,

pub fn split<'rb>(     &'rb mut self ) -> (Producer<'rb, T, N, U>, Consumer<'rb, T, N, U>)

Splits a statically allocated ring buffer into producer and consumer end points

impl<T, N, U> RingBuffer<T, N, U> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,     U: Uxx,

pub fn capacity(&self) -> U

Returns the maximum number of elements the ring buffer can hold

pub fn is_empty(&self) -> bool

Returns true if the ring buffer has a length of 0

Important traits for Iter<'a, T, N, U>

impl<'a, T, N, U> Iterator for Iter<'a, T, N, U> where
    N: Add<U1> + Unsigned,
    Sum<N, U1>: ArrayLength<T>,
    T: 'a,
    U: 'a + Uxx,  type Item = &'a T;

pub fn iter(&self) -> Iter<T, N, U>

Iterates from the front of the queue to the back

Important traits for IterMut<'a, T, N, U>

impl<'a, T, N, U> Iterator for IterMut<'a, T, N, U> where
    N: Add<U1> + Unsigned,
    Sum<N, U1>: ArrayLength<T>,
    T: 'a,
    U: 'a + Uxx,  type Item = &'a mut T;

pub fn iter_mut(&mut self) -> IterMut<T, N, U>

Returns an iterator that allows modifying each value.

impl<T, N> RingBuffer<T, N, usize> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,

pub const fn new() -> Self

Alias for RingBuffer::usize

impl<T, N> RingBuffer<T, N, u8> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,

pub const fn u8() -> Self

Creates an empty ring buffer with a fixed capacity of N

pub fn dequeue(&mut self) -> Option<T>

Returns the item in the front of the queue, or None if the queue is empty

pub fn enqueue(&mut self, item: T) -> Result<(), T>

Adds an item to the end of the queue

Returns back the item if the queue is full

pub fn enqueue_unchecked(&mut self, item: T)

Adds an item to the end of the queue, without checking if it's full

WARNING If the queue is full this operation will make the queue appear empty to the Consumer, thus leaking (destructors won't run) all the elements that were in the queue.

pub fn len(&self) -> u8

Returns the number of elements in the queue

impl<T, N> RingBuffer<T, N, u16> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,

pub const fn u16() -> Self

Creates an empty ring buffer with a fixed capacity of N

pub fn dequeue(&mut self) -> Option<T>

Returns the item in the front of the queue, or None if the queue is empty

pub fn enqueue(&mut self, item: T) -> Result<(), T>

Adds an item to the end of the queue

Returns back the item if the queue is full

pub fn enqueue_unchecked(&mut self, item: T)

Adds an item to the end of the queue, without checking if it's full

WARNING If the queue is full this operation will make the queue appear empty to the Consumer, thus leaking (destructors won't run) all the elements that were in the queue.

pub fn len(&self) -> u16

Returns the number of elements in the queue

impl<T, N> RingBuffer<T, N, usize> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,

pub const fn usize() -> Self

Creates an empty ring buffer with a fixed capacity of N

pub fn dequeue(&mut self) -> Option<T>

Returns the item in the front of the queue, or None if the queue is empty

pub fn enqueue(&mut self, item: T) -> Result<(), T>

Adds an item to the end of the queue

Returns back the item if the queue is full

pub fn enqueue_unchecked(&mut self, item: T)

Adds an item to the end of the queue, without checking if it's full

WARNING If the queue is full this operation will make the queue appear empty to the Consumer, thus leaking (destructors won't run) all the elements that were in the queue.

pub fn len(&self) -> usize

Returns the number of elements in the queue

Trait Implementations

impl<T, N, U> Drop for RingBuffer<T, N, U> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,     U: Uxx,

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T, N, U> IntoIterator for &'a RingBuffer<T, N, U> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,     U: Uxx,

type Item = &'a T

The type of the elements being iterated over.

type IntoIter = Iter<'a, T, N, U>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<'a, T, N, U> IntoIterator for &'a mut RingBuffer<T, N, U> where     N: Add<U1> + Unsigned,     Sum<N, U1>: ArrayLength<T>,     U: Uxx,

type Item = &'a mut T

The type of the elements being iterated over.

type IntoIter = IterMut<'a, T, N, U>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.