README.md
1# ringbuf
2
3[![Crates.io][crates_badge]][crates]
4[![Docs.rs][docs_badge]][docs]
5[![Travis CI][travis_badge]][travis]
6[![Appveyor][appveyor_badge]][appveyor]
7[![Codecov.io][codecov_badge]][codecov]
8[![License][license_badge]][license]
9
10[crates_badge]: https://img.shields.io/crates/v/ringbuf.svg
11[docs_badge]: https://docs.rs/ringbuf/badge.svg
12[travis_badge]: https://api.travis-ci.org/agerasev/ringbuf.svg
13[appveyor_badge]: https://ci.appveyor.com/api/projects/status/github/agerasev/ringbuf?branch=master&svg=true
14[codecov_badge]: https://codecov.io/gh/agerasev/ringbuf/graphs/badge.svg
15[license_badge]: https://img.shields.io/crates/l/ringbuf.svg
16
17[crates]: https://crates.io/crates/ringbuf
18[docs]: https://docs.rs/ringbuf
19[travis]: https://travis-ci.org/agerasev/ringbuf
20[appveyor]: https://ci.appveyor.com/project/agerasev/ringbuf
21[codecov]: https://codecov.io/gh/agerasev/ringbuf
22[license]: #license
23
24Lock-free single-producer single-consumer (SPSC) FIFO ring buffer with direct access to inner data.
25
26# Overview
27
28`RingBuffer` is the initial structure representing ring buffer itself.
29Ring buffer can be splitted into pair of `Producer` and `Consumer`.
30
31`Producer` and `Consumer` are used to append/remove elements to/from the ring buffer accordingly. They can be safely transfered between threads.
32Operations with `Producer` and `Consumer` are lock-free - they're succeded or failed immediately without blocking or waiting.
33
34Elements can be effectively appended/removed one by one or many at once.
35Also data could be loaded/stored directly into/from [`Read`]/[`Write`] instances.
36And finally, there are `unsafe` methods allowing thread-safe direct access in place to the inner memory being appended/removed.
37
38[`Read`]: https://doc.rust-lang.org/std/io/trait.Read.html
39[`Write`]: https://doc.rust-lang.org/std/io/trait.Write.html
40
41When building with nightly toolchain it is possible to run benchmarks via `cargo bench --features benchmark`.
42
43Also the crate could be used with `no_std` (but `alloc` is still required).
44
45# Examples
46
47## Simple example
48
49```rust
50use ringbuf::RingBuffer;
51
52let rb = RingBuffer::<i32>::new(2);
53let (mut prod, mut cons) = rb.split();
54
55prod.push(0).unwrap();
56prod.push(1).unwrap();
57assert_eq!(prod.push(2), Err(2));
58
59assert_eq!(cons.pop().unwrap(), 0);
60
61prod.push(2).unwrap();
62
63assert_eq!(cons.pop().unwrap(), 1);
64assert_eq!(cons.pop().unwrap(), 2);
65assert_eq!(cons.pop(), None);
66```
67
68## Message transfer
69
70This is more complicated example of transfering text message between threads.
71
72```rust
73use std::io::Read;
74use std::thread;
75use std::time::Duration;
76
77use ringbuf::RingBuffer;
78
79let buf = RingBuffer::<u8>::new(10);
80let (mut prod, mut cons) = buf.split();
81
82let smsg = "The quick brown fox jumps over the lazy dog";
83
84let pjh = thread::spawn(move || {
85 println!("-> sending message: '{}'", smsg);
86
87 let zero = [0];
88 let mut bytes = smsg.as_bytes().chain(&zero[..]);
89 loop {
90 if prod.is_full() {
91 println!("-> buffer is full, waiting");
92 thread::sleep(Duration::from_millis(1));
93 } else {
94 let n = prod.read_from(&mut bytes, None).unwrap();
95 if n == 0 {
96 break;
97 }
98 println!("-> {} bytes sent", n);
99 }
100 }
101
102 println!("-> message sent");
103});
104
105let cjh = thread::spawn(move || {
106 println!("<- receiving message");
107
108 let mut bytes = Vec::<u8>::new();
109 loop {
110 if cons.is_empty() {
111 if bytes.ends_with(&[0]) {
112 break;
113 } else {
114 println!("<- buffer is empty, waiting");
115 thread::sleep(Duration::from_millis(1));
116 }
117 } else {
118 let n = cons.write_into(&mut bytes, None).unwrap();
119 println!("<- {} bytes received", n);
120 }
121 }
122
123 assert_eq!(bytes.pop().unwrap(), 0);
124 let msg = String::from_utf8(bytes).unwrap();
125 println!("<- message received: '{}'", msg);
126
127 msg
128});
129
130pjh.join().unwrap();
131let rmsg = cjh.join().unwrap();
132
133assert_eq!(smsg, rmsg);
134```
135
136## License
137
138Licensed under either of
139
140 * Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
141 * MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
142
143at your option.
144
145### Contribution
146
147Unless you explicitly state otherwise, any contribution intentionally submitted
148for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any
149additional terms or conditions.
150