### Rust Slice SIMD Splitting Example

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Demonstrates splitting a slice into mutable prefix, middle SIMD, and suffix parts using `as_simd_mut`. Requires the `portable_simd` feature.

```rust
#![feature(portable_simd)]
use core::simd::prelude::*;

let short = &[1, 2, 3];
let (prefix, middle, suffix) = short.as_simd::<4>();
assert_eq!(middle, []); // Not enough elements for anything in the middle

// They might be split in any possible way between prefix and suffix
let it = prefix.iter().chain(suffix).copied();
assert_eq!(it.collect::<Vec<_>>(), vec![1, 2, 3]);

fn basic_simd_sum(x: &[f32]) -> f32 {
    use std::ops::Add;
    let (prefix, middle, suffix) = x.as_simd();
    let sums = f32x4::from_array([
        prefix.iter().copied().sum(),
        0.0,
        0.0,
        suffix.iter().copied().sum(),
    ]);
    let sums = middle.iter().copied().fold(sums, f32x4::add);
    sums.reduce_sum()
}

let numbers: Vec<f32> = (1..101).map(|x| x as _).collect();
assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0);

```

--------------------------------

### Repeat Slice Elements (Panic Example)

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Demonstrates a panic scenario when attempting to repeat a slice with a count that would cause capacity overflow.

```rust
// this will panic at runtime
b"0123456789abcdef".repeat(usize::MAX);
```

--------------------------------

### ConstStorage Implementor Example

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/storage/trait.ConstStorage.html

Shows a generic implementation of ConstStorage for any type T that already implements Storage and ConstInit. This is typically how ConstStorage is used.

```rust
impl<T> ConstStorage for T
where T: Storage + ConstInit,

```

--------------------------------

### ConstInit for Polling

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/export/trait.ConstInit.html

Example implementation of ConstInit for the Polling type, providing a constant `INIT` value.

```rust
impl ConstInit for Polling {
    const INIT: Self = Polling
}
```

--------------------------------

### Get StreamConsumer for BBQueue

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/queue.rs.html

Creates a StreamConsumer for the BBQueue. Mixing stream and framed producers/consumers is not recommended and can lead to incorrect behavior.

```rust
pub const fn stream_consumer(&self) -> StreamConsumer<&'_ Self> {
        StreamConsumer { bbq: self }
    }
```

--------------------------------

### Check if a slice starts with a prefix

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `starts_with` to determine if a slice begins with a specific sequence of elements. It always returns `true` if the prefix is an empty slice.

```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

```rust
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```

--------------------------------

### Get FramedProducer for BBQueue

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/queue.rs.html

Creates a FramedProducer for the BBQueue. Note that mixing stream and framed producers/consumers is not recommended and may lead to incorrect behavior.

```rust
pub const fn framed_producer(&self) -> FramedProducer<&'_ Self> {
        FramedProducer {
            bbq: self,
            pd: PhantomData,
        }
    }
```

--------------------------------

### Initialize BBQueue with different storage types

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/lib.rs.html

Demonstrates initializing BBQueue with static inline storage, dynamically allocated inline storage, and boxed slice storage.

```rust
static BBQ: BBQueue<Inline<64>, AtomicCoord, Polling> = BBQueue::new();
let _ = BBQ.stream_producer();
let _ = BBQ.stream_consumer();

let buf2 = Inline::<64>::new();
let bbq2: BBQueue<_, AtomicCoord, Polling> = BBQueue::new_with_storage(&buf2);
let _ = bbq2.stream_producer();
let _ = bbq2.stream_consumer();

let buf3 = BoxedSlice::new(64);
let bbq3: BBQueue<_, AtomicCoord, Polling> = BBQueue::new_with_storage(buf3);
let _ = bbq3.stream_producer();
let _ = bbq3.stream_consumer();
```

--------------------------------

### Get First Element of Slice

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Returns the first element of the slice, or `None` if it is empty. Example: `[10, 40, 30].first()` returns `Some(&10)`.

```rust
pub fn first(&self) -> Option<&T>
```

--------------------------------

### MaiNotSpsc::INIT

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/notifier/maitake/struct.MaiNotSpsc.html

Provides the default, constant initialization value for `MaiNotSpsc`.

```APIDOC
## MaiNotSpsc::INIT

### Description
The default value of this type.

### Constant
`const INIT: Self`
```

--------------------------------

### Get Mutable Reference to First Element

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Returns a mutable reference to the first element of the slice, or `None` if it is empty. Example: Modifies the first element of `&mut [0, 1, 2]` to `5`.

```rust
pub fn first_mut(&mut self) -> Option<&mut T>
```

--------------------------------

### Get Element Offset

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `element_offset` to find the index of an element reference within a slice. This method uses pointer arithmetic and does not compare elements. It returns `None` if the element reference is not aligned with the start of an element.

```rust
let nums: &[u32] = &[1, 7, 1, 1];
let num = &nums[2];

assert_eq!(num, &1);
assert_eq!(nums.element_offset(num), Some(2));
```

```rust
let arr: &[[u32; 2]] = &[[0, 1], [2, 3]];
let flat_arr: &[u32] = arr.as_flattened();

let ok_elm: &[u32; 2] = flat_arr[0..2].try_into().unwrap();
let weird_elm: &[u32; 2] = flat_arr[1..3].try_into().unwrap();

assert_eq!(ok_elm, &[0, 1]);
assert_eq!(weird_elm, &[1, 2]);

assert_eq!(arr.element_offset(ok_elm), Some(0)); // Points to element 0
assert_eq!(arr.element_offset(weird_elm), None); // Points between element 0 and 1
```

--------------------------------

### BBQueue::new

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Braai.html

Creates a new BBQueue instance in a const context.

```APIDOC
## `new`

Source

```rust
pub const fn new() -> Self
```

### Description

Creates a new `BBQueue` instance in a constant context. This is useful for initializing the queue at compile time when using `ConstStorage`.

### Method

`new`

### Parameters

This function takes no parameters.
```

--------------------------------

### Iterating Over Non-Overlapping Reverse Chunks

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantW.html

Use `rchunks` to get an iterator over non-overlapping chunks of a specified `chunk_size` starting from the end of the slice. The last chunk may be smaller if `chunk_size` does not divide the slice length. It panics if `chunk_size` is zero.

```rust
let slice = [0, 1, 2, 3, 4];
let mut iter = slice.rchunks(2);
assert_eq!(iter.next().unwrap(), &[3, 4]);
assert_eq!(iter.next().unwrap(), &[1, 2]);
assert_eq!(iter.next().unwrap(), &[0]);
```

--------------------------------

### Get the Last Element of a Slice

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `last` to get an immutable reference to the last element. Returns `None` if the slice is empty.

```rust
let v = [10, 40, 30];
assert_eq!(Some(&30), v.last());

let w: &[i32] = &[];
assert_eq!(None, w.last());
```

--------------------------------

### MaiNotSpsc Constructor and Initialization

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/traits/notifier/maitake.rs.html

Provides a constant constructor `new()` and implements `Default` and `ConstInit` for `MaiNotSpsc`. The `INIT` constant ensures zero-cost initialization.

```rust
impl MaiNotSpsc {
    /// Create a new Maitake-Sync based notifier
    pub const fn new() -> Self {
        Self::INIT
    }
}

impl Default for MaiNotSpsc {
    fn default() -> Self {
        Self::new()
    }
}

impl ConstInit for MaiNotSpsc {
    #[allow(clippy::declare_interior_mutable_const)]
    const INIT: Self = Self {
        not_empty: WaitCell::new(),
        not_full: WaitCell::new(),
    };
}
```

--------------------------------

### starts_with

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Checks if a slice begins with a specified prefix slice.

```APIDOC
## pub fn starts_with(&self, needle: &[T]) -> bool

### Description
Returns `true` if `needle` is a prefix of the slice or equal to the slice.

### Parameters
- `needle` (*&[T]*): The slice to check as a prefix.

### Returns
- `bool`: `true` if `needle` is a prefix, `false` otherwise.

### Examples
```rust
let v = [10, 40, 30];
assert!(v.starts_with(&[10]));
assert!(v.starts_with(&[10, 40]));
assert!(v.starts_with(&v));
assert!(!v.starts_with(&[50]));
assert!(!v.starts_with(&[10, 50]));
```

Always returns `true` if `needle` is an empty slice:
```rust
let v = &[10, 40, 30];
assert!(v.starts_with(&[]));
let v: &[u8] = &[];
assert!(v.starts_with(&[]));
```
```

--------------------------------

### Get a Mutable Reference to the Last Element of a Slice

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `last_mut` to get a mutable reference to the last element. Returns `None` if the slice is empty.

```rust
let x = &mut [0, 1, 2];

if let Some(last) = x.last_mut() {
    *last = 10;
}
assert_eq!(x, &[0, 1, 10]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.last_mut());
```

--------------------------------

### Get Slice as Array Reference

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Gets a reference to the underlying array if the requested size `N` exactly matches the slice length. Returns `None` otherwise.

```rust
let arr = [1, 2, 3];
let slice = &arr[..];
let sub_slice = &slice[1..3];

let array_ref: Option<&[i32; 2]> = sub_slice.as_array();
assert!(array_ref.is_none());

let array_ref_ok: Option<&[i32; 2]> = slice.as_array();
assert!(array_ref_ok.is_some());
```

--------------------------------

### Inline::new

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/storage/struct.Inline.html

Creates a new instance of Inline storage with a specified capacity.

```APIDOC
## Inline::new

### Description
Creates a new inline storage, e.g. `[u8; N]`.

### Method
`fn new() -> Self`

### Parameters
None

### Returns
A new `Inline` storage instance.
```

--------------------------------

### Get the Last N Elements as an Array

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `last_chunk` to get an array reference to the last `N` elements. Returns `None` if the slice is shorter than `N`.

```rust
let x = &[0, 1, 2];

// Example usage would go here, but is not provided in the source.
```

--------------------------------

### MaiNotSpsc::new

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/notifier/maitake/struct.MaiNotSpsc.html

Creates a new instance of the Maitake-Sync based SPSC notifier.

```APIDOC
## MaiNotSpsc::new

### Description
Creates a new Maitake-Sync based notifier.

### Method
`new()`

### Returns
A new `MaiNotSpsc` instance.
```

--------------------------------

### Get the First N Elements as an Array

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `first_chunk` to get an array reference to the first `N` elements. Returns `None` if the slice is shorter than `N`.

```rust
let u = [10, 40, 30];
assert_eq!(Some(&[10, 40]), u.first_chunk::<2>());

let v: &[i32] = &[10];
assert_eq!(None, v.first_chunk::<2>());

let w: &[i32] = &[];
assert_eq!(Some(&[]), w.first_chunk::<0>());
```

--------------------------------

### Create BBQueue with Storage

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Memphis.html

Instantiates a new BBQueue with the provided storage implementation. Ensure the storage implementation is compatible with the BBQueue's requirements.

```rust
pub fn new_with_storage(sto: S) -> Self

```

--------------------------------

### Demonstrate slice shift_right operation

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Illustrates the `shift_right` operation on slices, showing how elements are shifted and returned. Includes examples of its similarity to bitshifts and its behavior with sub-slices and matching sizes.

```rust
#![feature(slice_shift)]

// Same as the diagram above
let mut a = [5, 6, 7, 8, 9];
let inserted = [0];
let returned = a.shift_right(inserted);
assert_eq!(returned, [9]);
assert_eq!(a, [0, 5, 6, 7, 8]);

// The name comes from this operation's similarity to bitshifts
let mut a: u8 = 0b10010110;
a >>= 3;
assert_eq!(a, 0b00010010_u8);
let mut a: [_; 8] = [1, 0, 0, 1, 0, 1, 1, 0];
a.shift_right([0; 3]);
assert_eq!(a, [0, 0, 0, 1, 0, 0, 1, 0]);

// Remember you can sub-slice to affect less that the whole slice.
// For example, this is similar to `.remove(4)` + `.insert(1, 'Z')`
let mut a = ['a', 'b', 'c', 'd', 'e', 'f'];
assert_eq!(a[1..=4].shift_right(['Z']), ['e']);
assert_eq!(a, ['a', 'Z', 'b', 'c', 'd', 'f']);

// If the size matches it's equivalent to `mem::replace`
let mut a = [1, 2, 3];
assert_eq!(a.shift_right([7, 8, 9]), [1, 2, 3]);
assert_eq!(a, [7, 8, 9]);

// Some of the "inserted" elements end up returned if the slice is too short
let mut a = [];
assert_eq!(a.shift_right([1, 2, 3]), [1, 2, 3]);
let mut a = [9];
assert_eq!(a.shift_right([1, 2, 3]), [2, 3, 9]);
assert_eq!(a, [1]);
```

--------------------------------

### Get the First N Elements Mutably as an Array

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Use `first_chunk_mut` to get a mutable array reference to the first `N` elements. Returns `None` if the slice is shorter than `N`.

```rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_chunk_mut::<2>() {
    first[0] = 5;
    first[1] = 4;
}
assert_eq!(x, &[5, 4, 2]);

assert_eq!(None, x.first_chunk_mut::<4>());
```

--------------------------------

### Split Off Slice Starting from Third Element

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Use `split_off` with a range starting from an index to remove and return a subslice from that point onwards. The original slice is modified to contain elements before the specified index.

```rust
let mut slice: &[_] = &['a', 'b', 'c', 'd'];
let mut tail = slice.split_off(2..).unwrap();

assert_eq!(slice, &['a', 'b']);
assert_eq!(tail, &['c', 'd']);
```

--------------------------------

### Rust Slice rsplit Example

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Demonstrates splitting a slice from the end using `rsplit` with a predicate that matches the number 0. Shows how empty slices can be returned if the delimiter is at the beginning or end.

```rust
let slice = [11, 22, 33, 0, 44, 55];
let mut iter = slice.rsplit(|num| *num == 0);

assert_eq!(iter.next().unwrap(), &[44, 55]);
assert_eq!(iter.next().unwrap(), &[11, 22, 33]);
assert_eq!(iter.next(), None);
```

--------------------------------

### Get Mutable Slice as Mutable Array Reference

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Gets a mutable reference to the slice’s underlying array if the requested size `N` exactly matches the slice length. Returns `None` otherwise.

```rust
let mut arr = [1, 2, 3];
let slice = &mut arr[..];
let sub_slice = &mut slice[1..3];

let array_mut_ref: Option<&mut [i32; 2]> = sub_slice.as_mut_array();
assert!(array_mut_ref.is_none());

let array_mut_ref_ok: Option<&mut [i32; 2]> = slice.as_mut_array();
assert!(array_mut_ref_ok.is_some());
```

--------------------------------

### BBQueue framed producer misuse example

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/lib.rs.html

Illustrates potential misuse scenarios with the framed producer, specifically focusing on incorrect grant sizes (too large or too small) that lead to errors when reading.

```rust
use crate::traits::notifier::polling::Polling;

static BBQ: BBQueue<Inline<64>, AtomicCoord, Polling> = BBQueue::new();
let prod = BBQ.stream_producer();
let cons = BBQ.framed_consumer();

// Bad grant one: HUGE header value
let write_once = &[0xFF, 0xFF, 0x03, 0x04, 0x11, 0x12];
let mut wgr = prod.grant_exact(6).unwrap();
wgr[..6].copy_from_slice(write_once);
wgr.commit(6);

assert!(cons.read().is_err());

{
    // Clear the bad grant
    let cons2 = BBQ.stream_consumer();
    let rgr = cons2.read().unwrap();
    rgr.release(6);
}

// Bad grant two: too small of a grant
let write_once = &[0x00];
let mut wgr = prod.grant_exact(1).unwrap();
wgr[..1].copy_from_slice(write_once);
wgr.commit(1);

assert!(cons.read().is_err());
```

--------------------------------

### BBQueue::new_with_storage

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Braai.html

Creates a new BBQueue instance with the provided storage.

```APIDOC
## `new_with_storage`

Source

```rust
pub fn new_with_storage(sto: S) -> Self
```

### Description

Creates a new `BBQueue` instance, initializing it with the given `Storage` implementation. This allows for custom storage solutions.

### Method

`new_with_storage`

### Parameters

#### Path Parameters

- **sto** (S) - Required - The storage implementation to use for the BBQueue.
```

--------------------------------

### Split Off Mutable Slice Starting from Third Element

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Use `split_off_mut` with a range starting from an index to remove and return a mutable subslice from that point onwards. The original mutable slice is modified to contain elements before the specified index.

```rust
let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd'];
let mut tail = slice.split_off_mut(2..).unwrap();

assert_eq!(slice, &mut ['a', 'b']);
assert_eq!(tail, &mut ['c', 'd']);
```

--------------------------------

### Get Slice Length

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Returns the number of elements in the slice.

```rust
pub fn len(&self) -> usize
```

```rust
let a = [1, 2, 3];
assert_eq!(a.len(), 3);
```

--------------------------------

### Create BBQueue with Storage

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/queue.rs.html

Instantiates a new BBQueue using a provided Storage implementation. Initializes coordination and notifier components with their default values.

```rust
pub fn new_with_storage(sto: S) -> Self {
        Self {
            sto,
            cor: C::INIT,
            not: N::INIT,
        }
    }
```

--------------------------------

### iter

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Returns an iterator over the slice, yielding items from start to end.

```APIDOC
## pub fn iter(&self) -> Iter<'_, T>

### Description
Returns an iterator over the slice.
The iterator yields all items from start to end.
### Examples
```
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```
```

--------------------------------

### capacity

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Barbacoa.html

Gets the total capacity of the buffer, indicating how much space is available in the Storage.

```APIDOC
## capacity

```rust
pub fn capacity(&self) -> usize
```

### Description
Get the total capacity of the buffer, e.g. how much space is present in `Storage`
```

--------------------------------

### BoxedSlice::new

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/storage/struct.BoxedSlice.html

Creates a new BoxedSlice with a specified capacity. This is the primary way to instantiate a BoxedSlice for use as storage.

```APIDOC
## BoxedSlice::new

### Description
Create a new BoxedSlice with capacity `len`.

### Signature
```rust
pub fn new(len: usize) -> Self
```

### Parameters
* `len` (usize) - The desired capacity for the BoxedSlice.
```

--------------------------------

### get

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Safely retrieves a reference to an element or subslice by index. Returns `None` if the index is out of bounds.

```APIDOC
## get<I>

### Description
Returns a reference to an element or subslice depending on the type of index. If given a position, returns a reference to the element at that position or `None` if out of bounds. If given a range, returns the subslice corresponding to that range, or `None` if out of bounds.

### Method
`get(index: I)` where `I: SliceIndex<[T]>`

### Parameters
* `index` (I) - The index or range to access.

### Response
* `Option<&<I as SliceIndex<[T]>>::Output>` - A reference to the element or subslice, or `None` if out of bounds.

### Examples
```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```
```

--------------------------------

### Static BBQueue Usage with Churrasco

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/index.html

Illustrates static usage of BBQueue with 'Churrasco', suitable for global or static contexts. This example includes a separate receiver thread to demonstrate inter-thread communication. Note the use of `sleep` for polling, which is not recommended for production; consider using `Notify` instead.

```rust
use bbqueue::nicknames::Churrasco;
use std::{thread::{sleep, spawn}, time::Duration};

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

    // Set the data
    wgr[0] = 123;

    assert_eq!(wgr.len(), 1);

    // Make the data ready for consuming
    wgr.commit(1);

    // make sure the receiver terminated
    hdl.join().unwrap();
}
```

--------------------------------

### Asynchronous BBQueue stream producer and consumer with Tokio

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/lib.rs.html

Demonstrates asynchronous data transfer using BBQueue with Tokio. It shows spawning tasks for producer and consumer, using `wait_read` for asynchronous reading, and `grant_exact` for writing.

```rust
use crate::traits::notifier::polling::Polling;
use core::ops::Deref;

static BBQ: BBQueue<Inline<64>, AtomicCoord, MaiNotSpsc> = BBQueue::new();
let prod = BBQ.stream_producer();
let cons = BBQ.stream_consumer();

let rxfut = tokio::task::spawn(async move {
    let rgr = cons.wait_read().await;
    assert_eq!(rgr.deref(), &[1, 2, 3]);
});

let txfut = tokio::task::spawn(async move {
    tokio::time::sleep(Duration::from_millis(500)).await;
    let mut wgr = prod.grant_exact(3).unwrap();
    wgr.copy_from_slice(&[1, 2, 3]);
    wgr.commit(3);
});

// todo: timeouts
rxfut.await.unwrap();
txfut.await.unwrap();
```

--------------------------------

### Get BBQueue Capacity

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/queue.rs.html

Retrieves the total capacity of the buffer. This operation is safe as the capacity is immutable.

```rust
pub fn capacity(&self) -> usize {
        // SAFETY: capacity never changes, therefore reading the len is safe
        unsafe {
            self.0.sto.ptr_len().1
        }
    }
```

--------------------------------

### Rust partition_point for Insertion

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Demonstrates using `partition_point` to find the correct insertion index for an element in a sorted vector to maintain sort order. This can be more efficient than `binary_search` followed by `insert`.

```rust
let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];
let num = 42;
let idx = s.partition_point(|&x| x <= num);
// If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to
// `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert`
// to shift less elements.
s.insert(idx, num);
assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]);
```

--------------------------------

### iter_mut

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantW.html

Returns an iterator that allows modifying each value in the slice, yielding items from start to end.

```APIDOC
## iter_mut

### Description
Returns an iterator that allows modifying each value. The iterator yields all items from start to end.

### Method
`iter_mut`

### Parameters
None

### Returns
`IterMut<'_, T>` - A mutable iterator over the slice.

### Examples
```rust
let x = &mut [1, 2, 4];
for elem in x.iter_mut() {
    *elem += 2;
}
assert_eq!(x, &[3, 4, 6]);
```
```

--------------------------------

### new_with_storage

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Carolina.html

Creates a new BBQueue instance with the provided Storage implementation.

```APIDOC
## new_with_storage

### Description
Create a new `BBQueue` with the given `Storage` impl

### Method
`pub fn new_with_storage(sto: S) -> Self`
```

--------------------------------

### Synchronous BBQueue framed producer and consumer

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/lib.rs.html

Demonstrates using BBQueue with framed messages, showing how to grant, write, commit, read, and release framed data. Verifies correct data reception and checks for empty queue conditions.

```rust
use crate::traits::notifier::polling::Polling;
use core::ops::Deref;

static BBQ: BBQueue<Inline<64>, AtomicCoord, Polling> = BBQueue::new();
let prod = BBQ.framed_producer();
let cons = BBQ.framed_consumer();

let write_once = &[0x01, 0x02, 0x03, 0x04, 0x11, 0x12];
let mut wgr = prod.grant(8).unwrap();
wgr[..6].copy_from_slice(write_once);
wgr.commit(6);

let rgr = cons.read().unwrap();
assert_eq!(rgr.deref(), write_once.as_slice());
rgr.release();

assert!(cons.read().is_err());
```

--------------------------------

### get

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Returns a reference to an element or subslice based on the index type. Returns `None` if the index is out of bounds.

```APIDOC
## get<I>(&self, index: I) -> Option<&<I as SliceIndex<[T]>>::Output>

### Description
Returns a reference to an element or subslice depending on the type of index. If given a position, returns a reference to the element at that position or `None` if out of bounds. If given a range, returns the subslice corresponding to that range, or `None` if out of bounds.

### Parameters
* `index` (I): The index, which can be a position (usize) or a range (e.g., `0..2`). `I` must implement `SliceIndex<[T]>`.

### Returns
- `Some(&<I as SliceIndex<[T]>>::Output)`: A reference to the element or subslice if the index is within bounds.
- `None`: If the index is out of bounds.

### Example
```rust
let v = [10, 40, 30];
assert_eq!(Some(&40), v.get(1));
assert_eq!(Some(&[10, 40][..]), v.get(0..2));
assert_eq!(None, v.get(3));
assert_eq!(None, v.get(0..4));
```
```

--------------------------------

### as_array

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Attempts to get a reference to the underlying array if the specified size `N` matches the slice length.

```APIDOC
## pub fn as_array<const N: usize>(&self) -> Option<&[T; N]>

### Description
Gets a reference to the underlying array.
If `N` is not exactly equal to the length of `self`, then this method returns `None`.
```

--------------------------------

### BBQueue::new

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Memphis.html

Creates a new BBQueue instance in a const context, utilizing const-generics for storage.

```APIDOC
## BBQueue::new

### Description
Create a new `BBQueue` in a const context

### Method
`new`

### Parameters
None
```

--------------------------------

### LenHeader for usize Implementation

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/trait.LenHeader.html

Provides the LenHeader implementation for usize, allowing for the maximum platform available size for headers.

```rust
type Bytes = [u8; 8]
```

```rust
fn to_le_bytes(&self) -> Self::Bytes
```

```rust
fn from_le_bytes(by: Self::Bytes) -> Self
```

--------------------------------

### BBQueue::capacity

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Churrasco.html

Gets the total capacity of the buffer, indicating how much space is available in the underlying storage.

```APIDOC
## BBQueue::capacity

### Description
Get the total capacity of the buffer, e.g. how much space is present in `Storage`

### Method
`capacity`

### Parameters
This method takes no parameters.

### Response
#### Success Response (usize)
- **capacity** (usize) - The total capacity of the buffer.
```

--------------------------------

### Rust Slice binary_search Example

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantR.html

Performs a binary search on a sorted slice. Returns Ok with the index if found, or Err with the insertion index if not found. Multiple matches may return any one index.

```rust
let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55];

assert_eq!(s.binary_search(&13),  Ok(9));
assert_eq!(s.binary_search(&4),   Err(7));
assert_eq!(s.binary_search(&100), Err(13));
let r = s.binary_search(&1);
assert!(match r { Ok(1..=4) => true, _ => false, });
```

--------------------------------

### Iterate Over Slice Elements

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Returns an iterator that yields immutable references to each element in the slice from start to end.

```rust
let x = &[1, 2, 4];
let mut iterator = x.iter();

assert_eq!(iterator.next(), Some(&1));
assert_eq!(iterator.next(), Some(&2));
assert_eq!(iterator.next(), Some(&4));
assert_eq!(iterator.next(), None);
```

--------------------------------

### storage

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Barbacoa.html

Provides access to the internal storage implementation details. Use with extreme caution.

```APIDOC
## storage

```rust
pub fn storage(&self) -> &S
```

### Description
Get access to the internal storage implementation details
NOTE: Although this method is safe, use of the `Storage` methods are not. You should _never_ attempt to access or modify the underlying data contained in a storage implementation while the bbqueue is live. That will IMMEDIATELY lead to undefined behavior.
As far as I am aware, the only reasonable use for this is for cases where you have a custom `Storage` implementation that has unique teardown/drop in place requirements. Treat any uses of this function with _extreme_ caution!
```

--------------------------------

### AtomicCoord::read

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/coordination/cas/struct.AtomicCoord.html

Attempts to obtain a read grant, returning the start index and length of the readable data.

```APIDOC
## AtomicCoord::read

### Description
Attempt to obtain a read grant.

### Method
`read(&self) -> Result<(usize, usize), ReadGrantError>`

### Returns
A `Result` containing a tuple of `(read_start_index, read_length)` on success, or a `ReadGrantError` on failure.
```

--------------------------------

### as_mut_array

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Attempts to get a mutable reference to the underlying array if the specified size `N` matches the slice length.

```APIDOC
## pub fn as_mut_array<const N: usize>(&mut self) -> Option<&mut [T; N]>

### Description
Gets a mutable reference to the slice’s underlying array.
If `N` is not exactly equal to the length of `self`, then this method returns `None`.
```

--------------------------------

### Create BBQueue with Storage

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Lechon.html

Constructs a new BBQueue instance initialized with the provided Storage implementation.

```rust
pub fn new_with_storage(sto: S) -> Self;
```

--------------------------------

### Local BBQueue Usage with Churrasco

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/index.html

Demonstrates local usage of the BBQueue with the 'Churrasco' nickname, which features inline storage and hardware atomic support. Use this for in-process communication where async is not required.

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

--------------------------------

### Get First Element of Slice

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Returns an `Option` containing a reference to the first element, or `None` if the slice is empty.

```rust
pub fn first(&self) -> Option<&T>
```

```rust
let v = [10, 40, 30];
assert_eq!(Some(&10), v.first());

let w: &[i32] = &[];
assert_eq!(None, w.first());
```

--------------------------------

### Get FramedConsumer for BBQueue

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/queue.rs.html

Creates a FramedConsumer for the BBQueue. Mixing stream and framed producers/consumers is not advised and can cause issues.

```rust
pub const fn framed_consumer(&self) -> FramedConsumer<&'_ Self> {
        FramedConsumer {
            bbq: self,
            pd: PhantomData,
        }
    }
```

--------------------------------

### storage

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Carolina.html

Provides access to the internal storage implementation details. Use with extreme caution, as direct manipulation of storage can lead to undefined behavior.

```APIDOC
## storage

### Description
Get access to the internal storage implementation details
NOTE: Although this method is safe, use of the `Storage` methods are not. You should _never_ attempt to access or modify the underlying data contained in a storage implementation while the bbqueue is live. That will IMMEDIATELY lead to undefined behavior.
As far as I am aware, the only reasonable use for this is for cases where you have a custom `Storage` implementation that has unique teardown/drop in place requirements. Treat any uses of this function with _extreme_ caution!

### Method
`pub fn storage(&self) -> &S`
```

--------------------------------

### Get BBQueue Capacity

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Lechon.html

Retrieves the total capacity of the buffer, indicating the total space available in the underlying Storage.

```rust
pub fn capacity(&self) -> usize;
```

--------------------------------

### Create StreamProducer

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/nicknames/type.Lechon.html

Creates a new StreamProducer for the BBQueue. Mixing stream and framed producers/consumers is not recommended as it may not work correctly.

```rust
pub fn stream_producer(&self) -> StreamProducer<Arc<BBQueue<S, C, N>>>;
```

--------------------------------

### BBQueue Configurations Table

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/nicknames.rs.html

This table summarizes the different BBQueue configurations, detailing their storage, coordination, notifier, Arc usage, nickname, and source.

```markdown
| Storage | Coordination     | Notifier | Arc?   | Nickname     | Source        |
| :---    | :---             | :---     | :---   | :---         | :---          |
| Inline  | Critical Section | Polling  | No     | Jerk         | Jamaica       |
| Inline  | Critical Section | Polling  | Yes    | Asado        | Argentina     |
| Inline  | Critical Section | Async    | No     | Memphis      | USA           |
| Inline  | Critical Section | Async    | Yes    | Carolina     | USA           |
| Inline  | Atomic           | Polling  | No     | Churrasco    | Brazil        |
| Inline  | Atomic           | Polling  | Yes    | Barbacoa     | Mexico        |
| Inline  | Atomic           | Async    | No     | Texas        | USA           |
| Inline  | Atomic           | Async    | Yes    | KansasCity   | USA           |
| Heap    | Critical Section | Polling  | No     | Braai        | South Africa  |
| Heap    | Critical Section | Polling  | Yes    | Kebab        | Türkiye       |
| Heap    | Critical Section | Async    | No     | SiuMei       | Hong Kong     |
| Heap    | Critical Section | Async    | Yes    | Satay        | SE Asia       |
| Heap    | Atomic           | Polling  | No     | YakiNiku     | Japan         |
| Heap    | Atomic           | Polling  | Yes    | GogiGui      | South Korea   |
| Heap    | Atomic           | Async    | No     | Tandoori     | India         |
| Heap    | Atomic           | Async    | Yes    | Lechon       | Philippines   |
```

--------------------------------

### Get Type ID

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/traits/coordination/cas/struct.AtomicCoord.html

Retrieves the `TypeId` of the current type. This is part of the `Any` trait implementation and is useful for runtime type identification.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Partial Sort Unstable Slice Example

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Demonstrates various use cases of `partial_sort_unstable` on a slice, including empty ranges, single-element ranges, subranges, and the entire slice. Requires the `slice_partial_sort_unstable` feature.

```rust
#![feature(slice_partial_sort_unstable)]

let mut v = [4, -5, 1, -3, 2];

// empty range at the beginning, nothing changed
v.partial_sort_unstable(0..0);
assert_eq!(v, [4, -5, 1, -3, 2]);

// empty range in the middle, partitioning the slice
v.partial_sort_unstable(2..2);
for i in 0..2 {
   assert!(v[i] <= v[2]);
}
for i in 3..v.len() {
  assert!(v[2] <= v[i]);
}

// single element range, same as select_nth_unstable
v.partial_sort_unstable(2..3);
for i in 0..2 {
   assert!(v[i] <= v[2]);
}
for i in 3..v.len() {
  assert!(v[2] <= v[i]);
}

// partial sort a subrange
v.partial_sort_unstable(1..4);
assert_eq!(&v[1..4], [-3, 1, 2]);

// partial sort the whole range, same as sort_unstable
v.partial_sort_unstable(..);
assert_eq!(v, [-5, -3, 1, 2, 4]);

```

--------------------------------

### Rust Slice is_sorted_by Example

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Checks if a slice is sorted using a custom comparison function. The comparator determines the order.

```rust
assert!([1, 2, 2, 9].is_sorted_by(|a, b| a <= b));
assert!(![1, 2, 2, 9].is_sorted_by(|a, b| a < b));

assert!([0].is_sorted_by(|a, b| true));
assert!([0].is_sorted_by(|a, b| false));

let empty: [i32; 0] = [];
assert!(empty.is_sorted_by(|a, b| false));
assert!(empty.is_sorted_by(|a, b| true));

```

--------------------------------

### as_simd

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Splits a slice into a prefix, a middle of aligned SIMD types, and a suffix. This is a safe wrapper around `slice::align_to`. This is a nightly-only experimental API.

```APIDOC
## pub fn as_simd<const LANES: usize>(&self) -> (&[T], &[Simd<T, LANES>], &[T])

### Description
Splits a slice into a prefix, a middle of aligned SIMD types, and a suffix.
This is a safe wrapper around `slice::align_to`, so inherits the same guarantees as that method.
This is a nightly-only experimental API. (`portable_simd`)

### Panics
This will panic if the size of the SIMD type is different from `LANES` times that of the scalar.
At the time of writing, the trait restrictions on `Simd<T, LANES>` keeps that from ever happening, as only power-of-two numbers of lanes are supported. It’s possible that, in the future, those restrictions might be lifted in a way that would make it possible to see panics from this method for something like `LANES == 3`.
```

--------------------------------

### as_array

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/struct.FramedGrantW.html

Gets a reference to the underlying array if the specified size `N` exactly matches the length of the slice. Returns `None` otherwise.

```APIDOC
## as_array<const N: usize>

### Description
Gets a reference to the underlying array. If `N` is not exactly equal to the length of `self`, then this method returns `None`.

### Method
`as_array<const N: usize>`

### Parameters
* `N` (usize) - The expected size of the array.

### Returns
`Option<&[T; N]>` - A reference to the underlying array if the size matches, otherwise `None`.
```

--------------------------------

### Get Mutable Reference to First Element

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/stream/struct.StreamGrantR.html

Returns an `Option` containing a mutable reference to the first element, or `None` if the slice is empty.

```rust
pub fn first_mut(&mut self) -> Option<&mut T>
```

```rust
let x = &mut [0, 1, 2];

if let Some(first) = x.first_mut() {
    *first = 5;
}
assert_eq!(x, &[5, 1, 2]);

let y: &mut [i32] = &mut [];
assert_eq!(None, y.first_mut());
```

--------------------------------

### LenHeader for u16 Implementation

Source: https://docs.rs/bbqueue/0.7.0/bbqueue/prod_cons/framed/trait.LenHeader.html

Provides the LenHeader implementation for u16, suitable for headers requiring two bytes and limiting grants to 64KiB.

```rust
type Bytes = [u8; 2]
```

```rust
fn to_le_bytes(&self) -> Self::Bytes
```

```rust
fn from_le_bytes(by: Self::Bytes) -> Self
```

--------------------------------

### Get FramedProducer for ArcBBQueue

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/queue.rs.html

Creates a FramedProducer for an ArcBBQueue. Mixing stream and framed producers/consumers is not recommended and may lead to incorrect behavior.

```rust
pub fn framed_producer(&self) -> FramedProducer<alloc::sync::Arc<BBQueue<S, C, N>>> {
        FramedProducer {
            bbq: self.0.bbq_ref(),
            pd: PhantomData,
        }
    }
```

--------------------------------

### Asynchronous BBQueue framed producer and consumer with Tokio

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/lib.rs.html

Shows asynchronous, framed message passing with BBQueue using Tokio. This example utilizes `framed_producer`, `framed_consumer`, and `wait_read` for non-blocking operations.

```rust
use crate::traits::notifier::polling::Polling;
use core::ops::Deref;

static BBQ: BBQueue<Inline<64>, AtomicCoord, MaiNotSpsc> = BBQueue::new();
let prod = BBQ.framed_producer();
let cons = BBQ.framed_consumer();

let rxfut = tokio::task::spawn(async move {
    let rgr = cons.wait_read().await;
    assert_eq!(rgr.deref(), &[1, 2, 3]);
});

let txfut = tokio::task::spawn(async move {
    tokio::time::sleep(Duration::from_millis(500)).await;
    let mut wgr = prod.grant(3).unwrap();
    wgr.copy_from_slice(&[1, 2, 3]);
    wgr.commit(3);
});

// todo: timeouts
rxfut.await.unwrap();
txfut.await.unwrap();
```

--------------------------------

### Get total buffer capacity

Source: https://docs.rs/bbqueue/0.7.0/src/bbqueue/prod_cons/framed.rs.html

Retrieves the total capacity of the underlying storage buffer. This indicates the maximum amount of data that can be held.

```rust
pub fn capacity(&self) -> usize {
    self.bbq.capacity()
}
```