Rust — Beyond the Basics

The mental models, decisions, and hard-won details that separate working Rust from idiomatic Rust

Read this after Vol. 07. That book teaches the syntax: what a Vec is, how match works, what ? does. This one teaches the judgement — which of six ways to hold data to reach for, when a clone is honest versus lazy, why the borrow checker is fighting you, and which crates will still be here in 2030.

Every code block in this book was compiled and run against rustc 1.98.1. Every crate version and download number was read from the crates.io API on October 2026. Nothing here is from memory.

🔗How to Read This Book

The chapters are ordered roughly by how much they change how you write code. If you only read six, read these:

🔗The Core Mental Model

Most Rust confusion comes from one misreading. Rust does not manage memory. It manages ownership, and memory follows from that.

Three consequences generate nearly every rule in the language:

Everything else — lifetimes, traits, generics, Send/Sync, the ? operator — is a consequence of these three. When a rule surprises you, ask which of the three it protects.

Rust is not about performance. It is about making illegal states unrepresentable, and performance falls out of that. Code that is correct-by-construction usually needs no unsafe, no caching, and no premature optimization.

🔗Data Structure Selection

This is the chapter that most changes how your code looks. Rust gives you six ways to hold data, and choosing wrong is the root of most "the borrow checker hates me" situations.

🔗The Selection Table

🔗Struct vs Enum: The Actual Rule

The question is not "how many fields" but "how many valid shapes does this thing have?"

 1    // ONE shape → struct
 2    struct Point { x: f64, y: f64 }
 3
 4    // MANY shapes, each carrying different data → enum
 5    enum Shape {
 6        Circle { radius: f64 },
 7        Rect { w: f64, h: f64 },
 8        Empty,              // a variant with no data is legal and meaningful
 9    }

The enum version is strictly better because the compiler forces you to handle Empty. A struct with an Option for each field produces states like "circle with a width of 3.0" that your domain forbids.

Reach for Option before reaching for the new struct. Only introduce a new type when you genuinely need two or more variants with different payloads.

🔗Struct Update Syntax and ..Default

..Default::default() is the cleanest way to have optional fields. Combine it with #[derive(Default)] and you never write a manual constructor again:

 1    #[derive(Debug, Clone, Default, PartialEq)]
 2    struct ServerConfig {
 3        host: String,          // "" — caller almost always sets this
 4        port: u16,             // 0 — invalid, must be set
 5        tls: bool,             // false — sane default
 6        timeout_secs: Option<u64>,
 7    }
 8
 9    impl ServerConfig {
10        // Named constructor for the common case
11        fn dev() -> Self {
12            Self { host: "localhost".into(), port: 8080, tls: false, ..Default::default() }
13        }
14    }
15
16    // Patch a single field, keep the rest — the real workhorse
17    let prod = ServerConfig { tls: true, ..ServerConfig::dev() };
18    assert!(prod.tls && prod.port == 8080);

Warning: struct update syntax moves non-Copy fields out of the base value. ..cfg consumes cfg. If you need the base afterwards, derive Clone or operate on a reference.

🔗The Newtype: Zero-Cost Type Safety

A newtype is a one-field tuple struct. It costs zero bytes and zero runtime — the compiler optimizes it to the inner representation — while making illegal programs uncompilable.

 1    // `type` aliases are NOT types — this compiles but buys nothing:
 2    type UserId = u64;
 3    fn f(a: UserId, b: UserId) {}  // you can now pass any u64. Useless.
 4
 5    // A newtype IS a real, distinct type:
 6    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
 7    struct UserId(u64);
 8
 9    #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
10    struct OrderId(u64);
11
12    fn process(user: UserId, order: OrderId) { /* ... */ }
13
14    // process(5, 6);   // COMPILE ERROR: expected UserId, found OrderId
15    // process(OrderId(5), UserId(6));  // COMPILE ERROR: arguments swapped

Newtypes are the single best answer to "the compiler can't help me here." They cost nothing and they eliminate whole classes of bugs. Pair one with TryFrom for parsing:

 1    use std::num::ParseIntError;
 2
 3    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
 4    struct UserId(u64);
 5
 6    impl std::str::FromStr for UserId {
 7        type Err = ParseIntError;
 8        fn from_str(s: &str) -> Result<Self, Self::Err> {
 9            s.parse::<u64>().map(UserId)   // maps u64 -> UserId
10        }
11    }
12
13    fn lookup(raw: &str) -> Result<UserId, ParseIntError> {
14        raw.parse()   // returns UserId, no map needed
15    }

Real uses: domain identifiers (UserId vs OrderId), units (Meters vs Feet), validated strings (Email that can only be constructed post-validation), and phantom type parameters that make a unit visible in the signature.

 1    #[derive(Debug, Clone, Copy)]
 2    struct Meters(f64);
 3
 4    impl Meters {
 5        fn to_feet(self) -> Feet { Feet(self.0 * 3.28084) }
 6    }
 7
 8    #[derive(Debug, Clone, Copy)]
 9    struct Feet(f64);
10
11    // Now this is impossible: you cannot pass Feet where Meters is expected.
12    fn draw(d: Meters) { /* ... */ }

🔗Typestate: Encoding Valid Order in the Type System

Instead of a runtime Option/Result, make each state a distinct type. Then the compiler rejects out-of-order calls entirely.

 1    use std::marker::PhantomData;
 2
 3    struct Tcp;           // raw socket
 4    struct Handshaked;    // TLS negotiated
 5    struct Authed;        // credentials accepted
 6
 7    struct Conn<S> {
 8        inner: Tcp,              // the payload stays one type
 9        _state: PhantomData<S>,  // the type param is the state marker
10    }
11
12    impl Tcp {
13        fn connect(self) -> Conn<Tcp> {
14            Conn { inner: self, _state: PhantomData }
15        }
16    }
17
18    // Each method is only available in the right state — note `self` is consumed
19    // and a new, differently-typed value is returned.
20    impl Conn<Tcp> {
21        fn handshake(self) -> Conn<Handshaked> {
22            Conn { inner: self.inner, _state: PhantomData }
23        }
24    }
25
26    impl Conn<Handshaked> {
27        fn auth(self) -> Conn<Authed> {
28            Conn { inner: self.inner, _state: PhantomData }
29        }
30    }
31
32    // This method exists ONLY on Conn<Authed>.
33    impl Conn<Authed> {
34        fn query(&self, _sql: &str) -> &'static str { "rows" }
35    }
36
37    // Correct order: compiles.
38    let conn = Tcp.connect().handshake().auth();
39    assert_eq!(conn.query("SELECT 1"), "rows");
40
41    // conn.query("...") on a fresh Conn<Tcp> does not exist. The compiler stops you.

The PhantomData gotcha that costs everyone an hour: the type parameter S and the field inner must be different types. If you write struct Conn<S> { inner: S } and try to transition Conn<Tcp> -> Conn<Handshaked>, you hit expected Handshaked, found Tcp — because you're trying to store a Tcp in a field that must hold a Handshaked. Decouple them: store the real payload in a concrete field and use PhantomData<S> purely as the state tag. This compiles cleanly, as shown above.

Typestate is genuinely worth it for protocol clients, parsers, and anything with a "must do X before Y" rule. Do not use it for simple "optional value" — that's what Option is for.

🔗HashMap vs BTreeMap vs IndexMap

Rule of thumb: default to HashMap. Switch to BTreeMap when you need sorted output or range queries. Use IndexMap when the order is semantically meaningful (e.g. preserving a config file's order, rendering a UI list) and you still want O(1) lookup.

HashMap has no stable iteration order and does not guarantee it between runs. Never rely on it. If you need determinism, collect and sort, or use BTreeMap.

The entry API is the idiomatic way to avoid the "check then insert" double-lookup:

 1    use std::collections::HashMap;
 2
 3    let mut scores: HashMap<String, Vec<i32>> = HashMap::new();
 4    scores.entry("ana".into()).or_default().push(10);
 5    scores.entry("ana".into()).or_default().push(20);
 6    // entry().or_insert(v)  -> insert v only if vacant
 7    // entry().or_insert_with(|| expensive())  -> lazy, only runs if vacant
 8    // entry().or_default() -> for Vec/HashMap/String/Box (implements Default)
 9    assert_eq!(scores["ana"], vec![10, 20]);

🔗Vec vs Array vs Slice

These three differ only in ownership and location, which makes the choice mechanical once you see it:

1    let arr: [i32; 3] = [1, 2, 3];   // fixed size, inline on the stack, Copy if i32
2    let vec: Vec<i32> = vec![1, 2, 3]; // growable, heap buffer + (ptr, len, cap)
3    let sl: &[i32] = &arr;           // borrowed view, fat pointer (ptr + len), no copy
4    let sl2: &[i32] = &vec;          // borrows the Vec, no copy
5
6    assert_eq!(sl.len(), 3);          // slices know their length at runtime
7    // arr.len() is a compile-time constant; arrays are length-checked by the type system

When each one:

• Array [T; N] — the count is known at compile time and small. [u8; 32] for a hash, [i32; 3] for a vertex. No allocation.
• Vec<T> — the default. Growable, heap-allocated, three-word size (ptr, len, cap).
• Slice &[T] — you have data someone else owns and you only want to read or transform it. The single most under-used type in beginner Rust because people pass &Vec<T> out of habit.

Never write &Vec<T>. Write &[T]. A &Vec<T> is a pointer to a specific growable buffer and it leaks the implementation detail into your API, preventing callers from passing arrays, slices from other sources, or sub-ranges. &[T] accepts all of those.

&mut Vec<T> is a different story — there you sometimes do want &mut Vec<T> specifically, because push is not on slices. Use &mut [T] when you only need to mutate existing elements.

🔗Ownership: The Parts That Surprise

The basics are in Vol. 07. These are the details that bite.

🔗Partial Moves

You can move out of a struct field without moving the whole struct — and you can still use the parts you didn't move.

1    struct User { name: String, age: u32 }
2
3    let u = User { name: "ana".to_string(), age: 30 };
4
5    let name = u.name;       // partial move: String moved out
6    // println!("{}", u.name);  // ERROR: u.name was moved
7    println!("{}", u.age);      // FINE: u.age is u32 (Copy), untouched

But the whole struct is not usable as a value after a partial move, because the compiler no longer knows it's fully initialized:

1    let u2 = User { name: "bob".to_string(), age: 25 };
2    let n2 = u2.name;
3    // let u3 = u2;               // ERROR: u2 partially moved
4    // u2.age = 40;               // ERROR: cannot assign to u2, it's partially moved

Partial move out of a collection works the same way, and it's how you drain without clone:

1    let v = vec![String::from("a"), String::from("b")];
2    // `into_iter()` moves every String out — no clones, zero allocation.
3    let owned: Vec<String> = v.into_iter().collect();
4    // Or, to keep the Vec and take one item:
5    let mut v2 = vec![String::from("x"), String::from("y")];
6    let first = v2.remove(0);      // moves the String out, shifts the rest
7    assert_eq!(first, "x");

🔗Drop Order: Reverse Declaration

Rust drops values in reverse declaration order, and struct fields drop in declaration order. This matters when values depend on each other.

 1    struct Guard(&'static str);
 2    impl Drop for Guard {
 3        fn drop(&mut self) { println!("drop {}", self.0); }
 4    }
 5
 6    {
 7        let _a = Guard("a");
 8        let _b = Guard("b");
 9        let _c = Guard("c");
10        // Dropped in reverse: c, then b, then a
11    }

Why reverse? Because a later-declared value often depends on an earlier one (a guard that must drop before the lock it holds). Reverse order makes that the safe default.

Manually controlling order with std::mem::drop when you need an early release:

 1    let lock = std::sync::Mutex::new(0);
 2    {
 3        let _guard = lock.lock().unwrap();
 4        // ... critical section ...
 5    }   // guard released here
 6
 7    // Equivalent, when you need to release mid-scope:
 8    let big = vec![0u8; 1024];
 9    drop(big);              // free memory NOW, before allocating more
10    let other = vec![0u8; 1024];

RAII is the whole point. A MutexGuard releases the lock on drop. A file handle closes on drop. A database transaction commits or rolls back on drop. You almost never write explicit cleanup code in Rust — you attach cleanup to a value's lifetime.

🔗Copy Is Not "Cheap"

Copy means "bitwise copy and the original stays usable." It requires all fields to be Copy. It is not about performance and it is not a marker of "simple type."

 1    // Derived Copy works automatically for plain data:
 2    #[derive(Clone, Copy, Debug, PartialEq)]
 3    struct Point { x: f64, y: f64 }
 4
 5    let a = Point { x: 1.0, y: 2.0 };
 6    let b = a;            // copied, `a` still usable
 7    let c = a;            // copied again
 8    assert_eq!(a, b);
 9
10    // Arrays of Copy types are Copy up to length 32 (historically). Modern Rust:
11    let arr = [1u8; 64];
12    let arr2 = arr;       // copies the whole array (64 bytes)

What is Copy: integers, floats, bool, char, raw pointers, shared references &T, and tuples/arrays of those.

What is not Copy: String, Vec, Box, Rc, Arc, anything with a Drop impl, and &mut T.

Do not derive Copy on a struct that contains a String, Vec, or a Drop type — the compiler will refuse, and rightly so.

🔗Clone vs Deep Copy

clone() is not necessarily a deep copy. It calls your type's Clone impl, which you control.

 1    // Clone for Rc is a refcount bump, NOT a deep copy:
 2    let data = Rc::new(vec![1, 2, 3]);
 3    let copy = data.clone();
 4    assert_eq!(Rc::strong_count(&data), 2);
 5    // Both point to ONE heap allocation.
 6
 7    // For plain owned data, Clone is a real deep copy:
 8    let v = vec![1, 2, 3];
 9    let w = v.clone();    // new allocation
10    assert_eq!(v, w);

This matters for the "when to clone" question: cloning a handle (Rc, Arc, &-backed smart pointer) is cheap and often correct. Cloning a Vec<String> of a thousand strings is expensive, and usually a design smell — see below.

🔗Clone, Copy, and When to Stop Fighting

Cloning has a reputation as "giving up on the borrow checker." That is wrong, but the nuance is real. Here is the decision framework.

🔗The Four Legitimate Uses

1. Escaping a borrow — usually correct, usually cheap.

 1    // You need to store data beyond the lifetime of a borrow you were handed.
 2    fn parse(input: &str) -> Vec<u32> {
 3        input.split(',').map(|s| s.parse().unwrap()).collect()
 4    }   // `input` is borrowed; the Vec<u32> is owned. No clone needed here —
 5        // because parse() produces owned numbers.
 6
 7    // When you DO need a clone: transforming borrowed data into owned storage.
 8    fn normalize(s: &str) -> String {
 9        s.trim().to_lowercase()   // to_lowercase() returns a NEW String, not a clone
10    }

2. Keeping the API ergonomic for the caller.

 1    struct Server { name: String }
 2
 3    impl Server {
 4        // Accept &self but return owned, so the caller can keep the result
 5        // around without fighting the borrow checker. Cost: one small alloc.
 6        fn name(&self) -> String { self.name.clone() }
 7
 8        // Better when the caller doesn't need ownership:
 9        fn name_ref(&self) -> &str { &self.name }
10    }

Rule of thumb: a String clone is a single heap allocation of a small buffer. For anything but the hottest inner loop, it is free and the ergonomic win is large. Do not contort your API to avoid a small String clone.

3. Small, cheap, and the borrow would otherwise be awkward.

1    #[derive(Clone, Copy)]
2    struct Point { x: f64, y: f64 }
3
4    let p = Point { x: 1.0, y: 2.0 };
5    let snapshot = p;    // Copy — no heap, no clone needed
6    use_it(p);
7    use_it(snapshot);    // still works

4. Thread/task boundaries require ownership.

1    // `thread::spawn` requires `'static`, so anything borrowed can't go in.
2    let data = vec![1, 2, 3];
3    let handle = std::thread::spawn({
4        let data = data.clone();       // clone here is CORRECT — the thread
5        move || data.iter().sum::<i32>()   // needs owned data
6    });
7    let _ = handle.join().unwrap();

🔗When Clone Is a Smell

Cloning to escape the borrow checker is fine for small types. It is a design signal for large collections or in loops.

 1    // BAD: clone inside a loop — O(n) allocations for no reason
 2    fn bad(rows: &[String]) -> Vec<Vec<String>> {
 3        rows.iter().map(|r| {
 4            let owned = r.clone();      // unnecessary: we could return borrowed refs
 5            owned.chars().rev().collect()
 6        }).collect()
 7    }
 8
 9    // BETTER: return references when the output is a view of the input
10    fn better<'a>(rows: &'a [String]) -> Vec<&'a String> {
11        rows.iter().collect()          // just copies the references, not the data
12    }

Better still: restructure so there is no intermediate collection at all.

1    // BEST: fuse the operations, return one owned result
2    fn best(rows: &[String]) -> Vec<String> {
3        rows.iter()
4            .filter(|r| !r.is_empty())
5            .map(|r| r.to_uppercase())      // new value, no clone of r
6            .collect()                       // one Vec built directly
7    }

🔗The Cow Escape Hatch

Cow (clone-on-write) is std's built-in answer to "this might need to allocate, but often won't." It is an enum that is either a borrowed view or an owned value.

 1    use std::borrow::Cow;
 2
 3    fn normalize(s: &str) -> Cow<'_, str> {
 4        if s.contains(' ') {
 5            Cow::Owned(s.replace(' ', "-"))   // allocate, because we must
 6        } else {
 7            Cow::Borrowed(s)                  // zero-cost, just a reference
 8        }
 9    }
10
11    assert_eq!(normalize("a b"), "a-b");
12    assert_eq!(normalize("ab"), "ab");

Cow<'a, T> means "a borrowed &'a T or an owned T." It shows up in real APIs: String::from_utf8_lossy returns Cow<str>, and many parsers return Cow<'a, str>.

🔗When to Stop Fighting and What to Reach For

If you find yourself adding .clone() three times in one function, do not add a fourth. Change the design:

The test: clone is acceptable if the cloned value is small (a few dozen bytes, one allocation) and not in a hot loop. It's a smell if you clone collections, clone repeatedly, or clone to work around a function signature you control.

🔗Borrowing & Lifetimes: Surviving the Checker

🔗Reading Borrow Checker Errors

The error message is a specification, not a complaint. It tells you the two conflicting borrows and their spans. Work through it in this order:

1. Which two borrows conflict? One is usually shared (&), one mutable (&mut).
2. Where does the first borrow end? (NLL = last use, not end of scope.)
3. Does the value need to outlive the borrow? Then it needs ownership, not a borrow.

🔗Non-Lexical Lifetimes in Practice

Since Rust 2018, a borrow ends at its last use, not the end of the block. This unblocks a lot:

1    let mut v = vec![1, 2, 3];
2    let first = &v[0];     // shared borrow
3    println!("{}", first); // last use of `first` — borrow ENDS here
4    v.push(4);             // MUTABLE borrow now allowed (would not compile pre-NLL)
5    assert_eq!(v.len(), 4);

But the borrow is still alive if you hold a reference past the mutation:

1    let mut v = vec![1, 2, 3];
2    let r = &v[0];
3    v.push(4);             // ERROR: v is mutably borrowed because `r` is still live
4    println!("{}", r);

🔗Reborrowing: The Automatic Fix

When you pass &mut T to a function that takes &T, the compiler reborrows automatically — you don't need &*:

1    fn read(s: &[i32]) -> usize { s.len() }
2
3    let mut v = vec![1, 2, 3];
4    let n = read(&v);      // &v is coerced to &[i32]; reborrow, not a move
5    v.push(4);             // fine — the borrow ended at `read`
6    assert_eq!(n, 3);

🔗The Four Legitimate Escape Hatches

When borrowing genuinely can't work, these are the tools, in order of preference:

1. Change the signature to take ownership (best).

1    // Instead of fighting over a borrow, consume what you need.
2    fn process(data: Vec<u32>) -> u32 { data.iter().sum() }
3
4    let owned = vec![1, 2, 3];
5    let total = process(owned);   // moved in; caller doesn't need it after

2. Box — break the size cycle.

Useful when a struct needs to hold itself (recursive) or when a large variant bloats every instance:

1    enum Node {
2        Leaf(i32),
3        Branch { left: Box<Node>, right: Box<Node> },   // Box makes this finite
4    }

3. Rc / Arc — shared ownership.

When two owners genuinely need the same data:

1    use std::rc::Rc;
2    let shared = Rc::new(vec![1, 2, 3]);
3    let a = Rc::clone(&shared);       // refcount++, same allocation
4    assert_eq!(Rc::strong_count(&shared), 2);

4. Lifetimes — tie the output to the input (the right tool, used last).

See the next section. This is not an escape hatch — it's the correct solution when a function returns a view into its argument.

🔗When You Actually Need a Lifetime Annotation

Lifetimes are elided in the overwhelming majority of cases. You write one only when the compiler cannot infer the relationship. There are exactly three situations:

1. Returning a reference derived from an input.

 1    // Elision can't tell which input `out` refers to — there are two.
 2    fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
 3        if x.len() >= y.len() { x } else { y }
 4    }
 5
 6    // If you only need the output to live as long as ONE input,
 7    // name them separately:
 8    fn first_word<'a>(s: &'a str) -> &'a str {
 9        s.split(' ').next().unwrap_or("")
10    }

2. A struct holds a reference.

 1    #[derive(Debug)]
 2    struct Excerpt<'a> {
 3        part: &'a str,     // must not outlive the data it points to
 4    }
 5
 6    impl<'a> Excerpt<'a> {
 7        fn first_sentence(text: &'a str) -> Self {
 8            Excerpt { part: text.split('.').next().unwrap_or("") }
 9        }
10        fn level(&self) -> i32 { 3 }   // 'a elided here
11    }
12
13    let novel = String::from("Call me Ishmael. ...");
14    let ex = Excerpt::first_sentence(&novel);
15    assert!(ex.part.starts_with("Call"));

3. Higher-ranked trait bounds (for<'a>), when a closure must work for any lifetime:

 1    fn apply<F>(f: F, xs: &[i32]) -> Vec<i32>
 2    where
 3        F: for<'a> Fn(&'a i32) -> i32,   // accepts references of ANY lifetime
 4    {
 5        xs.iter().map(|x| f(x)).collect()
 6    }
 7
 8    assert_eq!(apply(|x| x * 2, &[1, 2, 3]), vec![2, 4, 6]);

🔗Lifetime Elision Rules

These three rules cover ~99% of signatures without you writing anything:

Rule 3 is why this works with no annotation:

 1    struct Parser<'a> { input: &'a str, pos: usize }
 2
 3    impl<'a> Parser<'a> {
 4        fn new(input: &'a str) -> Self { Parser { input, pos: 0 } }
 5
 6        // Rule 3: return lifetime == &self's lifetime. No annotation needed.
 7        fn rest(&self) -> &'a str { &self.input[self.pos..] }
 8    }

Design heuristic: if a struct needs a lifetime, it probably wants to own the data instead (String not &str, Vec<u8> not &[u8]). Owning removes the lifetime entirely, and the allocation usually costs less than the ergonomic tax of threading 'a through every signature. Use lifetimes when you genuinely cannot afford the copy.

🔗Structurally Validating Lifetimes

A struct with PhantomData<&'a T> inherits the lifetime even if it stores no actual reference — useful for carrying ownership semantics:

 1    use std::marker::PhantomData;
 2
 3    struct Parser<'a> {
 4        input: &'a str,
 5        pos: usize,
 6    }
 7
 8    struct OwnedWithLifetime<'a> {
 9        data: String,          // actually owns the data
10        _marker: PhantomData<&'a ()>,   // but still tracks a lifetime
11    }

The _marker field tells the compiler "this struct behaves as if it borrows for 'a," which matters for variance and drop-check. Name it with a leading underscore so it's not flagged as unused.

🔗Traits & Generics

A trait is a contract. Rust has no inheritance; traits compose instead. This chapter covers the parts you need beyond "define a trait and implement it."

🔗Generic vs dyn: Choosing Dispatch

This is the decision that shapes every library API. There are exactly two kinds of dispatch in Rust:

Static dispatch (generics, impl Trait) — monomorphized at compile time. One copy of the function per concrete type. Zero runtime cost, but code bloat and compile-time cost.

Dynamic dispatch (dyn Trait, Box<dyn Trait>) — one copy of the function, a vtable pointer at runtime. Flexible, accepts heterogeneous collections, but one indirection.

 1    trait Render { fn render(&self) -> String; }
 2    struct Html; struct Md;
 3    impl Render for Html { fn render(&self) -> String { "<p/>".into() } }
 4    impl Render for Md   { fn render(&self) -> String { "**p**".into() } }
 5
 6    // Generic: one binary copy per type, inlined, no indirection.
 7    fn show_one(r: &impl Render) -> String { r.render() }
 8
 9    // Dynamic: one copy, works with a heterogeneous Vec.
10    fn show_any(r: &dyn Render) -> String { r.render() }
11
12    let docs = vec![Box::new(Html) as Box<dyn Render>, Box::new(Md)];
13    let parts: Vec<String> = docs.iter().map(|d| show_any(d.as_ref())).collect();
14    assert_eq!(parts.join(","), "<p/>,**p**");

Decision rule:

Performance reality: dyn dispatch costs one pointer dereference per call — a few nanoseconds. This is almost always irrelevant. Compile times and binary size are the real costs of generics, and those are real. Do not contort your API for runtime speed you cannot measure.

🔗Associated Types vs Generic Type Parameters

This trips up nearly everyone. The rule:

• Generic type parameter (fn f<T: Trait>) → the caller picks one type for the whole function. Use when the caller has exactly one choice.
• Associated type (trait Repo { type Item; }) → each implementor picks its own. Use when the type is tied to the implementor.

 1    // Generic param: ONE T for the whole function.
 2    fn show_all<T: Display>(items: &[T]) { for i in items { println!("{i}"); } }
 3    // Can't hold a Vec of mixed Display types.
 4
 5    // Associated type: each impl chooses its own Item.
 6    trait Repo {
 7        type Item;                     // e.g. User, or Row, or Document
 8        fn all(&self) -> Vec<Self::Item>;
 9    }
10
11    struct Users;
12    struct User { id: u64 }
13    impl Repo for Users { type Item = User; fn all(&self) -> Vec<User> { vec![User{id:1}] } }
14
15    struct Posts;
16    struct Post { slug: String }
17    impl Repo for Posts { type Item = Post; fn all(&self) -> Vec<Post> { vec![] } }
18
19    // Now one function handles both:
20    fn count<R: Repo>(r: &R) -> usize { r.all().len() }
21    assert_eq!(count(&Users), 1);

When you need both, use an associated type with a where clause:

 1    trait Repo { type Item; fn all(&self) -> Vec<Self::Item>; }
 2
 3    // Associated type constrained to Display:
 4    fn print_all<R>(r: &R) -> String
 5    where
 6        R: Repo,
 7        R::Item: std::fmt::Display,   // now we know Item is printable
 8    {
 9        r.all().iter().map(|i| i.to_string()).collect::<Vec<_>>().join(",")
10    }

🔗Blanket Implementations

You can implement a trait for all types satisfying a bound. This is how From<T> gives you Into<T> for free, and how Display implies ToString.

 1    use std::fmt::Display;
 2
 3    // Blanket impl: every T: Display automatically gets ToString.
 4    // (This is what actually exists in std — you don't write it yourself.)
 5    // impl<T: Display> ToString for T { ... }
 6
 7    // A useful custom blanket impl:
 8    trait Describe { fn describe(&self) -> String; }
 9
10    impl<T: Display> Describe for T {
11        fn describe(&self) -> String { format!("<{self}>") }
12    }
13
14    assert_eq!(42u32.describe(), "<42>");
15    assert_eq!("hi".describe(), "<hi>");

Blanket impls are powerful and dangerous. They apply everywhere, so you cannot later add a specific impl for one concrete type without a coherence conflict. Use them when the implementation is genuinely universal.

🔗Marker and Sealed Traits

A marker trait has no methods — it just tags a type as having a property.

 1    trait JsonSerialize {}          // no methods; just a capability tag
 2
 3    struct Money;  impl JsonSerialize for Money {}
 4    struct User;   impl JsonSerialize for User {}
 5    struct Blob;                            // NOT serializable
 6
 7    fn to_json<T: JsonSerialize>(_v: &T) -> String { "{}".into() }
 8
 9    to_json(&Money);   // ok
10    // to_json(&Blob); // ERROR: Blob does not implement JsonSerialize

A sealed trait is a trait you can implement, but only inside your own crate. It prevents downstream code from implementing it, which lets you add methods later without breaking them.

 1    mod sealed {
 2        pub trait Sealed {}   // private module = downstream can't impl
 3        impl Sealed for u32 {}
 4        impl Sealed for String {}
 5    }
 6
 7    // Public trait, but bound to a private one: nobody outside can implement it.
 8    pub trait Shiny: sealed::Sealed {
 9        fn shine(&self) -> String;
10    }
11
12    impl Shiny for u32    { fn shine(&self) -> String { format!("{}✨", self) } }
13    impl Shiny for String { fn shine(&self) -> String { format!("{self}✨") } }
14
15    assert_eq!(7u32.shine(), "7✨");
16    // External crates cannot impl Shiny for their own types. You can add
17    // methods to Shiny in a minor release without breaking anyone.

🔗Supertraits

A supertrait is a trait bound that another trait requires. It guarantees a trait always has its dependency's methods.

 1    use std::fmt::Debug;
 2
 3    trait Summary: Debug {          // any Summary must also be Debug
 4        fn summarize(&self) -> String;
 5    }
 6
 7    #[derive(Debug)]
 8    struct Article;
 9
10    impl Summary for Article {
11        fn summarize(&self) -> String { "article".into() }
12    }
13
14    // We get .summarize() AND .debug() because Debug is a supertrait.
15    fn render(s: &impl Summary) -> String {
16        format!("{} ({:?})", s.summarize(), s)
17    }

🔗The Orphan Rule

You can only implement a trait for a type if either the trait or the type is defined in your crate. This prevents two crates from both adding Display to Vec<T> and conflicting.

Legal: you define MyTrait, Vec<T> is foreign → you may implement MyTrait for Vec<T>. Illegal: both Display and Vec are foreign → forbidden.

The workaround — newtype wrapper (covered in Data Structure Selection):

1    struct MyVec(Vec<u8>);       // local type unlocks impls on it
2    impl std::fmt::Display for MyVec {
3        fn fmt(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
4            write!(f, "MyVec({} bytes)", self.0.len())
5        }
6    }
7    assert_eq!(MyVec(vec![1,2,3]).to_string(), "MyVec(3 bytes)");

🔗Errors That Carry Information

Rust has no exceptions. Result<T, E> makes failure part of the type. The design question is what shape should E have?

🔗Library vs Application

Rule: libraries define typed errors; applications erase them. Never put anyhow::Error in a public library API — you are forcing your callers to Box::dyn their way through, and they cannot handle your variants.

🔗thiserror for Libraries

 1    use thiserror::Error;
 2
 3    #[derive(Debug, Error)]
 4    pub enum ConfigError {
 5        #[error("could not read {path}")]
 6        Io {
 7            path: String,
 8            #[source]                     // marks the underlying cause
 9            source: std::io::Error,
10        },
11
12        #[error("invalid value for `{key}`: {reason}")]
13        Invalid { key: String, reason: String },
14
15        #[error("missing required field `{0}`")]
16        Missing(String),
17    }
18
19    fn load(path: &str) -> Result<Config, ConfigError> {
20        let raw = std::fs::read_to_string(path)
21            .map_err(|source| ConfigError::Io { path: path.into(), source })?;
22        Ok(Config { name: raw })
23    }
24
25    struct Config { name: String }

The #[from] attribute generates a From impl automatically:

 1    #[derive(Debug, thiserror::Error)]
 2    enum StoreError {
 3        #[error("io failure")]
 4        Io(#[from] std::io::Error),      // #[from] == #[source] + From impl
 5
 6        #[error("db: {0}")]
 7        Db(String),
 8    }
 9
10    fn save() -> Result<(), StoreError> {
11        std::fs::write("x", b"y")?;       // io::Error converts automatically
12        Ok(())
13    }

🔗anyhow for Applications

anyhow gives you a type-erased error with .context() for adding a human-readable message as it propagates.

 1    use anyhow::{Context, Result, bail, ensure};
 2
 3    fn load_config(path: &str) -> Result<String> {
 4        let raw = std::fs::read_to_string(path)
 5            .with_context(|| format!("failed to read config at {path}"))?;   // adds context
 6        ensure!(!raw.trim().is_empty(), "config file {path} is empty");     // early return
 7        Ok(raw)
 8    }
 9
10    // bail! is `return Err(anyhow!("..."))`
11    fn validate(s: &str) -> Result<()> {
12        if s.len() > 100 { bail!("input too long: {} bytes", s.len()); }
13        Ok(())
14    }

The context chain is the real value. A bare No such file or directory is useless; failed to read config at ./prod.yaml tells you what failed and where.

1    // Printing an anyhow error shows the full chain:
2    // Error: failed to read config at ./prod.yaml
3    //
4    // Caused by:
5    //     No such file or directory (os error 2)

🔗The ? Operator and Conversion

? does three things: unwrap Ok, return the Err, and convert the error type if From exists.

 1    fn parse_and_save() -> Result<(), StoreError> {
 2        let n: u32 = "42".parse().map_err(|_| StoreError::Db("bad int".into()))?;
 3        std::fs::write("f", n.to_string())?;     // io::Error -> StoreError via #[from]
 4        Ok(())
 5    }
 6
 7    // In a function returning Option, ? works too — it returns None early.
 8    fn first_word_opt(s: &str) -> Option<&str> {
 9        let t = s.split(' ').next()?;     // returns None if no space
10        Some(t)
11    }

The # operator (Err(#err_expr)) inside a Result/Option block lets you match and immediately return a transformed error. Rare, occasionally clearer than a full match.

🔗Panic vs Error

 1    // Unwrap is FINE for values that cannot fail by construction:
 2    let x: i32 = "42".parse().unwrap();         // literal — always succeeds
 3    let v: Vec<i32> = Vec::new();
 4    let first = v.first();                      // Option, handled below
 5
 6    // Unwrap is WRONG for runtime input:
 7    fn port_from_env() -> u16 {
 8        std::env::var("PORT").unwrap().parse().unwrap()   // two panics waiting to happen
 9    }

Use expect instead of unwrap in library code. The message documents the invariant:

1    let config = std::fs::read_to_string("app.toml")
2        .expect("app.toml must exist next to the binary; run from the project root");

🔗Never let unwrap Reach Production

The practical rules:

1. Clippy is your friend: #![deny(clippy::unwrap_used, clippy::expect_used)] at the crate root turns every one into a compile error in library code.
2. In tests and examples, unwrap() is encouraged — it is clearer than .expect("...") for a value you constructed yourself.
3. In main, returning Result from main is fine: fn main() -> Result<(), Box<dyn Error>>.

🔗Iterators & Closures

Iterators are Rust's main tool for expressing transformations without loops. They are lazy by default: nothing runs until you consume the iterator.

🔗Lazy vs Eager

 1    let v = vec![1, 2, 3, 4, 5];
 2
 3    // Lazy — adaptor chain, nothing executed yet
 4    let squares = v.iter().map(|x| x * x).filter(|x| *x % 2 == 1);
 5
 6    // Consumed now. collect() forces evaluation.
 7    let out: Vec<i32> = squares.collect();
 8    assert_eq!(out, vec![1, 9, 25]);
 9
10    // Nothing ran above except building the chain. Forgetting to consume
11    // an iterator is a (silent) no-op — use `.for_each()` or `collect()`
12    // to actually execute it.

🔗The Adaptor Catalogue

The 20 adaptors that cover ~95% of real use:

 1    let words = vec!["apple", "banana", "cherry", "date", "elderberry"];
 2
 3    // Long words, sorted by length descending, first three:
 4    let top: Vec<&str> = words.iter()
 5        .filter(|w| w.len() > 4)
 6        .sorted_by_key(|w| std::cmp::Reverse(w.len()))  // reverse sort
 7        .take(3)
 8        .copied()
 9        .collect();
10    assert_eq!(top, vec!["elderberry", "banana", "cherry"]);
11
12    // flat_map: one-to-many expansion (iter + collect::&lt;Vec&lt;_&gt;&gt; chained)
13    let letters: Vec<char> = words[0].chars().collect();
14    let total_len: usize = words.iter().map(|w| w.chars().count()).sum();
15    assert_eq!(total_len, 5 + 6 + 6 + 4 + 11);

🔗Grouping Without itertools

The "group consecutive equal elements" problem is common enough that itertools (Itertools::chunk_by) exists. Here is the plain-std version:

 1    fn group_consecutive<T: PartialEq, I: IntoIterator<Item = T>>(it: I) -> Vec<Vec<T>> {
 2        let mut out: Vec<Vec<T>> = vec![];
 3        for v in it {
 4            match out.last_mut() {
 5                Some(g) if g.last() == Some(&v) => g.push(v),   // extends current run
 6                _ => out.push(vec![v]),                        // starts a new one
 7            }
 8        }
 9        out
10    }
11
12    assert_eq!(group_consecutive(vec![1,1,2,2,2,3]), vec![vec![1,1], vec![2,2,2], vec![3]]);

A note on itertools: it's a mature, ubiquitous crate (1.6B+ downloads) that fills real gaps in std — chunk_by, exactly_one, Itertools::join, multipeek, Itertools::into_group_map. But for the top 40% of cases, std is enough. Reach for itertools when you need chunk_by, izip!, or Either; otherwise prefer std so your code has fewer dependencies.

🔗fold vs for

Use for when you just want to iterate. Use fold when you're building an accumulator.

 1    // for: clearest for a simple loop
 2    let mut total = 0;
 3    for n in [1, 2, 3] { total += n; }
 4
 5    // fold: clearest when accumulating into a non-numeric type
 6    let joined = ["a", "b", "c"]
 7        .iter()
 8        .fold(String::new(), |mut acc, s| { acc.push_str(s); acc });
 9    assert_eq!(joined, "abc");

🔗Custom Iterators

Implement Iterator to build reusable abstractions. Only next() is required.

 1    struct Evens { n: u64 }
 2    impl Iterator for Evens {
 3        type Item = u64;
 4        fn next(&mut self) -> Option<u64> {
 5            let r = self.n;
 6            self.n += 2;
 7            (r < 10).then_some(r)     // then_some instead of if/else
 8        }
 9    }
10
11    assert_eq!(Evens { n: 0 }.collect::<Vec<_>>(), vec![0, 2, 4, 6, 8]);

Now every adaptor works on it, for free:

1    let sum: u64 = Evens { n: 0 }.filter(|x| x % 4 == 0).sum();
2    assert_eq!(sum, 12);      // 4 + 8

🔗.iter() vs .into_iter() vs .iter_mut()

 1    let v = vec![String::from("a"), String::from("b")];
 2
 3    let lens: Vec<usize> = v.iter().map(|s| s.len()).collect();      // borrows
 4    let owned: Vec<String> = v.clone().into_iter().map(|s| s + "!").collect(); // moves the clone
 5    let mut upper = vec![String::from("a")];
 6    for s in upper.iter_mut() { *s = s.to_uppercase(); }             // mutates in place
 7    assert_eq!(upper, vec!["A"]);
 8    assert_eq!(lens, vec![1, 1]);

v.into_iter() on a Vec<T> moves the elements — a genuinely cheap operation (it's just taking the buffer), no cloning involved. This is the idiomatic way to consume a collection.

🔗Smart Pointers & Interior Mutability

A smart pointer is a struct that owns data and adds semantics. Each one answers a different question.

🔗The Pointer Family

🔗Box<T> — The Default Indirection

Box is a heap allocation with exactly one owner. You reach for it in three cases: recursive types, very large values moved around, or trait objects.

 1    // 1. Recursive — impossible without indirection (infinite size)
 2    enum Tree {
 3        Leaf,
 4        Node(Box<Tree>, i32, Box<Tree>),
 5    }
 6
 7    // 2. Trait objects
 8    let handlers: Vec<Box<dyn Fn(i32) -> i32>> = vec![
 9        Box::new(|x| x + 1),
10        Box::new(|x| x * 2),
11    ];
12    assert_eq!(handlers[0](10), 11);
13
14    // 3. Deliberately-large, move-rarely values (e.g. a big buffer you pass by &)
15    let big = Box::new([0u8; 1_000_000]);
16    assert_eq!(big.len(), 1_000_000);

Vec<T> is already a Box-like handle (it owns a heap buffer). Box<Vec<T>> is almost always a mistake — it adds a pointer hop for no reason.

🔗Rc vs Arc

Identical APIs; the difference is atomic vs non-atomic refcounting. Rc is cheaper but cannot cross threads. Arc can, at the cost of atomic operations on every clone/drop.

 1    use std::rc::Rc;
 2    use std::sync::Arc;
 3
 4    // Single-threaded shared ownership
 5    let data = Rc::new(vec![1, 2, 3]);
 6    let a = Rc::clone(&data);        // refcount++, SAME allocation
 7    assert_eq!(Rc::strong_count(&data), 2);
 8    drop(a);
 9    assert_eq!(Rc::strong_count(&data), 1);
10
11    // Cross-thread shared ownership
12    let shared = Arc::new(String::from("hello"));
13    let handles: Vec<_> = (0..4).map(|_| {
14        let s = Arc::clone(&shared);
15        std::thread::spawn(move || s.len())
16    }).collect();
17    let total: usize = handles.into_iter().map(|h| h.join().unwrap()).sum();
18    assert_eq!(total, 20);

Always use Arc::clone(&x) rather than x.clone() — same result, but the explicit form signals to readers (and to clippy) that you're bumping a refcount, not deep-copying.

🔗Rc<RefCell<T>> vs Arc<Mutex<T>>

This is the classic shared-mutable-state question. Both give shared ownership plus interior mutability; the runtime mechanism differs.

 1    use std::cell::RefCell;
 2    use std::sync::{Arc, Mutex};
 3
 4    // SINGLE THREAD: RefCell — borrow checked at RUNTIME, no OS locking
 5    let data = RefCell::new(vec![1, 2, 3]);
 6    data.borrow_mut().push(4);            // runtime-checked mutable borrow
 7    assert_eq!(data.borrow().len(), 4);
 8
 9    // MULTIPLE THREADS: Mutex — OS-level lock, poisons on panic
10    let counter = Arc::new(Mutex::new(0u64));
11    {
12        let mut c = counter.lock().unwrap();     // guard releases on drop
13        *c += 1;
14    }   // lock released HERE automatically
15    assert_eq!(*counter.lock().unwrap(), 1);

RefCell panics on overlapping borrows at runtime. The compiler checked the types but not the timing. If you see already borrowed at runtime, a reference is held across a mutation. Restructure to shorten the borrow, not by using try_borrow_mut in a loop.

🔗Cell<T> — Mutate-Only, No References

Cell skips the runtime borrow check by requiring get/set (a move in, a move out) rather than handing out references. Faster and simpler for Copy types and small values.

 1    use std::cell::Cell;
 2
 3    let count = Cell::new(0);
 4    count.set(count.get() + 1);      // read + write, no borrow held
 5    count.set(count.get() + 1);
 6    assert_eq!(count.get(), 2);
 7
 8    // Works inside a shared reference, so a struct with &self methods can count:
 9    struct Hits(Cell<u64>);
10    impl Hits {
11        fn hit(&self) { self.0.set(self.0.get() + 1); }   // &self, mutates anyway
12    }
13    let h = Hits::default();
14    h.hit();
15    assert_eq!(h.0.get(), 1);

🔗Weak<T> — Breaking Cycles

Rc/Arc counts strong references. A cycle (A holds Arc to B, B holds Arc to A) means the count never hits zero and the memory leaks. Weak doesn't count, so it breaks cycles.

 1    use std::rc::{Rc, Weak};
 2
 3    let strong = Rc::new(1);
 4    let weak = Rc::downgrade(&strong);       // Weak<i32>, no ownership
 5
 6    assert_eq!(weak.upgrade().map(|r| *r), Some(1));   // upgrade() -> Option<Rc>
 7    drop(strong);
 8    assert!(weak.upgrade().is_none());                 // data is gone, no leak

Canonical use: a parent with many children. The parent owns the children (strong), the children reference the parent (weak), so dropping the parent actually frees everything.

🔗Pin — When Self-Reference Forces the Heap

Pin<T> promises "this value will not be moved again." Most of the time you only care about the type Pin<Box<T>>, because the Box gives a stable address — the heap location never changes, so self-referential structs become possible.

 1    use std::pin::Pin;
 2    use std::boxed::Box;
 3
 4    // A self-referential struct: borrows from its own field.
 5    // Impossible on the stack, possible in a Box because the address is stable.
 6    struct SelfRef {
 7        data: String,
 8        slice_ptr: *const str,       // would dangle if `data` ever moved
 9    }
10
11    impl SelfRef {
12        fn new(s: &str) -> Pin<Box<SelfRef>> {
13            let mut boxed = Box::new(SelfRef { data: s.to_string(), slice_ptr: std::ptr::null() });
14            let ptr = boxed.data.as_str();
15            unsafe { boxed.slice_ptr = ptr; }     // set after the Box is stable
16            Box::pin(boxed)                        // Pin<Box<SelfRef>>
17        }
18    }
19
20    let sr = SelfRef::new("hello");
21    assert_eq!(sr.data, "hello");

Do not write unsafe pointers yourself. Pin exists because async state machines and self-referential types genuinely need it. Box::pin is the safe entry point. If you find yourself hand-rolling *const fields, you almost certainly want self_cell, ouroboros, or just a different design.

🔗Concurrency

Rust makes data races impossible to compile. It does not prevent deadlocks, logic races, or deadlocks — those remain your problem.

🔗Send and Sync

Two auto-trait markers the compiler checks:

• Send — safe to move to another thread. (String, Vec, most types: yes. Rc: no.)
• Sync — safe to share by reference across threads. (&T: Send when T: Sync.)

 1    use std::sync::Arc;
 2    use std::thread;
 3
 4    // Rc is NOT Send — this would not compile:
 5    // let rc = std::rc::Rc::new(5);
 6    // thread::spawn(move || println!("{}", rc));   // Rc<Vec<i32>> cannot be sent
 7
 8    // Arc is Send + Sync:
 9    let data = Arc::new(vec![1, 2, 3]);
10    let handle = {
11        let d = Arc::clone(&data);
12        thread::spawn(move || d.iter().sum::<i32>())    // sends an Arc clone
13    };
14    assert_eq!(handle.join().unwrap(), 6);

🔗Threads: join and Scoping

 1    use std::thread;
 2
 3    // Spawn with a join handle to collect the result
 4    let handle = thread::spawn(|| 2 + 2);
 5    assert_eq!(handle.join().unwrap(), 4);
 6
 7    // Spawn MANY, collect handles, then join in order
 8    let handles: Vec<_> = (0..8)
 9        .map(|i| thread::spawn(move || i * i))
10        .collect();
11    let squares: Vec<i32> = handles.into_iter().map(|h| h.join().unwrap()).collect();
12    assert_eq!(squares, vec![0, 1, 4, 9, 16, 25, 36, 49]);

🔗Scoped Threads: Borrow Without Arc

std::thread::scope (stable since 1.63) lets spawned threads borrow stack data. No Arc, no 'static requirement, no clone.

 1    fn parallel_sum(v: &[u32]) -> u32 {
 2        std::thread::scope(|s| {
 3            let mid = v.len() / 2;
 4            let (a, b) = v.split_at(mid);
 5            let h1 = s.spawn(|| a.iter().sum::<u32>());   // borrows `a`
 6            let h2 = s.spawn(|| b.iter().sum::<u32>());
 7            h1.join().unwrap() + h2.join().unwrap()      // scope guarantees completion
 8        })
 9    }
10
11    assert_eq!(parallel_sum(&[1, 2, 3, 4]), 10);

This is the idiomatic way to parallelize a function over a slice with zero ceremony. The scope guarantees all threads finish before returning.

🔗Rayon: Data Parallelism Without Threads

rayon turns sequential iterator chains into parallel ones with one trait: .par_iter() instead of .iter().

 1    use rayon::prelude::*;
 2
 3    let v: Vec<u64> = (0..100_000u64).collect();
 4
 5    // Sequential
 6    let total: u64 = v.iter().sum();
 7
 8    // Parallel — same chain shape, ~all cores
 9    let ptotal: u64 = v.par_iter().sum();
10
11    // Parallel map + filter + collect
12    let evens: Vec<u64> = v.par_iter().copied().filter(|x| x % 2 == 0).collect();
13
14    assert_eq!(total, ptotal);
15    assert_eq!(evens.len(), 50_000);

When Rayon is the right tool: CPU-bound work over a large collection where the per-item cost is nontrivial. For tiny collections, Rayon's overhead exceeds the gain — use sequential.

🔗Channels: Message Passing

 1    use std::sync::mpsc;
 2    use std::thread;
 3
 4    let (tx, rx) = mpsc::channel::<u32>();       // unbounded
 5    let tx2 = tx.clone();                        // multi-producer
 6
 7    thread::spawn(move || tx.send(1).unwrap());
 8    thread::spawn(move || tx2.send(2).unwrap());
 9    drop(tx);                                    // drop original sender
10
11    let sum: u32 = rx.iter().sum();              // ends when all senders drop
12    assert_eq!(sum, 3);
13
14    // Bounded (backpressure) — send blocks when full
15    let (btx, brx) = mpsc::sync_channel::<u32>(2);
16    btx.send(10).unwrap();
17    assert_eq!(brx.recv().unwrap(), 10);

Modern alternative: crossbeam-channel (3x more downloads, better API: select, after, MPMC). For simple cases std mpsc is fine.

🔗Shared State: Arc<Mutex<T>>

 1    use std::sync::{Arc, Mutex};
 2    use std::thread;
 3
 4    let counter = Arc::new(Mutex::new(0u64));
 5    let handles: Vec<_> = (0..10).map(|_| {
 6        let c = Arc::clone(&counter);
 7        thread::spawn(move || {
 8            // Lock for as short a scope as possible
 9            let mut n = c.lock().unwrap();
10            *n += 1;
11        })
12    }).collect();
13
14    for h in handles { h.join().unwrap(); }
15    assert_eq!(*counter.lock().unwrap(), 10);

Lock as little as possible. Hold the guard across only the mutation, never across .await, never across an expensive computation, never while calling out to code that might re-lock. A common bug is holding a MutexGuard across an .await in async code — that blocks the whole executor thread and is a deadlock waiting to happen.

🔗Locking Rules (Deadlock Prevention)

• One lock at a time. Never hold two mutexes at once in a fixed order; it deadlocks if another thread takes them in reverse.
• Keep guards tiny. Acquire, mutate, drop.
• Never hold across .await. Copy what you need out of the guard, drop the guard, then await.

1    use std::sync::Mutex;
2
3    let m = Mutex::new(vec![1, 2, 3]);
4    let snapshot: Vec<i32> = { let g = m.lock().unwrap(); g.clone() };   // copy, then guard drops
5    drop(snapshot);   // safe to await here — no guard held

🔗Async Rust

Async is Rust's model for I/O-bound concurrency: thousands of connections, few threads. It is not about making code run in parallel on multiple cores.

🔗Async Is Not Multithreading

The rule: async for I/O, threads for CPU. Mixing them is fine (spawn_blocking bridges them), but don't use async for pure computation — you'll just make it slower and more complex.

🔗Futures Are Lazy

 1    async fn fetch(id: u32) -> String { format!("item-{id}") }
 2
 3    // Nothing runs until you await or spawn it:
 4    let fut = fetch(1);          // just a value describing future work
 5    let s = fut.await;           // NOW it runs
 6    assert_eq!(s, "item-1");
 7
 8    // tokio::join! runs two futures concurrently on ONE thread:
 9    let (a, b) = tokio::join!(fetch(2), fetch(3));
10    assert_eq!((a.as_str(), b.as_str()), ("item-2", "item-3"));

🔗Spawning Tasks

 1    use std::sync::Arc;
 2    use std::sync::atomic::{AtomicU64, Ordering};
 3
 4    #[tokio::main]
 5    async fn main() {
 6        let counter = Arc::new(AtomicU64::new(0));
 7
 8        let handles: Vec<_> = (0..10u64).map(|i| {
 9            let c = Arc::clone(&counter);
10            tokio::spawn(async move {
11                c.fetch_add(1, Ordering::SeqCst);
12                i * 2
13            })                       // runs on the runtime's thread pool
14        }).collect();
15
16        let results: Vec<u64> = futures::future::join_all(handles)
17            .await
18            .into_iter()
19            .map(|r| r.unwrap())
20            .collect();
21
22        assert_eq!(counter.load(Ordering::SeqCst), 10);
23        assert_eq!(results.iter().sum::<u64>(), 90);
24    }

🔗select! and Cancellation Safety

select! races multiple futures and takes the first to complete. The critical property: cancellation safety — whether dropping the losing futures loses data.

 1    use std::time::Duration;
 2
 3    async fn with_timeout() -> Option<&'static str> {
 4        let work = async { "done" };
 5        tokio::select! {
 6            r = work => Some(r),                              // work finished first
 7            _ = tokio::time::sleep(Duration::from_secs(5)) => None,   // timed out
 8        }
 9    }
10
11    #[tokio::main]
12    async fn main() {
13        assert_eq!(with_timeout().await, Some("done"));
14    }