bbqueue

To use BBQueue locally, you can use one of the pre-configured variants (nicknames) like Churrasco. The workflow involves:

1. Creating the buffer.
2. Obtaining a stream_producer and a stream_consumer.
3. Writing: Using grant_exact(n) to get a write grant, filling it, and then calling commit(n) to make the data available.
4. Reading: Using read() to get a read grant, accessing the data, and then calling release(n) to free the space.

use bbqueue::nicknames::Churrasco;

// Create a buffer with six elements
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();

// 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);

BBQueue (BipBuffer Queue) is a Single Producer Single Consumer (SPSC), lockless, no_std, thread-safe queue based on the BipBuffer design.

Unlike standard Circular/Ring Buffers that require data to be pushed one piece at a time, BBQueue grants access to contiguous blocks of memory. This makes it specifically designed for use with DMA (Direct Memory Access) on embedded systems, as a DMA engine can fill or empty a single contiguous block without needing to handle wrap-around logic mid-transfer.

Key characteristics:

• SPSC: One producer and one consumer.
• Lockless: Uses atomic operations for thread safety.
• Contiguous Grants: Provides slices of memory for efficient bulk transfers.

# use bbqueue::BBBuffer;
#
// 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);

Grants are temporary handles to the underlying buffer memory that implement Deref<Target = [u8]> and DerefMut.

StreamGrantW (Writing Grant)

• Purpose: Provides mutable access to a slice of the buffer for writing.
• Lifecycle: You must call .commit(used) to finalize the write and notify the consumer.
• Safety: It is marked #[must_use] because failing to commit means the data written is not visible to the consumer.

StreamGrantR (Reading Grant)

• Purpose: Provides access to a slice of the buffer for reading. It also implements DerefMut so you can mutate the storage in-place (e.g., for in-place decoding).
• Lifecycle: You must call .release(used) to free the space back to the producer.

Both types implement Drop. If they are dropped without an explicit commit or release, they will attempt to commit/release based on their internal tracking, but explicit calls are the intended way to manage the stream flow.

Framed mode allows BBQueue to operate with variable-length packets (chunks) rather than a continuous stream of bytes. It achieves this by prepending an internal size header to each frame.

When you request a grant, the system calculates a header size based on the maximum requested size. This header is used to store the actual number of bytes committed.

Important Considerations:

• Header Overhead: You must factor the header size into your total buffer capacity calculations. The header size is determined by the max_sz requested in grant(), not the number of bytes actually committed.
• Header Size Mapping: | Grant Size (bytes) | Header size (bytes) | | :--- | :--- | | 1..(2^7) | 1 | | (2^7)..(2^14) | 2 | | (2^14)..(2^21) | 3 | | (2^21)..(2^28) | 4 | | (2^28)..(2^35) | 5 | | (2^35)..(2^42) | 6 | | (2^42)..(2^49) | 7 | | (2^49)..(2^56) | 8 | | (2^56)..(2^64) | 9 |

Lifecycle Rules:

• Writing: If a FrameGrantW is dropped without calling commit() or to_commit(), no frame is committed.
• Reading: If a FrameGrantR is dropped without calling release(), no space is released back to the producer.

use bbqueue::BBBuffer;

let bb: BBBuffer<1000> = BBBuffer::new();
let (mut prod, mut cons) = bb.try_split_framed().unwrap();

// One frame in, one frame out
let mut wgrant = prod.grant(128).unwrap();
assert_eq!(wgrant.len(), 128);
for (idx, i) in wgrant.iter_mut().enumerate() {
    *i = idx as u8;
}
wgrant.commit(128);

let rgrant = cons.read().unwrap();
assert_eq!(rgrant.len(), 128);
for (idx, i) in rgrant.iter().enumerate() {
    assert_eq!(*i, idx as u8);
}
rgrant.release();

The BbqHandle trait is an abstraction used to manage how a BBQueue is accessed and shared. It decouples the data storage (where the bytes live) from the header storage (how the queue's state/metadata is shared between producers and consumers).

By using BbqHandle, you can write generic code that works regardless of whether the BBQueue is stored as a 'static reference (common in embedded systems) or wrapped in an Arc (common in hosted environments).

Instead of being generic over four different types, most consumer code only needs to be generic over a single type Q: BbqHandle. The trait bundles the following associated types:

• Target: The type used to reference the BBQueue (must implement Deref<Target = BBQueue<...>> and Clone).
• Storage: The mechanism for data storage (implements Storage).
• Coord: The coordination mechanism for producers/consumers (implements Coord).
• Notifier: The notification mechanism (implements Notifier).

BBQueue (BipBuffer Queue) is a Single Producer Single Consumer (SPSC), lockless, no_std, thread-safe queue based on the BipBuffer design.

Unlike standard circular/ring buffers where data must be pushed one piece at a time, BBQueue grants the user a block of contiguous memory. This makes it ideal for use with DMA (Direct Memory Access) on embedded systems, as a DMA engine can fill or empty a contiguous buffer without CPU intervention.

BBQueue uses generics to allow developers to customize four main aspects of the data structure:

1. Storage: Inline (const-generic) or heap-allocated.
2. Notification: Polling-only or async/await support.
3. Coordination: Lock-free algorithm with CAS (Compare-And-Swap) atomics, or critical sections (for targets without CAS).
4. Ownership: Reference counted (allowing Producer and Consumer halves to be passed around without lifetime constraints) or not.

use bbqueue::nicknames::Churrasco;

// Create a buffer with six elements
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();

// 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);