Rust Mastery Notes

This is my learn-by-doing knowledge base — the distilled lessons from each Rust concept I drill in rust-scratch.

For every concept I finish a ladder of 7–9 problems (foundations → mechanics → footguns → real-world patterns → a build-it-from-scratch capstone), living in src/bin/<concept>.rs. Once a ladder is done, I write the lasting takeaways here — the mental model, the signatures worth memorizing, the footguns I hit, and the “explain it back” prompts that prove I actually own it.

The code is the gym. This is the notebook.

How to read a note

Each concept page follows the same shape:

Completed concepts

New notes get added under Concepts as each ladder is finished — see Adding a new note.

Modules & visibility

Ladder: src/bin/modules.rs · Run: cargo run --bin modules · Phase 0 · 9 rungs

TL;DR

A crate is a tree of modules rooted at the crate root. mod declares a node in that tree — it imports nothing. Everything is private by default, and privacy is tree-relative: an item is visible to its own module and all of that module’s descendants; a parent can only see into a child what the child marks pub. Paths walk the tree (crate:: from the root, super:: up one, self:: here). use is just a local alias for a path; pub use is a re-export that adds a brand-new public path. Master those three facts and everything else — field privacy, pub(crate), facades, sealed traits — is a corollary.

Why this exists (from first principles)

Without modules, every name in a crate lives in one flat namespace, and every function is callable from everywhere. Two problems follow immediately:

1. No encapsulation. If any code can call any function and read any field, you can’t enforce invariants. A Celsius could be set to -1000; a half-built value could be observed. “It’s an internal detail” becomes a comment, not a guarantee.
2. No stable API. If your internal organization is your public surface, you can’t rename a helper or move a file without breaking everyone who depends on you. Refactoring becomes a breaking change.

Modules + visibility solve both. The module tree gives you namespaces and a place to hide things; pub and its restricted variants let you publish exactly the surface you intend, and nothing more. The compiler enforces it — privacy is a checked rule, not advice. That’s the whole point: the things you don’t mark pub are things you are free to change.

The ladder at a glance

The ideas, built up

1. A module is a node; paths walk the tree

mod kitchen { ... } does not “import” anything. It creates a node named kitchen under the current module, and the items inside it live at kitchen::.... To reach an item you spell a path, and the prefix you choose says where the path starts:

fn oven_temp() -> u32 { 220 }              // lives at the crate ROOT

mod kitchen {
    pub mod pantry {
        pub fn flour_grams() -> u32 { 500 }
    }
    pub mod stove {
        pub fn bake() -> (u32, u32) {
            // pantry is a SIBLING of stove → go up one (super), then down
            // oven_temp is at the ROOT → start from the root (crate)
            (super::pantry::flour_grams(), crate::oven_temp())
        }
    }
}

Three prefixes, three starting points:

Key insight: super::pantry and crate::kitchen::pantry resolve to the same item here. The difference is robustness to change. super:: survives the whole subtree being moved or renamed; crate:: survives local shuffling. Reach for super:: for tight siblings, crate:: for things that live near the root.

2. pub opens a door — and privacy is about the tree

By default an item is private to its module. Privacy is relative: an item is visible to its defining module and every descendant of that module. A parent sees a child’s item only if it’s pub.

mod billing {
    fn tax_rate() -> u32 { 8 }               // PRIVATE: internal detail

    pub fn total_with_tax(price: u32) -> u32 { // PUBLIC entry point
        price + price * tax_rate() / 100        // can call the private helper
    }
}

// at the crate root:
billing::total_with_tax(100);  // OK — it's pub
// billing::tax_rate();        // E0603: function `tax_rate` is private

Two subtleties worth internalizing:

• mod billing itself needed no pub because billing and its caller both live at the crate root — same module, already visible. If billing were nested inside another module, the outside would need pub mod billing.
• E0603 is a hard error. Privacy isn’t a lint you can ignore; the compiler refuses to let unrelated code reach in.

3. pub struct is not pub fields

Marking a struct pub makes the type nameable. Its fields stay private unless each one is individually pub. That asymmetry is the single most useful tool in the whole topic: publish the type, hide the data, force everyone through your methods.

mod temperature {
    #[derive(Debug, PartialEq)]
    pub struct Celsius {
        degrees: i32,                 // PRIVATE — note: no `pub`
    }
    impl Celsius {
        pub fn new(d: i32) -> Option<Celsius> {   // smart constructor
            if d >= -273 { Some(Celsius { degrees: d }) } else { None }
        }
        pub fn get(&self) -> i32 { self.degrees }
    }
}

// let bogus = temperature::Celsius { degrees: -1000 };  // E0451: field is private

Because the field is private, the struct literal Celsius { degrees: ... } is forbidden outside the module (E0451), and reading .degrees directly is too (E0616). The only way to obtain a Celsius is new, which checks the invariant. This is parse, don’t validate enforced by the module system: a Celsius existing is proof it’s valid — downstream code never re-checks.

Inside the defining module you can still use the literal freely — privacy only bites when you cross the module boundary.

4. use aliases; pub use re-exports

These look similar and do fundamentally different things.

mod deep { pub mod nested { pub mod core {
    pub struct Engine { pub power: u32 }
    impl Engine { pub fn new(power: u32) -> Engine { Engine { power } } }
}}}

fn start_deep() -> u32 {
    use crate::deep::nested::core::Engine;  // LOCAL alias — only this fn sees it
    Engine::new(9000).power
}

pub use deep::nested::core::Engine;         // RE-EXPORT — adds crate::Engine

• use is private plumbing: it shortens a path for the current scope and changes nobody else’s view of the tree.
• pub use is API surface: it makes the item reachable through a new path (crate::Engine), in addition to its real one.

This is how every mature crate is laid out: deep folders internally for organization, a thin layer of pub use at the root so users write tokio::spawn instead of tokio::runtime::task::spawn. The internal tree is an implementation detail; the re-exports are the contract.

5. You can’t leak a private type through a public API

If a pub fn returns (or accepts) a type less visible than the function itself, that’s a leak: an outside caller would receive a value of a type they can’t name or use. The compiler stops you.

mod widget {
    pub struct Inner { pub id: u32 }   // must be pub to be honestly returned
    pub fn make(n: u32) -> Inner { Inner { id: n } }
}

let w: widget::Inner = widget::make(7);  // naming the type needs it pub (else E0603)
assert_eq!(w.id, 7);                      // reading the field needs it pub (else E0616)

Where the error shows up depends on the crate kind. In a library crate, exposing a private type in a pub signature fires the private_interfaces lint (and historically the hard error E0446). In a binary like this ladder, there’s no external consumer, so the leak instead bites at the use site: callers can’t name the private type (E0603) or read its private fields (E0616).

The fix isn’t to silence the error — it’s to decide the type’s honest visibility. If you return it, you must publish it (this rung). If it should have stayed internal, don’t return it — hide it behind a facade (rung 7).

6. The visibility dial: pub(crate), pub(super), pub(in path)

pub and private are the two extremes. Between them sits a dial: “public, but only up to here.”

mod engine {
    pub(crate) const fn version() -> u32 { 3 }     // anywhere in THIS crate

    pub mod fuel {
        pub(super) const fn secret_formula() -> u32 { 42 }  // only the parent `engine`
    }
    pub mod electrical {
        pub(in crate::engine) const fn calibrate() -> u32 { 7 }  // the engine subtree
    }

    pub fn diagnostics() -> u32 {
        fuel::secret_formula() + electrical::calibrate()  // engine can see both
    }
}

// engine::fuel::secret_formula();  // privacy error: pub(super) doesn't reach the root

Pick the narrowest visibility that satisfies the actual callers. In the ladder, VERSION could even stay fully private, because the only thing reading it (version()) lives in the same module. pub(crate) would only earn its keep if some other module needed to read VERSION directly. Don’t reach for a wider marker than the call sites demand.

Footguns

• Forgetting fields aren’t auto-pub. pub struct Foo { x: i32 } exposes the type but not x. Outside code can’t build it with a literal (E0451) or read x (E0616). Usually that’s what you want — but it surprises people who expected pub struct to mean “all public.”
• Returning a private type from a pub fn. private_interfaces lint in libs, E0603/E0616 at use sites in bins. The cure is to decide the type’s real visibility, not to paper over the symptom.
• pub(super) doesn’t reach the crate root unless the item’s parent is the root. It’s exactly one level of upward reach (plus descendants of that parent).
• use vs pub use mix-up. A plain use in your lib root does not expose anything to downstream crates — it only aliases for your own code. If you meant to re-export, you need pub use.
• Over-widening visibility to “make it compile.” The compiler will happily accept pub everywhere; then your entire internal structure becomes API you can’t change. Tighten to the minimum the callers actually need.

Real-world patterns

The facade: private internals, curated surface

This is how production crates are organized. Implementation lives in private modules; a thin layer of pub use exposes only the handful of names that form the public API.

mod api {
    mod internal {                       // PRIVATE — no `pub`
        struct RawSocket;                // guts the public API must NOT expose
        pub struct Client { pub name: &'static str }
        impl Client {
            pub fn connect(name: &'static str) -> Self { Self { name } }
            pub fn ping(&self) -> &'static str { "pong" }
        }
    }
    pub use internal::Client;            // re-export ONLY Client
}

api::Client::connect("db-1");      // OK
// api::internal::RawSocket;       // E0603 — `internal` is private, path sealed

The payoff: you can rename RawSocket, split internal into ten files, restructure freely — and nothing downstream breaks, because the only public path is the curated pub use. The module tree stops being part of your API contract.

The sealed trait: a private-module supertrait

Privacy can gate not just calling but implementing. Make your public trait require a supertrait that lives in a private module. Outsiders can see and call your trait, but can’t impl it — satisfying it requires impl’ing the supertrait, which they can’t even name.

mod format {
    mod sealed { pub trait Sealed {} }      // private module → unnameable downstream

    pub trait Encoder: sealed::Sealed {     // supertrait bound is the seal
        fn encode(&self, input: &str) -> String;
    }

    pub struct Json;
    impl sealed::Sealed for Json {}         // only possible INSIDE `format`
    impl Encoder for Json {
        fn encode(&self, input: &str) -> String { format!("json:{input}") }
    }
}

// Downstream:
// struct Rogue;
// impl format::Encoder for Rogue { ... }   // error: Rogue: format::sealed::Sealed
//                                           // not satisfied — and you can't impl it

The “sealed trait” you meet in typestate and blanket_coherence is, mechanically, just this: privacy applied to a supertrait. Because no downstream impl can ever exist, you’re free to add methods to Encoder later without breaking anyone — a genuine API-evolution tool.

Capstone insight

Rung 9 assembles everything into an inventory “library in a file”:

inventory                  (the library root)
├── util    (PRIVATE)      pub(crate) normalize() — shared by submodules
├── model   (PRIVATE)      Sku (private field + smart constructor), Item
├── store   (PRIVATE)      Warehouse (private items: Vec<Item>)
└── (facade) pub use model::{Sku, Item}; pub use store::Warehouse;

The structural “aha”: every visibility decision is driven by who the actual caller is, and the public surface is a deliberate, tiny re-export layer.

• util::normalize is pub(crate) — both model and store call it, so crate-wide is the right reach, but it’s not part of the public API. (A pub(super) would have been too narrow once two different submodules needed it.)
• Sku is pub with a private code field: the only way to get one is the normalizing, length-checking new, so an existing Sku is provably valid.
• The three submodules (util, model, store) are all private. The only way in is the facade — inventory::Sku works, inventory::model::Sku does not.
• Two seal probes prove it: inventory::store::Warehouse::new() is unreachable (the submodule is private) and inventory::Sku { code: ... } is forbidden (the field is private). The invariant and the encapsulation are both enforced, not hoped for.

Build this once and the mental model locks in: the module tree is your private workshop; pub use is the storefront window; and the narrowest pub(...) that satisfies the real callers is always the right answer.

Explain it back

• Why does mod foo; not “import” anything? What does it actually do?
• super::bar vs crate::foo::bar resolve to the same item — when would you prefer each, and why?
• Why does marking a struct pub not make its fields public, and how is that the foundation of “parse, don’t validate”?
• What’s the difference between use path::Thing and pub use path::Thing? Which one is part of your crate’s public API?
• A pub fn returns a private struct. What happens in a library crate vs a binary crate, and what are the two honest fixes?
• When would you choose pub(crate) over pub(super)? Over leaving it private?
• How does a private module turn a public trait into a sealed trait, and why is that an API-evolution tool?
• In the facade pattern, what exactly are you free to change without breaking downstream code, and why?

See also

• The typestate pattern — sealed State trait via a private supertrait.
• Blanket impls & coherence — the sealed extension-trait pattern.
• API evolution & semver — sealed traits and #[non_exhaustive] as evolution levers.
• Newtype & zero-cost wrappers — private fields + smart constructors for invariants.

Cargo features & cfg

Ladder: src/bin/features_cfg.rs · Run: cargo run --bin features_cfg · Phase 0 · 9 rungs

TL;DR

Conditional compilation lets the compiler decide which code even exists before it type-checks anything, based on cfg predicates (target_os, feature = "x", test, debug_assertions, …). Two faces of one idea:

• #[cfg(...)] — an attribute that includes or excludes an item entirely. Excluded code is never compiled. It can be broken Rust and nobody notices until the predicate flips.
• cfg!(...) — a macro that evaluates to a plain bool at runtime. Both branches around it are always compiled.

A feature is a named cfg flag you declare in Cargo.toml [features] and turn on with --features. The single law that governs all feature design: features must be additive — turning one on may only add behavior, never remove or change it, because Cargo compiles your crate once with the union of every feature anyone in the dependency graph requested.

Why this exists (from first principles)

One source tree has to compile for many worlds: Linux and Windows, 64-bit and 32-bit, debug and release, “with JSON support” and “without”. You could maintain separate files or if everything at runtime, but both are bad: runtime ifs still force you to compile and link code (and its dependencies) you’ll never run on this target, and some code is literally uncompilable elsewhere (a Windows API call on Linux).

Conditional compilation solves this by moving the decision before type checking. #[cfg(target_os = "windows")] on a function means: on Linux, that function does not exist — it is never parsed for types, never linked, costs nothing. The compiler enforces only what survives the cfg filter.

Features generalize this from “facts about the target” to “knobs the user picks”. But features carry a hazard that platform cfgs don’t: they are shared. If crate A and crate B both depend on your crate and each asks for a different feature, Cargo does not build your crate twice. It builds it once with the union. That single fact is the source of every feature footgun and the reason for the additivity law.

The ladder at a glance

The ideas, built up

1. cfg!(...) — the macro: a compile-time bool

cfg!(predicate) evaluates to true or false at compile time, but it is used at runtime like any other boolean. The key property: it does not delete code. Both arms of an if cfg!(...) are fully compiled and type-checked.

fn build_profile() -> String {
    let mut s = String::new();
    if cfg!(debug_assertions) {      // both the "debug" and "release" arms
        s.push_str("debug");         // are compiled; one is chosen at runtime
    } else {
        s.push_str("release");
    }
    if cfg!(target_os = "linux") {
        s.push_str(" on linux");
    }
    s
}

On a debug Linux build this returns "debug on linux". Because both arms compile, cfg! is only safe when every arm is valid Rust on every target. That’s its limitation and the reason rung 2 exists.

2. #[cfg(...)] — the attribute: an item either exists or it doesn’t

The attribute form is the exclusion tool. #[cfg(pred)] on an item means the item is compiled only if pred holds; otherwise it vanishes before name resolution. That lets you write two definitions of the same function gated by mutually exclusive predicates:

#[cfg(target_pointer_width = "64")]
fn platform_tag() -> &'static str { "64-bit" }

#[cfg(not(target_pointer_width = "64"))]
fn platform_tag() -> &'static str { "non-64-bit" }

There is no “defined multiple times” error because, on any given target, only one of these exists. The proof: change the second predicate to also be target_pointer_width = "64" and you get E0428: the name 'platform_tag' is defined multiple times — the collision only appears once both items survive the cfg filter. The cfg deletes one before the compiler ever sees a conflict.

This is the deep difference from cfg!: the attribute can guard code that wouldn’t even compile on the other target. The macro cannot — both its arms must always be valid.

3. Your first feature flag

A feature is a cfg flag you invent. Unlike target_os, the name feature = "demo" is unknown until you declare it in Cargo.toml:

[features]
demo = []   # the empty list = "enables no other features / optional deps (yet)"

Then #[cfg(feature = "demo")] works like any other cfg, and --features demo turns it on:

#[cfg(feature = "demo")]
fn feature_line() -> &'static str { "demo enabled" }

With the feature off, feature_line does not exist. The same binary now compiles two different ways depending on the flag:

cargo run --bin features_cfg                 # demo off — fn not compiled in
cargo run --bin features_cfg --features demo # demo on  — fn exists

Since Rust 1.80, an undeclared feature name in a #[cfg(feature = "...")] triggers the unexpected_cfgs lint (“consider adding demo as a feature in Cargo.toml”) instead of silently evaluating to false. That lint catches typo’d feature names — a class of bug that used to fail silently.

4. cfg_attr — conditionally applying another attribute

#[cfg(...)] includes or excludes an item. cfg_attr includes or excludes an attribute:

#[cfg_attr(PREDICATE, attr1, attr2, ...)]
// reads as: if PREDICATE holds, expand to #[attr1] #[attr2] ...; else nothing

The canonical use is gating a derive:

#[derive(Debug, Clone)]                          // always wanted
#[cfg_attr(feature = "demo", derive(PartialEq))] // PartialEq only under `demo`
struct Point { x: i32, y: i32 }

Without demo, Point has Debug and Clone but no PartialEq, so p == q won’t compile (and the test that does the comparison is itself behind #[cfg(feature = "demo")]). This is exactly how every serde-supporting crate works:

#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]

One line; no duplicated struct definition.

5. The additivity law (the rung the whole concept exists for)

Cargo compiles your crate once with the union of every feature any crate in the graph requested. Therefore a feature turning on may only add behavior. The anti-pattern is two features that assume they are mutually exclusive:

// ANTI-PATTERN — collides under unification
#[cfg(feature = "metric")]
fn unit_label() -> &'static str { "meters" }
#[cfg(feature = "imperial")]
fn unit_label() -> &'static str { "feet" }

Each builds fine alone. But --features metric,imperial produces E0428: defined multiple times — and that combination is exactly what unification can force on you: crate A enables metric, crate B enables imperial, and your build breaks through no fault of either. The victim never asked for the conflict.

The fix is to accumulate instead of choosing:

// ADDITIVE — enabling both just yields both
fn enabled_units() -> Vec<&'static str> {
    let mut units = Vec::new();
    if cfg!(feature = "metric")   { units.push("meters"); }
    if cfg!(feature = "imperial") { units.push("feet"); }
    units
}

Now --features metric,imperial returns ["meters", "feet"]. The design rules that fall out of this:

• Never gate the default behavior behind #[cfg(not(feature = "x"))] — that’s a feature that disables something, which is removal in disguise.
• Never make two features mutually exclusive — unification can turn both on.
• Enabling a feature must never break a consumer who didn’t ask for it.

6. The missing-symbol trap

If an item is gated behind a feature, every use of it must be gated too. This is where the cfg! vs #[cfg] distinction becomes a correctness issue, not a style choice. Consider a function that exists only under demo:

#[cfg(feature = "demo")]
fn pretty_print(label: &str, n: i32) -> String { format!("[ {label} = {n} ]") }

The tempting wrong solution uses the macro:

// WRONG — fails to compile when demo is OFF
fn describe(label: &str, n: i32) -> String {
    if cfg!(feature = "demo") { pretty_print(label, n) }  // E0425: cannot find `pretty_print`
    else { format!("{label}={n}") }
}

cfg! keeps both arms compiled, so the off-build still tries to resolve pretty_print, which doesn’t exist → E0425. The only correct solution gates the call site with the attribute form, so each build names only what it has:

// OK — each build compiles only its own arm
fn describe(label: &str, n: i32) -> String {
    #[cfg(feature = "demo")]
    { pretty_print(label, n) }
    #[cfg(not(feature = "demo"))]
    { format!("{label}={n}") }
}

The same discipline applies to use imports — use rand::RngExt; must carry #[cfg(feature = "dice")] or the off-build hits E0432: unresolved import. The rule in one line: gate the definition AND every reference (calls and imports), with the attribute, not the macro.

7. Optional dependency = a feature

A dependency you only sometimes need is marked optional = true. Cargo then does not compile it by default; a feature pulls it in via the dep: syntax:

[dependencies]
rand = { version = "0.10", optional = true }

[features]
dice = ["dep:rand"]

#[cfg(feature = "dice")]
fn roll_die() -> u32 { rand::rng().random_range(1..=6) }

Two subtleties worth owning:

• An optional dependency implicitly creates a same-named feature (rand) you could enable directly — unless you reference it as dep:rand somewhere, which suppresses that implicit feature and keeps your dependency names out of your public feature surface. dep: (Rust 1.60+) is the modern idiom.
• In the default build, rand is not merely unused — it is not downloaded or compiled at all. That’s the real payoff: feature-gated bloat costs nothing when off, both in compile time and binary size.

8. Feature graphs

Features form a directed graph, not a flat list. Three mechanisms:

[features]
default = ["metric"]          # on automatically; --no-default-features strips it
color   = []                  # a leaf feature
full    = ["color", "demo"]   # umbrella: enabling `full` transitively enables both

• default is the set Cargo turns on for a plain cargo build. --no-default-features removes it (common for no_std/embedded builds).
• A feature listing other features enables them transitively. Turning on full is guaranteed to also turn on color and demo.
• The combination --no-default-features --features full means “minimal build, plus exactly this subtree”.

The active set behaves like a closure under “enables”:

Footguns

Real-world patterns

• serde support behind a feature — the universal #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))], with serde as an optional dependency pulled in by dep:serde. Costs nothing when off.
• std vs no_std — libraries expose a std feature (often in default) and use #![cfg_attr(not(feature = "std"), no_std)] so embedded users can opt out via --no-default-features.
• Umbrella full feature — big crates (e.g. tokio’s features = ["full"]) ship one feature that enables a curated subtree, so users don’t have to know the whole list.
• Platform shims — #[cfg(target_os = "...")] selects one of several same-named functions, so callers write portable code over an OS-specific impl.

Capstone insight

The capstone builds a mod config that exercises the whole matrix at once — the shape of a real crate’s config/output layer:

#[cfg(target_os = "linux")]
pub fn config_dir() -> &'static str { "/etc/app" }   // platform path (attribute form)
#[cfg(not(target_os = "linux"))]
pub fn config_dir() -> &'static str { "/tmp/app" }

#[derive(Debug)]
#[cfg_attr(feature = "json", derive(serde::Serialize))]  // serde derive only under json
pub struct Report { pub name: &'static str, pub level: u8 }

pub fn render(r: &Report) -> Vec<String> {
    let mut lines = Vec::new();
    #[cfg(feature = "json")]   { lines.push(serde_json::to_string(r).unwrap()); }
    #[cfg(feature = "pretty")] { lines.push(format!("{} @ level {}", r.name, r.level)); }
    #[cfg(not(any(feature = "json", feature = "pretty")))]
    { lines.push(format!("{:?}", r)); }   // fallback when neither is on
    lines
}

The “aha” is that all four tools compose cleanly because each respects its lane: cfg(target_os) picks exactly one config_dir; cfg_attr adds the Serialize impl only when the JSON path needs it; the per-branch #[cfg] in render makes the output additive — --features json,pretty emits both lines, and the not(any(...)) fallback guarantees exactly one line when neither is on. The whole module is a microcosm of the additivity law: every feature only ever adds a line.

Explain it back

• What’s the difference between cfg!(...) and #[cfg(...)], and when does only one of them work?
• Why does if cfg!(feature = "x") { gated_fn() } fail to compile when the feature is off, while #[cfg(feature = "x")] { gated_fn() } succeeds?
• Why must features be additive? Construct the two-crate scenario where a non-additive feature breaks an innocent consumer.
• What does dep:rand do that bare rand in a feature list does not? What is the implicit feature, and why suppress it?
• Predict the active feature set for --no-default-features --features full given default = ["metric"] and full = ["color", "demo"].

See also

• Modules & visibility — what gets gated lives in modules; #[cfg] and pub both shape the surface a crate exposes.
• Newtype & zero-cost wrappers — #[cfg_attr(..., derive(...))] is the same conditional-derive machinery newtypes lean on for serde support.

Testing

Ladder: src/bin/testing.rs

• practice/testing_lab/ · Run: cargo test --bin testing and cargo test -p testing_lab · Phase 0 · 9 rungs

TL;DR

A test in Rust is just a function tagged #[test]. The compiler bundles all of them into a separate test harness binary; cargo test runs each one in isolation and catches its panic. A test fails iff it panics — and every assertion macro is just a fancy if !cond { panic!(...) }.

There are three places tests live, distinguished by scope:

Everything else — assert_eq!, #[should_panic], Result-returning tests, #[ignore], doctest fences — is detail layered on those two facts.

Why this exists (from first principles)

Most languages bolt testing on as a library: import a framework, register test classes, run a separate tool. Rust builds it into the compiler and cargo, and that design choice explains every quirk on this page.

Because the harness is part of the build, a test is an ordinary function the compiler already type-checks. There is no “test runner reflection” — #[test] is an attribute the compiler collects at compile time. And because the harness reports a result by observing whether the function returned or panicked, the entire assertion vocabulary reduces to “panic on failure.” Once you internalize “failing == panicking,” the rest follows: #[should_panic] simply inverts that rule, and a Result-returning test lets an Err stand in for a panic.

The one thing that trips everyone up — why integration tests and doctests need a library — also falls out of the build model. A tests/foo.rs file compiles as its own crate that links your code as a dependency. A dependency only exposes its pub surface. Binaries (src/main.rs, src/bin/*.rs) have no linkable public API, so there’s nothing for an external test crate to call. Hence this ladder spins up practice/testing_lab/ (a real src/lib.rs) the moment it needs tests/ and doctests.

The ladder at a glance

The ideas, built up

1. A test is a #[test] fn in a #[cfg(test)] module

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn add_works() {
        assert_eq!(add(2, 3), 5);
    }
}

Two attributes carry the whole foundation:

• #[cfg(test)] is conditional compilation. The module exists only when building under cargo test; a cargo build --release compiles it away to nothing. That’s why you can write as many tests as you like with zero binary cost.
• #[test] marks a function the harness should collect and run. It must take no arguments and return () (or Result, see rung 3).

use super::* matters because mod tests is a child module. Child modules don’t automatically see their parent’s items, so you import them. And because the test module is a child of the very module it tests, it can see private items — the defining privilege of unit tests, which rung 6 and 7 turn into a contrast.

2. The assertion toolbox, and why assert_eq! beats assert!

assert!(classify(0) == "zero");                       // boolean: prints only "false"
assert_eq!(classify(-4), "negative");                 // prints left AND right on failure
assert_ne!(classify(7), "zero");
assert_eq!(classify(2), "positive", "ctx: {}", 2);    // trailing custom message

All three panic on failure. The difference is the failure message:

// assert!(a == b)  on failure:
assertion failed: classify(0) == "ZERO"

// assert_eq!(a, b) on failure:
assertion `left == right` failed
  left: "zero"
 right: "ZERO"

assert_eq! captures both operands and prints them, so a red test tells you what the value actually was, not merely that a boolean came out false. Reach for assert_eq!/assert_ne! whenever you’re comparing two values; save bare assert! for genuine booleans. Any of them takes a trailing format string for extra context.

3. Result-returning tests and ?

A #[test] fn may return Result<(), E>. Ok(()) passes; Err(e) fails and prints e. That unlocks ? in test bodies:

#[test]
fn parse_pair_ok() -> Result<(), Box<dyn std::error::Error>> {
    let (a, b) = parse_pair("3,4")?;   // ? compiles ONLY because of the return type
    assert_eq!((a, b), (3, 4));
    Ok(())
}

The Box<dyn std::error::Error> is the catch-all error type any ?-converted error can flow into. Why prefer this over .unwrap()? Both fail the test on an unexpected error, but the intent differs: ? says “an error here is a test failure, surface it,” while .unwrap() says “this can’t happen, panic if it does.” When the error is part of the path you’re exercising, ? reads better and keeps the happy path uncluttered.

4. #[should_panic] — inverting the pass/fail rule

Sometimes the correct behavior is to panic, and you want to assert it does. #[should_panic] inverts the harness rule: the test passes iff the body panics.

#[should_panic]                                       // passes on ANY panic
#[test]
fn seat_too_high() { seat(99); }

#[should_panic(expected = "seat 99 out of range")]    // passes only on THIS panic
#[test]
fn seat_too_high_expected() { seat(99); }

The runner even labels them: test tests::seat_too_high - should panic ... ok.

The bare form is dangerously loose — it can’t tell a correct panic from an unrelated one (rung 6 weaponizes this). expected = "..." requires the panic message to contain that substring, pinning the test to the panic you actually mean. Always add expected.

5. Driving the runner

Knobs after a -- go to the test harness, not to cargo:

cargo test --bin testing                      # everything (ignored ones skipped)
cargo test --bin testing classify             # only tests whose name contains "classify"
cargo test --bin testing -- --ignored         # run ONLY the #[ignore] tests
cargo test --bin testing noisy -- --nocapture # let println! through
cargo test --bin testing -- --test-threads=1  # run serially, not in parallel

• #[ignore] marks a test skipped by default (slow/flaky/manual). It shows as N ignored and runs only with -- --ignored.
• Captured output: cargo test swallows the stdout of passing tests (it only surfaces output on failure, to keep noise down). -- --nocapture lets println! through.
• Name filter is a substring match on the full test path.

6. Tests run in parallel — the footgun that defines this rung

By default the harness runs tests on multiple threads at once. Independent tests get faster; tests that share mutable state (a global, a file, an env var, the current working dir) can interleave and clobber each other — green alone, flaky in the suite. Two fixes:

• Isolate — give each test its own state. The real fix.
• Serialize — -- --test-threads=1. A crutch that hides the coupling.

The add / classify / seat tests share zero mutable state, which is precisely why they’re safe in parallel. Keep tests that way by construction.

Footguns

The whole footgun tier (rung 6) is a catalogue of “passing” tests that lie.

Loose #[should_panic] passes for the wrong reason. A panic anywhere in the body satisfies a bare #[should_panic]:

// LIE: the unwrap panics FIRST, so seat(0) is never reached, yet the test is green
#[should_panic]
#[test]
fn footgun_loose() {
    let _bogus: u32 = "not a number".parse::<u32>().unwrap(); // panics HERE
    seat(0);                                                  // never runs
}

// HONEST: pin the message, and make the line under test the one that panics
#[should_panic(expected = "seat 0 out of range")]
#[test]
fn footgun_fixed() { seat(0); }

Adding expected fails the lying version (the parse panic doesn’t contain “seat 0 out of range”), exposing the bug. The same trap reappears in doctests: a should_panic doctest still containing a todo!() will pass, because todo!() panics.

Never assert_eq! raw floats. IEEE-754 makes 0.1 + 0.2 != 0.3:

// WRONG: fails with right: 0.30000000000000004
assert_eq!(0.1_f64 + 0.2, 0.3);

// OK: compare within a tolerance
assert!((0.1_f64 + 0.2 - 0.3).abs() < 1e-9);

Private reach is a unit-test-only superpower. A unit test can call a private fn secret_key() -> u32 because it lives inside the crate. Hold that thought — the next rung shows an integration test getting a compile error for the same call.

Real-world patterns

Integration tests: tests/ is a separate crate

The testing_lab library exposes pub fn normalize backed by a private squeeze_spaces. An integration test links the crate from outside:

// practice/testing_lab/tests/normalize.rs  — its own crate, black-box
mod common;

#[test]
fn normalizes_messy_input() {
    assert_eq!(testing_lab::normalize("  Hello   WORLD  "), "hello world");
}

Try to reach a private helper and the compiler stops you — this is the wall that defines black-box testing:

error[E0603]: function `squeeze_spaces` is private
 --> tests/_probe.rs:3:18
  |
3 |     testing_lab::squeeze_spaces("a  b");
  |                  ^^^^^^^^^^^^^^ private function

A unit test reaches privates; an integration test sees only pub. Different scope, different job.

Shared helpers go in tests/common/mod.rs, not tests/common.rs. Every file directly under tests/ compiles as its own test binary — so tests/common.rs would run as a confusing empty test target. A file in a subdirectory (tests/common/mod.rs) is a plain module other test files pull in with mod common;, and is not itself a test target:

// tests/common/mod.rs
use testing_lab::normalize;
pub fn assert_normalizes(input: &str, expected: &str) {
    assert_eq!(normalize(input), expected, "input: {input:?}");
}

Doctests: examples that can’t rot

A fenced code block in a /// comment is compiled and run by cargo test. If the example stops matching the API, the doctest fails — your docs can never silently drift:

/// ```
/// use testing_lab::normalize;
/// # let _unused = 1;                       // hidden `#` line: runs, not rendered
/// assert_eq!(normalize("  Hi   THERE "), "hi there");
/// ```
pub fn normalize(s: &str) -> String { /* ... */ }

Doctest mechanics worth knowing:

• Hidden lines. A line starting with # runs but is omitted from the rendered docs — perfect for boilerplate setup that would distract the reader.

• ? needs a Result-returning example. rustdoc wraps your snippet in a fn main() -> (), so ? won’t compile until the example returns a Result. End it with a hidden # Ok::<(), SomeError>(()) and rustdoc switches the wrapper’s return type to match:

  /// let p = parse_port("8080")?;
  /// assert_eq!(p, 8080);
  /// # Ok::<(), std::num::ParseIntError>(())

• Fence attributes change what “pass” means:

  • ```should_panic — passes only if the example panics.
  • ```compile_fail — passes only if the example fails to compile (great for proving an API rejects misuse, e.g. nth_word(42, 0) where a &str is required).
  • ```no_run — compiles but doesn’t execute (network/side-effects).
  • ```ignore — skip entirely.

Capstone insight

Rung 9 tests one small library — a money Ledger (balance in integer cents, a private entries counter, and a private check_invariant) — every way at once, and the structural lesson is how the techniques partition by scope:

cargo test -p testing_lab
  unittests src/lib.rs ...  white-box: assert on private `entries`, call check_invariant()
  tests/ledger.rs      ...  black-box: public deposit/withdraw + custom assert_balance helper
  Doc-tests testing_lab...  runnable docs: a basic one, a should_panic, a `?`-using one

• A unit test inside mod ledger::tests asserts ledger.entries == 3 — a field an integration test literally cannot name.
• An integration test in tests/ledger.rs drives only deposit/withdraw and checks results through a shared common::assert_balance, exactly as a downstream user would.
• A doctest on every public method doubles as documentation and a test, including deposit’s should_panic (negative amount) and withdraw’s ?-using example.

The “aha”: these aren’t three competing styles, they’re three altitudes. Unit tests verify internal invariants you can only see from inside; integration tests verify the contract you ship; doctests verify the contract as documented. A mature crate runs all three from one cargo test, and the harness reports each as its own section.

Explain it back

• Why does a test “fail”? What single mechanism underlies assert_eq!, #[should_panic], and a Result-returning test?
• What does #[cfg(test)] cost a release build, and why?
• Why can a unit test call a private function but an integration test gets E0603 for the same call?
• Why do integration tests and doctests require a library crate, but unit tests don’t?
• Your #[should_panic] test is green. Name two ways it could be lying, and the fix for each.
• Why does assert_eq!(0.1 + 0.2, 0.3) fail, and what do you write instead?
• Why is tests/common/mod.rs correct for shared helpers but tests/common.rs wrong?
• A doctest uses ? and won’t compile. What’s missing?

See also

• Modules & visibility — pub, privacy, and the crate boundary that decides what an integration test can see.
• Cargo features & cfg — #[cfg(test)] is the same conditional-compilation machinery as #[cfg(feature = "...")].
• Error handling architecture — Box<dyn Error> as the catch-all for ? in tests.

Cow — Clone-on-Write

Ladder: src/bin/cow.rs · Run: cargo run --bin cow · Phase 1 · 9 rungs

TL;DR

Cow<'a, B> (“clone on write”) is an enum with two states — Borrowed(&'a B) or Owned(B::Owned) — that lets one value be either a cheap borrow or a heap-owned thing, behind a single type. You hand back Borrowed when the data is already fine, and pay for an Owned allocation only when you actually have to change something. It Derefs to B, so callers use it like a plain &str / &[T] and never care which variant it’s holding.

Mental model: Cow is a maybe-allocation. “Here’s your string back. I only made a new one if I had to.”

Why this exists (from first principles)

Imagine a function ensure_https(url) -> ???. Most URLs already start with https:// — for those you’d love to just return the input untouched. But some don’t, and for those you must build a new string "https://" + url.

Now: what’s the return type?

• Return &str (a borrow)? Impossible for the fix-up case — the new string is a local; you can’t return a reference to data that dies at function end.
• Return String (owned)? Works, but forces an allocation + copy on every call, even for the 90% of inputs that were already correct. Wasteful.

You’re stuck because the two cases want different types. Cow is the type that says “either of those, decided at runtime”:

fn ensure_https(url: &str) -> Cow<'_, str> {
    if url.starts_with("https://") {
        Cow::Borrowed(url)                       // zero cost
    } else {
        Cow::Owned(format!("https://{}", url))   // allocate only here
    }
}

That’s the whole reason Cow exists: a function that usually borrows but sometimes must own, without committing every caller to the cost of owning.

The ladder at a glance

The ideas, built up

The defining discipline: inspect before you allocate

The naive way to replace spaces is input.replace(' ', "_") — but replace always returns a fresh String, even if there were no spaces to replace. That throws away the entire point of Cow. The fix is to check first:

fn sanitize(input: &str) -> Cow<'_, str> {
    if input.contains(' ') {
        Cow::Owned(input.replace(' ', "_"))  // allocate only on the dirty path
    } else {
        Cow::Borrowed(input)                 // clean input: zero allocation
    }
}

The pattern that repeats all ladder long: ask “is any work actually needed?” before you reach for an allocation. Cow only pays off if the borrowed path is genuinely free.

Cow as a field: one type, two origins

Cow isn’t just a return type — as a struct field it lets one type absorb both a borrowed literal and an owned runtime value:

struct Config<'a> { name: Cow<'a, str> }

Config { name: Cow::Borrowed("default") }      // from a &'static literal — no alloc
Config { name: Cow::Owned(format!("user-{id}")) } // from a runtime String

Both are the same Config<'a> type, and name(&self) -> &str reads either one uniformly (via .as_ref()). The lifetime 'a is the price: the struct can’t outlive whatever the borrowed variant points at.

The heart: .to_mut() and lazy upgrade

This is where “clone-on-write” earns its name. cow.to_mut() returns a &mut to the owned data — and here’s the mechanism:

• If the cow is Owned already: hands back the ref, no clone.
• If it’s Borrowed: clones into Owned first, swaps itself, then gives you the mutable ref.

So you call to_mut() exactly at the moment you first need to mutate, and the allocation happens then — and only then:

fn clamp_negatives(input: &[i32]) -> Cow<'_, [i32]> {
    let mut cow: Cow<[i32]> = Cow::Borrowed(input);   // start free
    for i in 0..input.len() {
        if input[i] < 0 {
            cow.to_mut()[i] = 0;   // first negative upgrades Borrowed -> Owned
        }
    }
    cow   // all-positive input is returned still-Borrowed
}

An all-positive slice never calls to_mut(), so it’s returned borrowed for free. One negative anywhere triggers a single clone, and every later write reuses it.

Note this also shows Cow is not string-only — here B = [i32], owned form Vec<i32>. Anything that is ToOwned works.

Ergonomics: Deref makes a Cow act like its target

Cow<str> implements Deref<Target = str>, so every &str method works on it directly — no match, no .as_ref(), no caring about the variant:

fn first_word(c: &Cow<str>) -> &str {
    c.split_whitespace().next().unwrap_or("")  // str methods, called straight on the Cow
}

c.len(), c.starts_with(..), &**c == "hello" — all Just Work. This is why Cow is pleasant to consume, not just to produce.

Footguns

You cannot borrow a local (rung 5)

This is the defining Cow compile error. This does not compile:

fn broken(name: &str) -> Cow<'_, str> {
    let local = format!("hi {name}");
    Cow::Borrowed(&local)   // WRONG: cannot return value referencing local variable
}

Cow::Borrowed ties its lifetime to data that must outlive the call. A String built inside the function dies at the closing brace, so you literally cannot hand it back borrowed. The correct version owns what it builds:

fn greeting(name: &str) -> Cow<'_, str> {
    if name == "hi there" {
        Cow::Borrowed(name)                       // OK: borrowing an INPUT is fine
    } else {
        Cow::Owned(format!("hi {}", name))        // OK: built locally -> must be Owned
    }
}

Rule: Borrowed = “I’m pointing at someone else’s data that lives long enough” (inputs, 'static literals). Owned = “I made this myself.” You can never borrow a local.

.replace() / .to_lowercase() always allocate

These produce a fresh String unconditionally. If you call them on the borrowed path “just in case”, you’ve silently defeated Cow. Gate them behind a .contains(..) / .any(..) check (rungs 2 and 7).

Signatures to know

// The enum itself — B is the borrowed form, B::Owned is the owned form
enum Cow<'a, B: ?Sized + ToOwned> {
    Borrowed(&'a B),
    Owned(<B as ToOwned>::Owned),
}

// Upgrade: clone into Owned on first write, then hand back &mut
fn to_mut(&mut self) -> &mut <B as ToOwned>::Owned

// Consume the Cow, producing an owned value either way
fn into_owned(self) -> <B as ToOwned>::Owned

// Transparent access: Cow<str> derefs to &str
impl<B: ?Sized + ToOwned> Deref for Cow<'_, B> {
    type Target = B;
}

Real-world patterns

Borrow most, own a few (rung 7)

Normalize a batch of words to lowercase, allocating only for the ones that actually had uppercase:

fn normalize<'a>(words: &'a [&'a str]) -> Vec<Cow<'a, str>> {
    words.iter().map(|w| {
        if w.chars().any(|c| c.is_uppercase()) {
            Cow::Owned(w.to_lowercase())   // dirty -> allocate
        } else {
            Cow::Borrowed(*w)              // already clean -> free
        }
    }).collect()
}

A mostly-clean batch costs almost nothing — each clean word still points into the original input.

Zero-copy deserialization with serde (rung 8)

This is the marquee payoff. Give a serde struct a Cow<'a, str> field and tag it #[serde(borrow)]:

#[derive(Deserialize)]
struct Msg<'a> {
    #[serde(borrow)]
    text: Cow<'a, str>,
}

Now when you deserialize:

• {"text":"hello world"} — Borrowed, pointing straight into the JSON input buffer. Zero copy.
• {"text":"line1\nline2"} — the \n escape must be decoded, so serde has no choice but to build a fresh String — Owned.

One field, both outcomes, decided by the data. Drop the #[serde(borrow)] and serde defaults to always Owned — watch the borrowed assertion fail. That contrast is the lesson.

Capstone insight

Re-implementing MyCow from scratch makes the whole thing click. It’s just two variants plus three methods — and to_mut is the only interesting one, because it performs the in-place state transition from borrowed to owned:

fn to_mut(&mut self) -> &mut String {
    match self {
        Self::Borrowed(s) => {
            *self = Self::Owned(s.to_string());  // clone + replace SELF
            match self {                         // now re-match to hand out the owned ref
                Self::Owned(s) => s,
                _ => unreachable!(),
            }
        }
        Self::Owned(s) => s,                     // already owned: no clone
    }
}

That *self = ...; re-match dance is exactly how std does it. Once you’ve written it, “clone on write” stops being a slogan and becomes a concrete line of code: the borrow becomes an allocation right here, and nowhere else.

Explain it back

• Why can’t ensure_https just return &str? Why not just String?
• What does .to_mut() do differently for a Borrowed vs an Owned cow?
• Why does Cow::Borrowed(&local) fail to compile, but Cow::Borrowed(input) is fine?
• What makes c.split_whitespace() work directly on a Cow<str>?
• In the serde rung, why does "line1\nline2" come back Owned but "hello world" comes back Borrowed?
• Cow<'a, B> requires B: ToOwned — why? (What couldn’t it do without it?)

See also

• Borrow / ToOwned — the two traits Cow is built on; B: ToOwned is what lets the Owned variant exist, and rung 8 there closes this exact loop.
• Drop & Ordering — mem::replace (used by to_mut internally) is covered in depth there.

Box & the Heap

Ladder: src/bin/box_heap.rs · Run: cargo run --bin box_heap · Phase 1 · 9 rungs

TL;DR

Box<T> is Rust’s simplest heap allocator: a single owning pointer to a value on the heap. It is exactly one pointer wide, implements Deref<Target = T> so you use the inner value transparently, and drops the heap allocation when it goes out of scope. Box exists because some values cannot live on the stack — recursive types have infinite size without indirection, and trait objects need a uniform container for heterogeneous values. When you see Box, think: “owned heap value, pointer-sized, cleaned up automatically.”

Mental model: Box<T> is a T that lives on the heap instead of the stack. You reach through it with *, but auto-deref means you rarely have to.

Why this exists (from first principles)

Every local variable in Rust lives on the stack, and the compiler must know its size at compile time. This creates two hard problems:

Problem 1 — Recursive types. An enum List { Cons(i32, List), Nil } is infinitely sized: a List contains a List contains a List… The compiler needs a finite size_of::<List>() and can’t get one. Wrapping the recursion in Box<List> breaks the cycle — a Box is always one pointer wide, regardless of what it points to.

Problem 2 — Heterogeneous collections. A Vec<Shape> doesn’t work when Shape is a trait — different implementors have different sizes. But Vec<Box<dyn Shape>> does: every element is the same size (a fat pointer), and the actual data lives on the heap at whatever size it needs.

Problem 3 — Large values. Moving a 10 MB array into a function copies 10 MB on the stack. Box::new(big_array) puts it on the heap; moving the Box copies just one pointer.

Box is the answer to “I need a value whose size isn’t known at compile time” or “I need a value that outlives this stack frame’s layout constraints.”

The ladder at a glance

The ideas, built up

Box basics: allocate, deref, pointer-sized

A Box<T> allocates T on the heap and gives you an owning pointer. You read the heap value by dereferencing:

fn boxed_sum(b: Box<i64>, n: i64) -> i64 {
    *b + n   // explicit deref — but arithmetic would auto-deref too
}

The critical size fact: a Box<T> is always exactly size_of::<usize>() bytes — one pointer — regardless of how large T is. A Box<[u8; 1024]> is 8 bytes on a 64-bit machine, same as Box<i64>. The heap holds the data; the stack holds just the address.

assert_eq!(size_of::<Box<i64>>(), size_of::<usize>());
assert_eq!(size_of::<Box<[u8; 1024]>>(), size_of::<usize>());

Drop timing: Box follows stack rules

When a Box goes out of scope, it drops the heap value — exactly like a stack value’s destructor runs at scope end. And when multiple Boxes are declared in sequence, they drop in reverse declaration order (LIFO), because the Box itself is on the stack and stack drops are LIFO:

let a = make("a");   // declared first
let b = make("b");   // declared second
drop(b);             // force "b" to drop first
drop(a);             // then "a"
// log == ["b", "a"]

Without explicit drop() calls, locals drop in reverse order at scope end anyway. The Noisy struct with a shared log (via Rc<RefCell<Vec<String>>>) proves this observationally — the drop impl pushes the label, and you assert the log matches. The takeaway: heap ownership follows stack scoping rules; the Box is on the stack, so it obeys stack destruction order.

Recursive types: why Box is required

This is the poster-child use case. A cons list:

// WRONG — infinite size
enum List { Cons(i32, List), Nil }

// OK — Box breaks the recursion
enum List { Cons(i32, Box<List>), Nil }

Without Box, the compiler tries to compute size_of::<List>() and finds that Cons contains a List which contains a Cons which contains a List… It’s turtles all the way down — error E0072, “recursive type has infinite size.”

Box<List> is the fix because a Box is one pointer regardless of its target. Now size_of::<List>() = max(size_of::<i32>() + size_of::<Box<List>>(), 0) + tag, which is finite and known. The recursion still exists at runtime — the heap chain can be arbitrarily long — but each type-level nesting is just “a pointer to more of the same.”

Summing the list is straightforward pattern-matching with recursion:

fn sum_list(list: &List) -> i32 {
    match list {
        List::Nil => 0,
        List::Cons(v, rest) => v + sum_list(rest),
    }
}

Auto-deref means rest (a &Box<List>) coerces to &List when passed recursively — no explicit * needed.

Deref, DerefMut, and moving out

Box<T> implements Deref<Target = T> and DerefMut, which gives three capabilities:

Auto-deref lets you access fields directly:

fn greet_len(p: &Box<Person>) -> usize {
    p.name.len()   // no *, no (**p).name — auto-deref handles it
}

DerefMut lets you mutate through the box:

fn rename(mut p: Box<Person>, new_name: &str) -> Box<Person> {
    p.name = new_name.to_string();   // writes straight through
    p
}

*box on an owned Box moves the value out of the heap:

fn unbox(p: Box<Person>) -> Person {
    *p   // consumes the Box, returns the owned Person
}

This last one is unique to Box — you can’t * a Rc or Arc to move out, because they might have other owners. A Box is the sole owner, so moving out is always safe. The box is consumed, the heap is freed, and you hold the value on the stack.

The infinite-size error: expression trees

The cons list had one recursive field. An expression tree has two:

// WRONG — Add(Expr, Expr) is doubly-infinite
enum Expr { Num(i64), Add(Expr, Expr), Mul(Expr, Expr) }

// OK — box each child
enum Expr {
    Num(i64),
    Add(Box<Expr>, Box<Expr>),
    Mul(Box<Expr>, Box<Expr>),
}

The error message (E0072) tells you exactly which type is recursive and suggests Box. The fix is mechanical: every recursive field gets wrapped.

Evaluating the tree is the natural recursive pattern:

fn eval(e: &Expr) -> i64 {
    match e {
        Expr::Num(n) => *n,
        Expr::Add(a, b) => eval(a) + eval(b),
        Expr::Mul(a, b) => eval(a) * eval(b),
    }
}

Why Box and not &Expr? A reference would need a lifetime and wouldn’t own the children. The tree owns its nodes — Box is the ownership-preserving indirection.

Moving out of a Box and partial moves

When you own a Box<T>, you can destructure the contents by moving them out:

fn into_parts(b: Box<Config>) -> (String, Vec<String>) {
    let Config { name, items } = *b;   // move all fields out, box freed
    (name, items)
}

But when you only have &mut Box<Config>, you cannot move a field out — that would leave a hole in a value someone else still holds a reference to:

fn steal_items(b: &mut Box<Config>) -> Vec<String> {
    b.items          // WRONG: "cannot move out of `b.items` which is behind a mutable reference"
}

The fix is std::mem::take, which swaps in a default value as it takes the old one out — no hole left behind:

fn steal_items(b: &mut Box<Config>) -> Vec<String> {
    std::mem::take(&mut b.items)   // items becomes Vec::new(), config stays valid
}

This is the same mem::take / mem::replace technique from the Drop & ordering ladder. It shows up constantly with linked structures — any time you need to rewire a pointer through &mut, you swap in a placeholder.

Box<dyn Trait>: heterogeneous collections

A Vec<Circle> can only hold circles. A Vec<Box<dyn Shape>> can hold anything that implements Shape — circles, squares, triangles, side by side:

trait Shape {
    fn area(&self) -> f64;
    fn name(&self) -> &'static str;
}

let shapes: Vec<Box<dyn Shape>> = vec![
    Box::new(Circle { radius: 1.0 }),
    Box::new(Square { side: 2.0 }),
];

Each element is a fat pointer: one word for the data on the heap, one word for the vtable (the table of function pointers for that concrete type’s Shape impl). This is dynamic dispatch — s.area() looks up the right function pointer at runtime.

The size difference tells the story:

assert_eq!(size_of::<Box<dyn Shape>>(), 2 * size_of::<usize>());  // fat: data + vtable
assert_eq!(size_of::<Box<Circle>>(),     size_of::<usize>());      // thin: data only

A concrete Box<Circle> is one pointer — the compiler knows the type statically. A Box<dyn Shape> needs the extra vtable pointer because the type is erased.

Summing areas just iterates and calls through the vtable:

fn total_area(shapes: &[Box<dyn Shape>]) -> f64 {
    shapes.iter().map(|s| s.area()).sum()
}

Auto-deref means s.area() works directly on &Box<dyn Shape> — you don’t need (**s).area().

Box<dyn Error> and Box::leak

Box<dyn Error> unifies error types. When a function can fail in multiple unrelated ways (parse error, IO error, custom validation), you need a single return type. Box<dyn std::error::Error> is the catch-all: any type implementing Error converts into it via ?, and you can build one from a plain string with .into():

fn parse_and_double(s: &str) -> Result<i32, Box<dyn Error>> {
    let n = s.parse::<i32>()?;           // ParseIntError -> Box<dyn Error>
    if n < 0 {
        Err(Box::new(std::io::Error::new(
            std::io::ErrorKind::Other,
            "negative number",            // custom error from string
        )))
    } else {
        Ok(n * 2)
    }
}

Box::leak gives you 'static from runtime data. It consumes a Box<T> and returns &'static mut T by deliberately never freeing the memory — an intentional leak. The use case is turning runtime-built data into a reference that lives forever (global config, interned strings, etc.):

fn leak_static(s: String) -> &'static str {
    Box::leak(s.into_boxed_str())
}

String::into_boxed_str() gives a Box<str>, and Box::leak on it yields &'static mut str (which coerces to &'static str). The heap allocation will never be freed — that’s the trade. Use it for data that genuinely must live for the whole program, not as a lifetime escape hatch.

Footguns

• Infinite-size enum (E0072). Every recursive field in an enum needs Box (or some other indirection). Two recursive fields means two Boxes — Vec can’t save you when each node has a fixed number of children.

• Moving out through &mut. You can destructure an owned Box<T>, but through a mutable reference you can’t leave a hole. Reach for mem::take or mem::replace to swap in a default.

• Recursive Drop on long chains. A linked list where each node’s Drop calls the next node’s Drop will blow the stack on long chains. You must write an iterative Drop that walks and frees one node at a time.

• Box::leak is permanent. The memory is never freed. It’s correct for process-lifetime data, but a leak in a loop is a real memory leak.

Signatures to know

// Allocate on the heap
fn Box::new(x: T) -> Box<T>

// Transparent access — Box<T> acts like T
impl<T: ?Sized> Deref for Box<T> {
    type Target = T;
}
impl<T: ?Sized> DerefMut for Box<T> { ... }

// Move the value out of the heap (consumes the Box)
let val: T = *boxed;

// Intentional leak -> 'static reference
fn Box::leak<'a>(b: Box<T>) -> &'a mut T

// String -> Box<str> (for leak or other unsized boxing)
fn String::into_boxed_str(self) -> Box<str>

Real-world patterns

Trait objects for plugin/strategy patterns

Box<dyn Trait> is how Rust does runtime polymorphism. Any time you’d reach for an interface/abstract class in another language — a logging backend, a storage driver, a rendering strategy — you store a Box<dyn Backend> and dispatch through the vtable.

Error propagation with ?

In application code (not libraries), Result<T, Box<dyn Error>> is the quick path when you don’t want to define a custom error enum. Every ? auto-converts the concrete error into the box. For libraries, prefer thiserror for typed errors; for applications, anyhow wraps this pattern with better ergonomics.

Recursive data structures

Trees, expression ASTs, and linked lists all use Box (or Rc/Arc for shared ownership) to break the infinite-size cycle. The pattern is always the same: Option<Box<Node<T>>> for an optional link.

Capstone insight

Building a generic LinkedList<T> from scratch makes every Box idea concrete. The link type is Option<Box<Node<T>>>: Some(box) is a node, None is the end. Every operation revolves around Option::take() — the same mem::take trick from rung 6, applied to rewire links through &mut self:

fn push(&mut self, elem: T) {
    let old_head = self.head.take();           // take the old head out (leaves None)
    let new_node = Box::new(Node {
        elem,
        next: old_head,                        // old head becomes next
    });
    self.head = Some(new_node);                // new node becomes head
}

pop is the mirror: take the head, set head to node.next, return node.elem.

The iterative Drop is the non-obvious piece. Without it, dropping a 100,000- node list recurses 100,000 deep and overflows the stack — each Box<Node> drops its next field, which drops its next, and so on. The fix is a while let loop that takes each link one at a time:

impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        let mut current = self.head.take();
        while let Some(mut node) = current {
            current = node.next.take();   // free one node per iteration
        }
    }
}

Each iteration drops one Box<Node> (the Some(mut node) binding owns it and drops it at the end of the loop body), but crucially that node’s next has already been take()-ed out to None, so no recursive drop fires. The chain unwinds iteratively, not recursively.

The iterator is the final piece: an Iter<'a, T> that holds Option<&'a Node<T>> and advances by following node.next.as_deref(). It borrows the list without consuming it, yielding &T references:

impl<'a, T> Iterator for Iter<'a, T> {
    type Item = &'a T;
    fn next(&mut self) -> Option<Self::Item> {
        self.next.take().map(|node| {
            self.next = node.next.as_deref();
            &node.elem
        })
    }
}

Once you’ve built this, Box stops being “the heap pointer” and becomes a concrete ownership link — a chain of sole-owner pointers you can rewire, iterate, and drop by hand.

Explain it back

• Why is Box<T> exactly one usize wide, no matter how big T is?
• What error do you get if you write enum List { Cons(i32, List), Nil }, and why does Box<List> fix it?
• How does *boxed_value differ from dereferencing an &T? (Hint: ownership.)
• Why can you destructure *owned_box but not borrowed_box.field through &mut?
• What is the size of Box<dyn Shape> vs Box<Circle>, and why?
• Why does the linked list need an iterative Drop, and what would happen without one on 100,000 nodes?
• What does Box::leak actually do, and when is it appropriate to use?

See also

• Cow — uses Box internally for the Owned variant’s heap allocation; into_boxed_str() appears in the leak rung.
• Drop & Ordering — mem::take and mem::replace, the tools that make Box-based linked structures work through &mut.
• Rc<RefCell<T>> patterns — shared ownership via Rc where Box’s sole ownership isn’t enough; the doubly-linked list there contrasts with this singly-linked capstone.

Cell & RefCell — Interior Mutability

Ladder: src/bin/cell_refcell.rs · Run: cargo run --bin cell_refcell · Phase 1 · 9 rungs

TL;DR

Rust enforces many &T XOR one &mut T at compile time. Interior mutability lets you mutate through a shared &T by upholding that same rule a different way. Cell<T> never hands out references at all — it copies values in and out, so no aliasing can occur. RefCell<T> hands out real &T / &mut T, but checks the borrow rule at runtime (and panics if you break it). Both are !Sync — single-threaded only; the multi-threaded counterparts are Mutex and RwLock.

Mental model: Cell is a slot you can only peek at or swap. RefCell is a slot with a borrow-checker bouncer who works the night shift (runtime) instead of the day shift (compile time).

Why this exists (from first principles)

The borrow checker is conservative. It enforces “many readers XOR one writer” at compile time by tracking & and &mut through the type system. This is sound and zero-cost — but it rejects programs that are actually safe:

struct Stats { count: u32 }

impl Stats {
    fn record(&mut self) { self.count += 1; }
    //        ^^^^^^^^^ requires exclusive access
}

If two parts of your program hold &Stats, neither can call record — the compiler can’t prove they won’t alias. But you know you’re single-threaded and the mutation is fine. The compiler won’t budge.

Interior mutability is the escape hatch: wrap the field in Cell or RefCell, and the type itself enforces the aliasing rule (by copying or by runtime checks), so the compiler can accept &self methods that mutate.

Without Cell/RefCell, you’d need &mut all the way up the call chain for any mutation — which is often impossible when multiple owners (Rc) or callbacks need to write.

The ladder at a glance

The ideas, built up

Cell: mutate by copying, never by reference

Cell<T> provides interior mutability for Copy types with zero runtime overhead. The API is deliberately narrow — you can get() a copy of the value and set() a new one, but you never get a reference to the contents:

fn bump(counter: &Cell<u32>, by: u32) {
    counter.set(counter.get() + by);
}

The signature is &Cell<u32>, not &mut Cell<u32> — two shared references can both drive mutations because no aliasing reference to the inner u32 ever exists. The value is copied out, modified, and copied back in. This is why get requires T: Copy — it can’t hand you a reference (that would create aliasing), so it must copy.

let counter = Cell::new(0u32);
let r1 = &counter;
let r2 = &counter;
bump(r1, 5);
bump(r2, 3);   // both shared refs can mutate — no &mut anywhere
assert_eq!(counter.get(), 8);

The Cell toolbox: replace, take, update

get/set handle Copy types, but what about a String in a Cell? You can’t copy it out. The toolbox fills the gap with swapping operations:

The classic trick for non-Copy types: Cell<Option<T>>. You can take() the Option, which replaces it with None (the Default for Option), giving you the owned value without needing Copy:

fn steal(slot: &Cell<Option<String>>) -> Option<String> {
    slot.take()   // moves the String out, leaves None behind
}

let name = Cell::new(Some(String::from("ferris")));
assert_eq!(steal(&name), Some(String::from("ferris")));
assert_eq!(steal(&name), None);   // already taken

RefCell: runtime borrow checking

Cell can’t help when you need a reference to the contents — you can’t get() a Vec and push to it. RefCell<T> solves this by handing out real references, guarded by a runtime borrow flag:

• borrow() -> Ref<T> : shared read borrow (many allowed)
• borrow_mut() -> RefMut<T> : exclusive write borrow (only one, no readers)

The returned Ref/RefMut are RAII guards. While they live, the borrow flag is held. When they drop, the flag resets.

fn log(entries: &RefCell<Vec<String>>, msg: &str) {
    entries.borrow_mut().push(msg.to_string());
}

Again: &RefCell, not &mut RefCell. The RefCell enforces exclusivity at runtime, so the compiler accepts the shared reference.

The “&self that mutates” pattern

This is the real reason RefCell exists in practice. A struct wraps its mutable state in RefCell and exposes all-&self methods — callers see a read-only interface, but the struct mutates internally:

struct Stats {
    samples: RefCell<Vec<i32>>,
}

impl Stats {
    fn add(&self, n: i32) {           // &self, NOT &mut self
        self.samples.borrow_mut().push(n);
    }
    fn len(&self) -> usize {
        self.samples.borrow().len()
    }
    fn sum(&self) -> i32 {
        self.samples.borrow().iter().sum()
    }
}

This is how caches, loggers, lazy-init fields, and counters work in safe Rust when &mut self isn’t available.

Multiple simultaneous read borrows are fine — borrow() can be called many times while other Ref guards are alive:

let a = s.samples.borrow();
let b = s.samples.borrow();    // both Refs alive — OK, many readers
assert_eq!(a.len(), b.len());
assert!(s.samples.try_borrow_mut().is_err());   // but a writer is refused

try_borrow / try_borrow_mut return Result instead of panicking — useful when you’re unsure whether a borrow is already active.

Ref::map — projecting a borrow to a single field

A common need: borrow one field out of a RefCell<Struct>. You can’t return a plain &str — the Ref guard would drop at function end, resetting the borrow flag, and the reference would dangle. The compiler won’t let you.

Ref::map solves this by transforming the guard while keeping it alive:

fn borrow_name(c: &RefCell<Config>) -> Ref<'_, str> {
    Ref::map(c.borrow(), |cfg| cfg.name.as_str())
}

fn borrow_retries_mut(c: &RefCell<Config>) -> RefMut<'_, u32> {
    RefMut::map(c.borrow_mut(), |cfg| &mut cfg.retries)
}

The returned Ref<str> still holds the borrow flag down — a try_borrow_mut will fail while it lives. When it drops, the flag releases. This lets you expose fine-grained borrows of individual fields without leaking the whole struct.

Footguns

The runtime borrow panic (rung 5)

This is the defining RefCell hazard. Overlap a read borrow with a write borrow and you get a panic at runtime, not a compile error:

fn trigger_panic(v: &RefCell<Vec<i32>>) {
    let _r = v.borrow();           // Ref alive for the rest of the scope
    v.borrow_mut().push(1);        // PANIC: "already borrowed"
}

The fix is scope the borrow — end the read borrow before taking the write borrow. Copy what you need out, drop the Ref, then mutate:

fn duplicate_first(v: &RefCell<Vec<i32>>) {
    let first = v.borrow()[0];     // temporary Ref dropped at semicolon
    v.borrow_mut().push(first);    // now safe — no outstanding borrows
}

The trap is subtle: v.borrow()[0] creates a temporary Ref that lives only for the expression. But let r = v.borrow(); ... r[0] keeps the Ref alive until r goes out of scope. The difference between a temporary and a binding is the difference between working code and a panic.

Re-entrant borrow through a callback (rung 6)

The most insidious variant: a read borrow held during iteration, and a callback that tries to write to the same RefCell:

fn each<F: FnMut(i32)>(v: &RefCell<Vec<i32>>, mut f: F) {
    for &x in v.borrow().iter() {   // Ref alive for the whole loop
        f(x);                        // if f() borrows v mutably -> PANIC
    }
}

fn double_into_buggy(v: &RefCell<Vec<i32>>) {
    each(v, |x| {
        v.borrow_mut().push(x * 2);   // re-entrant: panics
    });
}

The borrow() in each holds a Ref for the entire loop body. The closure calls borrow_mut() on the same RefCell — boom. The two borrows aren’t adjacent in the source; the mutable one is buried in a closure. This is why re-entrancy is the real danger with RefCell.

The fix: snapshot and release. Collect what you need, drop the read borrow, then mutate:

fn double_into_fixed(v: &RefCell<Vec<i32>>) {
    let doubles = v.borrow().iter().map(|x| x * 2).collect::<Vec<_>>();
    v.borrow_mut().extend(doubles);
}

The borrow() is a temporary — it lives for the collect() expression and drops before borrow_mut() is called.

RefCell is !Sync

RefCell’s borrow flag is a plain Cell<isize> with no atomics. Sharing &RefCell across threads would race on the flag. The compiler prevents this: RefCell<T> is !Sync, so std::thread::scope with a shared &RefCell is a compile error. The thread-safe equivalents are Mutex (one writer, blocks) and RwLock (many readers or one writer, blocks).

Real-world patterns

Rc<RefCell<T>> — shared mutable state

Rc gives multiple owners. RefCell gives mutation through &. Together: multiple handles to the same data, any of which can mutate it. This is how graphs, trees, and observer state work in single-threaded Rust:

fn new_node(value: i32) -> Rc<RefCell<Node>> {
    Rc::new(RefCell::new(Node { value, children: vec![] }))
}

fn add_child(parent: &Rc<RefCell<Node>>, child: Rc<RefCell<Node>>) {
    parent.borrow_mut().children.push(child);
}

The payoff: mutate through one handle, observe through another — they share the same underlying RefCell:

let root = new_node(1);
let a = new_node(2);
add_child(&root, Rc::clone(&a));

a.borrow_mut().value = 20;             // mutate through `a`
assert_eq!(sum_tree(&root), 1 + 20);   // see it through `root`

The threaded counterpart is Arc<Mutex<T>>.

Caches and lazy fields

A struct with a RefCell<Option<ExpensiveResult>> can lazily compute and cache a value through &self:

fn get_result(&self) -> Ref<'_, ExpensiveResult> {
    if self.cache.borrow().is_none() {
        *self.cache.borrow_mut() = Some(expensive_compute());
    }
    Ref::map(self.cache.borrow(), |opt| opt.as_ref().unwrap())
}

For single-init cases, OnceCell / OnceLock are simpler; RefCell shines when the cached value can be invalidated and recomputed.

Capstone insight

Building MyRefCell<T> from scratch reveals that the whole mechanism is just three pieces:

1. UnsafeCell<T> — the only legal way to get a *mut T from a shared &T. Any other route to &T -> &mut T is instant UB. UnsafeCell is the compiler-blessed primitive that says “I know what I’m doing; don’t optimize based on immutability.”

2. A borrow flag — a Cell<isize> tracking the state:

The rules:

• borrow(): panic if flag < 0 (writer out), else flag += 1.
• borrow_mut(): panic if flag != 0 (anyone out), else flag = -1.

3. RAII guard types — MyRef and MyRefMut. They Deref to the data (via the UnsafeCell’s raw pointer), and their Drop impl restores the flag. This is why borrows auto-release — when the guard goes out of scope, the destructor runs and the flag resets:

impl<T> Deref for MyRef<'_, T> {
    type Target = T;
    fn deref(&self) -> &T {
        unsafe { &*self.cell.value.get() }
    }
}

impl<T> Drop for MyRef<'_, T> {
    fn drop(&mut self) {
        self.cell.flag.set(self.cell.flag.get() - 1);
    }
}

impl<T> Drop for MyRefMut<'_, T> {
    fn drop(&mut self) {
        self.cell.flag.set(0);
    }
}

The unsafe in Deref is sound because the flag guarantees the aliasing invariant: if a MyRef exists, no MyRefMut can exist (flag would be -1, but it’s > 0), and vice versa. The flag is the proof obligation — get it right and the unsafe is justified; get it wrong and you have UB.

Once you’ve written this, RefCell stops being magic. It’s a Cell<isize> counter plus two RAII types that hold it. The borrow checker didn’t go away — it moved into your flag arithmetic.

Explain it back

• Why does Cell::get require T: Copy? What would go wrong if it handed out a &T instead?
• What is the exact runtime cost of RefCell compared to a plain &mut? (Hint: it’s a flag check, not a lock.)
• When a Ref drops, what happens to the borrow flag? Why is this an RAII pattern?
• Why does let _r = v.borrow(); v.borrow_mut().push(1); panic, but let x = v.borrow()[0]; v.borrow_mut().push(x); doesn’t?
• What makes RefCell !Sync? What’s the thread-safe replacement?
• In the re-entrant callback rung, where is the read borrow still alive when the write borrow fires? Why can’t the compiler catch this at compile time?
• What is UnsafeCell and why is it the foundation of all interior mutability in Rust?
• In MyRefCell, why is the unsafe in Deref for MyRef sound?

See also

• Rc<RefCell<T>> patterns — the full treatment of the Rc<RefCell<T>> combo: cycles, Weak, observer pattern, doubly-linked list.
• Box & the Heap — sole ownership on the heap; Box<dyn Trait> is the owned trait-object counterpart to Rc<RefCell<dyn Trait>>.
• Drop & Ordering — RAII guards and mem::take/replace, the same patterns that make RefCell guards and Cell::take work.

Conversion traits — From / Into, TryFrom / TryInto, AsRef / AsMut

Ladder: src/bin/conversions.rs · Run: cargo run --bin conversions · Phase 1 · 9 rungs

TL;DR

Type conversion in Rust is a small family of traits, split on two questions: can it fail? and do you consume or just borrow?

The unlock that makes the whole family small: you only ever implement From and TryFrom. The Into and TryInto directions are handed to you for free by blanket impls. And the ? operator converts error types through From, so making heterogeneous errors collapse into one type is also just writing From impls. Almost everything on this page falls out of those two facts.

Why this exists (from first principles)

A conversion is a function A -> B. You could just write free functions (celsius_to_fahrenheit, string_from_char, …) and be done. The reason Rust lifts conversions into traits is that traits are how you write code generic over “anything convertible.” Once conversion is a trait, a function can say “give me anything that becomes a String” and the compiler wires up the right conversion at each call site. Free functions can’t do that.

But one trait isn’t enough, because conversions differ along two independent axes that the type system has to respect:

1. Can it fail? Turning a Celsius into a Fahrenheit always succeeds — the result type can hold any value. Turning an i32 into a u8 cannot always succeed: 300 doesn’t fit. An infallible conversion returns B; a fallible one must return Result<B, E>. You cannot model both with one signature, so the family splits into From (returns Self) and TryFrom (returns Result<Self, Self::Error>).

2. Do you need to own the input? Producing a String from a &str allocates and consumes nothing it can’t recreate — that’s From/Into, which take the value by move. But a function that only reads text shouldn’t demand ownership or force a clone. It just needs a &str view of whatever you have. That’s AsRef: a cheap, non-consuming “give me a &T of yourself.”

What the compiler guarantees, given these traits: conversions are explicit and type-directed. There’s no silent coercion between unrelated types — you either call .into()/.try_into() (and the target type drives which impl runs) or you get a compile error. The one infamous exception is the as keyword, which is not a trait and silently truncates — rung 6 is about why you should reach for TryInto instead.

The ladder at a glance

The ideas, built up

From is the one you implement; Into is the one you get

Implement From in one direction and the reverse .into() appears for free:

struct Celsius(f64);
struct Fahrenheit(f64);

impl From<Celsius> for Fahrenheit {
    fn from(c: Celsius) -> Self {
        Fahrenheit(c.0 * 9.0 / 5.0 + 32.0)
    }
}

Both of these call the same impl:

let f1 = Fahrenheit::from(Celsius(100.0));   // explicit From
let f2: Fahrenheit = Celsius(0.0).into();    // .into() — free, type-driven

You never write impl Into<Fahrenheit> for Celsius. The stdlib has a blanket impl that derives it from your From:

impl<T, U: From<T>> Into<U> for T { /* calls U::from(self) */ }

This is the rule to memorize: implement From, callers enjoy Into. The asymmetry exists because the blanket impl only flows one way — From -> Into — and (historically) you couldn’t even impl Into for a foreign type. From is always the right thing to write.

Notice in f2 the conversion is driven by the target type annotation (let f2: Fahrenheit). .into() is “convert into something”; the compiler figures out which From impl from the type it’s assigned to. No annotation, no resolution.

Into bounds make APIs ergonomic — convert once at the boundary

The real reason Into matters at the call site: a parameter typed impl Into<String> accepts anything that knows how to become a String, and the function converts exactly once, at the boundary.

struct Tag { name: String }

impl Tag {
    fn new(name: impl Into<String>) -> Self {
        Self { name: name.into() }
    }
}

One function, three different argument types, zero clones written by the caller:

let a = Tag::new("literal");              // &'static str
let b = Tag::new(String::from("owned"));  // String — a no-op conversion
let c = Tag::new('x');                    // char -> String!

The String -> String case is free because of the reflexive impl (rung 5): it’s a real but no-op From. So you pay nothing for the flexibility when the caller already has the owned type.

Rule of thumb: put impl Into<T> (or T: From<X>) on the caller side of a generic boundary when the function needs to store an owned T. If it only needs to read the data, use AsRef instead (rung 7) — don’t take ownership you don’t need.

From powers the ? operator — the most important fact here

This is why From matters more than any other trait on the page. When you write ? on a Result whose error type doesn’t match the function’s return error type, the compiler inserts .map_err(From::from) for you. So you make heterogeneous errors flow into one error type just by implementing From for each source error.

#[derive(Debug, PartialEq)]
enum ConfigError {
    NotANumber(ParseIntError),
    OutOfRange(i32),
}

impl From<ParseIntError> for ConfigError {
    fn from(error: ParseIntError) -> Self {
        ConfigError::NotANumber(error)
    }
}

fn parse_config(s: &str) -> Result<i32, ConfigError> {
    let n: i32 = s.parse()?;                    // parse() errors with ParseIntError
    if !(0..=100).contains(&n) {
        return Err(ConfigError::OutOfRange(n)); // returned explicitly
    }
    Ok(n)
}

The s.parse()? line is the whole lesson. parse() returns Result<i32, ParseIntError>, but the function returns Result<_, ConfigError>. The ? desugars roughly to:

let n = match s.parse() {
    Ok(v) => v,
    Err(e) => return Err(ConfigError::from(e)),   // From::from inserted here
};

Because you wrote From<ParseIntError> for ConfigError, that conversion exists and the code compiles. This is the engine behind anyhow, thiserror, and every hand-rolled error enum: ? + From turns many failure types into one.

TryFrom — when the conversion can fail

From::from returns Self — it has no way to signal failure. So when a conversion can fail, From is simply the wrong trait. TryFrom is the fallible twin: fn try_from(v) -> Result<Self, Self::Error>, with an associated error type you choose.

struct Percent(i32);

#[derive(Debug, PartialEq)]
enum PercentError { OutOfRange(i32) }

impl TryFrom<i32> for Percent {
    type Error = PercentError;
    fn try_from(value: i32) -> Result<Self, Self::Error> {
        if value < 0 || value > 100 {
            return Err(PercentError::OutOfRange(value));
        }
        Ok(Percent(value))
    }
}

Exactly mirroring From -> Into, implementing TryFrom gives you try_into() for free:

let p: Result<Percent, _> = 100.try_into();   // free from the TryFrom impl

Note you must annotate the target (Result<Percent, _>) so the compiler knows which TryInto to pick — same type-direction rule as .into(). And TryFrom composes with ? because the error type already matches:

fn make(n: i32) -> Result<Percent, PercentError> {
    let p = Percent::try_from(n)?;   // ? works — error type is already PercentError
    Ok(p)
}

Here the ? calls From::from on the error, but since it’s PercentError -> PercentError that’s the reflexive identity — no conversion needed. Which leads straight to rung 5.

Reflexivity and the orphan rule — two coherence facts that bite

(a) impl<T> From<T> for T exists in the stdlib. Every type can “convert” to itself — a no-op identity. This quietly makes three earlier things work:

• ? works even when the error types already match (it calls From::from, which is identity here).
• impl Into<String> accepts a String at zero cost (String: From<String>).
• u64::from(42u64) is a real, if pointless, conversion.

let same = u64::from(42u64);   // identity From — a genuine impl, just a no-op
assert_eq!(same, 42);

(b) The orphan rule (coherence). You may implement a trait for a type only if the trait or the type is local to your crate. So this is rejected:

// WRONG — both From and Duration are foreign to your crate:
// impl From<u64> for std::time::Duration { ... }   // E0117

Uncommenting that in the source produces E0117 "only traits defined in the current crate can be implemented for types defined outside of the crate." You cannot make it compile from this crate — that’s the entire point. The rule exists so two different crates can’t write conflicting impls for the same trait/type pair and break each other.

The universal fix: a newtype you own.

struct Timeout(Duration);   // a local type -> now you CAN impl From for it

impl From<u64> for Timeout {
    fn from(secs: u64) -> Self {
        Timeout(Duration::from_secs(secs))
    }
}

fn secs_to_timeout(secs: u64) -> Timeout {
    secs.into()   // resolves to your From<u64> for Timeout
}

Because Timeout is local, the orphan rule is satisfied and the impl is allowed. This is also a second reason you implement From and never Into: the blanket impl gives Into for free and historically you couldn’t impl Into for a foreign type at all.

as truncates silently; TryInto is the checked path

as casts between numeric types and never fails — it silently truncates/wraps. This is a notorious bug source:

let truncated = 300i32 as u8;   // == 44, no error, no warning
assert_eq!(truncated, 44);      // 300 - 256 = 44, wrapped around

The safe counterpart is TryFrom/TryInto, which returns Err when the value doesn’t fit. You can write a generic that narrows anything try-convertible into a u8:

fn narrow<T: TryInto<u8>>(value: T) -> Result<u8, T::Error> {
    value.try_into()
}

Two things to unpack in that signature:

• T: TryInto<u8> — the bound is on the caller’s type, accepting any integer type that knows how to try to become a u8.
• T::Error — the error type isn’t named; it’s the trait’s associated type. Different source types may have different error types, and the return type tracks whichever one T brings.

assert!(narrow(300i32).is_err());     // doesn't fit -> Err (vs. `as` -> 44)
assert_eq!(narrow(200i32), Ok(200));  // fits
assert_eq!(narrow(200u32), Ok(200));  // different input type, same bound
assert!(narrow(-1i32).is_err());      // negative -> Err

This is exactly how the stdlib downcasts integers safely: u8::try_from(x) and x.try_into(). Reach for them whenever a numeric narrowing could lose data.

AsRef — cheap reference conversions, no allocation

From/Into consume a value and usually allocate. But often a function only needs to read the data — it shouldn’t demand ownership or force a clone. AsRef<T> is the answer: a zero-cost “give me a &T view of myself.” &str, String, &String, Box<str> all impl AsRef<str>, so a single bound accepts all of them by reference:

fn shout<S: AsRef<str>>(s: S) -> String {
    s.as_ref().to_uppercase()
}

fn byte_len<B: AsRef<[u8]>>(b: B) -> usize {
    b.as_ref().len()
}

The caller passes whatever it has, and a borrowed input stays usable afterward:

let owned = String::from("hi");
assert_eq!(shout(&owned), "HI");   // &String -> &str view
assert_eq!(owned, "hi");           // still usable: shout only borrowed it

AsRef<[u8]> is even broader — it unifies &str, String, &[u8], Vec<u8>, and arrays as a byte view:

assert_eq!(byte_len("abc"), 3);              // &str
assert_eq!(byte_len(vec![1u8, 2, 3]), 3);    // Vec<u8>
assert_eq!(byte_len([0u8; 5]), 5);           // [u8; 5]

AsRef vs Into, the decision: use impl Into<String> when you need to store an owned String (rung 2). Use impl AsRef<str> when you only need to look at the text (rung 7). Taking ownership you don’t need forces needless clones on the caller.

AsRef<Path> (the File::open trick) and AsMut

The most famous AsRef in the stdlib is the signature of File::open:

fn open<P: AsRef<Path>>(path: P) -> io::Result<File>

That single bound is why File::open("f.txt"), File::open(string), and File::open(path_buf) all work — &str, String, PathBuf, and &Path all impl AsRef<Path>. You write the bound once; callers pass whatever path-like thing they hold. The ladder mirrors it:

fn extension<P: AsRef<Path>>(p: P) -> Option<String> {
    p.as_ref()
        .extension()                 // Option<&OsStr>
        .and_then(|e| e.to_str())    // Option<&str>
        .map(String::from)           // Option<String>
}

AsMut is the mutable mirror: as_mut() hands back a &mut T view, so one function can mutate a Vec, an array, or a &mut slice in place:

fn double_all<T: AsMut<[i32]>>(mut data: T) -> T {
    data.as_mut().iter_mut().for_each(|x| *x *= 2);
    data
}

assert_eq!(double_all(vec![1, 2, 3]), vec![2, 4, 6]);  // Vec<i32>
assert_eq!(double_all([10, 20]), [20, 40]);            // [i32; 2]

AsMut<[i32]> abstracts over “anything that can lend a mutable i32 slice,” so the in-place algorithm is written once and works across container types.

Capstone insight: data flows in infallibly, out fallibly

The capstone builds a mini serde_json::Value and wires the whole family together — and the structural “aha” is the asymmetry:

Data flows into a dynamic type infallibly (From — a bool always makes a valid Value). Data flows out fallibly (TryFrom — a Value might not be the type you asked for). That asymmetry is the entire reason both traits exist.

enum Value {
    Null, Bool(bool), Num(f64), Str(String),
    Array(Vec<Value>), Object(Vec<(String, Value)>),
}

In, infallibly — every Rust value maps to some valid Value:

impl From<bool> for Value   { fn from(b: bool) -> Self { Value::Bool(b) } }
impl From<i64> for Value    { fn from(n: i64)  -> Self { Value::Num(n as f64) } }
impl From<&str> for Value   { fn from(s: &str) -> Self { Value::Str(s.to_string()) } }
impl From<Vec<Value>> for Value { fn from(v: Vec<Value>) -> Self { Value::Array(v) } }

This makes construction ergonomic, even for heterogeneous nested data — every element just .into()s:

let arr: Value = vec![1i64.into(), "two".into(), true.into()].into();

Lookup, by AsRef<str> — the key bound lets callers pass a &str or a String:

fn get<S: AsRef<str>>(&self, key: S) -> Option<&Value> {
    let key = key.as_ref();
    if let Value::Object(object) = self {
        object.iter().find(|(k, _)| k == key).map(|(_, v)| v)
    } else {
        None   // not an object -> no key
    }
}

obj.get("name");                  // &str key
obj.get(String::from("age"));     // String key — same function

Out, fallibly — extraction can disagree with the stored variant, so it returns Result:

impl TryFrom<Value> for f64 {
    type Error = WrongType;
    fn try_from(v: Value) -> Result<Self, Self::Error> {
        if let Value::Num(n) = v { Ok(n) } else { Err(WrongType) }
    }
}

impl TryFrom<Value> for String {
    type Error = WrongType;
    fn try_from(v: Value) -> Result<Self, Self::Error> {
        if let Value::Str(s) = v { Ok(s) } else { Err(WrongType) }
    }
}

let name = String::try_from(obj.get("name").unwrap().clone()).unwrap();  // "ada"
let age: f64 = obj.get("age").unwrap().clone().try_into().unwrap();      // 36.0
assert_eq!(f64::try_from(Value::Bool(true)), Err(WrongType));            // wrong type -> Err

Once you see this, every dynamic/serialization boundary in Rust reads the same way: From to build the loose representation, TryFrom to safely pull typed values back out, AsRef to keep the read-side flexible.

Footguns

• as silently truncates/wraps numeric casts. 300i32 as u8 == 44, no warning. Use u8::try_from(x) / x.try_into() whenever a narrowing could lose data — they return Err instead of corrupting the value.

• The orphan rule blocks impl ForeignTrait for ForeignType. You can’t impl From<u64> for Duration from your crate (E0117). Wrap the foreign type in a newtype you own and impl on that.

• Implement From, never Into. The blanket impl derives Into from your From. Writing Into by hand is redundant and was historically impossible for foreign types.

• .into() / .try_into() need a known target type. They convert “into something”; if the target isn’t pinned by an annotation or the surrounding context, the compiler can’t pick an impl. Annotate the binding or the return.

• Taking ownership when you only read. Using impl Into<String> where impl AsRef<str> would do forces callers to give up (or clone) their data. Match the bound to what the function actually needs: store -> Into, read -> AsRef.

• From can’t fail. If a conversion has any invalid inputs, it must be TryFrom. Reaching for From and panicking inside is a code smell — return a Result instead.

Real-world patterns

Explain it back

• Why do you only ever implement From, and where does .into() come from?
• What does ? insert on the error path, and which trait must you implement to make a foreign error type flow into your error enum?
• When is From the wrong choice, and what’s the fallible replacement? What does its associated Error type let you control?
• Why does ? compile even when the error types already match? (Which std impl?)
• State the orphan rule in one sentence. Why can’t you impl From<u64> for Duration, and what’s the standard fix?
• 300i32 as u8 is what, and why? What should you write instead, and what does it return on overflow?
• You have a function that only needs to read a string. impl Into<String> or impl AsRef<str> — which, and why does it matter to the caller?
• Why is File::open’s P: AsRef<Path> bound so convenient? Name three types that satisfy it.
• In the JSON Value capstone, why is construction From but extraction TryFrom? What does that asymmetry reflect about the data?

See also

• Borrow / ToOwned — AsRef’s cousins; Borrow adds an Eq/Hash contract that AsRef doesn’t, which is why HashMap keys use Borrow, not AsRef
• Cow — Clone-on-Write — pairs with Into/AsRef for APIs that borrow when they can and own when they must
• Box & the Heap — Box<dyn Error> is the other half of the ?/From error-conversion story

Borrow / ToOwned

Ladder: src/bin/borrow_toowned.rs · Run: cargo run --bin borrow_toowned · Phase 1 · 9 rungs

TL;DR

ToOwned and Borrow are the two traits that sit underneath Cow and HashMap-key lookups.

• ToOwned is a generalized Clone for when the borrowed and owned types differ: &str -> String, &[T] -> Vec<T>. Clone is &T -> T (same type), so it can’t express str -> String; ToOwned can, via an associated Owned type.
• Borrow<B> is the other direction — view an owned value as a borrowed &B (String -> &str) — but with a contract: the view must hash, compare, and order identically to the owner. That contract is exactly what lets a HashMap<String, V> be queried by &str without allocating.

Why this exists (from first principles)

A HashMap<String, V> stores owned String keys. You want to look something up with a cheap &str literal — without building a throwaway String every call. That’s only sound if &str hashes to the same bucket the String went into. Borrow<str> for String is the promise that it does.

But the problem is deeper than just HashMap. Consider str and String: they are different types, yet they represent the same data in different ownership modes. Standard Clone can’t express this — Clone is &T -> T, same type in, same type out. You can’t impl Clone for str to produce a String. So Rust needs a trait that says “given a borrowed &str, produce its owned counterpart String” — that’s ToOwned. And it needs the reverse: “given an owned String, produce a borrowed &str view” — that’s Borrow.

Together, these two traits form a round-trip contract between borrowed and owned forms. Cow is built directly on top of them: its Owned variant is <B as ToOwned>::Owned, and Borrow is how it hands out &B from that variant.

The ladder at a glance

The ideas, built up

ToOwned: Clone across type boundaries

Clone is &T -> T — same type. That works fine for i32 or Vec<String>, where the owned form and the borrowed form are the same type. But str and String are fundamentally different types. str is unsized (a [u8] with a UTF-8 invariant), living behind references. String is a Vec<u8> on the heap. You can’t clone a str into a str — there’s nowhere to put it.

ToOwned bridges the gap with an associated type:

pub trait ToOwned {
    type Owned: Borrow<Self>;       // the owned form must borrow BACK to Self
    fn to_owned(&self) -> Self::Owned;
}

So str: ToOwned<Owned = String> and [T]: ToOwned<Owned = Vec<T>>. The .to_owned() call on a &str produces a String:

fn duplicate(s: &str) -> String {
    s.to_owned()
}

fn duplicate_slice(xs: &[i32]) -> Vec<i32> {
    xs.to_owned()
}

The return types are different types than the inputs. That’s the whole point — Clone can’t do this.

Borrow: the other direction, with a contract

Borrow<B> goes the opposite way: given an owned value, hand out a borrowed &B view. String: Borrow<str> and Vec<T>: Borrow<[T]>. There’s also a blanket T: Borrow<T> so every type can borrow as itself.

fn borrow_sum<T: Borrow<[i32]>>(xs: T) -> i32 {
    let slice: &[i32] = xs.borrow();
    slice.iter().sum()
}

This one function accepts both Vec<i32> and &[i32] — borrow() normalizes either to &[i32].

But Borrow is not just “give me a reference.” It carries a semantic contract: x and x.borrow() must produce the same Eq, Ord, and Hash results. This is critical for HashMap and is what distinguishes Borrow from AsRef.

The payoff: HashMap lookup without allocation

This is why Borrow exists. The HashMap::get signature is:

fn get<Q>(&self, k: &Q) -> Option<&V>
where
    K: Borrow<Q>,        // the stored key can be viewed as Q
    Q: Hash + Eq + ?Sized // Q = str is unsized; only touched behind &Q

Read it as: “the stored key K can be Borrow’d as Q.” With K = String and Q = str, String: Borrow<str> holds, so map.get("key") just works — no String allocation needed.

The contract is what makes this sound: when the map hashes the &str query, it computes the same hash that the String key produced at insertion time. If those hashes differed, the lookup would silently miss the bucket.

Writing the bound yourself makes it stick:

fn contains_key2<K, Q>(map: &HashMap<K, u32>, key: &Q) -> bool
where
    K: Borrow<Q> + Eq + Hash,
    Q: Eq + Hash + ?Sized,
{
    map.contains_key(key)
}

The ?Sized on Q is required because Q = str is unsized — it’s only ever touched behind &Q, so unsized is fine.

The associated type puzzle

When generic over T: ToOwned, the owned value’s type is spelled T::Owned (or <T as ToOwned>::Owned) — never T. This trips people up. T is the borrowed type (e.g. str), which is usually unsized and can’t be returned by value:

fn owned_pair<T: ToOwned + ?Sized>(value: &T) -> (T::Owned, T::Owned) {
    (value.to_owned(), value.to_owned())
}

// Called with T = str:
let (a, b): (String, String) = owned_pair("hi");
// Called with T = [i32]:
let (v1, v2): (Vec<i32>, Vec<i32>) = owned_pair(&[1, 2][..]);

The ?Sized bound on T is needed because str and [T] are unsized types — without it, the compiler demands T: Sized and rejects owned_pair::<str>.

Footguns

Borrow vs AsRef: same shape, different promise

Borrow<T> and AsRef<T> have the same signature: fn(&self) -> &T. So why two traits?

• AsRef<T>: “you can view me as &T.” No other guarantee. Use it for flexible function arguments (accept &str, String, PathBuf, …).
• Borrow<T>: the view is semantically transparent — x and x.borrow() must produce the same Eq / Ord / Hash. Implement it only when that holds.

The CiString proof (rung 5)

A case-insensitive string hashes "Hello" and "HELLO" identically, but plain str hashes them differently:

impl Hash for CiString {
    fn hash<H: Hasher>(&self, state: &mut H) {
        for b in self.0.bytes() {
            state.write_u8(b.to_ascii_lowercase());
        }
    }
}

A Borrow<str> impl for CiString would force str’s hasher on lookup and silently miss the bucket. The ladder proves this by computing hashes both ways:

// CiString hashes case-insensitively: "Hello" == "HELLO"
assert_eq!(h(&CiString::new("Hello")), h(&CiString::new("HELLO")));
// but plain str hashes exactly: "Hello" != "HELLO"
assert_ne!(h("Hello"), h("HELLO"));

So CiString implements AsRef<str> (legal — AsRef makes no promise) but deliberately not Borrow<str>. When the equivalence relations don’t match, you must honestly allocate a CiString to query:

fn find_ci(map: &HashMap<CiString, i32>, query: &str) -> Option<i32> {
    let key = CiString::new(query);   // must allocate — no Borrow shortcut
    map.get(&key).copied()
}

Needless .to_string() at lookup (rung 6)

The classic wasteful pattern:

fn get_bad(&self, key: &str) -> Option<&str> {
    self.0.get(&key.to_string())...   // WRONG: allocates per lookup!
}

The fix is one generic method that accepts a borrowed key directly:

fn get<Q>(&self, key: &Q) -> Option<&str>
where
    String: Borrow<Q>,
    Q: Hash + Eq + ?Sized,
{
    self.0.get(key).map(|v| v.as_str())   // OK: zero allocation
}

Reflexively reach for key: &Q where Key: Borrow<Q> instead of taking or owning a String at query boundaries.

Real-world patterns

Into-in / Borrow-out (rung 7)

A keyed collection has two boundaries that want different traits:

impl TagSet {
    // INSERT: you must end up OWNING -> accept impl Into<String> (at most 1 alloc)
    fn add<S: Into<String>>(&mut self, tag: S) {
        self.tags.insert(tag.into());
    }

    // QUERY: you only LOOK -> borrow, never allocate
    fn has<Q>(&self, tag: &Q) -> bool
    where
        String: Borrow<Q>,
        Q: Hash + Eq + ?Sized,
    {
        self.tags.contains(tag)
    }
}

This is the pattern real APIs use: Into at the ownership boundary (insert, store, construct), Borrow at the lookup boundary (get, contains, find).

Borrow gives breadth for free

One Borrow<str> bound accepts &str, String, Box<str>, Rc<str>, and Cow<str>:

fn shout<S: Borrow<str>>(s: S) -> String {
    s.borrow().to_uppercase()
}

assert_eq!(shout("hi"), "HI");                  // &str
assert_eq!(shout(String::from("yo")), "YO");    // String
assert_eq!(shout(Box::<str>::from("be")), "BE"); // Box<str>
assert_eq!(shout(Rc::<str>::from("rc")), "RC");  // Rc<str>
assert_eq!(shout(Cow::Borrowed("cow")), "COW");  // Cow<str>

Closing the Cow loop (rung 8)

pub enum Cow<'a, B: ToOwned + ?Sized> {
    Borrowed(&'a B),
    Owned(<B as ToOwned>::Owned),
}

B: ToOwned is mandatory: the Owned variant must name a concrete owned type (<B as ToOwned>::Owned), and to_owned() is the only way to manufacture one from a borrow. Re-implementing Cow::into_owned yourself proves this is the only mechanism:

fn make_owned<B: ToOwned + ?Sized>(c: Cow<'_, B>) -> B::Owned {
    match c {
        Cow::Borrowed(b) => b.to_owned(),   // ToOwned builds the owned form
        Cow::Owned(o) => o,                 // already there
    }
}

That’s the full answer to “why does Cow require B: ToOwned?” — without it, Cow couldn’t name its owned half nor build it on demand.

Signatures to know

// ToOwned — generalized Clone across type boundaries
pub trait ToOwned {
    type Owned: Borrow<Self>;       // the owned form must borrow BACK to Self
    fn to_owned(&self) -> Self::Owned;
}

// Borrow — view owned as borrowed, with Eq/Ord/Hash transparency
pub trait Borrow<Borrowed: ?Sized> {
    fn borrow(&self) -> &Borrowed;
}

// HashMap::get — the single most important real-world use
fn get<Q>(&self, k: &Q) -> Option<&V>
where
    K: Borrow<Q>,        // the stored key can be viewed as Q
    Q: Hash + Eq + ?Sized // Q = str is unsized; only touched behind &Q

Capstone insight

The structural insight from building MyBorrow + MyToOwned + MyCow from scratch: MyToOwned::Owned carries a MyBorrow<Self> bound — the owned type must borrow back to Self. That round-trip guarantee is exactly what lets MyCow::borrow() return &B from the Owned variant:

trait MyToOwned {
    type Owned: MyBorrow<Self>;
    fn my_to_owned(&self) -> Self::Owned;
}

impl<'a, B: MyToOwned + ?Sized> MyCow<'a, B> {
    fn borrow(&self) -> &B {
        match self {
            Self::Borrowed(b) => b,
            Self::Owned(o) => o.my_borrow(),   // MyBorrow<Self> makes this possible
        }
    }
}

Without the Owned: MyBorrow<Self> bound, the Owned arm couldn’t produce a &B — there’d be no trait method to call. And Self: ?Sized being the default in trait defs is why impl MyToOwned for str (an unsized type) is even legal.

Explain it back

• Why can’t str just impl Clone to produce a String? (Clone is &T -> T, same type; str -> String needs the differing Owned associated type.)
• What exactly is the Borrow contract, and what breaks if you violate it?
• Why is the bound K: Borrow<Q> and not Q: Borrow<K>?
• In T::Owned, why can’t the return type just be T?
• Why does Cow<B> require B: ToOwned? Name both reasons (name it / build it).
• When do you pick AsRef<T> over Borrow<T> for a function argument?

See also

• Cow — this note closes the loop opened there; Cow is built directly on ToOwned and Borrow.
• Drop & Ordering — mem::replace, used internally by Cow::to_mut(), is covered in depth there.

Drop & Ordering

Ladder: src/bin/drop_ordering.rs · Run: cargo run --bin drop_ordering · Phase 1 · 9 rungs

TL;DR

When a value goes out of scope, Rust runs its destructor automatically — no GC, no free(), no forgetting. The Drop trait gives you a hook into that moment. The real depth is in ordering: locals drop in reverse declaration order (LIFO), struct fields drop in declaration order (FIFO), and the compiler inserts hidden drop flags so a conditionally-moved value is dropped exactly once. mem::forget, mem::replace, and ManuallyDrop give you escape hatches when the defaults don’t fit. The payoff is RAII: tie any cleanup action to a scope, and it runs on every exit path — normal return, early return, or panic.

Why this exists (from first principles)

C gives you malloc/free and hopes you pair them. C++ gives you destructors but lets you misuse them (double free, use after free). Garbage collectors solve the pairing problem but add latency spikes and can’t manage non-memory resources (file handles, locks, network connections) without finalizers that run “sometime, maybe.”

Rust’s answer: ownership determines cleanup. Every value has exactly one owner. When that owner’s scope ends, the value is dropped — deterministically, immediately, in a well-defined order. The Drop trait is the hook that lets you run code at that moment.

This determinism is what makes RAII (Resource Acquisition Is Initialization) a first-class pattern: a MutexGuard unlocks on drop, a File flushes and closes, a TempDir deletes itself. The compiler guarantees the cleanup runs, and ownership guarantees it runs exactly once.

But “exactly once, in a well-defined order” means you need to know that order. And you need tools for the cases where the default order is wrong, or where you want to skip the destructor entirely. That’s what this ladder teaches.

The ladder at a glance

The ideas, built up

Drop fires at scope end — and you don’t call it

The Drop trait has one method:

impl Drop for Noisy {
    fn drop(&mut self) {
        log(format!("drop {}", self.name));
    }
}

The compiler inserts a call to this at the end of the owning scope. You never call drop() yourself — in fact, x.drop() is a hard compiler error (E0040: explicit use of destructor method). The reason: after your drop(&mut self) body runs, the compiler still drops each field. If you could call .drop() on a live binding, the automatic scope-end drop would run the destructor again — double free. So the compiler forbids the direct call entirely.

To drop early, you use the free function std::mem::drop(x), which takes x by value. Ownership moves into drop(), the value dies at the end of that tiny function, and x is now moved-from — using it again is a compile error. That’s the mechanism that prevents double free: not a runtime check, but a move.

Two orderings to memorize

Here is where people get confused, because locals and struct fields follow opposite rules:

The ladder makes this concrete with Pair { id, a: Noisy, b: Noisy }:

impl Drop for Pair {
    fn drop(&mut self) {
        log(format!("drop pair {}", self.id));
    }
}

Dropping a Pair produces: ["drop pair P", "drop a", "drop b"]. The container’s body runs first (while fields are still alive — you can read them in your drop()), then fields drop in declaration order: a before b.

This is the opposite of locals. If you declared let a; let b; in a function, you’d get b before a. But if a and b are fields, you get a before b.

Why the container drops first: Your Drop impl gets &mut self, meaning it can still read all the fields. If fields dropped first, your drop() body would be reading dangling references. So the container must go first.

Drop flags: the compiler’s runtime bookkeeping

Consider this:

fn conditional_move(take_it: bool) -> Vec<String> {
    let x = Noisy::new("x");
    if take_it {
        consume(x);  // x moved into consume, drops there
    }
    // scope end: does x need dropping?
}

When take_it is true, x is moved into consume() and drops inside it. When false, x is still alive at scope end and drops there. Either way, x drops exactly once. But the compiler can’t know at compile time which branch ran.

The solution: a hidden boolean on the stack — a drop flag — next to x. It starts as “needs dropping.” When x is moved, the flag is cleared. At scope end, the compiler checks the flag and only drops if it’s still set.

You never write this flag. You never see it. But it’s there, and it’s how Rust guarantees “exactly once” even across conditional control flow. The cost is one byte and one branch per conditionally-moved value — cheap insurance against double free or leak.

forget, replace, take: bending the rules

Three std::mem functions that give you manual control over when (or whether) destructors run:

mem::forget(x) — moves x in and does not drop it. The destructor never runs; the value leaks. This is safe (leaking memory isn’t undefined behavior in Rust), and it’s how you hand ownership to something that will clean up later (FFI, ManuallyDrop, or intentional leaks like Box::leak).

let x = Noisy::new("leaked");
std::mem::forget(x);
// log is EMPTY — "drop leaked" never appears

mem::replace(&mut dst, new) — swaps new into the location behind a mutable reference and returns the old value. This is the only way to move a non-Copy value out of &mut self. You can’t write let v = self.field; — that would move out of a borrow (E0507). You have to swap something in to take something out:

impl Slot {
    fn swap_in(&mut self, replacement: Noisy) -> Noisy {
        std::mem::replace(&mut self.inner, replacement)
    }
}

mem::take(&mut dst) is replace with Default::default() as the replacement. It’s the idiomatic way to pull a value out of an Option, a Vec, or anything with a sensible default.

The key insight: replace and take don’t drop anything. They relocate the old value into your hands. You decide when (or whether) it drops.

RAII scope guard: the reason Drop exists

The killer application of Drop is tying a cleanup action to a scope. A Guard owns a closure and runs it when dropped — no matter how the scope exits:

struct Guard<F: FnOnce()> {
    action: Option<F>,
}

impl<F: FnOnce()> Drop for Guard<F> {
    fn drop(&mut self) {
        if let Some(action) = self.action.take() {
            action();
        }
    }
}

There’s a real puzzle here. drop() receives &mut self, but an FnOnce closure must be called by value (consumed). You can’t move self.action out of a mutable reference — that’s E0507 again. The solution is the rung-6 trick: store the closure in an Option<F> and .take() it (which is mem::replace with None). Now you have an owned F you can call.

.cancel() disarms the guard: set self.action = None before the scope ends, and drop() finds nothing to run.

impl<F: FnOnce()> Guard<F> {
    fn cancel(mut self) {
        self.action = None;
    }
}

This is exactly how MutexGuard, File, scopeguard::defer!, and every “undo on error” pattern works.

ManuallyDrop: suppressing the compiler’s destructor

ManuallyDrop<T> wraps a value and tells the compiler: do not drop this automatically. The wrapped value will leak unless you explicitly call the unsafe ManuallyDrop::drop(&mut md).

Why it exists: it’s the only way to override the fixed field-drop order. Normally fields a, b drop in declaration order (a then b). With ManuallyDrop, you take control:

struct Custom {
    a: ManuallyDrop<Noisy>,
    b: ManuallyDrop<Noisy>,
}

impl Drop for Custom {
    fn drop(&mut self) {
        // SAFETY: dropping each field exactly once, never used afterward.
        unsafe {
            ManuallyDrop::drop(&mut self.b);  // b first
            ManuallyDrop::drop(&mut self.a);  // then a
        }
    }
}

This produces ["drop b", "drop a"] — the reverse of the default. The unsafe is genuine: calling ManuallyDrop::drop twice on the same field is undefined behavior (double free). You must uphold the invariant that each field is dropped exactly once and never read afterward.

ManuallyDrop is also how Vec manages element drops internally — it wraps its allocation in ManuallyDrop so it can drop elements one by one in its own Drop impl, rather than relying on the compiler’s default.

Capstone: rollback-on-drop Transaction

The ladder’s synthesis rung combines everything into a pattern used by every database driver, every temp-file-unless-kept, every undo-on-error mechanism:

struct Transaction<'a> {
    db: &'a mut Vec<String>,
    added: usize,
    committed: bool,
}

The pieces:

• begin(db) — borrows the database mutably, starts with 0 rows added and committed: false.
• insert(row) — pushes the row onto db and increments added.
• commit(mut self) — sets self.committed = true. Takes self by value, so the guard is consumed and drop() runs with the flag set.
• Drop — if !self.committed, pops self.added rows back off and logs "rollback". If committed, does nothing.

impl Drop for Transaction<'_> {
    fn drop(&mut self) {
        if !self.committed {
            for _ in 0..self.added {
                self.db.pop();
            }
            log("rollback");
        }
    }
}

The committed field is a hand-written drop flag. commit() sets it to true, disarming the rollback — exactly like Guard::cancel() from rung 7. The difference: here the state mutation (the inserts) happens eagerly, and rollback undoes it, whereas the guard defers the action entirely.

The critical test: rollback fires during panic unwinding too. A catch_unwind around a panicking transaction proves the rows are rolled back even on the exceptional path. This is the whole point of RAII — cleanup on every exit, not just the happy path.

Footguns

• Assuming locals and fields drop in the same order. They don’t. Locals are LIFO (reverse declaration); fields are FIFO (declaration order). Getting this wrong causes subtle resource-ordering bugs (e.g., dropping a lock guard before the data it protects).

• Calling x.drop() directly. The compiler forbids it (E0040). Use std::mem::drop(x) instead — it moves x by value, so ownership transfer prevents double free.

• Forgetting that mem::forget is safe. It doesn’t cause UB, but it does leak. Any cleanup you rely on (flushing buffers, releasing locks, temp file deletion) is skipped. Code must be correct even if Drop never runs — that’s why mem::forget being safe is a design choice, not a bug.

• Moving out of &mut self in drop(). You can’t do let f = self.field; because drop() only gets a mutable borrow. The workaround is Option::take() (which is mem::replace with None) to get an owned value you can consume.

• Double ManuallyDrop::drop. Unlike everything else on this list, this is undefined behavior. Once you call ManuallyDrop::drop(&mut md), the inner value is gone. Calling it again is a double free. There’s no compiler protection here — you’re in unsafe territory.

Signatures to know

// The Drop trait — one method, &mut self, no return
trait Drop {
    fn drop(&mut self);
}

// Free function: takes ownership, value dies at end
fn std::mem::drop<T>(x: T) {}

// Leak: takes ownership, destructor is skipped
fn std::mem::forget<T>(x: T) {}

// Swap a new value in, get the old one back
fn std::mem::replace<T>(dest: &mut T, src: T) -> T

// replace with Default::default()
fn std::mem::take<T: Default>(dest: &mut T) -> T

// Wrapper that suppresses automatic drop
struct ManuallyDrop<T> { /* ... */ }
impl<T> ManuallyDrop<T> {
    fn new(value: T) -> Self;
    unsafe fn drop(slot: &mut ManuallyDrop<T>);
}

Real-world patterns

Explain it back

• Why are locals dropped in reverse order but struct fields in declaration order?
• Why does x.drop() produce a compiler error, and what do you use instead?
• What is a drop flag, and when does the compiler insert one?
• Is mem::forget safe? Why or why not — and what are the consequences?
• How do you move a value out of &mut self inside a drop() implementation?
• What happens if you call ManuallyDrop::drop twice on the same field?
• In the Transaction capstone, what happens if commit() is never called and the scope exits via panic?
• Why does the Guard’s action field need to be Option<F> rather than just F?

See also

• Cow — uses mem::replace internally for the to_mut() upgrade
• Borrow / ToOwned — the MyCow capstone also hits the “move out of enum variant” pattern

Lifetimes in depth

Ladder: src/bin/lifetimes_depth.rs · Run: cargo run --bin lifetimes_depth · Phase 1 · 9 rungs

TL;DR

A lifetime label like 'a does not create, extend, or change the life of anything. It is a name you attach to references so the compiler can check one single rule:

A reference must never outlive the data it points to.

<'a> on a function is a generic parameter — just over a lifetime instead of a type. Its whole job is to describe how an output borrow is connected to the input borrows, so the compiler can prove the returned reference is still valid at every call site. You are not telling the compiler how long things live; you are telling it which borrows share a fate.

Why this exists (from first principles)

Rust has no garbage collector. A reference (&T) is just a pointer — it does not keep the pointed-to data alive. So the danger is the dangling reference: a pointer to memory that has already been freed. C and C++ let you write this and hand you undefined behavior at runtime. Rust refuses to compile it.

To refuse it, the borrow checker needs to reason about spans of validity. Most of the time it figures these out on its own. But at function and struct boundaries the information is lost: a signature is a contract, and the compiler only sees the signature, not the body, when checking a call. Consider:

fn longest(a: &str, b: &str) -> &str { /* ... */ }   // WRONG: won't compile

When some other code calls longest(&x, &y), how long is the returned &str valid? It depends on whether the body returns a or b — but the caller can’t see the body, and the compiler refuses to peek (that would make signatures meaningless and changes to a body could silently break callers). So the signature must carry the answer. Lifetimes are that missing piece of the contract:

fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {   // OK
    if a.len() > b.len() { a } else { b }
}

Read it as: “for some lifetime 'a, both inputs are borrowed for at least 'a, and the result is valid for 'a.” At a call site the compiler picks 'a to be the overlap of the two input borrows, and guarantees the result doesn’t escape that overlap. No runtime cost — this is all erased before codegen.

The ladder at a glance

The ideas, built up

1. One lifetime ties inputs to output (longest)

The annotation <'a>(a: &'a str, b: &'a str) -> &'a str does not mean “a and b live equally long.” It means: the compiler will choose a single 'a that is no longer than either input’s actual borrow, and promise the output lives that long. The check that makes this sound:

let s1 = String::from("a long string");
let result;
{
    let s2 = String::from("short");
    result = longest(&s1, &s2);   // 'a = the shorter of the two borrows = s2's scope
    assert_eq!(result, "a long string");
}   // s2 dropped here; using `result` past this point would be rejected

'a collapses to the smaller region (here s2’s scope), and the borrow checker ties result to it. That is the entire mechanism: lifetimes are constraints the compiler solves, not durations you assign.

2. Elision — the rules that let you omit lifetimes (first_word)

You rarely write 'a because the compiler applies three elision rules, in order, to fill them in:

1. Each elided input reference gets its own fresh lifetime.
2. If there is exactly one input lifetime, it is assigned to all outputs.
3. If one input is &self / &mut self, its lifetime goes to all outputs.

If after these an output lifetime is still unknown, you get a hard error.

Rule 1 + rule 2 are why this needs no annotation — one input ref, so the output is unambiguous:

fn first_word(s: &str) -> &str {            // elided to fn first_word<'a>(s: &'a str) -> &'a str
    let first_space = s.find(' ').unwrap_or(s.len());
    &s[..first_space]
}

Where elision runs out: two input refs, no &self. Rule 2 doesn’t apply, rule 3 doesn’t apply, so the compiler cannot guess which input the output borrows from:

fn prefix_before(text: &str, marker: &str) -> &str   // WRONG: missing lifetime specifier

The fix is the real lesson — only annotate what flows to the output. Only text is returned, so only text gets the named lifetime. Leave marker with its own elided one:

fn prefix_before<'a>(text: &'a str, marker: &str) -> &'a str {   // OK
    let first = text.find(marker).unwrap_or(text.len());
    &text[..first]
}

This is a habit worth keeping: tying marker to 'a too would over-constrain every caller for no reason. Give the output’s source a name; let everything else elide.

3. Structs that hold references (Excerpt<'a>)

A struct that stores a reference must declare a lifetime and tag the field:

struct Excerpt<'a> {
    part: &'a str,
}

The new rule this buys: an Excerpt value may never outlive the str it borrows from. The lifetime parameter makes the struct generic over how long its borrow is good for, and the borrow checker enforces that the whole struct dies before the borrowed data does.

The constructor uses '_, the inferred lifetime:

fn first_sentence(text: &str) -> Excerpt<'_> {   // '_ = "infer it" -> tied to text by elision
    let dot = text.find('.').unwrap_or(text.len());
    let offset = if dot == text.len() { 0 } else { 1 };
    Excerpt { part: &text[..dot + offset] }
}

Excerpt<'_> reads as “an Excerpt borrowing for some lifetime the compiler will infer” — here, by elision, the lifetime of text. Writing Excerpt<'a> with an explicit <'a> on the fn would mean the same thing.

4. Methods, and the &self gotcha (impl<'a>)

To add methods, you declare the lifetime after impl and use it on the type — exactly like impl<T> Vec<T>:

impl<'a> Excerpt<'a> {
    fn part(&self) -> &str { self.part }   // rule 3: return tied to &self, no annotation needed
}

The gotcha appears the moment the return can come from a parameter instead of self. Elision rule 3 has already tied the elided return to &self, so a returned parameter is rejected — its lifetime is unrelated to &self:

// WRONG: returning `candidate` fails — its lifetime isn't tied to &self
fn longer_of(&self, candidate: &str) -> &str {
    if self.part.len() > candidate.len() { self.part } else { candidate }
}

The fix is to give self.part (which is &'a str — actually &'b self here) and candidate the same lifetime and return that:

fn longer_of<'b>(&'b self, candidate: &'b str) -> &'b str {   // OK
    if self.part.len() > candidate.len() { self.part } else { candidate }
}

Now both possible return sources provably share one lifetime, so either branch is valid. The general principle: when a method’s return may come from a parameter, elision’s default (tie to &self) is wrong — name a lifetime and share it.

5. The dangling-return footgun (make_label / after_slash)

This is the defining lifetime error. A function may only return a reference to data that outlives the call — i.e. data the caller owns. It cannot return a reference to a local, because the local is dropped at the closing brace and the reference would dangle:

// WRONG (E0515: cannot return reference to local variable `label`)
fn make_label(id: u32) -> &str {
    let label = format!("item-{id}");
    &label                              // label dies here; &label can't escape
}

There is no lifetime annotation that fixes this — the data genuinely doesn’t live long enough. The honest fix is to return owned data:

fn make_label(id: u32) -> String {     // OK: hand back ownership
    format!("item-{id}")
}

The contrast that makes it click: returning a slice of a parameter is fine, because the caller owns it and it outlives the call:

fn after_slash(haystack: &str) -> &str {   // OK: result borrows the caller's data
    match haystack.find('/') {
        Some(i) => &haystack[i + 1..],
        None => "",
    }
}

Rule of thumb: you can borrow out of what was borrowed in; you cannot borrow out of what you made locally. If you made it, return it (move it out).

6. 'a: 'b outlives bounds (or_default / store)

Syntax: 'a: 'b is a bound meaning “'a outlives 'b” — 'a lasts at least as long as 'b. It sits in the same slot as a trait bound T: Clone, but for lifetimes. It is what lets the compiler treat a longer-lived &'a T as a shorter &'b T (covariance, made explicit).

When you return the 'a reference where a 'b is promised, you must assert the relationship or the compiler refuses (“lifetime ’a may not live long enough”):

fn or_default<'a: 'b, 'b>(primary: &'a str, fallback: &'b str) -> &'b str {   // OK
    if !primary.is_empty() { primary } else { fallback }
}

Where the bound is unavoidable — you can’t unify the two lifetimes because they appear in different positions. store overwrites what a slot points at:

fn store<'a: 'b, 'b>(slot: &mut &'b str, value: &'a str) {   // OK
    *slot = value;   // dropping a &'a into a &'b slot requires 'a to last >= 'b
}

The slot holds a &'b str, so anything written into it must live at least as long as 'b. Without 'a: 'b the assignment is rejected. The lesson: when one reference is stored where another lives, you often need to spell out which one contains the other.

7. Lifetimes + generics + 'static (longest_with_announcement / leak_label)

Lifetime params and type params share one <...> list, lifetimes first. They don’t interfere — 'a constrains borrows, T constrains a type:

fn longest_with_announcement<'a, T>(x: &'a str, y: &'a str, ann: T) -> &'a str
where
    T: Display,
{
    println!("Announcing: {}", ann);
    if x.len() > y.len() { x } else { y }
}

'static is the lifetime that lasts the whole program. A &'static str borrows data that never goes away — string literals are baked into the binary. Rung 5 gave one escape from “can’t borrow out a local” (return owned). Here is the other one: deliberately leak the allocation so it lives forever, yielding a genuine &'static str:

fn leak_label(id: u32) -> &'static str {
    let label = format!("id-{}", id);
    Box::leak(label.into_boxed_str())   // never freed -> valid for 'static
}

Caution: Box::leak is a real, permanent memory leak. It’s the right tool for values that truly live for the program’s duration (config, interned strings), not a way to dodge the borrow checker in a loop.

Worth distinguishing: &'static T (“this reference is valid forever”) vs T: 'static (“this type contains no borrow shorter than the program” — which includes all owned types like String). They are not the same constraint.

8. A borrowing iterator (Words<'a>)

Words walks a string and yields each whitespace-separated word as a &str that borrows the original string — exactly how str::split and slice::iter hand out references without cloning. The crux is the Item lifetime:

struct Words<'a> { remainder: &'a str }

impl<'a> Iterator for Words<'a> {
    type Item = &'a str;   // borrows the STRING (lifetime 'a), NOT &mut self

    fn next(&mut self) -> Option<Self::Item> {
        let trimmed = self.remainder.trim_start_matches(' ');
        if trimmed.is_empty() { return None; }
        let word = match trimmed.find(' ') {
            Some(i) => { self.remainder = &trimmed[i + 1..]; &trimmed[..i] }
            None    => { self.remainder = "";              trimmed       }
        };
        Some(word)
    }
}

Read the signature carefully. &mut self is borrowed only for the duration of one next() call. But the &str we return points into the underlying string (lifetime 'a), which lives much longer than a single call. So Item must be &'a str, tied to the string — not to &mut self.

That choice is what makes this work:

let mut it = Words::new(&text);
let first = it.next().unwrap();    // holds a word...
let second = it.next().unwrap();   // ...across another next() call — compiles!
assert_eq!((first, second), ("the", "quick"));

If Item were tied to &mut self, first would borrow the iterator and the second next() (another &mut) would be a borrow-conflict — you could never keep a yielded item past the next iteration, and .collect::<Vec<&str>>() would be impossible. Tie Item to the data, not the cursor.

9. Capstone: StrSplit with two lifetimes

Build your own "a,b,c".split(",") that never allocates — every yielded piece is a &str slice into the original haystack. The structural insight is two distinct lifetimes:

struct StrSplit<'haystack, 'delimiter> {
    remainder: Option<&'haystack str>,
    delimiter: &'delimiter str,
}

impl<'haystack, 'delimiter> Iterator for StrSplit<'haystack, 'delimiter> {
    type Item = &'haystack str;   // items borrow the HAYSTACK, never the delimiter

    fn next(&mut self) -> Option<Self::Item> {
        let remainder = self.remainder.as_mut()?;   // None -> already exhausted
        match remainder.find(self.delimiter) {
            Some(i) => {
                let current = *remainder;
                let piece = &current[..i];
                *remainder = &current[i + self.delimiter.len()..];   // skip the whole delimiter
                Some(piece)
            }
            None => self.remainder.take(),   // last piece; mark exhausted in one move
        }
    }
}

Why two lifetimes. The yielded pieces borrow 'haystack. They do not borrow 'delimiter — once we’ve located a delimiter we keep no reference to it in the output. Keeping the lifetimes separate lets a caller pass a short-lived delimiter (even a temporary that drops before the results are used) and still keep the pieces:

let haystack = String::from("x-y-z");
let result: Vec<&str>;
{
    let delim = String::from("-");
    result = StrSplit::new(&haystack, &delim).collect();
}   // delim dropped here — result is still valid, because pieces borrow haystack
assert_eq!(result, vec!["x", "y", "z"]);

Collapsing both into one lifetime would over-constrain every caller — the same lesson as rung 2b and rung 6, now at struct scale: give each borrow its own lifetime; only unify when the data flow actually demands it.

Why remainder: Option<&str> and not just &str. To distinguish “more to yield, possibly an empty final field” from “fully exhausted.” Splitting "a," on "," must yield ["a", ""] — a trailing empty piece — and then stop. The Option lets next hand out that last "" once via .take() (which returns Some(last) and sets the field to None), and return None forever after.

Footguns

• Thinking 'a extends a life. It never does. It only names a borrow so the compiler can relate borrows. The compiler picks 'a to be the overlap of the inputs — the shortest region, not the longest.
• Over-annotating. Tying every reference to one 'a (e.g. marker in prefix_before, or merging 'haystack/'delimiter) compiles but needlessly restricts callers. Name only the borrow that flows to the output.
• The &self return trap. Elision rule 3 ties an elided return to &self. If the method can return a parameter, you must introduce a shared lifetime — the default will reject the parameter branch.
• Returning a reference to a local (E0515). No annotation fixes this; the data dies at the brace. Return owned data, or Box::leak for genuine &'static.
• Tying an iterator’s Item to &mut self. You then can’t hold an item across the next next() call, and .collect() breaks. Tie Item to the underlying data’s lifetime instead.
• Box::leak as a borrow-checker dodge. It’s a permanent leak. Fine for program-lifetime data; a bug inside a loop or per-request path.

Real-world patterns

• str::split / slice::iter are exactly the Words / StrSplit shape: zero-copy iterators whose Item borrows the source, not the cursor.
• Parsers and tokenizers lean on multi-lifetime structs so tokens can borrow the input buffer while transient state (delimiters, config) lives shorter.
• Cow<'a, str> (see Cow) carries a lifetime for its borrowed variant — the same struct holds a reference rule as Excerpt<'a>.
• 'a: 'b outlives bounds show up whenever you store one reference into a place that already holds another (caches, slot updates, builder APIs).
• T: 'static bounds are everywhere in std::thread::spawn and trait objects (Box<dyn Error + 'static>) — “this value carries no borrow that could dangle.”

Capstone insight

A reference-holding iterator has two clocks: the borrow of &mut self during one next() call, and the borrow of the data it yields. The whole design hinges on tying Item to the data clock, not the call clock. Generalize that to StrSplit and you see lifetimes are a dependency graph between borrows: give each borrow its own lifetime parameter, then add only the edges ('a: 'b, or shared names) the data flow forces. Under-constrain and it won’t compile; over-constrain and your callers suffer. Lifetimes are the language for drawing exactly that graph — no more, no less.

Explain it back

• Why does longest need 'a but first_word doesn’t? Which elision rules cover first_word?
• What does the compiler actually pick 'a to be at a call site — the longer or the shorter input borrow, and why?
• Why does returning candidate from longer_of(&self, candidate) fail under elision, and what’s the minimal fix?
• Why can after_slash return a &str but make_label cannot? What are the two escape hatches?
• What does 'a: 'b mean, and give a case where it’s unavoidable.
• In Words, why is type Item = &'a str and not tied to &mut self? What breaks if you get it wrong?
• In StrSplit, why two lifetimes instead of one, and why is remainder an Option?
• &'static str vs T: 'static — what’s the difference?

See also

• Cow — Clone-on-Write — a lifetime-carrying enum over borrowed/owned.
• Borrow / ToOwned — borrowed-vs-owned views, the Cow loop.
• Drop & Ordering — when the data a reference points at dies.

HRTB — for<'a>

Ladder: src/bin/hrtb.rs · Run: cargo run --bin hrtb · Phase 1 · 9 rungs

TL;DR

A higher-ranked trait bound moves the quantifier on a lifetime. The two bounds look almost identical but mean opposite things:

fn f<'a, F: Fn(&'a str)>(g: F)      // the CALLER picks one 'a; bound holds for THAT one
fn f<F: for<'a> Fn(&'a str)>(g: F)  // bound holds for EVERY 'a; the CALLEE picks fresh per call

for<'a> reads literally as “for all lifetimes 'a”. You need it whenever a value — almost always a closure or a trait impl — must work on a borrow whose lifetime doesn’t exist yet at the point you write the bound: a reference you’ll create inside your function and hand off, where the caller could never name its lifetime.

You have used HRTB for years without seeing it: Fn(&str) -> &str already desugars to for<'a> Fn(&'a str) -> &'a str. Elision writes the quantifier for you almost everywhere. This ladder is about the handful of places where it can’t, and where reading the explicit form is the only way to understand the error.

Why this exists (from first principles)

Start from the lifetime contract. A normal generic lifetime is chosen by the caller, at the call site:

fn longest<'a>(a: &'a str, b: &'a str) -> &'a str { /* ... */ }

When some code calls longest(&x, &y), the compiler picks 'a to be the overlap of those two specific borrows. 'a is one concrete region, fixed once, from the outside.

Now flip the direction. Suppose you are the one who will create the reference, deep inside your own function, and you want to accept a callback that operates on it:

fn run_on_local<F>(f: F) -> usize
where
    F: Fn(&str) -> &str,   // what lifetime is this &str?
{
    let s = String::from("hello world");   // born HERE, inside the function
    f(&s).len()                            // f operates on a borrow the caller can't see
}

The borrow &s has a lifetime that lasts only until the closing brace. The caller of run_on_local has no way to name it — it doesn’t exist at the call site. So a caller-chosen <'a> is fundamentally the wrong tool: there is no single 'a the caller could supply that would cover a string born after they called you.

The fix is to demand that f works for all lifetimes, so it certainly works for the private one you’ll mint internally. That demand is for<'a>:

where F: for<'a> Fn(&'a str) -> &'a str

The mental model in one line: a plain <'a> is a lifetime the caller fills in; for<'a> is a lifetime the callee fills in, freshly, every time it uses the value.

This is not an exotic corner. It is why Fn traits are defined with it implicitly, why serde’s DeserializeOwned exists, and why every parser-combinator library in Rust can compose at all. The bound is the load-bearing wall; you just rarely see it because elision plasters over it.

The ladder at a glance

The ideas, built up

1. The quantifier is already there (apply_to_each)

The first surprise is that you have been writing HRTB all along. This bound has no named lifetime at all:

fn apply_to_each<F>(items: &[String], f: F)
where
    F: Fn(&str),          // implicitly: for<'a> Fn(&'a str)
{
    for item in items {
        f(item);          // each &str lives only for this iteration
    }
}

Inside the loop, each item is borrowed for the span of one iteration. The closure must accept a &str of whatever lifetime each iteration produces — and it does, because Fn(&str) secretly means for<'a> Fn(&'a str): “works for every input lifetime.” The check feeds it borrows that only live one loop turn, and a closure capturing a RefCell records their lengths. Nothing forces you to think about lifetimes here precisely because the quantifier was inserted for you.

2. Spell it out (apply_to_each_explicit)

for<'a> is a real slot in the grammar — it sits immediately before the trait name and introduces a lifetime scoped to that one bound:

fn apply_to_each_explicit<F>(items: &[String], f: F)
where
    F: for<'a> Fn(&'a str),   // identical to Fn(&str) above
{ /* same body */ }

The 'a here is not a generic parameter of the function — notice it does not appear in <F>. It is bound by the trait bound itself. That scoping is the whole point: it is a lifetime the function body gets to instantiate, not one the caller supplies. The elided and explicit forms compile to exactly the same thing.

3. Returning a borrow forces the issue (measure_on_local)

Rung 1 took a borrow; this one returns one, which is where the caller-vs-callee distinction becomes load-bearing:

fn measure_on_local<F>(f: F) -> usize
where
    F: for<'a> Fn(&'a str) -> &'a str,   // same 'a in and out: output welded to input
{
    let s = String::from("hello world");
    let result = f(&s);   // &s lives only inside this function
    result.len()
}

Two things to read carefully:

• The -> &'a str reuses the same 'a as the input. That is what makes returning a borrow sound: the output is allowed to borrow the input and nothing else, so it can’t outlive it.
• s is born and dies inside measure_on_local. The lifetime of &s is private to this call. The caller cannot name it. So the bound must be higher-ranked — f has to promise it works for every lifetime, including this internal one.

The closures in the check pass inline, which matters (see rung 5):

let n = measure_on_local(|s: &str| s.split(' ').next().unwrap_or(""));  // first word
assert_eq!(n, 5);                                                        // "hello"
assert_eq!(measure_on_local(|s: &str| s), 11);                           // identity -> "hello world"

4. HRTB on your own trait (Slicer<'a>)

for<'a> is not special to Fn. It applies to any trait with a lifetime parameter:

trait Slicer<'a> {
    fn slice(&self, input: &'a str) -> &'a str;
}

struct FirstWord;
impl<'a> Slicer<'a> for FirstWord {
    fn slice(&self, input: &'a str) -> &'a str {
        input.split(' ').next().unwrap_or("")
    }
}

The key reframe: Slicer<'a> is not one trait, it’s a family of traits — one per lifetime. Writing impl<'a> Slicer<'a> for FirstWord implements every member of that family in a single stroke. And the bound that asks for the whole family is exactly for<'a> Slicer<'a>:

fn run_slicer<S>(s: S) -> usize
where
    S: for<'a> Slicer<'a>,   // S implements Slicer<'a> for ALL 'a
{
    let word = String::from("green eggs");
    s.slice(&word).len()     // &word is local -> needs the "for all 'a" guarantee
}

The ladder scaffolds this with a deliberately wrong placeholder bound (S: Slicer<'static>) that compiles only while the body is todo!(). The moment you write s.slice(&word) on a local, the compiler rejects 'static and forces you to generalize to for<'a> Slicer<'a>. The error is the lesson.

5. “implementation of Fn is not general enough” (apply_str)

This is the single most-cursed HRTB error, and it has a precise cause. In rung 3 the closures worked because they were passed inline. Factor a reference-returning closure into a let binding and it breaks:

fn apply_str<F>(f: F) -> usize
where
    F: for<'a> Fn(&'a str) -> &'a str,
{
    let s = String::from("scaffold");
    f(&s).len()
}

// WRONG: "implementation of `Fn` is not general enough"
let bad = |s: &str| s;
apply_str(bad);

Why does the identical closure fail when named? When a closure is bound to a let without a guiding context, type inference picks one concrete lifetime for its signature. A closure inferred as Fn(&'0 str) -> &'0 str for some specific '0 does not satisfy for<'a> — it is general over one lifetime, not all of them. When passed inline, the expected higher-ranked type propagates into inference and the closure is inferred higher-ranked from the start.

The fixes, and why they work:

// OK (i): fn-pointer coercion — fn pointers are inherently for<'a>
let good: fn(&str) -> &str = |s| s;
apply_str(good);

// OK (ii): a real fn item — fn items are inherently for<'a> too
fn id(s: &str) -> &str { s }
let good = id;
apply_str(good);

The rule to remember: only closures get a single inferred lifetime that can break HRTB. Function pointers (fn(&str) -> &str) and named fn items are always higher-ranked. Passing a closure inline usually also works, because the expected type guides inference.

6. The named-lifetime trap (sum_two_locals)

Rung 5 was a closure that wasn’t general enough. This is the dual: a bound you wrote that isn’t general enough, because you reached for a single named lifetime where you needed a higher-ranked one.

// WRONG: one named 'a, chosen by the caller, shared across every use of f
fn sum_two_locals<'a, F>(f: F) -> usize
where
    F: Fn(&'a str) -> &'a str,
{
    let s1 = String::from("ab");
    let s2 = String::from("cdef");
    f(&s1).len() + f(&s2).len()   // ERROR: borrowed value does not live long enough
}

The 'a in <'a, F> is a free parameter chosen by the caller, so it must outlive the entire function body. But s1 and s2 are locals that die inside it. One fixed 'a cannot cover either — let alone two borrows in different inner scopes.

The fix is to make each call mint its own lifetime:

fn sum_two_locals<F>(f: F) -> usize
where
    F: for<'a> Fn(&'a str) -> &'a str,   // OK: callee picks a fresh, short 'a per call
{
    let s1 = String::from("ab");
    let s2 = String::from("cdef");
    f(&s1).len() + f(&s2).len()          // each call gets its own 'a
}

The distinction this rung adds over rung 3: a single <'a> isn’t merely “caller-chosen”, it is one lifetime shared by every call to f. for<'a> gives each call site its own. Two locals in two scopes makes that concrete — no single 'a fits both, but “for all 'a” fits each.

7. DecodeOwned = for<'de> Decode<'de> (the serde pattern)

Now the payoff: a higher-ranked bound doing real work in the most-used crate in the ecosystem. serde has two traits:

pub trait Deserialize<'de> { /* may BORROW from the input (zero-copy) */ }

pub trait DeserializeOwned: for<'de> Deserialize<'de> {}
impl<T> DeserializeOwned for T where T: for<'de> Deserialize<'de> {}

DeserializeOwned is defined as “can be deserialized from input of any lifetime.” The ladder builds the miniature, where Decode<'a> plays the role of Deserialize<'de>:

trait Decode<'a>: Sized {
    fn decode(input: &'a str) -> Option<Self>;
}

trait DecodeOwned: for<'a> Decode<'a> {}
impl<T> DecodeOwned for T where T: for<'a> Decode<'a> {}

The two contrasting impls are the whole point:

// BORROWS from input -> Decode<'a> only for the ONE matching 'a
struct Borrowed<'a> { first: &'a str }
impl<'a> Decode<'a> for Borrowed<'a> {
    fn decode(input: &'a str) -> Option<Self> {
        input.split(',').next().map(|first| Borrowed { first })
    }
}

// OWNS its data -> Decode<'a> for EVERY 'a
struct Owned { sum: u32 }
impl<'a> Decode<'a> for Owned {
    fn decode(input: &'a str) -> Option<Self> { /* parse + sum the csv */ }
}

Borrowed<'a> ties Self to the input lifetime, so it implements Decode<'a> for exactly one 'a — it is not for<'a> Decode<'a>, therefore not DecodeOwned. Owned keeps a u32 that borrows nothing, so it implements Decode<'a> for all 'a and is DecodeOwned.

That distinction is enforced the moment you try to load from data you own internally:

fn load<T: DecodeOwned>(source: String) -> Option<T> {
    T::decode(&source)   // &source is local -> only a DecodeOwned T can be loaded this way
}

let got: Owned = load("1,2,3,4".to_string()).unwrap();   // OK: sum == 10
// let _: Borrowed = load("a,b".to_string()).unwrap();   // ERROR: Borrowed: DecodeOwned not satisfied

This is precisely why serde_json::from_reader requires DeserializeOwned and won’t deserialize a struct holding &str: the bytes are owned by the reader and dropped when it returns, so anything that borrows them would dangle. The for<'a> bound is what mechanically excludes the borrowing types.

8. HRTB inside a trait object (StrPipeline)

Up to here the higher-ranked thing was a generic parameter F. You can also erase it behind dyn. Putting for<'a> inside the box is what lets the surrounding type carry no lifetime parameter:

struct StrPipeline {
    steps: Vec<Box<dyn for<'a> Fn(&'a str) -> &'a str>>,
}

Because each boxed step is higher-ranked, one StrPipeline value can be applied to inputs of any lifetime — the struct itself stays lifetime-free:

impl StrPipeline {
    fn add<F>(mut self, f: F) -> Self
    where
        F: for<'a> Fn(&'a str) -> &'a str + 'static,
    {
        self.steps.push(Box::new(f));
        self
    }

    fn run<'a>(&self, input: &'a str) -> &'a str {
        let mut cur = input;
        for step in &self.steps {
            cur = step(cur);   // &'a str in, &'a str out — same 'a, every iteration
        }
        cur
    }
}

Watch the loop body type-check: cur is &'a str; each step is for<'a> Fn(&'a str) -> &'a str, so step(cur) returns &'a str — the same 'a — and the reassignment holds across every iteration.

The contrast that explains the design: if the box were Box<dyn Fn(&'x str) -> &'x str> for some fixed 'x, the struct would need an <'x> parameter and could only ever process borrows of that one lifetime. HRTB is what keeps StrPipeline a plain, storable, lifetime-free type while one value still serves a 'static string literal and a short-lived local alike.

9. Capstone: a parser combinator (Parser<T>)

A parser is a function: given input, either fail, or return (remaining input, value). The remaining slice is a sub-borrow of the input, so a parser is fundamentally:

for<'i> Fn(&'i str) -> Option<(&'i str, T)>

HRTB is the load-bearing wall of every parser-combinator library — nom, winnow, chumsky. It’s what lets Parser<T> be a lifetime-free type you can store, pass, and compose, while each parser still runs on input of any lifetime, and one parser’s leftover slice feeds straight into the next:

struct Parser<T>(Box<dyn for<'i> Fn(&'i str) -> Option<(&'i str, T)>>);

impl<T: 'static> Parser<T> {
    fn new(f: impl for<'i> Fn(&'i str) -> Option<(&'i str, T)> + 'static) -> Self {
        Parser(Box::new(f))
    }
    fn parse<'i>(&self, input: &'i str) -> Option<(&'i str, T)> {
        (self.0)(input)
    }
}

Notice Parser<T> has no lifetime parameter — the for<'i> lives inside the box, exactly as in rung 8. The base parser tag matches a literal prefix and yields it; its value type is &'static str, which never borrows from the input lifetime:

fn tag(prefix: &'static str) -> Parser<&'static str> {
    Parser::new(move |input: &str| input.strip_prefix(prefix).map(|rest| (rest, prefix)))
}

The combinators build on it. number parses a leading digit run; map transforms a parser’s output; and then — the heart of the rung — runs one parser and feeds its leftover into the next:

fn then<A: 'static, B: 'static>(a: Parser<A>, b: Parser<B>) -> Parser<(A, B)> {
    Parser::new(move |input| {
        a.parse(input)
            .and_then(|(rest, a)| b.parse(rest).map(|(rest, b)| (rest, (a, b))))
    })
}

The composition only type-checks because of for<'i>. a.parse(input) hands back rest: &'i str — a sub-slice of input, lifetime 'i. You then call b.parse(rest), and only because b is for<'i> can it accept that leftover slice of the very same 'i. A single-lifetime parser type could not chain to arbitrary depth without threading an explicit lifetime through every combinator. HRTB makes the lifetime disappear from the type while staying correct in the body:

let assignment = then(tag("x="), number());
let (rest, (key, value)) = assignment.parse("x=42;").unwrap();
assert_eq!((key, value, rest), ("x=", 42, ";"));

let incremented = map(then(tag("n:"), number()), |(_, n)| n + 1);
assert_eq!(incremented.parse("n:99").unwrap().1, 100);

Footguns

• Thinking for<'a> is just a fancy <'a>. It is the opposite quantifier. <'a> = caller picks one; for<'a> = holds for all, callee picks per call.
• let-bound reference-returning closures. They infer one concrete lifetime and fail for<'a> with “implementation of Fn is not general enough.” Pass inline, coerce to a fn pointer, or use a named fn item.
• Reaching for a named <'a> to accept a callback over locals. The 'a becomes caller-fixed and must outlive the whole function; your locals can’t satisfy it. Use for<'a> so each call mints its own.
• Expecting a borrowing type to be DeserializeOwned/DecodeOwned. A type whose Self borrows the input implements the trait for only one lifetime, so the for<'de> supertrait excludes it. Own your data, or thread the input lifetime.
• Adding a lifetime parameter to a struct that stores a callback. If the boxed Fn is higher-ranked (Box<dyn for<'a> Fn(&'a str) -> &'a str>), the struct needs no lifetime at all. Only a fixed inner lifetime forces one onto the struct.

Real-world patterns

• Fn/FnMut/FnOnce over references are all implicitly higher-ranked. Fn(&T) -> &U is for<'a> Fn(&'a T) -> &'a U; you only type the quantifier when elision can’t infer it.
• serde::de::DeserializeOwned is the canonical HRTB supertrait (for<'de> Deserialize<'de>) — and the reason from_reader/from_slice-into-owned reject borrowing types.
• Parser combinators (nom, winnow, chumsky) are built bottom-to-top on for<'i> Fn(&'i str) -> ..., keeping their Parser types lifetime-free.
• Closure-accepting APIs that borrow internal state — iterator adapters, visitor/callback registries, middleware chains — lean on the implicit for<'a> so one callback can be invoked on transient internal borrows.

Capstone insight

HRTB is the language’s answer to a quantifier-ordering problem. Ordinary generics put the caller’s choices outside the function: <'a> is decided at the call site. But a callback or impl frequently has to operate on data the function makes for itself, after the call has begun — data whose lifetime is logically inside the function. for<'a> moves the lifetime’s binder from the outside (caller-chosen, fixed) to the inside (callee-chosen, fresh each use). Once you see it as “who gets to fill in this lifetime, and when,” every symptom follows: the let-bound closure that’s “not general enough” (it committed to one lifetime too early), the named-<'a> that rejects your locals (it’s fixed from outside), DeserializeOwned (owns its data, so it qualifies for every lifetime), and the parser combinator that composes without a lifetime in sight (the binder hides inside each dyn). HRTB is how you write “works for any borrow I’ll ever hand it” — and most of the time, elision writes it for you.

Explain it back

• What is the difference in who chooses the lifetime between <'a, F: Fn(&'a str)> and <F: for<'a> Fn(&'a str)>?
• Why does Fn(&str) -> &str need no annotation, and what does it desugar to?
• In measure_on_local, why can’t the bound be a plain caller-chosen <'a>?
• You get “implementation of Fn is not general enough” from a let-bound closure. What exactly went wrong, and what are three ways to fix it?
• Why does a single named <'a> reject two locals in sum_two_locals, when for<'a> accepts them?
• Why is Owned a DecodeOwned but Borrowed<'a> is not? Relate it to why serde_json::from_reader needs DeserializeOwned.
• Why does Box<dyn for<'a> Fn(&'a str) -> &'a str> let StrPipeline avoid a lifetime parameter, where a fixed 'x would not?
• In then, which line relies on b being higher-ranked, and what would break without it?

See also

• Lifetimes in depth — caller-chosen <'a>, elision, and 'a: 'b bounds; HRTB is the next quantifier up.
• Conversion traits — From/TryFrom and trait families, the same “one impl, many instantiations” shape as Slicer<'a>.
• Cow — Clone-on-Write — the borrowed-vs-owned split that DecodeOwned turns into a trait bound.

Rc / Arc

Ladder: src/bin/rc_arc.rs · Run: cargo run --bin rc_arc · Phase 1 · 9 rungs

TL;DR

Rc<T> is shared ownership by counting. One heap allocation holds your value plus a counter; every Rc handle is a pointer to that allocation and owns one unit of the count. clone() bumps the count (cheap — it copies a pointer, never the data); drop decrements it; when the count hits 0 the value is freed exactly once. That’s the entire machine. Rc only ever hands out &T (shared, immutable access), which is what makes the counting sound. Arc is the same machine with an atomic counter, so it can be shared across threads; Rc uses a plain integer and is therefore single-threaded only. The two failure modes to internalize: Rc gives you aliasing but not mutation (reach for make_mut or RefCell), and a strong reference cycle leaks because the counts never reach 0.

Why this exists (from first principles)

Rust’s default ownership is a tree: each value has exactly one owner, and when that owner goes out of scope the value is freed. Box<T> is the canonical single-owner heap pointer. This is wonderful — it makes “when is this freed?” decidable at compile time with zero runtime bookkeeping — but it can’t express every shape.

Some data is a DAG or a graph: one node reachable from two parents, a value several structs all need to keep alive, a string tag shared by thousands of records. There is no single, statically-known owner. So the question “when is this freed?” can’t be answered at compile time. You need to answer it at runtime, and the simplest correct answer is: free it when the last user is gone. That requires counting users.

That is precisely Rc:

What the compiler still guarantees, even with shared ownership: no use-after-free (the value lives as long as any handle does) and no double-free (only the 0-transition frees). What it gives up: it can no longer prove the value is uniquely owned, so it refuses to hand out &mut T through an Rc. That single restriction — shared access only — is the source of everything interesting in this ladder.

The ladder at a glance

The ideas, built up

Two owners, one allocation

The foundational move is just new then clone:

fn two_owners(text: &str) -> (Rc<String>, Rc<String>) {
    let rc = Rc::new(text.to_string());
    (rc.clone(), rc.clone())
}

The original rc is moved out by the time the tuple is built (both elements are clones), so we return two handles to the same String. The proof is not that the values are equal — it’s that they share an address:

let (a, b) = two_owners("shared");
assert_eq!(*a, "shared");
assert_eq!(*b, "shared");
assert!(Rc::ptr_eq(&a, &b));   // SAME allocation, not two copies

Rc::ptr_eq compares the raw pointer inside each handle. This is the literal meaning of shared ownership: not two equal Strings, but two pointers to one String. clone() here copied 16 bytes of pointer + length + capacity… no, it copied a single pointer-to-the-Rc-allocation and incremented a counter. The heap String and its bytes were never touched.

The count is the whole machine

Rc’s entire correctness rests on one number: strong_count. Rung 2 makes it observable by sampling it at four moments:

fn count_lifecycle(rc: &Rc<String>) -> [usize; 4] {
    let a = Rc::strong_count(rc);        // 1: just the original

    let (b, c) = {
        let _rc2 = Rc::clone(rc);
        let b = Rc::strong_count(rc);    // 2: one clone alive
        let _rc3 = Rc::clone(rc);
        let c = Rc::strong_count(rc);    // 3: two clones alive
        (b, c)
    };                                   // _rc2, _rc3 drop here

    let d = Rc::strong_count(rc);        // 1: back to just the original
    [a, b, c, d]
}

The result is [1, 2, 3, 1]. clone() increments; the end of the inner scope runs the Drop for _rc2 and _rc3, each decrementing. Note the function takes &Rc<String> — a borrow of a handle, which does not add an owner. Only clone() does. This distinction (borrowing a handle vs. cloning it) is worth burning in: passing &Rc lets you read the value or the count without participating in ownership.

The shared diamond — the shape Box can’t make

This is why Rc exists, drawn out:

        top
       /    \
   left      right
       \    /
       shared      <- ONE node, owned by BOTH left and right

With Box, shared would need a single owner — left or right, not both. Rc lets both branches hold a handle to the same node:

struct Node { name: String, children: Vec<Rc<Node>> }

let shared = Rc::new(Node { name: "shared".into(), children: vec![] });
let left  = Rc::new(Node { name: "left".into(),  children: vec![Rc::clone(&shared)] });
let right = Rc::new(Node { name: "right".into(), children: vec![Rc::clone(&shared)] });

After building it, the shared node’s strong_count is 2 (held by left’s and right’s children vectors), and the two paths to it are pointer-equal:

assert!(Rc::ptr_eq(shared_via_left, shared_via_right));
assert_eq!(Rc::strong_count(shared_via_left), 2);

This is a DAG. As long as you only ever follow edges downward (parent to child), the counts behave and everything frees when the roots go. The moment you add an edge back upward with a strong Rc, you get rung 6’s leak.

Rc<str> — interning an immutable string the cheap way

Rc<T> shines when T is large and immutable and shared widely. The classic case: thousands of records all tagged "electronics". Storing a String in each is one heap allocation per record. Instead, allocate the string once as Rc<str> and hand each record a clone:

fn tag_all(category: &str, n: usize) -> Vec<Rc<str>> {
    let rc: Rc<str> = Rc::from(category);   // ONE allocation of the bytes
    let mut tags = Vec::with_capacity(n);
    for _ in 0..n {
        tags.push(Rc::clone(&rc));          // each push: pointer copy + count bump
    }
    tags
}

All n elements are the same allocation:

let tags = tag_all("electronics", 4);
for t in &tags[1..] {
    assert!(Rc::ptr_eq(&tags[0], t));       // every tag clones the SAME Rc<str>
}
assert_eq!(Rc::strong_count(&tags[0]), 4);  // the count sees all four

Rc<str> vs Rc<String>. Rc<String> is a double indirection: Rc -> String (ptr/len/cap on the heap) -> the bytes. Rc<str> stores the length in the Rc’s fat pointer and points directly at the bytes — one indirection, no String header. For an immutable shared string, Rc<str> is the leaner choice. Build it with Rc::from(&str) or .into(). The same logic gives Rc<[T]> for shared immutable slices.

make_mut — clone-on-write through a shared handle

Rc won’t give you &mut T directly, because while other handles exist a mutation would be visible through them and break aliasing. Rc::make_mut resolves this by checking the count first:

fn push_isolated(rc: &mut Rc<Vec<i32>>, value: i32) {
    Rc::make_mut(rc).push(value);
}

• Sole owner (count == 1): hands you &mut T to the existing allocation — mutate in place, no copy.
• Shared (count > 1): clones the inner T into a fresh allocation, points this Rc at the clone, and gives you &mut to that. The other owners keep seeing the original. This is the “write” half of copy-on-write.

The ladder proves both branches. Sole owner mutates in place — same address before and after:

let mut solo = Rc::new(vec![1, 2, 3]);
let addr_before = Rc::as_ptr(&solo);
push_isolated(&mut solo, 4);
assert_eq!(Rc::as_ptr(&solo), addr_before);   // no reallocation

Shared owner forces a copy that isolates the writer:

let original = Rc::new(vec![1, 2, 3]);
let mut writer = Rc::clone(&original);         // count == 2
push_isolated(&mut writer, 99);

assert_eq!(*writer,   vec![1, 2, 3, 99]);      // writer sees its push
assert_eq!(*original, vec![1, 2, 3]);          // original UNCHANGED
assert!(!Rc::ptr_eq(&original, &writer));      // writer points at a fresh clone
assert_eq!(Rc::strong_count(&original), 1);    // the split made each sole again
assert_eq!(Rc::strong_count(&writer),   1);

This is exactly the Cow mental model, but the “am I shared?” test is the refcount rather than an explicit enum tag. It’s how Rc::make_mut and friends power cheap, structural-sharing-friendly data structures.

The reference cycle that leaks — the defining Rc failure

Rc frees its value when strong_count reaches 0. So what if two nodes hold strong handles to each other?

struct Cycle { name: &'static str, link: RefCell<Option<Rc<Cycle>>> }

fn make_leaky_cycle() {
    let a = Rc::new(Cycle::new("a"));
    let b = Rc::new(Cycle::new("b"));
    a.link.borrow_mut().replace(Rc::clone(&b));   // a -> b (strong)
    b.link.borrow_mut().replace(Rc::clone(&a));   // b -> a (strong)
}   // a and b go out of scope here

(The RefCell is only there because the back-edge must be wired after both nodes exist — you need interior mutability to mutate a once it’s already in an Rc.)

Walk the counts. After wiring, a has 2 strong owners (the local a + b’s link); same for b. When the function returns, the locals a and b drop — each count falls from 2 to 1, never to 0, because each node’s link still holds the other. Neither Drop ever fires:

let drops = DROP_COUNT.with(|c| c.get());
assert_eq!(drops, 0, "expected the cycle to LEAK (0 drops)");

This is safe code. Rust guarantees no use-after-free and no double-free — it does not guarantee no leaks. An Rc cycle is the single-threaded equivalent of an object graph that’s unreachable but uncollected: the memory is gone for the rest of the program.

Weak breaks the cycle — the parent/child tree

The fix is Weak<T>: a handle that points at the allocation and bumps the weak count, but never the strong count. Because it doesn’t touch the strong count, a Weak can’t keep a value alive, so a chain of weak edges can’t form a keep-alive cycle. To use one you must upgrade() it — which returns Option<Rc<T>>, Some if the target is still alive, None if it’s gone.

The ownership rule that makes graphs leak-free:

The direction that owns uses Rc (strong). The direction that merely refers back uses Weak.

In a tree: parent -> child is strong (the parent owns its children); child -> parent is weak (a child can navigate up but must not pin its parent alive).

struct TreeNode {
    name: &'static str,
    parent: RefCell<Weak<TreeNode>>,        // weak: does NOT own
    children: RefCell<Vec<Rc<TreeNode>>>,   // strong: owns
}

fn link_parent_child(parent: &Rc<TreeNode>, child: &Rc<TreeNode>) {
    parent.children.borrow_mut().push(Rc::clone(child));   // strong down
    *child.parent.borrow_mut() = Rc::downgrade(parent);    // weak up
}

fn parent_name(child: &Rc<TreeNode>) -> &'static str {
    child.parent.borrow().upgrade()
        .map(|p| p.name)
        .unwrap_or("<no parent>")           // None if the parent is gone
}

The counts confirm the weak edge is free:

assert_eq!(Rc::strong_count(&root), 1);   // ONLY the `root` binding owns it
assert_eq!(Rc::strong_count(&leaf), 2);   // `leaf` binding + root.children

And the payoff — dropping the parent actually frees it, and the child’s weak pointer correctly reports the parent is gone:

drop(root);
assert_eq!(parent_name(&leaf), "<no parent>");   // upgrade() now returns None

When both nodes leave scope, both Drops run (the test asserts 2 drops) — no leak, unlike rung 6. Rc::downgrade(&rc) makes a Weak from an Rc; weak.upgrade() tries to promote it back, succeeding only while a strong owner remains.

Rc is !Send -> Arc across threads

Rc’s counter is a plain usize. If two threads cloned/dropped the same Rc concurrently, their increments and decrements could interleave and corrupt the count — leading to a double-free or a leak. Rust forbids this at compile time by making Rc: !Send: you literally cannot move one into another thread.

// WRONG — won't compile:
// let data = Rc::new(0);
// thread::spawn(move || { let _ = data; });
// error: `Rc<i32>` cannot be sent between threads safely

Arc (“atomic Rc”) is the same machine with an atomic counter. The atomic increment/decrement is safe under contention, so Arc is Send + Sync and crosses threads. But Arc, like Rc, still only gives shared access — to mutate shared state across threads you wrap the data in a lock: Arc<Mutex<T>>. Arc shares the lock; the Mutex hands out &mut T to one thread at a time.

fn concurrent_count(n_threads: usize, per_thread: usize) -> usize {
    let counter = Arc::new(Mutex::new(0usize));
    let handles = (0..n_threads).map(|_| {
        let counter = Arc::clone(&counter);     // each thread gets its own handle
        thread::spawn(move || {
            let mut counter = counter.lock().unwrap();
            *counter += per_thread;
        })
    }).collect::<Vec<_>>();

    for h in handles { h.join().unwrap(); }
    *counter.lock().unwrap()
}

assert_eq!(concurrent_count(8, 10_000), 80_000);   // no lost updates

Two different counters. Arc’s atomic counter protects the reference count (how many handles exist). The Mutex protects the data. Atomicity of the refcount does not make the inner value thread-safe to mutate — that’s the Mutex’s job. Arc<T> alone gives shared reads; Arc<Mutex<T>> gives synchronized writes.

Atomic operations cost more than a plain integer bump, which is why Rc exists at all: when you’re single-threaded, you shouldn’t pay for atomics. Rc and Arc are otherwise the same API.

Capstone insight: build MyRc<T> from scratch

The capstone strips Rc to its essence and reveals there’s no magic — just one heap box holding { count, value } and a pointer to it.

struct MyRcInner<T> {
    strong: Cell<usize>,   // Cell: mutate the count through a shared &self
    value: T,
}

struct MyRc<T> {
    ptr: NonNull<MyRcInner<T>>,
    _marker: PhantomData<MyRcInner<T>>,   // "I logically own a T" for drop-check
}

Two design choices encode deep facts about real Rc:

• strong: Cell<usize> — the count must be mutable through &self (clone and drop both take shared references), so it needs interior mutability. A Cell (non-atomic) is exactly why real Rc is !Sync: a non-atomic counter is unsafe to touch from two threads. Arc swaps this for AtomicUsize.
• PhantomData<MyRcInner<T>> — we hold the value behind a raw NonNull, so the compiler can’t see that MyRc owns a T. The marker tells dropck “I own a T,” which makes drop-checking correct for Ts with lifetimes.

The four operations are the machine:

fn new(value: T) -> MyRc<T> {                       // allocate inner, strong = 1
    let inner = Box::new(MyRcInner { strong: Cell::new(1), value });
    MyRc { ptr: NonNull::new(Box::into_raw(inner)).unwrap(), _marker: PhantomData }
}

fn clone(&self) -> MyRc<T> {                        // bump count, copy the pointer
    self.inner().strong.set(self.inner().strong.get() + 1);
    MyRc { ptr: self.ptr, _marker: PhantomData }
}

fn deref(&self) -> &T {                             // SHARED access only
    &self.inner().value
}

fn drop(&mut self) {
    if self.inner().strong.get() == 1 {             // I'm the last one
        unsafe { drop(Box::from_raw(self.ptr.as_ptr())); }   // free once, runs T's Drop
    } else {
        self.inner().strong.set(self.inner().strong.get() - 1);  // others remain
    }
}

The whole correctness argument: new starts at 1, clone adds 1 and shares the pointer, drop either frees (on the 1-transition, reconstructing the Box so its destructor runs T’s Drop exactly once) or decrements. The verification uses a Dropper that logs its own drop to prove the inner value is freed exactly once — not zero (leak), not twice (double-free):

let a = MyRc::new(Dropper("payload"));
{
    let b = MyRc::clone(&a);
    assert_eq!(MyRc::strong_count(&a), 2);   // clone bumped the shared count
    assert_eq!(a.ptr, b.ptr);                // same inner, no deep copy
}   // b drops: count 2 -> 1, inner still alive
assert_eq!(DROP_COUNT, 0);                   // nothing freed yet
// ... a drops: count 1 -> 0, Dropper runs once

Once you’ve written these four functions, Rc stops being a black box. It’s a counter, a pointer, and the discipline of freeing on the last drop — and Arc is the same four functions with Cell swapped for an atomic.

Reaching for unsafe here is unavoidable (raw pointer deref, manual free), so this is the rung to validate with Miri: cargo miri run --bin rc_arc catches a leak, a double-free, or use-after-free that a normal run might miss.

Footguns

• Rc gives you aliasing, not mutation. Rc<T> only ever yields &T. To mutate, either use Rc::make_mut (clone-on-write — fine when sharing is rare) or stack a RefCell: Rc<RefCell<T>> (runtime-checked shared mutation). See the Rc<RefCell<T>> note.

• Strong cycles leak — silently. a strong-points at b and vice versa -> neither count reaches 0 -> destructors never run. Safe Rust prevents use-after-free and double-free; it does not prevent leaks. Fix: make the back-edge Weak.

• The ownership rule for back-pointers: the direction that owns is Rc (strong); the direction that merely navigates back is Weak. Parent -> child strong, child -> parent weak.

• Weak::upgrade() can return None. A Weak doesn’t keep the value alive, so by the time you upgrade() the target may be gone. You must handle the None — that’s the whole point of Weak.

• Rc is !Send / !Sync. You cannot move it across threads, by design — its counter isn’t atomic. Use Arc for that. But don’t reach for Arc reflexively when single-threaded: you’d pay for atomics you don’t need.

• Arc shares; it doesn’t synchronize the data. Arc<T> gives shared reads. For cross-thread mutation you still need a Mutex/RwLock: Arc<Mutex<T>>. The atomic refcount protects the handle count, not the value.

• Rc<String> is a double indirection. Prefer Rc<str> (or Rc<[T]>) for shared immutable strings/slices — one fewer pointer hop and no String header.

Real-world patterns

Explain it back

• What two things live in an Rc’s heap allocation, and what does a single Rc handle own?
• Why is clone() on an Rc cheap, and what exactly gets copied?
• Give a data shape Box cannot express but Rc can. Why not?
• When does Rc::make_mut mutate in place, and when does it copy? What decides?
• Walk the strong counts through an a <-> b strong cycle as the locals drop. Which count stays non-zero, and what’s the consequence?
• In a parent/child tree, which edge is Rc and which is Weak? What leaks if you swap them?
• What does Weak::upgrade() return, and when is it None?
• Why is Rc !Send? What does Arc change, and what does it not change about mutating the inner value?
• Which two distinct things does Arc<Mutex<T>> protect, and with which mechanism each?
• In MyRc, why is the count a Cell<usize> rather than a plain usize, and what would you change to get Arc? Why does the last drop free exactly once?

See also

• Rc<RefCell<T>> patterns — add interior mutability on top of the shared-ownership layer built here; the cycle/Weak story in full
• Cell / RefCell — the interior-mutability layer (the make_mut and capstone Cell<usize> both rely on it)
• Drop & Ordering — why a cycle means destructors never run, and how the last Rc drop triggers the free
• Cow — Clone-on-Write — make_mut is the refcount-driven version of the same copy-on-write idea

Rc<RefCell<T>> patterns

Ladder: src/bin/rc_refcell.rs · Run: cargo run --bin rc_refcell · Phase 1 · 10 rungs

TL;DR

Rc<RefCell<T>> is the single-threaded “shared mutable state” idiom, built by stacking two jobs: Rc gives many owners (it lets the value be aliased), and RefCell lets you mutate through a shared & by moving the borrow check from compile time to runtime. The whole tension — and every footgun — lives in that stack: Rc hands out N references to one cell, but RefCell still allows only one &mut at a time, so the aliasing Rc enables is exactly what makes RefCell panic at runtime. Reach for it only when you genuinely need both shared ownership and mutation; the cost is runtime borrow panics and the ever-present risk of reference-cycle leaks.

Why it exists (from first principles)

Plain Rust ownership is a tree: one owner, borrows flow down. But some data shapes are graphs — a node pointed at from two places (doubly-linked list, DOM, a tree with parent pointers), or one piece of state several objects mutate (an event log, an observer registry).

You can’t express “two owners” with &mut — that’s exclusive. And you can’t mutate through Rc<T> alone, because Rc only hands out &T (shared references). Neither layer solves the problem on its own:

Stack them: Rc provides the shared-ownership topology (multiple handles to one allocation), and RefCell provides the mutation through those shared handles. The price is that the borrow check moves from compile time to runtime — two borrow_mut() calls on the same cell at the same time will panic, not fail to compile.

The ladder at a glance

The ideas, built up

The shared-cell “aha”

The fundamental move: make one RefCell, wrap it in Rc, clone the Rc. Now two handles point at the same underlying cell. A mutation through one is immediately visible through the other — because there is no copy; both handles dereference to the same allocation.

fn shared_cell(start: i32) -> (Rc<RefCell<i32>>, Rc<RefCell<i32>>) {
    let original = Rc::new(RefCell::new(start));
    let cloned = original.clone();
    (original, cloned)
}

The check proves this:

let (a, b) = shared_cell(10);
*a.borrow_mut() += 5;
assert_eq!(*b.borrow(), 15);    // b sees a's mutation
assert!(Rc::ptr_eq(&a, &b));    // same allocation

Rc::ptr_eq is the definitive test — it compares the raw pointer inside each Rc, confirming they reference the same heap allocation, not just equal values. This is what “shared ownership” means: not two copies of the data, but two handles to one copy.

From loose handles to owned structs

Loose locals sharing a cell is a demo. The real pattern is separate structs each holding a handle to the same shared state, mutating it through &self methods. The type alias makes the intent clear:

type Log = Rc<RefCell<Vec<String>>>;

struct Logger { log: Log }
struct Auditor { log: Log }

Both Logger::record(&self, msg) and Auditor::count(&self) take &self — no &mut self needed, because mutation goes through the RefCell, not through the Rust borrow of self:

impl Logger {
    fn record(&self, msg: &str) {
        self.log.borrow_mut().push(msg.to_string());
    }
}

impl Auditor {
    fn count(&self) -> usize {
        self.log.borrow().len()
    }
}

After two record() calls, the Auditor — a completely separate struct — sees both entries. And Rc::strong_count(&log) reports 3: the original handle, the Logger’s clone, and the Auditor’s clone. Three owners, one Vec.

This is why the pattern exists: it decouples ownership from mutability. Each struct holds a shared reference to the cell; the cell enforces exclusive access at runtime.

&Rc peeks, .clone() owns, borrow_mut() reaches inside

Three distinct operations, and confusing them creates bugs:

fn peek_count(h: &Counter) -> usize {
    Rc::strong_count(h)              // reads the count, no new owner
}

fn bump(h: &Counter, n: i32) {
    *h.borrow_mut() += n;            // mutates the inner value, no new owner
}

fn make_sibling(h: &Counter) -> Counter {
    Rc::clone(h)                     // creates a new owner (bumps strong_count)
}

Passing &Rc<RefCell<T>> lets you read AND mutate the shared value without changing the owner count. The &Rc auto-derefs through Rc to reach the RefCell, and borrow_mut() is a &self method on RefCell — so all you need is a shared reference to the Rc.

Only Rc::clone() (or the equivalent .clone() on an Rc) bumps strong_count. The clone is cheap — it copies a pointer and increments a counter, not the underlying data.

And dropping an owner doesn’t kill the value — it decrements strong_count. The value survives as long as at least one Rc exists:

let sib = make_sibling(&h);
assert_eq!(peek_count(&h), 2);   // two owners
drop(sib);
assert_eq!(peek_count(&h), 1);   // back to one; value still alive
assert_eq!(*h.borrow(), 115);    // the value is unaffected

Footgun 1: double borrow_mut panics at runtime

This is the defining cost of Rc<RefCell<T>>. The compiler can’t see that two Rc handles alias the same cell, so it can’t reject a double borrow at compile time. RefCell re-imposes the rule at runtime: one &mut XOR many &, enforced by a panic.

fn try_double_mut(x: &Counter, y: &Counter, add: i32) -> Result<(), ()> {
    let mut first = x.borrow_mut();                     // holds a &mut to the cell
    let mut second = y.try_borrow_mut().map_err(|_| ())?; // tries ANOTHER &mut
    *first += add;
    *second += add;
    Ok(())
}

When x and y are different cells, both borrows succeed — they’re independent RefCells. When they alias (created via Rc::clone), the second borrow finds the cell already mutably borrowed and fails. The non-panicking try_borrow_mut() returns Err(BorrowMutError); the panicking borrow_mut() would crash the thread.

The check also proves the panic version directly:

let _first = h2.borrow_mut();
let _second = alias2.borrow_mut();   // BorrowMutError -> panic

The key detail: it’s the overlap that triggers the panic, not the mere existence of two handles. If you scope the first borrow so it’s dropped before the second one starts, no conflict occurs. The RefMut guard returned by borrow_mut() tracks the borrow’s lifetime — when it drops, the borrow ends.

Footgun 2: borrow held across a call (reentrancy)

The rung-4 double borrow was obvious because both borrows were on adjacent lines. The version that actually bites people in real code is indirect: you hold a borrow, then call a function that — somewhere down the stack — borrows the same cell again. The cell doesn’t know it’s “the same logical operation”; it just sees a second borrow while the first is live, and panics.

The ladder sets up a Bank scenario: an Account can have a backup account (another Rc<RefCell<Account>>). Withdrawal falls through to the backup if the primary balance is insufficient. If the backup aliases the primary (a self-referential backup), the naive implementation holds a borrow_mut() of the account while recursing into the backup — which tries to borrow_mut() the same cell again.

The fix: extract what you need from the cell into local variables, drop the guard (by ending its scope), then recurse:

fn withdraw(acct: &Acct, amount: i32) -> Result<i32, &'static str> {
    let (shortfall, backup) = {
        let mut account = acct.borrow_mut();   // borrow starts
        if account.balance >= amount {
            account.balance -= amount;
            return Ok(account.balance);
        }
        let shortfall = amount - account.balance;
        account.balance = 0;
        (shortfall, account.backup.clone())    // clone the Rc handle out
    };                                          // borrow ENDS here

    // Now the cell is unborrowed — safe to pass to a recursive call
    let Some(backup) = backup else {
        return Err("insufficient");
    };
    if Rc::ptr_eq(acct, &backup) {
        return Err("insufficient");            // self-backup: can't double-spend
    }
    withdraw(&backup, shortfall)?;
    Ok(0)
}

The pattern is: read what you need, drop the guard, then call. The curly braces around the borrow block are the mechanism — when the RefMut guard goes out of scope, the borrow ends. The Rc::ptr_eq check is an additional safety net: even after releasing the borrow, recursing into the same cell would drain an already-zeroed balance, so the function short-circuits.

Footgun 3: the reference cycle that never frees

The runtime borrow panic is loud — you find it fast. This footgun is silent: it’s a memory leak. Rc frees its value only when strong_count hits 0. If two nodes hold strong Rc handles to each other, each keeps the other’s count at >=1 forever — even after every external handle is gone. Destructors never run.

The ladder builds a Node with a Drop impl that logs into a shared Vec when it dies:

impl Drop for Node {
    fn drop(&mut self) {
        self.dropped.borrow_mut().push(self.name.clone());
    }
}

Then it creates a cycle:

let a = make_node("a", &log);
let b = make_node("b", &log);
link(&a, &b);   // a -> b (strong)
link(&b, &a);   // b -> a (strong) — now it's a cycle

Each node starts with 2 strong owners: the local variable and the other node’s link. When the locals go out of scope, each count drops to 1 — but never to 0, because the cycle holds. Neither Node::drop ever fires. The drop log is empty.

This is safe — Rust prevents use-after-free and double-free, but it does not prevent leaks. Rc cycles are the single-threaded equivalent of a “GC-proof” leak in a garbage-collected language: the objects are unreachable but never collected.

Breaking cycles with Weak: the parent-pointer tree

The fix for the cycle leak is Weak<T> — a non-owning handle. Weak does not increment strong_count, so it cannot pin a value alive. To use the value behind a Weak, you must upgrade() it to an Option<Rc<T>> — and you get None if the value was already dropped.

The ownership rule for avoiding cycles:

The direction that owns uses Rc (strong). The direction that merely observes uses Weak.

In a tree: parent -> child is strong (the parent owns its children); child -> parent is weak (the child can navigate up but must not keep the parent alive).

fn add_child(parent: &Tree, child: &Tree) {
    parent.borrow_mut().children.push(Rc::clone(child));  // strong down
    child.borrow_mut().parent = Rc::downgrade(parent);     // weak up
}

fn parent_value(child: &Tree) -> Option<i32> {
    child.borrow().parent.upgrade()                        // Option<Rc<...>>
        .map(|parent| parent.borrow().value)
}

Rc::downgrade(&rc) creates a Weak from an Rc. weak.upgrade() tries to promote it back to an Rc, succeeding only if the target still has at least one strong owner.

The counts tell the story:

assert_eq!(Rc::strong_count(&root), 1);   // only the local variable
assert_eq!(Rc::weak_count(&root), 1);     // the child's parent pointer
assert_eq!(Rc::strong_count(&leaf), 2);   // local + parent's children vec

The child’s weak pointer to the root does not bump strong_count. When the locals go out of scope, the root’s strong count reaches 0 — it drops, its children Vec drops, the leaf’s strong count reaches 0 — it drops too. Both TreeNode::drop implementations fire. The drop log confirms both nodes freed.

The ladder also proves that you can mutate the parent through the child’s back-pointer — shared mutability across the tree, which is the whole reason RefCell is in the stack:

if let Some(p) = leaf.borrow().parent.upgrade() {
    p.borrow_mut().value = 99;
}
assert_eq!(root.borrow().value, 99);

Real-world pattern: observer / subject fan-out

The other canonical use: one event source (“subject”) pushes updates into many independent observers, each holding its own mutable state. The subject owns a list of Rc<RefCell<Observer>> handles; calling publish borrows each one mutably in a loop:

impl Subject {
    fn publish(&self, value: i32) {
        for observer in &self.observers {
            let mut observer = observer.borrow_mut();
            observer.seen += 1;
            observer.last = value;
        }
    }
}

The callers holding their own Rc handles to the same observers see the mutations — because they’re the same cells:

subject.publish(10);
subject.publish(20);
assert_eq!(a.borrow().seen, 2);    // the caller's handle sees the subject's writes
assert_eq!(a.borrow().last, 20);

The borrow discipline from rung 4 matters here: each borrow_mut() must be scoped to one loop iteration. If you held a borrow across iterations and two observers aliased the same cell, you’d hit the same double-borrow panic.

This is the shape behind event buses, reactive signals, and GUI data-binding in single-threaded Rust.

Capstone: a doubly-linked list from scratch

The structure that forces everything from this ladder together. A doubly-linked list can’t be built with plain ownership: a node is pointed at from both directions (its predecessor’s next and its successor’s prev), so it needs shared ownership — and you need to mutate those links after the nodes exist, so it needs interior mutability.

The rung-7 ownership rule maps perfectly:

struct DNode {
    value: i32,
    next: Option<DLink>,           // strong: owns the next node
    prev: Weak<RefCell<DNode>>,    // weak: observes the previous node
    dropped: IntDropLog,
}

struct List {
    head: Option<DLink>,
    tail: Option<DLink>,
    dropped: IntDropLog,
}

push_back appends a node. The wiring is: set the new node’s prev to a weak handle of the old tail, then set the old tail’s next to a strong handle of the new node. The borrow discipline requires care — you borrow the old tail mutably to set its next, and borrow the new node mutably to set its prev, but they are different cells so no conflict:

fn push_back(&mut self, value: i32) {
    let new_node = Rc::new(RefCell::new(DNode::new(value, &self.dropped)));
    match self.tail.take() {
        None => {
            self.head = Some(Rc::clone(&new_node));
            self.tail = Some(new_node);
        }
        Some(old_tail) => {
            new_node.borrow_mut().prev = Rc::downgrade(&old_tail);
            old_tail.borrow_mut().next = Some(Rc::clone(&new_node));
            self.tail = Some(new_node);
        }
    }
}

Forward traversal walks head -> next -> next -> ...:

fn to_vec(&self) -> Vec<i32> {
    let mut values = Vec::new();
    let mut current = self.head.clone();
    while let Some(node) = current {
        let node_ref = node.borrow();
        values.push(node_ref.value);
        current = node_ref.next.clone();
    }
    values
}

Backward traversal walks tail -> prev.upgrade() -> prev.upgrade() -> ..., proving the Weak back-links are correctly wired:

fn to_vec_rev(&self) -> Vec<i32> {
    let mut values = Vec::new();
    let mut current = self.tail.clone();
    while let Some(node) = current {
        let node_ref = node.borrow();
        values.push(node_ref.value);
        current = node_ref.prev.upgrade();
    }
    values
}

The traversal clone()s the Rc handle to advance the cursor, then borrows the node to read its value and get the next link. The borrow ends when node_ref goes out of scope at the next iteration — so no borrow overlaps.

The drop test is the proof that the whole structure works: when the List is dropped, its head drops node 1, whose next drops node 2, and so on — a cascade of strong-count-reaching-zero. No prev link holds anything alive because they’re all Weak. The drop log shows all 4 nodes freed in front-to-back order:

assert_eq!(dropped, vec![1, 20, 3, 4], "front-to-back drop order");

Interior mutability works through the list too — borrowing a node handle and mutating its value is visible via traversal:

n2.borrow_mut().value = 20;
assert_eq!(list.to_vec(), vec![1, 20, 3, 4]);

Footguns

• Rc defeats the compile-time aliasing check, so RefCell re-imposes it at runtime. Two borrow_mut()s on the same cell (reachable via two Rc handles) panic with already borrowed: BorrowMutError. You traded a compile error for a possible panic.

• Borrow held across a call (reentrancy). The sneaky version: you hold a borrow_mut(), then call a method that — somewhere down the stack — borrows the same cell. The cell doesn’t know it’s “the same logical operation”; it panics. Fix: read what you need out of the cell, drop the guard (scope it in a { } block or drop(guard)), then make the call.

• Strong reference cycles leak. a holds a strong Rc to b and vice versa -> neither count reaches 0 -> destructors never run, memory never frees. Safe Rust prevents use-after-free and double-free; it does not prevent leaks. Fix: make one direction Weak.

• The ownership rule for back-pointers: the direction that owns uses Rc (strong); the direction that merely observes/navigates back uses Weak. Parent -> child strong, child -> parent weak. next strong, prev weak.

• Rc-chained structures recurse on Drop. Dropping the head of a long Rc-linked list drops its next, which drops its next… -> stack overflow in the destructor for very long chains. Fix: a manual iterative Drop that pops nodes in a loop.

Signatures to know

type Shared<T> = Rc<RefCell<T>>;

// Rc — shared ownership (no mutation of its contents)
Rc::new(v)            -> Rc<T>
Rc::clone(&rc)        -> Rc<T>     // cheap: bumps strong_count, same allocation
Rc::strong_count(&rc) -> usize
Rc::weak_count(&rc)   -> usize
Rc::ptr_eq(&a, &b)    -> bool      // same allocation?
Rc::downgrade(&rc)    -> Weak<T>   // a non-owning handle

// Weak — non-owning; doesn't keep the value alive
Weak::new()           -> Weak<T>   // points at nothing
weak.upgrade()        -> Option<Rc<T>>  // None if the target was dropped

// RefCell — interior mutability, borrow-checked at RUNTIME
cell.borrow()         -> Ref<'_, T>        // panics if a &mut is out
cell.borrow_mut()     -> RefMut<'_, T>     // panics if ANY borrow is out
cell.try_borrow_mut() -> Result<RefMut, BorrowMutError>  // non-panicking

Real-world patterns

Explain it back

• Why does Rc<RefCell<T>> need both layers — what fails if you drop either?
• Two Rc handles to one cell, both borrow_mut() at once: compile error or runtime panic? Why?
• You have a graph traversal that panics with BorrowMutError even though it “looks single-threaded and sequential.” What’s the likely cause?
• In the withdraw function, why must the borrow end before the recursive call? What happens if you remove the inner { } block?
• Why does an a <-> b strong cycle leak, and exactly which count stays non-zero?
• In a tree with parent pointers, which link is Rc and which is Weak, and what breaks if you swap them?
• What does Weak::upgrade() return, and when is it None?
• In the doubly-linked list, why does the drop cascade proceed front-to-back? What would happen if prev were strong instead of Weak?

See also

• Rc / Arc — the shared-ownership layer on its own
• Cell / RefCell — the interior-mutability layer and the runtime borrow check
• Drop & Ordering — why the cycle leak means destructors never run; iterative Drop for linked structures
• Borrow / ToOwned — the MyCow capstone also stacks shared-ownership with interior mutability

Associated Types vs Generic Params

Ladder: src/bin/assoc_vs_generic.rs · Run: cargo run --bin assoc_vs_generic · Phase 2 · 9 rungs

TL;DR

A trait can carry “extra” types in two ways, and the choice is not stylistic — it changes what the type system lets you do:

• Generic parameter (trait Convert<T>): the type is an input. The caller or the impl picks it, so one type can implement the trait many times, once per choice of T.
• Associated type (trait Iterator { type Item; }): the type is an output. The implementor determines it once, so there is exactly one impl per type and the compiler can deduce the output instead of asking you.

Rule of thumb: input → generic param, output → associated type.

Why this exists (from first principles)

Say you want a trait whose method returns “some related type”. You need to tell the trait what that type is. There are only two places it can come from:

1. The caller supplies it. Then it must be a parameter on the trait: Convert<T>. Different callers want different T, so the same type must be allowed to implement Convert<i32> and Convert<String>.
2. The implementor fixes it. Then it belongs inside the impl as an associated type: type Output = i32;. There is one right answer per type, so a second impl with a different answer would be a contradiction.

That single fork — “who chooses the type?” — drives everything else: how many impls are allowed, whether the compiler can infer the result, whether you can put it behind dyn, and how the whole iterator-adapter ecosystem resolves element types at compile time.

The ladder at a glance

The ideas, built up

1. Two shapes for the same idea

The same “pop an item out” trait, written both ways:

// Shape A: associated type — implementor names the output once.
trait PopAssoc {
    type Item;
    fn pop_it(&mut self) -> Option<Self::Item>;
}

// Shape B: generic param — output is a parameter on the trait.
trait PopGeneric<T> {
    fn pop_it(&mut self) -> Option<T>;
}

The difference shows up at the impl site. With the associated type the chosen type goes inside the impl body; with the generic param it goes in the impl header:

impl PopAssoc for Stack {
    type Item = i32;                 // output: declared inside
    fn pop_it(&mut self) -> Option<Self::Item> { self.items.pop() }
}

impl PopGeneric<i32> for Stack {    // input: chosen in the header
    fn pop_it(&mut self) -> Option<i32> { self.items.pop() }
}

Because Stack now has two pop_it methods (one per trait), a bare s.pop_it() is ambiguous — the ladder calls them with fully-qualified syntax (PopAssoc::pop_it(&mut s), PopGeneric::<i32>::pop_it(&mut s)). That ambiguity is a first hint that generic params multiply impls.

2. The defining rule: one impl vs many

This is the whole concept in miniature. An associated type makes the trait a function of Self — one input, one answer:

trait Producer { type Output; fn produce(&self) -> Self::Output; }

impl Producer for Counter { type Output = i32; /* ... */ }

// WRONG: a second impl, even with a different Output, is rejected.
// impl Producer for Counter { type Output = String; /* ... */ }
//   error[E0119]: conflicting implementations of trait `Producer`
//                 for type `Counter`

A generic param makes the trait a relation — many answers are fine:

trait Convert<T> { fn convert(&self) -> T; }

impl Convert<i32>    for Counter { /* ... */ }   // OK
impl Convert<String> for Counter { /* ... */ }   // OK — different T

The consequence you feel immediately: produce() needs no annotation (one answer), but convert() does (the compiler must know which impl):

let p = c.produce();              // i32, deduced
let as_int: i32 = c.convert();    // must say which T
let as_str: String = c.convert();

3. Equality bounds and projection

Associated types unlock two things generic params make clumsy.

Equality bounds pin the output type inside a where clause, keeping the iterator the only type parameter:

fn sum_items<I>(it: I) -> u64
where
    I: Iterator<Item = u64>,   // "any iterator whose Item is exactly u64"
{
    it.sum()
}

Projection lets you name the output as I::Item in your own signature — again with no extra type parameter:

fn first<I>(mut it: I) -> Option<I::Item>
where
    I: Iterator,
{
    it.next()
}

Contrast the generic-trait version. With trait Stream<T> you would be forced to introduce a separate T that leaks into every signature:

// What you'd be stuck writing with a generic-param iterator trait:
fn first_g<S, T>(s: S) -> Option<T> where S: Stream<T> { /* ... */ }
//        ^^^ extra param, and callers must disambiguate T because a type
//            could implement Stream<u64> AND Stream<String>.

Associated types turn that T from a parameter-you-must-supply into an output-the-compiler-deduces.

4. Implementing the real Iterator

Iterator is the canonical associated-type trait:

trait Iterator { type Item; fn next(&mut self) -> Option<Self::Item>; }

Why is Item associated? Because a given iterator yields exactly one type of value. If it were generic (Iterator<T>), a single type could “be an iterator” of many T, and then for x in it wouldn’t know what x is, and .map, .filter, .sum would all be ambiguous. The ladder implements it for a countdown:

impl Iterator for Countdown {
    type Item = u32;
    fn next(&mut self) -> Option<Self::Item> {
        if self.current == 0 { None }
        else { let c = self.current; self.current -= 1; Some(c) }
    }
}

The payoff: because you implemented the real std trait, you get .collect(), .sum(), .map(), and for-loops for free — all keyed off the single Item.

Footguns

Generic params owe you a disambiguation tax (E0283)

Because Counter: Convert<T> holds for more than one T, a function that returns the generic output can’t be called without help:

fn pull<T>(c: &Counter) -> T where Counter: Convert<T> { c.convert() }

// let oops = pull(&c);          // error[E0283]: type annotations needed
let via_annotation: i32 = pull(&c);   // fix 1: pin via the binding's type
let via_turbofish = pull::<String>(&c); // fix 2: pin at the call site

This is the same tax you already pay on .into(), .parse(), and .collect::<Vec<_>>(). Associated outputs (c.produce()) never charge it, because there is only one answer.

dyn forces you to pin the associated type (E0191)

A trait object must be a concrete, fully-known type behind the pointer. So the associated type has to be nailed down:

fn boxed_counter(n: u32) -> Box<dyn Iterator<Item = u32>> { /* ... */ }

// WRONG:
// fn bad(n: u32) -> Box<dyn Iterator> { /* ... */ }
//   error[E0191]: the value of the associated type `Item` must be specified

For a generic-param trait the analogue is simply choosing which object you mean: dyn Convert<i32> and dyn Convert<String> are two unrelated trait-object types. The associated type is part of the object’s identity; the generic param selects the object.

Real-world patterns

Add deliberately uses both

std::ops::Add is the masterclass — it carries a generic param and an associated type, each chosen for the right reason:

pub trait Add<Rhs = Self> {
    type Output;
    fn add(self, rhs: Rhs) -> Self::Output;
}

• Rhs is a generic param (an input): you might add Meters + Meters, or Meters + f64, or Meters + Vector. Multiple right-hand sides → many impls per type. It even defaults to Self.
• Output is an associated type (an output): once you fix the pair (Self, Rhs), the result type is determined. One answer per impl.

impl Add        for Meters { type Output = Meters; /* Meters + Meters */ }
impl Add<f64>   for Meters { type Output = Meters; /* Meters + f64    */ }

// The determined output can even be named with projection:
let r: <Meters as Add<f64>>::Output = Meters(3.0) + 1.0;

Designing your own split

When you design a trait, sort each “extra type” into input or output. The ladder’s Graph trait makes both node-id and weight associated, because a graph has exactly one of each — they are facts about the graph, not knobs a caller turns:

trait Graph {
    type NodeId: Copy + Eq;   // one id type per graph  → associated
    type Weight;              // one weight type per graph → associated
    fn neighbors(&self, n: Self::NodeId) -> Vec<(Self::NodeId, Self::Weight)>;
}

// A consumer stays clean — one type param, node type via projection:
fn neighbor_count<G: Graph>(g: &G, n: G::NodeId) -> usize { g.neighbors(n).len() }

Had NodeId been a generic Graph<N> param, a single graph type could claim to be a graph of u32 ids and (i32,i32) ids, and every consumer would need an extra ambiguous type parameter.

Capstone insight

The capstone rebuilds the iterator-adapter machinery and reveals the deepest move: an adapter’s associated type is computed from its generic parameters.

struct Map<I, F> { iter: I, f: F }   // generic over inner iter + closure

impl<I, F, B> MyIterator for Map<I, F>
where
    I: MyIterator,
    F: FnMut(I::Item) -> B,          // F maps inner items to some B
{
    type Item = B;                   // <-- the adapter's output IS the closure's output
    fn next(&mut self) -> Option<Self::Item> {
        match self.iter.next() {
            Some(x) => Some((self.f)(x)),
            None => None,
        }
    }
}

type Item = B is the whole trick. B is a generic parameter of the impl, constrained by the closure’s return type, and it becomes the associated type of the resulting iterator. That is how a chain like

Upto { next: 1, end: 4 }
    .map_it(|x| x + 10)        // u32 -> u32
    .map_it(|x| x as usize * 2) // u32 -> usize

threads its element type u32 → u32 → usize entirely through associated-type projection, resolved statically with zero annotations. Every std iterator chain you have ever written works exactly this way.

Explain it back

Answer these cold:

1. Why can a type implement From<A> and From<B> but not have two Iterator impls with different Items?
2. Why does let x: i32 = something.into() need the annotation while iter.next() does not?
3. What does where I: Iterator<Item = u64> give you that where I: Stream<u64> (a generic-param trait) would not?
4. Why must you write Box<dyn Iterator<Item = u32>> and not Box<dyn Iterator>?
5. In Add<Rhs = Self> { type Output; }, why is Rhs generic but Output associated?
6. In the Map<I, F> adapter, where does type Item come from, and why is that the key to compile-time iterator chains?

See also

• Conversion traits — From/Into are the archetypal generic-param traits (and the source of .into() ambiguity).
• Borrow / ToOwned — ToOwned::Owned is an associated type used exactly as an “output determined by the impl”.
• Lifetimes in depth — the Iterator Item lifetime rung is the lifetime-flavored version of projection.

Generic bounds & where clauses

Ladder: src/bin/generic_bounds.rs · Run: cargo run --bin generic_bounds · Phase 2 · 9 rungs

TL;DR

A generic parameter T arrives as a black box: the compiler knows nothing about it, so you can’t call anything on it. A bound (T: Trait) is a contract that does two things at once — it restricts the caller (“you may only pass types that implement Trait”) and empowers the body (“therefore I’m allowed to use Trait’s methods on a T”). Every method you call on a generic must be justified by a bound.

A where clause is the same bounds written below the signature instead of inline. It’s not just cosmetic: the inline <T: Bound> form can only bound a bare type parameter, so anything structured — a projection like I::Item, or a bound on a derived type like &'a C or Vec<T> — must live in a where clause. That’s the dividing line.

Why this exists (from first principles)

Rust monomorphizes generics: min_item::<i32> and min_item::<char> compile to separate machine code. But type-checking happens once, on the generic definition, before any concrete type is known — not separately per instantiation (that’s C++ templates, where errors surface at the use site as walls of noise).

So when the compiler sees this generic body, it must decide right now whether it’s legal:

fn min_item<T>(items: &[T]) -> T {
    // is `a < b` allowed here? the compiler has NO idea what T is.
}

With nothing known about T, almost nothing is permitted — you can move it, drop it, take its address, and little else. A bound is how you tell the checker what T is guaranteed to support, so it can verify the body once and trust it for every future T:

fn min_item<T: PartialOrd>(items: &[T]) -> T {
    // now `a < b` typechecks: PartialOrd guarantees it for EVERY T a caller can pass.
}

This is the whole game. Bounds are how you trade away “any type at all” for “the capabilities you actually need.” Too few bounds and the body won’t compile; too many and you needlessly reject callers (the over-constraint footgun in rung 3).

The ladder at a glance

The ideas, built up

1. A bound is a contract in two directions

fn min_item<T>(items: &[T]) -> T
where
    T: PartialOrd + Copy,
{
    *items
        .iter()
        .min_by(|a, b| a.partial_cmp(b).expect("items are comparable"))
        .expect("items is non-empty")
}

Two bounds, two distinct reasons:

• PartialOrd lets the body compare elements (a.partial_cmp(b)). Without it, < and partial_cmp don’t exist for T.
• Copy lets the function return a T by value out of a borrowed &[T]. You’re handing back one of the borrowed elements; Copy says “duplicating it is a trivial bit-copy, the original stays put.”

Why PartialOrd, not Ord? The test passes &[2.5, 0.5, 7.0]. Floats are only PartialOrd, never Ord, because NaN makes them not totally ordered (NaN < x, NaN > x, and NaN == x are all false). Reaching for PartialOrd keeps f64 callers in; demanding Ord would lock them out. Picking the weakest bound that still compiles is a real API-design instinct — see Associated types vs generic params for the same theme.

2. Multiple bounds, and where where earns its keep

fn dedup_describe<T>(items: &[T]) -> String
where
    T: PartialEq + Copy + Debug,
{
    let mut result = Vec::new();
    for item in items {
        if result.last() != Some(item) {   // PartialEq: compare neighbours
            result.push(*item);            // Copy: duplicate out of the borrow
        }
    }
    format!("{:?}", result)                // Debug: render with {:?}
}

Each bound again maps to one capability: PartialEq for the !=, Copy for *item, Debug for {:?}. With three bounds, inline <T: PartialEq + Copy + Debug> already crowds the line; the where form scales without pushing the return type off-screen. For these bounds it’s pure style — they’d work inline too. Rung 6 is where where stops being optional.

A subtlety worth noting: result.last() is Option<&T> and Some(item) is Option<&T>, so the != compares two Option<&T>. That works because PartialEq is lifted through Option and & — Option<&T>: PartialEq holds whenever T: PartialEq. The single bound on T quietly powers a comparison two layers up.

3. Bound the method, not the struct

The single most common beginner mistake:

// WRONG: the bound infects every use site.
struct Stack<T: Debug> { items: Vec<T> }
// Now `Stack<SomethingNotDebug>` won't even compile — you can't store a socket,
// a closure, or any non-Debug type, even if you never print it.

// OK: the struct holds ANYTHING; the capability lives on the impl that needs it.
struct Stack<T> { items: Vec<T> }

impl<T> Stack<T> {                 // unbounded: available for every T
    fn new() -> Self { Self { items: Vec::new() } }
    fn push(&mut self, value: T) { self.items.push(value); }
    fn len(&self) -> usize { self.items.len() }
}

impl<T: Debug> Stack<T> {          // bounded: only when T: Debug
    fn dump(&self) -> String { format!("{:?}", self.items) }
}

The ladder proves it: Stack<NotDebug> (a type with no Debug impl) still constructs, pushes, and reports its length, because those methods live in the unbounded impl<T>. Only dump requires Debug, and only dump is gated.

This is exactly how Vec<T> is built. Vec<T> stores any T; .contains appears only for T: PartialEq, .to_vec only for T: Clone, .sort only for T: Ord. The capabilities are sliced across many impl blocks so the container itself constrains nothing.

Rule of thumb: put a bound at the lowest point that needs it. On a struct definition it’s almost always wrong; on the impl block or the individual method is almost always right.

4. A method that exists only for some T

Push rung 3 one notch further: the bound can gate a single method, and a value whose T doesn’t satisfy it simply doesn’t have that method.

struct Pair<T> { first: T, second: T }

impl<T> Pair<T> {
    fn new(first: T, second: T) -> Self { Self { first, second } }
}

impl<T: PartialOrd + std::fmt::Display> Pair<T> {
    fn cmp_display(&self) -> String {
        let largest = if self.first > self.second { &self.first } else { &self.second };
        format!("the largest is {}", largest)   // > from PartialOrd, {} from Display
    }
}

Pair<NotDebug> is a perfectly valid, constructible type — it just has a smaller API surface. Try to call the gated method on it and you get:

error[E0599]: the method `cmp_display` exists for struct `Pair<NotDebug>`,
              but its trait bounds were not satisfied
              `NotDebug: PartialOrd` is not satisfied

Note the wording: the method exists, but its bounds aren’t met. Method availability is decided per concrete type, at the call site. This is the literal mechanism behind the Rust Book’s cmp_display example, and behind every “why doesn’t .sum() work on my Vec<String>” question.

5. The hidden Sized bound, and ?Sized

Here is a bound you never wrote but is always there:

fn show<T>(x: &T) -> String { ... }
// really means:
fn show<T: Sized>(x: &T) -> String { ... }

Every generic parameter has an implicit T: Sized — Rust assumes types have a size known at compile time, because that’s what you need to put them on the stack, pass them by value, etc. The consequence bites the moment you try to use a DST (dynamically sized type) like str or [u8]:

fn show<T: std::fmt::Display>(x: &T) -> String { format!("{}", x) }

show(&42);                  // ok: T = i32, Sized
show("hello str");          // ERROR before the fix

error[E0277]: the size for values of type `str` cannot be known at compilation time

Why? The argument "hello str" is &str, which matches &T with T = str. But str is unsized, and the implicit Sized rejects it. The fix is the one bound you remove rather than add:

fn show<T: std::fmt::Display + ?Sized>(x: &T) -> String { format!("{}", x) }
//                              ^^^^^^ opt out of the default Sized bound

?Sized means “T might not be sized.” The price: you may only touch the value behind a pointer (&T, Box<T>, Rc<T>), never by value — because by-value needs a size. That is the deep reason you always see &str and never bare str in a signature, and why impl<T: Display + ?Sized> ToString for T (the impl that gives str a .to_string()) needs that ?Sized.

6. Bounds you can write only in a where clause

This rung is the concrete answer to “when do I actually need where?” Inline <T: Bound> syntax can only attach a bound to a bare type parameter. The moment your bound is about a type expression — T::Item, &T, Vec<T> — it has nowhere to go but a where clause.

6a — associated-type projection. You can declare <I: IntoIterator> inline, but the bound that its items are printable is a fact about I::Item, not I:

fn join_display<I>(iter: I) -> String
where
    I: IntoIterator,
    I::Item: std::fmt::Display,   // a projection — cannot go inline in <...>
{
    iter.into_iter().map(|x| x.to_string()).collect::<Vec<_>>().join(", ")
}

6b — a higher-ranked bound on a derived type. To sum a collection by reference (without consuming it), the capability you need is “I can iterate &C”, which is a bound on &'a C, not on C:

fn sum_borrowed<'a, C>(collection: &'a C) -> i32
where
    &'a C: IntoIterator<Item = &'a i32>,   // bound on &'a C — impossible inline
{
    let mut sum = 0;
    for item in collection { sum += item; }   // uses the &C: IntoIterator impl
    sum
}

The fully general version of 6b uses a higher-ranked trait bound: where for<'a> &'a C: IntoIterator<Item = &'a i32> — “for any lifetime, &C is iterable.” See HRTB — for<'a> for why for<'a> is needed and how it differs from a single named 'a. Either form proves the same point: the bound is structurally a clause about &C, and only where accepts clauses about type expressions.

7. Blanket impls — implement a trait for every qualifying type

trait Summary {
    fn summary(&self) -> String;
}

impl<T: Debug> Summary for T {            // ONE impl covers infinitely many types
    fn summary(&self) -> String { format!("{:?}", self) }
}

After this, 42.summary(), vec![1, 2].summary(), and Point { x: 1, y: 2 }.summary() all work with zero per-type code. This is the mechanism behind ToString (impl<T: Display + ?Sized> ToString for T) and Into (impl<T, U: From<T>> Into<U> for T — implement From, get Into free).

The cost is coherence. Once a blanket impl covers a set of types, you cannot carve out a special case:

// uncommenting this triggers:
// error[E0119]: conflicting implementations of trait `Summary` for type `i32`
impl Summary for i32 {
    fn summary(&self) -> String { format!("the int {}", self) }
}

i32 is already covered by the blanket impl, and stable Rust has no specialization, so the second impl is an illegal overlap. This trade-off — “implement for all T: Bound” versus “exactly one impl per (trait, type)” — is the central tension of trait design. It’s covered in depth in its own note: Blanket impls & coherence.

8. Conditional trait impls — what #[derive] really does

A wrapper should gain a capability only when its contents have it. That’s a conditional trait impl, and it’s literally what #[derive(PartialEq)] and #[derive(Clone)] expand to:

struct MyBox<T>(T);   // no derives — hand-written below

impl<T: PartialEq> PartialEq for MyBox<T> {
    fn eq(&self, other: &Self) -> bool { self.0 == other.0 }
}

impl<T: Clone> Clone for MyBox<T> {
    fn clone(&self) -> Self { MyBox(self.0.clone()) }
}

The bound lives on the impl block, not on the struct. So MyBox<T> exists for any T; it only acquires == when T: PartialEq and .clone() when T: Clone. Two consequences the ladder checks:

• MyBox<MyBox<i32>> is comparable, because the requirement recurses: MyBox<i32>: PartialEq holds because i32: PartialEq, so MyBox<MyBox<i32>>: PartialEq holds in turn.
• A MyBox of a non-comparable type silently lacks == — no error until you try to use it.

The one place #[derive] is subtly wrong. #[derive(Clone)] on MyBox<T> mechanically emits impl<T: Clone> Clone for MyBox<T>. But if the field were an Rc<T>, MyBox would be cloneable even when T itself isn’t (cloning an Rc just bumps a refcount). Hand-writing the impl lets you choose a tighter or looser bound than derive’s reflexive T: Clone. Crates like derivative exist precisely to fix this.

Footguns

Real-world patterns

• Capability slicing across impl blocks. Vec<T>, HashMap<K, V>, Option<T> all keep the type definition unbounded and attach methods to bounded impls. Mimic this in your own containers.
• Blanket extension traits. itertools::Itertools and tower::ServiceExt declare a trait with default methods plus impl<T: Bound> Ext for T {}, instantly adding methods to every existing type. The capstone builds a miniature of this.
• ?Sized in generic APIs. Functions that should accept &str and &String take T: AsRef<str> + ?Sized or impl AsRef<str>; ToString/Borrow/Hash impls thread ?Sized through so DSTs participate.
• Conditional impls = how #[derive] works. Every derived Clone/PartialEq/Debug is a impl<T: Trait> Trait for Wrapper<T>. Reading derive output demystifies a huge amount of std.

Capstone insight

The IterExt extension trait fuses every earlier rung into the exact pattern real iterator-adapter crates use:

trait IterExt: Iterator {                       // supertrait: gives access to Self::Item + iteration
    fn min_max(self) -> Option<(Self::Item, Self::Item)>
    where
        Self: Sized,                            // self-by-value needs a known size
        Self::Item: Ord + Copy,                 // per-method capability bound
    { /* fold to running (min, max); `min.zip(max)` yields None if empty */ }

    fn counts(self) -> HashMap<Self::Item, usize>
    where
        Self: Sized,
        Self::Item: Eq + Hash,                  // HashMap key requirements
    { /* *map.entry(item).or_insert(0) += 1 */ }

    fn join_with(self, sep: &str) -> String
    where
        Self: Sized,
        Self::Item: std::fmt::Display,
    { /* map(to_string).collect::<Vec<_>>().join(sep) */ }
}

impl<I: Iterator> IterExt for I {}              // blanket impl: EVERY iterator gets all three

Three ideas snap together:

1. Supertrait bound (: Iterator) — every method body can use Self::Item and consume self by iterating.
2. Blanket impl (impl<I: Iterator> IterExt for I {}) — like rung 7, this hands the methods to every iterator in the program for free. The method bodies live as defaults in the trait; the impl is empty. This is the canonical Itertools shape.
3. Per-method where Self::Item: bounds — like rung 6, each adapter is callable only when the element type qualifies. "abc".chars().min_max() works (char: Ord + Copy); an iterator of a non-Ord type silently won’t offer min_max.

The aha: this is precisely how std::iter::Iterator itself is built. .sum() needs Self::Item: Sum, .max() needs Ord, .collect::<String>() needs the right FromIterator. Bounds aren’t bureaucracy bolted onto generics — they’re the dials that let one trait expose a different API to every element type, decided independently at each call.

Explain it back

• Why can’t you call any methods on a bare T with no bounds? What can you still do with it?
• A bound restricts the caller and empowers the body. Give one concrete example of each direction from min_item.
• Why does min_item use PartialOrd instead of Ord? Which caller would Ord exclude?
• Where should the bound go: on struct Stack<T> or on an impl? Why is the struct almost always wrong?
• What is the hidden default bound on every <T>? What exactly does ?Sized change, and why must a ?Sized value sit behind a reference?
• Name two bounds that can be written only in a where clause, and say why inline syntax can’t express them.
• What does #[derive(Clone)] expand to for struct MyBox<T>(T)? When is that derived bound too strict?
• In IterExt, why does each method need both where Self: Sized and a where Self::Item: ... bound? What goes wrong without each?

See also

• Blanket impls & coherence — the E0119/orphan-rule story behind rung 7, in depth.
• Associated types vs generic params — the other axis of generic API design.
• HRTB — for<'a> — the for<'a> &'a C: ... bound from rung 6, fully unpacked.
• Static vs dynamic dispatch — what bounds enable at monomorphization vs. dyn Trait.
• Lifetimes in depth — 'a: 'b outlives bounds are bounds too.

Blanket impls & coherence

Ladder: src/bin/blanket_coherence.rs · Run: cargo run --bin blanket_coherence · Phase 2 · 9 rungs

TL;DR

An impl block is a fact you assert to the compiler: “this trait is implemented for this type.” Coherence is the rule that there is exactly one such fact for any given (trait, type) pair — never zero-ambiguity, never two conflicting answers. A blanket impl (impl<T> Trait for T) asserts a fact about infinitely many types in one block. The orphan rule is the guardrail that stops two different crates from each asserting conflicting facts about types neither of them owns.

Every error in this topic — E0117, E0119, E0210 — is coherence defending that “exactly one” invariant from a different angle.

Why this exists (from first principles)

Method resolution has to be deterministic and global. When you write x.into(), the compiler must find the impl — not “an” impl, and definitely not two. Now imagine impls were unrestricted:

• Crate A does impl Display for Vec<i32> to print [1, 2, 3].
• Crate B does impl Display for Vec<i32> to print 1 2 3.
• Your program depends on both. vec![1,2,3].to_string() now has two answers.

There is no sound way to pick. Worse, adding a dependency could silently change which impl wins, breaking code far away. Rust forbids the situation from ever being written, rather than trying to resolve it after the fact. That ban is coherence, and its crate-boundary half is the orphan rule:

To impl SomeTrait for SomeType, at least one of {the trait, the type} must be local to your crate.

If both are foreign, you can’t write the impl — which means no two crates can both reach in and define conflicting impls for types they don’t own. The guarantee buys you: any (trait, type) pair resolves to the same impl no matter what crates are linked.

The ladder at a glance

The ideas, built up

1. A blanket impl is one fact about infinitely many types

trait Named {
    fn type_label(&self) -> &'static str;
}

impl<T> Named for T {
    fn type_label(&self) -> &'static str {
        "a value"
    }
}

After that single block, 42i32, String::from("hi"), and your own Widget all have .type_label(). You never wrote a per-type impl. The generic T ranges over every type that exists, so the impl is a universally-quantified statement: “for all T, T: Named.”

This is also the first hint at why the orphan rule must exist. If a downstream crate also wrote impl<T> Named for T, then for i32 there would be two impls — exactly the ambiguity coherence forbids. Owning the trait Named is what lets you (and only you) make this universal claim.

2. Bounds narrow the blanket to a subset

Real blanket impls almost always carry a bound:

impl<T: Display> Loud for T {
    fn loud(&self) -> String {
        format!("{}!!!", self)
    }
}

Now 7i32.loud() and "hi".loud() work (both are Display), but a non-Display type gets a compile error if you call .loud() on it. The bound is doing real work: it restricts which types the universal claim applies to. Mentally, impl<T: Display> Loud for T reads as “for all T where T: Display, T: Loud.”

Key consequence for rung 6: impl<T> Loud for T and impl<T: Display> Loud for T could not coexist for the same trait — every Display type would match both, and the compiler has no tiebreaker. Two different traits (Named vs Loud) is fine, because each impl is a separate fact about a separate trait.

3. The From → Into trick (std’s most famous blanket impl)

This is the pattern in the standard library:

// std (paraphrased):
impl<T, U> Into<U> for T where U: From<T> {
    fn into(self) -> U { U::from(self) }
}

You implement From, and .into() materializes for free, in the correct direction. The ladder rebuilds it with MyFrom / MyInto so the machinery is visible:

impl<T, U> MyInto<U> for T
where
    U: MyFrom<T>,
{
    fn my_into(self) -> U {
        U::my_from(self)
    }
}

impl MyFrom<Celsius> for Fahrenheit {
    fn my_from(c: Celsius) -> Fahrenheit {
        Fahrenheit(c.0 * 9.0 / 5.0 + 32.0)
    }
}

You write zero direct impls of MyInto — the one blanket covers every convertible pair. Note the shape: the impl is for T (the source), with U a free type parameter pinned down by the where-clause.

The inference gotcha. In let f: Fahrenheit = c.my_into();, what supplies U? Nothing in c says Fahrenheit — the type annotation does. If you’d also written impl MyFrom<Celsius> for Kelvin, then c.my_into() with no annotation is ambiguous (E0282/E0283). Coherence guarantees at most one impl per (T, U) pair; it does not pick U for you. That’s why real .into() calls so often need let x: Target = or a turbofish.

4. The extension trait — adding methods to types you don’t own

You can’t add an inherent method to Iterator (you don’t own it). But you can define your own trait and blanket-impl it for everything that is an Iterator. This is exactly how itertools bolts .chunks(), .dedup(), etc. onto every iterator:

trait IterExt: Iterator<Item = u64> {        // supertrait: Self IS the iterator
    fn sum_of_squares(self) -> u64
    where
        Self: Sized,
    {
        self.map(|n| n * n).sum()
    }
}

impl<I: Iterator<Item = u64>> IterExt for I {} // empty body: inherits the default

One blanket impl, and vec![...].into_iter(), (1..=3), and (0..10).filter(...) all gain .sum_of_squares() — because they’re all Iterator<Item = u64>.

Two design shapes, know both:

// Supertrait form (idiomatic, std/itertools use this):
trait IterExt: Iterator<Item = u64> { ... }
impl<I: Iterator<Item = u64>> IterExt for I {}

// Type-parameter form (works, but threads an extra param everywhere):
trait IterExt<I: Iterator<Item = u64>> { ... }
impl<I: Iterator<Item = u64>> IterExt<I> for I { ... }

The supertrait form makes Self be the iterator — no extra parameter to name in bounds. The type-parameter form parameterizes the trait, so every bound that mentions it (fn f<T: IterExt<?>>) has to thread the I. Prefer the supertrait.

Why does this need a separate trait? The orphan rule (next): you can’t blanket-impl a foreign trait over all iterators, and you can’t add methods to Iterator itself. Owning IterExt is what makes the blanket legal.

Footguns

E0117 — the orphan rule (foreign trait + foreign type)

// WRONG: Display is foreign, Vec<i32> is foreign -> E0117
impl Display for Vec<i32> { ... }

// OK: you own Summary (local trait), so a foreign type is fine
impl Summary for Vec<i32> { ... }

// OK: you own Temperature (local type), so a foreign trait is fine
impl Display for Temperature { ... }

The rule in one line: at least one of {trait, type} must be yours. The first breaks it from both sides; the other two each satisfy it from one side. This is also why a blanket impl of a foreign trait like impl<T> Display for T is doubly forbidden — it’s a foreign trait and it would monopolize Display, locking every other crate out of implementing it for their own types.

E0119 — overlapping impls (no specialization on stable)

trait Kind { fn kind(&self) -> &'static str; }

// Both legal individually, both in your crate...
impl<T> Kind for T   { fn kind(&self) -> &'static str { "generic" } } // (D)
impl Kind for i32    { fn kind(&self) -> &'static str { "integer" } } // (C)
// ...but i32 matches BOTH -> E0119 conflicting implementations

The instinct is “the compiler should just prefer the more specific i32 impl.” That preference is specialization — and it is nightly-only. On stable Rust there is no tiebreaker, so two impls that can both match one type is simply ambiguous and rejected. The fix without specialization is to not overlap: drop the blanket and write concrete impls per type, so exactly one matches each.

Contrast with rung 3: impl<T, U> MyInto<U> for T never conflicted because it was the only impl of MyInto. Overlap requires two impls of the same trait both covering one type.

E0210 — the uncovered type parameter (the subtle one)

The orphan rule is not just “some type must be local” — it’s about order and coverage. Scanning Self, then the trait’s type arguments left-to-right, a local type must appear before any bare (uncovered) type parameter.

• A bare T is uncovered.
• A T wrapped in your local type, like Wrapper<T>, is covered.

use std::ops::Add;
struct Meters(f64);

// WRONG: Add is foreign; Self is a BARE T (uncovered), and the only local
// type `Meters` appears AFTER it as Rhs -> E0210
impl<T> Add<Meters> for T { ... }

// OK: local type is in the Self position, first
impl Add for Meters { type Output = Meters; ... }

// OK: From is foreign, but T is COVERED by your local Wrapped<T>
impl<T> From<T> for Wrapped<T> { ... }

Why the asymmetry? impl<T> Add<Meters> for T claims Add<Meters> for types you don’t own — so the crate that owns some Foo could legitimately add impl Add<Meters> for Foo, and now Foo has two impls the compiler can’t see across crates. impl<T> From<T> for Wrapped<T> only ever claims From for your Wrapped, and the orphan rule stops anyone else from impl’ing From<…> for Wrapped<…>. The covered case is collision-proof; the uncovered one is a future-collision waiting to happen, so it’s banned.

Real-world patterns

The newtype workaround

Rung 5 showed impl Display for Vec<i32> is illegal. The standard escape hatch: wrap the foreign type in your own local newtype, then impl the foreign trait for the newtype. Now one side is local — legal.

struct Wrapper(Vec<i32>);

impl std::fmt::Display for Wrapper {       // legal: Wrapper is local
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let parts: Vec<String> = self.0.iter().map(|n| n.to_string()).collect();
        write!(f, "[{}]", parts.join(", "))
    }
}

impl std::ops::Deref for Wrapper {         // restore the inner type's methods
    type Target = Vec<i32>;
    fn deref(&self) -> &Vec<i32> { &self.0 }
}

The cost of a newtype is that you lose the inner type’s methods; Deref buys them back via deref coercion, so w.len(), w.iter(), w.first() all work.

Deref is fine here, but don’t abuse it. A transparent wrapper that exposes everything is the right use. But if the newtype exists to enforce an invariant (a SortedVec, a NonEmptyVec), Deref leaks the inner type’s mutators (push, clear) and lets callers break the invariant behind your back. Deref should mean “is-a smart pointer to,” not “has-a field I’m exposing.” For restricting wrappers, expose a curated API instead.

Capstone insight: sealing a trait with a private blanket impl

The capstone ships a tiny stats library: a StatsExt extension trait that adds .mean() and .variance() to any Iterator<Item = f64> via a blanket impl — and then seals it so downstream code can use the methods but can never implement the trait.

mod sealed {
    pub trait Sealed {}
    impl<I: Iterator<Item = f64>> Sealed for I {}   // the ONLY impl of Sealed
}

trait StatsExt: Iterator<Item = f64> + sealed::Sealed {
    fn mean(self) -> f64;
    fn variance(self) -> f64;
}

impl<I: Iterator<Item = f64>> StatsExt for I {
    fn mean(self) -> f64 { /* collect to Vec<f64>, average; empty -> 0.0 */ }
    fn variance(self) -> f64 { /* mean, then average of (x - mean)^2 */ }
}

The “aha” is how coherence makes the seal unbreakable:

1. Sealed is pub inside a private module — outside code literally cannot name it.
2. The only impl of Sealed is your blanket impl. Coherence means no one else can add another.
3. StatsExt requires Sealed as a supertrait. So to write impl StatsExt for MyType, a downstream crate would also need MyType: Sealed — which they can neither name nor satisfy.

The result: a public trait that is fully usable but closed to implementation. This is the production pattern std uses to keep traits like Error-adjacent helpers (and many crate APIs) extensible internally while presenting a stable, non-overridable surface. The blanket impl of a private trait is the gate; coherence is the lock.

Explain it back

Future-you should be able to answer these cold:

1. Why does vec![1,2,3].to_string() having “two answers” have to be a compile error rather than a runtime choice?
2. State the orphan rule in one sentence. Which of {trait, type} is local in impl Display for Wrapper?
3. Why can’t impl<T> Kind for T and impl Kind for i32 coexist on stable Rust? What single nightly feature would make it work, and what would it do?
4. In let f: Fahrenheit = c.into(), what supplies the target type? When does omitting the annotation become a hard error?
5. Why is impl<T> Add<Meters> for T (E0210) a future-collision risk, but impl<T> From<T> for Wrapped<T> is not? Define “covered.”
6. When is Deref on a newtype the right call, and when does it actively break your type’s guarantees?
7. In the sealed-trait capstone, name the three things that together make impl StatsExt for MyType impossible downstream.

See also

• Associated types vs generic params — the other half of “designing a trait”: type Item vs <T>, and where E0119 also shows up.
• Conversion traits — From/Into, TryFrom, the orphan rule and reflexivity in the conversion setting.
• HRTB — for<’a> — the DecodeOwned: for<'de> Decode<'de> pattern is another supertrait-based bound, like the sealed-trait supertrait here.

Static vs dynamic dispatch

Ladder: src/bin/dispatch.rs · Run: cargo run --bin dispatch · Phase 2 · 9 rungs

TL;DR

When you call a trait method, which concrete implementation runs has to be decided somewhere. Rust gives you two places to decide it:

• Static dispatch (<T: Trait>, impl Trait): the compiler knows the concrete type at the call site. It stamps out a specialized copy of the code per type (monomorphization) and can inline. Fast, zero indirection — but code size grows and the set of types is fixed at compile time.
• Dynamic dispatch (dyn Trait): the concrete type is erased behind a fat pointer (data, vtable). The method is looked up at runtime through the vtable. One copy of the code, and it unlocks runtime flexibility (heterogeneous collections, types chosen by runtime values) — but each call is an indirection that usually can’t be inlined.

Every design choice in this area is picking which side of that trade you want. And there’s a third option for closed sets — an enum + match — that gets much of the best of both.

Why this exists (from first principles)

A trait is a promise: “this type has a hello() method.” But hello() for English and hello() for French are different functions at different machine addresses. When you write g.hello(), the generated code needs an address to jump to. The whole topic is: how does the compiler find that address, and when?

Two answers:

1. At compile time. If the compiler can see the concrete type of g right here, it just bakes in the correct address. To make that true for generic code, it duplicates the function once per concrete type used — monomorphization. Calls become direct, inlinable, free.

2. At runtime. If the concrete type isn’t known until the program runs (you chose it from user input, or you stuffed many different types into one list), the compiler can’t bake an address in. Instead it attaches a vtable — a little table of function pointers — to the value, and emits “load the address out of the vtable, then call it.” That indirection is the cost of not knowing the type until runtime.

Neither is “better.” They solve different problems, and a lot of Rust API design is about recognizing which problem you have.

The ladder at a glance

The ideas, built up

1. The same method, two dispatch strategies

Start with one trait and write the identical logic twice — once generic, once dyn:

trait Greet {
    fn hello(&self) -> String;
}

fn greet_static<T: Greet>(g: &T) -> String { g.hello() } // monomorphized per T
fn greet_dynamic(g: &dyn Greet) -> String  { g.hello() } // one fn, vtable lookup

The bodies are byte-for-byte the same. The difference is invisible in the source and lives entirely in how the call compiles:

• greet_static is generic. The compiler produces a distinct machine-code copy for English and another for French. Each call jumps straight to a known address.
• greet_dynamic is one function. &dyn Greet is a fat pointer (data_ptr, vtable_ptr), and g.hello() reads the method address out of the vtable at runtime.

That second form is what lets you do this — pick the concrete type at runtime and still have a single static type for the variable:

let who: &dyn Greet = if condition { &en } else { &fr };
greet_dynamic(who);

2. impl Trait means two different things by position

impl Trait is one syntax with two opposite meanings depending on where it appears:

fn loudest(g: impl Greet) -> String { g.hello().to_uppercase() } // ARGUMENT
fn default_greeter() -> impl Greet  { French }                   // RETURN

• Argument position is pure sugar for a generic bound: fn loudest(g: impl Greet) is exactly fn loudest<T: Greet>(g: T). Static dispatch, monomorphized per call site. The caller picks the type.
• Return position means “I return one specific concrete type that I’m not naming.” Still static — the compiler knows the real type (French), the caller just can’t name it. The callee picks, and it must be a single type across all return paths.

That “single type” rule is quiet here but becomes a wall in rung 4.

Scaffolding note from the file: a bare todo!() in a -> impl Greet function won’t even compile. The inferred return type would be !, and !: Greet is false. Return-position impl Trait demands a real concrete type at compile time.

3. Seeing monomorphization with your own eyes

“Monomorphization” stays abstract until you prove it. This function reports the name of its own type parameter, with no value argument at all:

fn tag<T>() -> &'static str { std::any::type_name::<T>() }

tag::<English>();     // ".../dispatch::English"
tag::<i32>();         // "i32"
tag::<Vec<String>>(); // "alloc::vec::Vec<alloc::string::String>"

If there were only one compiled tag, it couldn’t possibly know which T it was called with — it takes no runtime input. It knows because the compiler stamped a separate copy of tag per T, each with its own type name baked in. That’s monomorphization made visible. A &dyn parameter erases the type, so a single function literally cannot recover it this way.

4. The first wall: a type chosen at runtime

Now ask for one of two types based on a runtime flag:

// WRONG — does not compile:
fn broken_pick(french: bool) -> impl Greet {
    if french { French } else { English } // `if` and `else` have incompatible types
}

-> impl Greet promised one concrete type, but the type now depends on a runtime value. There is no single type the compiler can fill in. Static dispatch is out of road.

The fix is to erase the type behind a trait object, giving both branches the same type — Box<dyn Greet>:

// OK:
fn pick_greeter(french: bool) -> Box<dyn Greet> {
    if french { Box::new(French) } else { Box::new(English) }
}

The cost: a heap allocation plus a vtable lookup per .hello(). The payoff: a type decided at runtime. The moment the type is a runtime decision, you reach for dyn.

5. Heterogeneous collections: the headline feature of dyn

A Vec<T> is monomorphic — every element is the exact same T:

// WRONG — different types in one Vec:
let bad = vec![English, French]; // expected `English`, found `French`

To hold a mixed bag of “things that implement Greet,” erase each element:

// OK:
fn build_crowd() -> Vec<Box<dyn Greet>> {
    vec![Box::new(English), Box::new(French), Box::new(English)]
}

Now every slot has the same type — a fat pointer — even though the values underneath differ. A list of differently-typed things behind one shared interface is simply impossible with pure static dispatch. This is the single biggest thing dynamic dispatch buys you.

6. The mirror: -> Self is the thing only static can do

Rung 5 showed what dyn can do that generics can’t. Rung 6 is the reverse — a trait generics handle fine but that cannot become a dyn at all:

trait Doubler {
    fn doubled(&self) -> Self; // returns Self -> NOT object-safe
}

fn twice<T: Doubler>(x: T) -> T { x.doubled() } // totally fine

// WRONG — does not compile:
let obj: Box<dyn Doubler> = Box::new(21_i32);
// "the trait `Doubler` cannot be made into an object because method `doubled`
//  references the `Self` type"

Why? A dyn Doubler erases the concrete type, but doubled(&self) -> Self returns a value of that erased type. A vtable can’t describe “returns something whose size and layout is the type we just threw away.” Under <T: Doubler>, the concrete type is known at each instantiation, so -> Self is no problem.

This is exactly why there is no dyn Clone: clone(&self) -> Self references Self by value. Generic methods and by-value Self are the other common object-safety blockers.

So rungs 5 and 6 bracket the trade: