bbq2 is the new bbqueue (jamesmunns#119)

* A few docs and organization changes

* bbq2 is the new bbqueue

* bless bbq2 as bbqueue

* Update some remaining bbq2s

* Fix docs

Closes jamesmunns#112

Author: jamesmunns

.github/workflows/build.yml

@@ -9,7 +9,7 @@ on:
 
 defaults:
   run:
-    working-directory: ./bbq2
+    working-directory: ./bbqueue
 
 jobs:
   build:
@@ -23,22 +23,22 @@ jobs:
       # BUILD + TEST
       #
       # no features, on std
-      - name: Check bbq2 (no features, on host)
+      - name: Check bbqueue (no features, on host)
         run: cargo build --no-default-features
       # default features, on std
-      - name: Check bbq2 (default features, on host)
+      - name: Check bbqueue (default features, on host)
         run: cargo build
       # std features, on std
-      - name: Check bbq2 (std features, on host)
+      - name: Check bbqueue (std features, on host)
         run: cargo build --features=std
       # std features, on std, test
-      - name: Test bbq2 (std features, on host)
+      - name: Test bbqueue (std features, on host)
         run: cargo test --features=std
 
       # no features, on mcu
-      - name: Check bbq2 (no features, on mcu)
+      - name: Check bbqueue (no features, on mcu)
         run: cargo build --no-default-features --target=thumbv6m-none-eabi
       # default features, on mcu
-      - name: Check bbq2 (no features, on mcu)
+      - name: Check bbqueue (no features, on mcu)
         run: cargo build --target=thumbv6m-none-eabi
 

.github/workflows/miri.yml

@@ -9,7 +9,7 @@ on:
 
 defaults:
   run:
-    working-directory: ./bbq2
+    working-directory: ./bbqueue
 
 jobs:
   miri:
@@ -22,5 +22,5 @@ jobs:
       #
       # crate
       #
-      - name: Miri test bbq2
+      - name: Miri test bbqueue
         run: ./miri.sh

Cargo.toml

@@ -1,7 +1,7 @@
 [workspace]
 resolver = "3"
 members = [
-    "bbq2",
+    "bbqueue",
     "legacy-bbqtest",
     "legacy-core",
 ]

README.md

@@ -2,13 +2,12 @@
 
 [![Documentation](https://docs.rs/bbqueue/badge.svg)](https://docs.rs/bbqueue)
 
+# 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/The-Bip-Buffer-The-Circular-Buffer-with-a-Twist
 [this blog post]: https://ferrous-systems.com/blog/lock-free-ring-buffer/
 
@@ -22,9 +21,14 @@ block of contiguous memory, which can be filled (or emptied) by a DMA engine.
 ## Local usage
 
 ```rust
+// The "Churrasco" flavor has inline storage, hardware atomic
+// support, no async support, and is not reference counted.
+use bbqueue::nicknames::Churrasco;
+
 // Create a buffer with six elements
-let bb: BBBuffer<6> = BBBuffer::new();
-let (mut prod, mut cons) = bb.try_split().unwrap();
+let bb: Churrasco<6> = Churrasco::new();
+let prod = bb.stream_producer();
+let cons = bb.stream_consumer();
 
 // Request space for one byte
 let mut wgr = prod.grant_exact(1).unwrap();
@@ -48,17 +52,32 @@ rgr.release(1);
 
 ## Static usage
 
-```rust, no_run
-use bbqueue::BBBuffer;
+```rust
+use bbqueue::nicknames::Churrasco;
+use std::{thread::{sleep, spawn}, time::Duration};
 
 // Create a buffer with six elements
-static BB: BBBuffer<6> = BBBuffer::new();
+static BB: Churrasco<6> = Churrasco::new();
+
+fn receiver() {
+    let cons = BB.stream_consumer();
+    loop {
+        if let Ok(rgr) = cons.read() {
+            assert_eq!(rgr.len(), 1);
+            assert_eq!(rgr[0], 123);
+            rgr.release(1);
+            break;
+        }
+        // don't do this in real code, use Notify!
+        sleep(Duration::from_millis(10));
+    }
+}
 
 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();
+    let prod = BB.stream_producer();
+
+    // spawn the consumer
+    let hdl = spawn(receiver);
 
     // Request space for one byte
     let mut wgr = prod.grant_exact(1).unwrap();
@@ -71,26 +90,28 @@ fn main() {
     // Make the data ready for consuming
     wgr.commit(1);
 
-    // Read all available bytes
-    let rgr = cons.read().unwrap();
+    // make sure the receiver terminated
+    hdl.join().unwrap();
+}
+```
 
-    assert_eq!(rgr[0], 123);
+## Nicknames
 
-    // Release the space for later writes
-    rgr.release(1);
+bbqueue uses generics to customize the data structure in four main ways:
 
-    // The buffer cannot be split twice
-    assert!(BB.try_split().is_err());
-}
-```
+* Whether the byte storage is inline (and const-generic), or heap allocated
+* Whether the queue is polling-only, or supports async/await sending/receiving
+* Whether the queue uses a lock-free algorithm with CAS atomics, or uses a critical section
+  (for targets that don't have CAS atomics)
+* Whether the queue is reference counted, allowing Producer and Consumer halves to be passed
+  around without lifetimes.
 
-The `bbqueue` crate is located in `core/`, and tests are located in `bbqtest/`.
+See the [`nicknames`](crate::nicknames) module for all sixteen variants.
 
-## Features
+## Stability
 
-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.
+`bbqueue` v0.6 is a breaking change from the older "classic" v0.5 interfaces. The intent is to
+have a few minor breaking changes in early 2026, and to get to v1.0 as quickly as possible.
 
 
 # License