Struct heapless::spsc::Queue

pub struct Queue<T, N, U = usize, C = MultiCore>where
    N: ArrayLength<T>,
    U: Uxx,
    C: XCore,{ /* private fields */ }

A statically allocated single producer single consumer queue with a capacity of N elements

IMPORTANT: To get better performance use a capacity that is a power of 2 (e.g. U16, U32, etc.).

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

IMPORTANT: spsc::Queue<_, _, u8> has a maximum capacity of 255 elements; spsc::Queue<_, _, u16> has a maximum capacity of 65535 elements.

spsc::Queue also comes in a single core variant. This variant can be created using the following constructors: u8_sc, u16_sc, usize_sc and new_sc. This variant is unsafe to create because the programmer must make sure that the queue’s consumer and producer endpoints (if split) are kept on a single core for their entire lifetime.

Examples

use heapless::spsc::Queue;
use heapless::consts::*;

let mut rb: Queue<u8, U4> = Queue::new();

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

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

Single producer single consumer mode

use heapless::spsc::Queue;
use heapless::consts::*;

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

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

enum Event { A, B }

fn main() {
    unsafe { RB = Some(Queue::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();
    }

    // ..
}

Implementations

impl<T, N, U, C> Queue<T, N, U, C>where
    N: ArrayLength<T>,
    U: Uxx,
    C: XCore,

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

Splits a statically allocated queue into producer and consumer end points

impl<T, N, U, C> Queue<T, N, U, C>where
    N: ArrayLength<T>,
    U: Uxx,
    C: XCore,

pub fn capacity(&self) -> U

Returns the maximum number of elements the queue can hold

pub fn is_empty(&self) -> bool

Returns true if the queue has a length of 0

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

Iterates from the front of the queue to the back

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

Returns an iterator that allows modifying each value.

impl<T, N> Queue<T, N, usize, MultiCore>where
    N: ArrayLength<T>,

pub fn new() -> Self

Alias for spsc::Queue::usize

impl<T, N> Queue<T, N, usize, SingleCore>where
    N: ArrayLength<T>,

pub unsafe fn new_sc() -> Self

Alias for spsc::Queue::usize_sc

impl<T, N> Queue<T, N, usize, MultiCore>where
    N: ArrayLength<T>,

pub fn usize() -> Self

Creates an empty queue with a fixed capacity of N

impl<T, N> Queue<T, N, usize, SingleCore>where
    N: ArrayLength<T>,

pub unsafe fn usize_sc() -> Self

Creates an empty queue with a fixed capacity of N (single core variant)

impl<T, N, C> Queue<T, N, usize, C>where
    N: ArrayLength<T>,
    C: XCore,

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 unsafe fn enqueue_unchecked(&mut self, item: T)

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

Unsafety

If the queue is full this operation will leak a value (T’s destructor won’t run on the value that got overwritten by item), and will allow the dequeue operation to create a copy of item, which could result in T’s destructor running on item twice.

pub fn len(&self) -> usize

Returns the number of elements in the queue

Trait Implementations

impl<T, N, U, C> Drop for Queue<T, N, U, C>where
    N: ArrayLength<T>,
    U: Uxx,
    C: XCore,

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T, N, U, C> IntoIterator for &'a Queue<T, N, U, C>where
    N: ArrayLength<T>,
    U: Uxx,
    C: XCore,

type Item = &'a T

The type of the elements being iterated over.

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

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, C> IntoIterator for &'a mut Queue<T, N, U, C>where
    N: ArrayLength<T>,
    U: Uxx,
    C: XCore,

type Item = &'a mut T

The type of the elements being iterated over.

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

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.