Crates.io | ringbuf-basedrop |
lib.rs | ringbuf-basedrop |
version | 0.1.1 |
source | src |
created_at | 2022-05-30 19:37:45.587076 |
updated_at | 2022-05-30 22:05:44.059648 |
description | A fork of the `ringbuf` crate that uses basedrop's Shared pointer in place of Arc |
homepage | https://github.com/RustyDAW/ringbuf-basedrop |
repository | https://github.com/RustyDAW/ringbuf-basedrop.git |
max_upload_size | |
id | 597121 |
size | 97,815 |
This is a fork of the ringbuf
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.
Lock-free single-producer single-consumer (SPSC) FIFO ring buffer with direct access to inner data.
RingBuffer
is the initial structure representing ring buffer itself.
Ring buffer can be splitted into pair of Producer
and Consumer
.
Producer
and Consumer
are used to append/remove elements to/from the ring buffer accordingly. They can be safely transfered between threads.
Operations with Producer
and Consumer
are lock-free - they're succeded or failed immediately without blocking or waiting.
Elements can be effectively appended/removed one by one or many at once.
Also data could be loaded/stored directly into/from Read
/Write
instances.
And finally, there are unsafe
methods allowing thread-safe direct access in place to the inner memory being appended/removed.
When building with nightly toolchain it is possible to run benchmarks via cargo bench --features benchmark
.
Also the crate could be used with no_std
(but alloc
is still required).
use basedrop::Collector;
use ringbuf::RingBuffer;
let collector = Collector::new();
let rb = RingBuffer::<i32>::new(2);
let (mut prod, mut cons) = rb.split(&collector.handle());
prod.push(0).unwrap();
prod.push(1).unwrap();
assert_eq!(prod.push(2), Err(2));
assert_eq!(cons.pop().unwrap(), 0);
prod.push(2).unwrap();
assert_eq!(cons.pop().unwrap(), 1);
assert_eq!(cons.pop().unwrap(), 2);
assert_eq!(cons.pop(), None);
This is more complicated example of transfering text message between threads.
use std::io::Read;
use std::thread;
use std::time::Duration;
use basedrop::Collector;
use ringbuf::RingBuffer;
let collector = Collector::new();
let buf = RingBuffer::<u8>::new(10);
let (mut prod, mut cons) = buf.split(&collector.handle());
let smsg = "The quick brown fox jumps over the lazy dog";
let pjh = thread::spawn(move || {
println!("-> sending message: '{}'", smsg);
let zero = [0];
let mut bytes = smsg.as_bytes().chain(&zero[..]);
loop {
if prod.is_full() {
println!("-> buffer is full, waiting");
thread::sleep(Duration::from_millis(1));
} else {
let n = prod.read_from(&mut bytes, None).unwrap();
if n == 0 {
break;
}
println!("-> {} bytes sent", n);
}
}
println!("-> message sent");
});
let cjh = thread::spawn(move || {
println!("<- receiving message");
let mut bytes = Vec::<u8>::new();
loop {
if cons.is_empty() {
if bytes.ends_with(&[0]) {
break;
} else {
println!("<- buffer is empty, waiting");
thread::sleep(Duration::from_millis(1));
}
} else {
let n = cons.write_into(&mut bytes, None).unwrap();
println!("<- {} bytes received", n);
}
}
assert_eq!(bytes.pop().unwrap(), 0);
let msg = String::from_utf8(bytes).unwrap();
println!("<- message received: '{}'", msg);
msg
});
pjh.join().unwrap();
let rmsg = cjh.join().unwrap();
assert_eq!(smsg, rmsg);
Licensed under either of
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.