Struct rtrb::RingBuffer

pub struct RingBuffer<T> { /* fields omitted */ }

A bounded single-producer single-consumer queue.

Elements can be written with a Producer and read with a Consumer, both of which can be obtained with RingBuffer::split().

See also the crate-level documentation.

Implementations

impl<T> RingBuffer<T>

pub fn new(capacity: usize) -> RingBuffer<T>

Creates a RingBuffer with the given capacity.

The returned RingBuffer is typically immediately split into the Producer and the Consumer side by split().

If you want guaranteed wrap-around behavior, use with_chunks().

Examples

use rtrb::RingBuffer;

let rb = RingBuffer::<f32>::new(100);

Specifying an explicit type with the turbofish is is only necessary if it cannot be deduced by the compiler.

use rtrb::RingBuffer;

let (mut producer, consumer) = RingBuffer::new(100).split();
assert_eq!(producer.push(0.0f32), Ok(()));

pub fn with_chunks(chunks: usize, chunk_size: usize) -> RingBuffer<T>

Creates a RingBuffer with a capacity of chunks * chunk_size.

On top of multiplying the two numbers for us, this also guarantees that the ring buffer wrap-around happens at an integer multiple of chunk_size. This means that if Consumer::read_chunk() is used exclusively with chunk_size (and Consumer::pop() is not used in-between), the first slice returned from ReadChunk::as_slices() will always contain the entire chunk and the second slice will always be empty. Same for Producer::write_chunk()/WriteChunk::as_mut_slices() and Producer::write_chunk_uninit()/WriteChunkUninit::as_mut_slices() (as long as Producer::push() is not used in-between).

If above conditions have been violated, the wrap-around guarantee can be restored wit reset().

pub fn split(self) -> (Producer<T>, Consumer<T>)

Splits the RingBuffer into Producer and Consumer.

Examples

use rtrb::RingBuffer;

let (producer, consumer) = RingBuffer::<f32>::new(100).split();

pub fn reset(producer: &mut Producer<T>, consumer: &mut Consumer<T>)

Resets a ring buffer.

This drops all elements that are currently in the queue (running their destructors if T implements Drop) and resets the internal read and write positions to the beginning of the buffer.

This also resets the guarantees given by with_chunks().

Exclusive access to both Producer and Consumer is needed for this operation. They can be moved between threads, for example, with a RingBuffer<Producer<T>> and a RingBuffer<Consumer<T>>, respectively.

Panics

Panics if the producer and consumer do not originate from the same RingBuffer.

Examples

use rtrb::RingBuffer;

let (mut p, mut c) = RingBuffer::new(2).split();

p = std::thread::spawn(move || {
    assert_eq!(p.push(10), Ok(()));
    p
}).join().unwrap();

RingBuffer::reset(&mut p, &mut c);

// The full capacity is now available for writing:
if let Ok(mut chunk) = p.write_chunk(p.buffer().capacity()) {
    let (first, second) = chunk.as_mut_slices();
    // The first slice is now guaranteed to span the whole buffer:
    first[0] = 20;
    first[1] = 30;
    assert!(second.is_empty());
    chunk.commit_all();
} else {
    unreachable!();
}

pub fn capacity(&self) -> usize

Returns the capacity of the queue.

Examples

use rtrb::RingBuffer;

let rb = RingBuffer::<f32>::new(100);
assert_eq!(rb.capacity(), 100);

Trait Implementations

impl<T: Debug> Debug for RingBuffer<T>

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

Formats the value using the given formatter.

impl<T> Drop for RingBuffer<T>

pub fn drop(&mut self)

Drops all non-empty slots.

impl<T> Eq for RingBuffer<T>

impl<T> PartialEq<RingBuffer<T>> for RingBuffer<T>

pub fn eq(&self, other: &Self) -> bool

This method tests for self and other values to be equal, and is used by ==.

Examples

use rtrb::RingBuffer;

let (p, c) = RingBuffer::<f32>::new(1000).split();
assert_eq!(p.buffer(), c.buffer());

let rb1 = RingBuffer::<f32>::new(1000);
let rb2 = RingBuffer::<f32>::new(1000);
assert_ne!(rb1, rb2);

#[must_use]pub fn ne(&self, other: &Rhs) -> bool

This method tests for !=.