update original

Author: funkill

rust-cookbook/.github/workflows/spellcheck.yml

@@ -0,0 +1,31 @@
+name: Spellcheck
+
+on:
+  pull_request:
+    branches:
+      - master
+  workflow_dispatch:
+
+jobs:
+  spellcheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Install aspell
+        run: sudo apt-get update && sudo apt-get install -y aspell aspell-en
+
+      - name: Run spellcheck
+        id: spellcheck
+        run: ./ci/spellcheck.sh list
+
+      - name: Spellcheck Results
+        if: always()
+        run: |
+          if [ "${{ steps.spellcheck.outcome }}" == "success" ]; then
+            echo "✅ Spellcheck passed!"
+          else
+            echo "❌ Spellcheck found unknown words. Add valid words to ci/dictionary.txt."
+            exit 1
+          fi

rust-cookbook/ci/dictionary.txt

@@ -349,3 +349,19 @@ zurich
 enum
 thiserror
 tempfile
+alloc
+handleactormessage
+heapless
+Heapless
+LazyCell
+lazycell
+LazyLock
+lazylock
+oncecell
+stdcell
+stdcelllazycell
+stdsynclazylock
+tokio
+Tokio
+Waker
+waker

rust-cookbook/crates/concurrency/actor/Cargo.toml

@@ -7,4 +7,5 @@ license.workspace = true
 publish.workspace = true
 
 [dependencies]
+thiserror = "2"
 tokio = { version = "1", features = ["full"] }

rust-cookbook/crates/concurrency/actor/src/bin/actor_pattern.rs

@@ -1,5 +1,16 @@
+use thiserror::Error;
 use tokio::sync::{mpsc, oneshot};
 
+#[derive(Debug, Error)]
+enum ActorError {
+    #[error("failed to send message to actor")]
+    Send(#[from] mpsc::error::SendError<Message>),
+    #[error("actor dropped response channel")]
+    Recv(#[from] oneshot::error::RecvError),
+    #[error("task failed")]
+    Join(#[from] tokio::task::JoinError),
+}
+
 // The Message enum represents commands sent to the actor.
 enum Message {
     UpdateLocation {
@@ -94,7 +105,7 @@ impl DriverHandle {
         driver_id: u32,
         lat: f64,
         lng: f64,
-    ) -> Result<(), Box<dyn std::error::Error>> {
+    ) -> Result<(), ActorError> {
         self.sender
             .send(Message::UpdateLocation {
                 driver_id,
@@ -108,7 +119,7 @@ impl DriverHandle {
     async fn get_driver_status(
         &self,
         driver_id: u32,
-    ) -> Result<Option<DriverStatus>, Box<dyn std::error::Error>> {
+    ) -> Result<Option<DriverStatus>, ActorError> {
         let (tx, rx) = oneshot::channel();
         self.sender
             .send(Message::GetDriverStatus {
@@ -121,33 +132,37 @@ impl DriverHandle {
 }
 
 #[tokio::main]
-async fn main() -> Result<(), Box<dyn std::error::Error>> {
+async fn main() -> Result<(), ActorError> {
     let handle = DriverHandle::new();
 
     // Multiple clones can be sent to different tasks.
     let h1 = handle.clone();
     let h2 = handle.clone();
 
     let task1 = tokio::spawn(async move {
-        h1.update_location(1, 40.7128, -74.0060).await.unwrap();
-        h1.update_location(1, 40.7130, -74.0062).await.unwrap();
+        h1.update_location(1, 40.7128, -74.0060).await?;
+        h1.update_location(1, 40.7130, -74.0062).await?;
+        Ok::<(), ActorError>(())
     });
 
     let task2 = tokio::spawn(async move {
-        h2.update_location(2, 34.0522, -118.2437).await.unwrap();
+        h2.update_location(2, 34.0522, -118.2437).await?;
+        Ok::<(), ActorError>(())
     });
 
-    task1.await?;
-    task2.await?;
+    task1.await??;
+    task2.await??;
 
-    let status = handle.get_driver_status(1).await?;
-    println!("Driver 1: {:?}", status);
+    if let Some(s) = handle.get_driver_status(1).await? {
+        println!("Driver {}: ({}, {}), updates: {}", s.driver_id, s.lat, s.lng, s.update_count);
+    }
 
-    let status = handle.get_driver_status(2).await?;
-    println!("Driver 2: {:?}", status);
+    if let Some(s) = handle.get_driver_status(2).await? {
+        println!("Driver {}: ({}, {}), updates: {}", s.driver_id, s.lat, s.lng, s.update_count);
+    }
 
-    let status = handle.get_driver_status(99).await?;
-    println!("Driver 99: {:?}", status);
+    let missing = handle.get_driver_status(99).await?;
+    println!("Driver 99: {:?}", missing);
 
     Ok(())
 }

rust-cookbook/crates/safety_critical/heapless_alloc/Cargo.toml

@@ -8,3 +8,4 @@ publish.workspace = true
 
 [dependencies]
 heapless = "0.8"
+thiserror = "2"

rust-cookbook/crates/safety_critical/heapless_alloc/src/bin/heapless_alloc.rs

@@ -1,4 +1,15 @@
 use heapless::{String, Vec};
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+enum LogError {
+    #[error("log full (capacity exceeded)")]
+    Full,
+    #[error("log is empty")]
+    Empty,
+    #[error(transparent)]
+    Fmt(#[from] core::fmt::Error),
+}
 
 /// A fixed-capacity event log that never touches the heap.
 ///
@@ -29,9 +40,9 @@ impl<const N: usize> EventLog<N> {
 
     /// Records an event.  Returns `Err` if the log is full instead
     /// of panicking or allocating—the caller decides what to do.
-    fn record(&mut self, timestamp_ms: u32, code: u16) -> Result<(), Event> {
+    fn record(&mut self, timestamp_ms: u32, code: u16) -> Result<(), LogError> {
         let event = Event { timestamp_ms, code };
-        self.entries.push(event).map_err(|e| e)
+        self.entries.push(event).map_err(|_| LogError::Full)
     }
 
     /// Returns how many events have been recorded.
@@ -40,8 +51,8 @@ impl<const N: usize> EventLog<N> {
     }
 
     /// Returns the most recent event, if any.
-    fn latest(&self) -> Option<&Event> {
-        self.entries.last()
+    fn latest(&self) -> Result<&Event, LogError> {
+        self.entries.last().ok_or(LogError::Empty)
     }
 }
 
@@ -50,35 +61,40 @@ impl<const N: usize> EventLog<N> {
 /// [`heapless::String<N>`] works like `std::string::String` but
 /// stores up to `N` bytes on the stack.  `write!` returns `Err` if
 /// the formatted text would exceed capacity.
-fn format_label(sensor_id: u16, value: f32) -> Result<String<32>, core::fmt::Error> {
+fn format_label(sensor_id: u16, value: f32) -> Result<String<32>, LogError> {
     use core::fmt::Write;
     let mut buf: String<32> = String::new();
     write!(buf, "S{sensor_id}={value:.1}")?;
     Ok(buf)
 }
 
-fn main() {
+fn main() -> Result<(), LogError> {
     // A log that holds at most 8 events — zero heap allocation.
     let mut log: EventLog<8> = EventLog::new();
 
-    log.record(100, 0x01).expect("log not full");
-    log.record(200, 0x02).expect("log not full");
-    log.record(300, 0xFF).expect("log not full");
+    log.record(100, 0x01)?;
+    log.record(200, 0x02)?;
+    log.record(300, 0xFF)?;
 
     println!("logged {} events", log.len());
-    println!("latest: {:?}", log.latest().unwrap());
+    let latest = log.latest()?;
+    println!(
+        "latest: timestamp={}ms code=0x{:02X}",
+        latest.timestamp_ms, latest.code
+    );
 
     // Stack-allocated string formatting.
-    let label = format_label(42, 3.14).expect("fits in 32 bytes");
+    let label = format_label(42, 3.14)?;
     println!("label: {label}");
 
     // Demonstrate capacity enforcement — the 9th push returns Err.
     let mut full_log: EventLog<2> = EventLog::new();
-    full_log.record(0, 1).unwrap();
-    full_log.record(1, 2).unwrap();
-    let overflow = full_log.record(2, 3);
-    assert!(overflow.is_err());
+    full_log.record(0, 1)?;
+    full_log.record(1, 2)?;
+    assert!(full_log.record(2, 3).is_err());
     println!("overflow correctly rejected");
+
+    Ok(())
 }
 
 #[cfg(test)]

rust-cookbook/src/concurrency/actor/actor-pattern.md

@@ -12,7 +12,7 @@ Because only one task ever accesses the data, there is no locking. Request–res
 pairs use a [`oneshot`] channel embedded in the message variant.
 
 ```rust,edition2021
-{{#include ../../../crates/concurrency/actor/src/bin/actor_pattern.rs::153 }}
+{{#include ../../../crates/concurrency/actor/src/bin/actor_pattern.rs::168 }}
 ```
 
 [Alice Ryhl]: https://ryhl.io/blog/actors-with-tokio/

rust-cookbook/src/concurrency/custom_future/custom-future.md

@@ -8,12 +8,16 @@ instead of relying on `async`/`await`.
 
 Every custom future must handle three concepts:
 
+<div class="comparison">
+
 | Concept | Why it matters |
 |---------|----------------|
 | **[`Pin<&mut Self>`]** | Guarantees the future won't move in memory after the first poll. This is critical for self-referential futures (e.g., those holding borrows across `.await` points). If your struct contains only ordinary fields (no self-references), the compiler auto-implements `Unpin` and pinning is effectively a no-op. |
 | **[`Poll::Pending`] / [`Poll::Ready`]** | `Pending` tells the executor "not done yet," while `Ready(value)` completes the future. |
 | **[`cx.waker()`]** | A handle the executor gives you. You *must* call `wake()` at some point after returning `Pending`, or the executor will never poll the future again and it will hang. |
 
+</div>
+
 The example below builds a simple `Delay` future that resolves after a
 deadline.  It has no self-referential fields, so it is `Unpin` automatically—
 pinning costs nothing.  A production timer would register with a reactor;

rust-cookbook/src/safety_critical/heapless_alloc/heapless-alloc.md

@@ -11,19 +11,23 @@ on the **stack** (or in a `static`) with a capacity fixed at compile time.
 Pushing beyond capacity returns `Err` instead of panicking or allocating,
 letting the caller decide how to handle it.
 
+<div class="comparison">
+
 | `std` type | `heapless` equivalent | Guarantee |
 |---|---|---|
 | `Vec<T>` | `heapless::Vec<T, N>` | At most `N` elements, no allocator |
 | `String` | `heapless::String<N>` | At most `N` bytes, no allocator |
 | `VecDeque<T>` | `heapless::Deque<T, N>` | Fixed-capacity ring buffer |
 | `HashMap<K,V>` | `heapless::IndexMap<K,V,S,N>` | Fixed-capacity hash map |
 
+</div>
+
 The example below builds a stack-allocated event log and demonstrates
 capacity enforcement—the kind of predictable, constant-memory behavior
 required by embedded and real-time systems.
 
 ```rust
-{{#include ../../../crates/safety_critical/heapless_alloc/src/bin/heapless_alloc.rs::83}}
+{{#include ../../../crates/safety_critical/heapless_alloc/src/bin/heapless_alloc.rs::98}}
 ```
 
 [`heapless`]: https://docs.rs/heapless

rust-cookbook/src/safety_critical/no_panic/no-panic.md

@@ -10,13 +10,17 @@ The [`#[no_panic]`][no-panic] attribute macro makes the **compiler prove** at
 link time that a function can never reach a panicking code path.  If it can't
 prove it, the build fails.
 
+<div class="comparison">
+
 | Panicking pattern | Safe alternative |
 |-------------------|-----------------|
 | `slice[i]` | `slice.get(i)` with exhaustive `match` |
 | `for i in 0..len { slice[i] }` | `for &v in slice` (iterator) |
 | `value.unwrap()` | `match` / `if let` / `?` |
 | `a / b` (integer, `b` might be 0) | Check `b` before dividing |
 
+</div>
+
 The example below shows three panic-free functions—aggregation, lookup, and
 sensor normalization—each proven at compile time by `#[no_panic]`.