ringbuf-basedrop 0.1.0

# ringbuf-basedrop

[![Crates.io][crates_badge]][crates]
[![Docs.rs][docs_badge]][docs]
[![Github Actions][github_badge]][github]
[![License][license_badge]][license]

[crates_badge]: https://img.shields.io/crates/v/ringbuf-basedrop.svg
[docs_badge]: https://docs.rs/ringbuf-basedrop/badge.svg
[github_badge]: https://github.com/RustyDAW/ringbuf-basedrop/actions/workflows/test.yml/badge.svg
[license_badge]: https://img.shields.io/crates/l/ringbuf-basedrop.svg

[crates]: https://crates.io/crates/ringbuf-basedrop
[docs]: https://docs.rs/ringbuf-basedrop
[github]: https://github.com/RustyDAW/ringbuf-basedrop/actions/workflows/test.yml
[license]: #license

This is a fork of the [`ringbuf`] crate that uses [`basedrop`]'s `Shared` pointer in place of `Arc`. This ensures that when all references 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.

# Overview

`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.

[`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
[`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html

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).

# Examples

## Simple example

```rust
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);
```

## Message transfer

This is more complicated example of transfering text message between threads.

```rust
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);
```

## License

Licensed under either of

 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

### Contribution

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.

[`ringbuf`]: https://github.com/agerasev/ringbuf
[`basedrop`]: https://github.com/glowcoil/basedrop