Crate rtrb_basedrop

Expand description

This is a fork of the rtrb crate that uses basedrop’s Shared pointer in place of Arc. This ensures that when all references to the ring buffer are dropped, the underlying Vec will never potentially get deallocated (a non-realtime safe operation) in the realtime thread. Instead, all allocations are cleaned up in whatever thread owns the basedrop Collector object.

This is especially useful for audio applications.

A realtime-safe single-producer single-consumer (SPSC) ring buffer.

A RingBuffer consists of two parts: a Producer for writing into the ring buffer and a Consumer for reading from the ring buffer.

A fixed-capacity buffer is allocated on construction. After that, no more memory is allocated (unless the type T does that internally). Reading from and writing into the ring buffer is lock-free and wait-free. All reading and writing functions return immediately. Attempts to write to a full buffer return an error; values inside the buffer are not overwritten. Attempts to read from an empty buffer return an error as well. Only a single thread can write into the ring buffer and a single thread (typically a different one) can read from the ring buffer. If the queue is empty, there is no way for the reading thread to wait for new data, other than trying repeatedly until reading succeeds. Similarly, if the queue is full, there is no way for the writing thread to wait for newly available space to write to, other than trying repeatedly.

Examples

Moving single elements into and out of a queue with Producer::push() and Consumer::pop(), respectively:

use rtrb_basedrop::{RingBuffer, PushError, PopError};
use basedrop::Collector;

let collector = Collector::new();

let (mut producer, mut consumer) = RingBuffer::new(2, &collector.handle());

assert_eq!(producer.push(10), Ok(()));
assert_eq!(producer.push(20), Ok(()));
assert_eq!(producer.push(30), Err(PushError::Full(30)));

std::thread::spawn(move || {
    assert_eq!(consumer.pop(), Ok(10));
    assert_eq!(consumer.pop(), Ok(20));
    assert_eq!(consumer.pop(), Err(PopError::Empty));
}).join().unwrap();