Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jamesmunns/bbqueue
A SPSC, lockless, no_std, thread safe, queue, based on BipBuffers
https://github.com/jamesmunns/bbqueue
Last synced: 8 days ago
JSON representation
A SPSC, lockless, no_std, thread safe, queue, based on BipBuffers
- Host: GitHub
- URL: https://github.com/jamesmunns/bbqueue
- Owner: jamesmunns
- License: apache-2.0
- Created: 2018-12-31T00:26:47.000Z (almost 6 years ago)
- Default Branch: main
- Last Pushed: 2023-12-06T00:36:16.000Z (11 months ago)
- Last Synced: 2024-05-02T05:14:10.126Z (6 months ago)
- Language: Rust
- Homepage:
- Size: 221 KB
- Stars: 389
- Watchers: 12
- Forks: 48
- Open Issues: 30
-
Metadata Files:
- Readme: README.md
- License: LICENSE-APACHE
Awesome Lists containing this project
README
# BBQueue
[](https://docs.rs/bbqueue)
BBQueue, short for "BipBuffer Queue", is a Single Producer Single Consumer,
lockless, no_std, thread safe, queue, based on [BipBuffers]. For more info on
the design of the lock-free algorithm used by bbqueue, see [this blog post].
For a 90 minute guided tour of BBQueue, you can also view this [guide on YouTube].
[guide on YouTube]: https://www.youtube.com/watch?v=ngTCf2cnGkY
[BipBuffers]: https://www.codeproject.com/Articles/3479/%2FArticles%2F3479%2FThe-Bip-Buffer-The-Circular-Buffer-with-a-Twist
[this blog post]: https://ferrous-systems.com/blog/lock-free-ring-buffer/
BBQueue is designed (primarily) to be a First-In, First-Out queue for use with DMA on embedded
systems.
While Circular/Ring Buffers allow you to send data between two threads (or from an interrupt to
main code), you must push the data one piece at a time. With BBQueue, you instead are granted a
block of contiguous memory, which can be filled (or emptied) by a DMA engine.
## Local usage
```rust
// Create a buffer with six elements
let bb: BBBuffer<6> = BBBuffer::new();
let (mut prod, mut cons) = bb.try_split().unwrap();
// Request space for one byte
let mut wgr = prod.grant_exact(1).unwrap();
// Set the data
wgr[0] = 123;
assert_eq!(wgr.len(), 1);
// Make the data ready for consuming
wgr.commit(1);
// Read all available bytes
let rgr = cons.read().unwrap();
assert_eq!(rgr[0], 123);
// Release the space for later writes
rgr.release(1);
```
## Static usage
```rust, no_run
use bbqueue::BBBuffer;
// Create a buffer with six elements
static BB: BBBuffer<6> = BBBuffer::new();
fn main() {
// Split the bbqueue into producer and consumer halves.
// These halves can be sent to different threads or to
// an interrupt handler for thread safe SPSC usage
let (mut prod, mut cons) = BB.try_split().unwrap();
// Request space for one byte
let mut wgr = prod.grant_exact(1).unwrap();
// Set the data
wgr[0] = 123;
assert_eq!(wgr.len(), 1);
// Make the data ready for consuming
wgr.commit(1);
// Read all available bytes
let rgr = cons.read().unwrap();
assert_eq!(rgr[0], 123);
// Release the space for later writes
rgr.release(1);
// The buffer cannot be split twice
assert!(BB.try_split().is_err());
}
```
The `bbqueue` crate is located in `core/`, and tests are located in `bbqtest/`.
## Features
By default BBQueue uses atomic operations which are available on most platforms. However on some
(mostly embedded) platforms atomic support is limited and with the default features you will get
a compiler error about missing atomic methods.
# 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.