Lots of docs, API cleanup (#4)

This adds:

* Accessor functions on the handle to get producer/consumers, which is useful for preserving the `BbqHandle` generic when you're holding a handle
* Adds a ton of docs
* Adds real error types for grants
* Adds CI

This is going to be the 0.3 release very shortly.

Author: jamesmunns

.github/workflows/build.yml

@@ -0,0 +1,42 @@
+name: Build and Test
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  miri:
+    name: "Build all crates"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install embedded target
+        # Note: once https://github.com/hawkw/mycelium/pull/538 lands we can test on
+        # thumbv6m-none-eabi
+        run: rustup target add thumbv7em-none-eabi
+      #
+      # BUILD + TEST
+      #
+      # no features, on std
+      - name: Check bbq2 (no features, on host)
+        run: cargo build --no-default-features
+      # default features, on std
+      - name: Check bbq2 (default features, on host)
+        run: cargo build
+      # std features, on std
+      - name: Check bbq2 (std features, on host)
+        run: cargo build --features=std
+      # std features, on std, test
+      - name: Test bbq2 (std features, on host)
+        run: cargo test --features=std
+
+      # no features, on mcu
+      - name: Check bbq2 (no features, on mcu)
+        run: cargo build --no-default-features --target=thumbv7em-none-eabi
+      # default features, on mcu
+      - name: Check bbq2 (no features, on mcu)
+        run: cargo build --target=thumbv7em-none-eabi
+

.github/workflows/miri.yml

@@ -0,0 +1,22 @@
+name: Run miri tests
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+  workflow_dispatch:
+
+jobs:
+  miri:
+    name: "miri all the things"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install miri component
+        run: rustup component add --toolchain nightly-x86_64-unknown-linux-gnu miri
+      #
+      # crate
+      #
+      - name: Miri test bbq2
+        run: ./miri.sh

Cargo.lock

@@ -15,6 +15,7 @@ categories = [
 license = "MIT OR Apache-2.0"
 
 [dependencies]
+const-init = "1.0.0"
 
 [dependencies.maitake-sync]
 version = "0.2"
@@ -33,19 +34,18 @@ features = ["macros", "rt", "time"]
 [features]
 default = [
     "cas-atomics",
-    "std",
     "maitake-sync-0_2",
     "critical-section",
-    # "tokio-sync",
 ]
+
 cas-atomics = []
 critical-section = [
     "dep:critical-section",
 ]
+disable-cache-padding = [
+    "maitake-sync?/no-cache-pad",
+]
 std = []
-# tokio-sync = [
-#     "dep:tokio",
-# ]
 maitake-sync-0_2 = [
     "dep:maitake-sync",
 ]

Cargo.toml

@@ -0,0 +1,10 @@
+#!/bin/bash
+
+# We disable isolation because we use tokio sleep
+# We disable leaks because ???
+#
+# TODO: Can we eliminate some of these limitations for testing?
+MIRIFLAGS="-Zmiri-disable-isolation -Zmiri-ignore-leaks" \
+    cargo +nightly miri test \
+    --target x86_64-unknown-linux-gnu \
+    --features=std

miri.sh

@@ -1,12 +1,32 @@
-#![allow(clippy::result_unit_err)]
+//! bbq2
+//!
+//! A new and improved bipbuffer queue.
+
 #![cfg_attr(not(any(test, feature = "std")), no_std)]
 
+/// Type aliases for different generic configurations
+///
 pub mod nicknames;
+
+/// Producer and consumer interfaces
+///
 pub mod prod_cons;
+
+/// Queue storage
+///
 pub mod queue;
+
+/// Generic traits
+///
 pub mod traits;
 
-#[cfg(test)]
+/// Re-export of external types/traits
+///
+pub mod export {
+    pub use const_init::ConstInit;
+}
+
+#[cfg(all(test, feature = "std"))]
 mod test {
     use core::{ops::Deref, time::Duration};
 
@@ -212,5 +232,7 @@ mod test {
         // todo: timeouts
         rxfut.await.unwrap();
         txfut.await.unwrap();
+
+        drop(bbq);
     }
 }

src/lib.rs

@@ -19,6 +19,8 @@
 //! | Heap    | Atomic           | Async    | No     | Tandoori     | India         |
 //! | Heap    | Atomic           | Async    | Yes    | Lechon       | Philippines   |
 
+#![allow(unused_imports)]
+
 #[cfg(feature = "std")]
 use crate::queue::ArcBBQueue;
 #[cfg(feature = "cas-atomics")]