The escape hatches

Try this before reading anything else. It is meant to fail.

You cannot do it, and the reason is precise: ownership is a tree. Document owns its Sections. A back-reference from Section to Document makes it a cycle, and there is no way to write that with & without the lifetime propagating into both structs and then deadlocking on itself — Document<'a> containing Section<'a> containing &'a Document<'a> is a type that cannot be constructed.

That failure is worth having had. Everything below exists because of it, and the tools make much more sense when you have felt the gap they fill.

The key idea

Everything in std::cell is built on one primitive: UnsafeCell<T>, the single type in the language where the compiler permits mutation through a &. Every safe wrapper — Cell, RefCell, Mutex, RwLock, the atomics — is UnsafeCell plus a discipline that makes it sound.

The menu

Two things fall out of the table that people routinely get wrong.

Rc is not a mutability tool. Rc<T> gives shared ownership, and shared ownership means you only ever get &T out of it. To mutate you need Rc<RefCell<T>> — two separate mechanisms doing two separate jobs. The combination is common enough to look like one thing, but it is not.

Cell is genuinely free. It never hands out a reference, so there is nothing to track. You replace whole values (get, set, replace, take). For a counter or a flag, Cell is the right tool and costs nothing at all — a fact that surprises people who think all interior mutability is expensive.

use std::cell::RefCell;

fn main() {
    let c = RefCell::new(vec![1, 2, 3]);

    let first = c.borrow();
    c.borrow_mut().push(4);

    println!("{:?}", first);
}

thread 'main' panicked at src/main.rs:7:7:
already borrowed: BorrowMutError

Rc<RefCell<T>>, and its bill

This is the pattern that solves the opening exercise:

use std::rc::{Rc, Weak};
use std::cell::RefCell;

struct Document {
    sections: RefCell<Vec<Rc<Section>>>,
}

struct Section {
    doc: Weak<Document>,      // note: Weak, not Rc
}

It works. It is also the pattern newcomers reach for far too often, so it is worth naming the costs explicitly:

• Runtime borrow tracking, and a panic path in code that was not there before.
• No Send — Rc and RefCell are single-threaded. If this data ever needs to cross a thread boundary you rewrite to Arc<Mutex<T>>, and that is not a find-and-replace.
• Cycles leak. This is the big one.

Rc is reference counting with no cycle collector. If Document holds Rc<Section> and Section holds Rc<Document>, both counts stay at 1 forever and neither is ever dropped. Memory leaked, quietly, with no unsafe code and no warning.

That is why the field above is Weak<Document>. A Weak does not contribute to the strong count; you call .upgrade() to get an Option<Rc<T>> and handle the case where the target is gone.

Worth being precise about in conversation: Rust does not prevent memory leaks, and never claimed to. Leaks are safe. mem::forget is a safe function. The guarantee is about use-after-free and data races, not about leaking — and people who say “Rust prevents memory leaks” are overselling it in a way a knowledgeable listener will notice.

What experienced Rust programmers do instead

Here is the part most tutorials never get to, and it is the most useful thing in this lesson.

For graph-shaped data, real Rust codebases usually do not use Rc<RefCell<T>>. They use an arena with indices:

struct Graph {
    nodes: Vec<Node>,          // the arena owns everything
    edges: Vec<(usize, usize)>,
}

struct Node {
    name: String,
    // no pointers, no lifetimes, no Rc
}

Nodes refer to each other by usize index. What that buys:

• Ownership stays a tree — the arena owns every node, so no cycles, no leaks, no refcounts.
• Indices are Copy and carry no lifetimes, so they can be stored anywhere, sent between threads, and serialised.
• Everything is contiguous, which is dramatically better for cache locality than a graph of separate allocations.

The cost is that an index is not checked: remove a node and old indices now point at the wrong element or out of bounds. Real libraries fix this with generational indices — the index carries a generation counter, so a stale index fails to resolve. That is what slotmap and petgraph do, and it is why petgraph addresses nodes with NodeIndex rather than pointers.

Knowing this distinguishes someone who has read about Rust from someone who has written it. The newcomer question is “how do I do a linked list in Rust?”; the experienced answer is usually “use a Vec and indices, and ask why you wanted a linked list.”

Part 2 checkpoint

Out loud, no notes:

1. State the borrow rule. (2.1)
2. Give the three reasons it exists. (2.1)
3. Why is &mut T not Copy? (2.2)
4. What is a lifetime? (2.3)
5. What are the two meanings of 'static? (2.4)
6. Six of the nine error codes are the same rule — which rule? (2.5)
7. What does RefCell change about the borrow rule? (2.6)

You have now crossed the hardest part of the course. Part 3 is a different machine — the trait solver — and most people find it substantially easier, because it rewards the kind of type-level thinking a TypeScript developer already has.

Next: 3.1 — Enums are TypeScript discriminated unions, done right.