Cover

About this book

This book is about systems programming in Rust.

By systems programming I mean programs that work close to the computer’s hardware and operating system. Data structures that decide how bytes are laid out in memory are one example. Threads that share work are another, and so are servers that read requests from a network connection. For programs like these, you need to know what happens underneath your code. That includes how memory is allocated and how the processor reads it. It also includes how the operating system runs threads and moves data across a network.

I use Rust because it lets you control these details. Its compiler also checks how your program uses memory and threads before the program runs. When the compiler rejects a program in this book, I explain what it found.

The book starts with small things and builds up. The first chapters cover bindings, files, and collections. The middle chapters build data structures and look at how they use memory. The later chapters add threads and the network, then the kernel boundary and production networking. In each chapter I introduce an idea in plain terms and work through a small example by hand. Only then do I show the code, a few lines at a time. Each chapter ends with the complete program.

Some programs appear in more than one version. When an early version has a problem, I show how the problem was found and what the next version changes.

Who should read this book

This book is for a programmer who has written some Rust and wants to use it for systems work.

You should know fn, let, if, match, struct, enum, Vec, and String. You should have met ownership and borrowing, for example in The Rust Programming Language. You do not need to know lifetimes in signatures, trait implementations such as TryFrom, Rc, Arc, atomics, unsafe, or async. Each of these is introduced in the chapter that first needs it.

No knowledge of operating systems or networking is assumed. When a chapter relies on a hardware or kernel detail, such as a cache line or a page fault, it explains that detail first.

What you will learn

After working through the book, you will be able to

• use Rust’s collections and iterators to solve problems on arrays, strings, and maps
• design types that reject invalid values where input enters a program
• implement linked lists, trees, graphs, and caches in safe Rust
• choose between Box, Rc, and a Vec of nodes to store linked data
• measure a data structure with a benchmark you can trust
• explain how CPU caches, false sharing, and page faults affect a running program
• build locks, queues, and thread pools from atomics and condition variables
• parse a network protocol safely and write a server with threads and with epoll
• explain how an async executor runs a Future to completion

How this book is organized

The book has ten parts. Each part builds on the ones before it.

Part 1, First steps

• Chapter 1 covers bindings, shadowing, functions, recursion, and loops, and times three ways of computing Fibonacci numbers.
• Chapter 2 covers files, directories, and command-line arguments, and introduces Result and ?.

Part 2, Collections and algorithms

• Chapter 3 solves problems with vectors, strings, and hash maps.
• Chapter 4 explains iterators and references, and introduces lifetimes.
• Chapter 5 uses heaps and sorted collections.
• Chapter 6 covers recursion and dynamic programming, and ends with jobs that also need a GPU’s memory and cores.

Part 3, Modeling data and ownership

• Chapter 7 builds types that reject invalid values, with structs, enums, and error types.
• Chapter 8 covers the pointer types Box, Rc, RefCell, Weak, Arc, and Cow.
• Chapter 9 builds linked lists, and measures four ways to store one.
• Chapter 10 merges many sorted lists into one.
• Chapter 11 covers trees and tries.
• Chapter 12 covers graphs.

Part 4, Memory and the machine

• Chapter 13 builds an LRU cache and measures two ways of storing its nodes.
• Chapter 14 splits a cache across locks and across machines.
• Chapter 15 covers allocation, CPU caches, paging, scheduling, and system calls.

Part 5, Concurrency

• Chapter 16 covers threads, atomics, and locks.
• Chapter 17 builds queues that threads use to pass work.
• Chapter 18 builds thread pools.
• Chapter 19 covers rate limiting, retries, and operations that are safe to repeat.

Part 6, The network

• Chapter 20 covers addresses, TCP, and two designs for a server.
• Chapter 21 parses and serves HTTP/1.1.
• Chapter 22 builds an async executor and two HTTP clients.

Part 7, The kernel boundary

• Chapter 23 maps files into memory, weighs mmap against read, and sends a file to a socket with sendfile.
• Chapter 24 opens the file descriptor table, and builds ls | wc -l from pipe, fork, dup2, and execvp.
• Chapter 25 covers edge-triggered epoll, the stall a missed edge leaves behind, and the modes that let several threads share one listener.

Part 8, Under the locks

• Chapter 26 builds a futex-backed mutex, counts its system calls, and runs two litmus tests on memory ordering.

Part 9, Production networking

• Chapter 27 follows a TCP connection as it closes, and the states a busy server leaves behind.
• Chapter 28 adds TLS and mutual TLS, with certificates made at startup.
• Chapter 29 builds a client connection pool with a hard limit and a reused connection.

Part 10, Compact implementations

• Chapter 30 gives ten short implementations, each sized to type in a live round, and points at the chapter that holds its full version.

Appendix A is the Rust cheat sheet: the compile errors and idioms that cost the most time. Appendix B is the full benchmark report. Appendix C is the long version of chapter 10, kept for readers who want every borrow trick.

Conventions

Code in the text looks like this. Programs are introduced in numbered listings, usually a few lines at a time. Each caption names the source file and the lines it shows. At the end of each chapter, the complete program appears as one listing.

Output from a program follows the command that produced it. Timings name the machine they were measured on. They will differ on yours.

A term is printed in bold where it is defined.

Three kinds of callouts appear in the text:

Each chapter ends with a summary and a few exercises.

About the code

The programs are in the rust-interview-lab directory of the repository at https://github.com/arpanpathak/cracking-the-systems-programming-interview. They use Rust edition 2024 and were built with rustc 1.96.0. The listings are taken from the source files without changes.

Library code with unit tests is in src/problems/. Runnable programs are in src/bin/. The data structures measured in chapters 9 and 13 are in benchmarking_examples/.

Run the programs from the rust-interview-lab directory:

cargo test --lib                        # the library's unit tests
cargo test --bin http_server            # the tests inside one program
cargo run --bin tcp_echo_server         # run one program
cargo run --release --bin benchmark     # benchmarks, always in release mode

Building the book

The book’s source is in the cracking-the-systems-programming-interview directory:

make art        # the chapter plates and the cover (needs rsvg-convert)
make figures    # the diagrams (needs Graphviz)
make html       # the browser edition, in book/
make pdf        # the print edition, in build/
make serve      # the browser edition at http://localhost:3000

About the cover

The cover shows the Chief Mechanic of the Ferrous Works in a workshop of gears. The crates are labelled Arc, Mutex, epoll, and Box, and the chain ends in a crate marked unsafe. Each chapter opens with a member of the same crew at a machine that represents the chapter’s subject.

The plates are generated by tools/art.py.

Bindings, functions, and loops

This chapter begins Part 1 of the book. Part 1 covers the pieces of Rust that every later chapter uses. This first chapter works with the smallest pieces: names for values, functions, and loops.

You will read and run two short programs. The first gives one name to three different values in turn. It shows what a let statement does, and how that differs from changing a value in place. The second program computes Fibonacci numbers in three ways and times each one. It shows how a function that calls itself uses memory, and it compares the running times of the three versions.

A few terms first:

• A binding is a name attached to a value. let x = 5; binds the name x to the value 5.
• A scope is the region of code where a binding can be used. In Rust, a scope is usually a block between { and }.
• The stack is the memory where a function keeps its local values while it runs.
• A stack frame is the part of the stack that belongs to one running call of a function.

1.1 A binding is a name for a value

When a function starts, Rust reserves a stack frame for it. Each let in the function gets a place in that frame, sized for its type. A u32 takes 4 bytes, and a usize takes 8 bytes on a 64-bit machine.

A String is different. Its text can grow, so the text is kept in heap memory. The heap is memory the program requests while it runs and gives back when it is done. The String value on the stack holds three numbers. They are the address of the text on the heap, the length of the text, and the size of the heap block.

When a function returns, its frame is removed. Every value in the frame is dropped. For a String, dropping it also frees its heap block.

1.2 Shadowing: one name, several values

You can write a second let with a name that is already in use. This does not change the first value. It creates a second binding with the same name, and the name now refers to the new value. Rust calls this shadowing. The first value still exists until the end of its scope, but you can no longer reach it by that name.

Because the second binding is a new variable, it can have a different type. Figure 1.1 follows the name value through three bindings of three types.

Here is the function that performs those three steps:

Listing 1.1 One name, three types. src/bin/shadowing.rs, lines 27 to 41

fn demonstrate_shadowing() -> String {
    // First binding is an integer.
    let value: u32 = 7;
    let mut log = format!("integer: {value}");

    // Shadow the integer with a String. The old integer is gone.
    let value = value.to_string();
    log.push_str(&format!("\nstring: {value}"));

    // Shadow the String with a usize computed from it.
    let value = value.len();
    log.push_str(&format!("\nusize: {value}"));

    log
}

Read the three let value lines in order:

1. let value: u32 = 7; creates a u32.
2. let value = value.to_string(); reads the u32, builds a String from it, and binds the name to the String. On the right-hand side, value still means the u32, because the new binding does not exist until the statement finishes.
3. let value = value.len(); reads the String and binds the name to its length, a usize.

None of these lines needs mut, because no value is changed after it is created. The log string does change, so it is declared let mut log. Each push_str appends one line to it, so the test can check all three stages.

Figure 1.2 (left) shows the stack frame after the third line. There are three values, and only the last one has a usable name.

1.2.1 When shadowing helps

Programs often receive a value in one form and need it in another. A number typed by a user arrives as text. After you parse it, you want the number and never the text again. Shadowing lets the number take the text’s name:

let count = read_line_from_user();   // a String, for example "42"
let count: u32 = count.trim().parse().expect("a number");

After the second line, count is a u32. Code below it cannot use the unparsed text by mistake, because no name refers to it any more.

1.2.2 A value captured earlier keeps its old value

A closure or a reference created before a shadowing let still refers to the first value:

let x = 1;
let show = || println!("{x}");
let x = x + 1;   // a new x
show();          // prints 1

The closure captured the first x. The second let created a new variable, and the closure never sees it.

1.3 Mutation: one value that changes

When you want one variable whose value changes over time, declare it with mut. The type stays the same, and each assignment writes into the same place in the frame.

Listing 1.2 A counter that changes in place. src/bin/shadowing.rs, lines 43 to 53

fn demonstrate_mutation() -> String {
    // If you need to mutate the same binding's value (same type) without
    // creating a new binding, mark it `mut`.
    let mut count = 0;
    let mut log = String::from("mut count:");
    for _ in 0..3 {
        count += 1;
        log.push_str(&format!(" {count}"));
    }
    log
}

for _ in 0..3 runs the loop body three times. The _ means the loop does not use the counter it is given. Each pass adds 1 to count and appends the new value to log. Figure 1.2 (right) shows the one slot for count at four moments.

Table 1.1 compares the two ways of changing what a name refers to.

1.4 The first complete program

The rest of shadowing.rs runs both functions and tests them. The file starts with a comment that explains the program:

Listing 1.3 The complete program. src/bin/shadowing.rs

// ============================================================================
// Variable shadowing vs mutation
//
// Ported from the Rust playground repo (`shadowing.rs`).
//
// What this demonstrates:
//   - Rust allows a new `let` binding with the same name as an existing
//     binding. This is called **shadowing**.
//   - Shadowing can change the value *and the type* of a variable without
//     declaring it `mut`.
//   - The old binding is no longer reachable after the shadowing `let`.
//
// Where this appears in practice:
//   - Rust SDK code often shadows parsed/deserialized values to convert them
//     from raw input to typed domain values:
//
//       let raw = request.header("X-GPU-Count")?;
//       let raw: u64 = raw.parse()?;   // shadow with a typed value
//
//   - Shadowing is also useful after unwrapping an `Option`/`Result` when the
//     guard value is no longer needed.
//
// Run:
//   cargo run --bin shadowing
// ============================================================================

fn demonstrate_shadowing() -> String {
    // First binding is an integer.
    let value: u32 = 7;
    let mut log = format!("integer: {value}");

    // Shadow the integer with a String. The old integer is gone.
    let value = value.to_string();
    log.push_str(&format!("\nstring: {value}"));

    // Shadow the String with a usize computed from it.
    let value = value.len();
    log.push_str(&format!("\nusize: {value}"));

    log
}

fn demonstrate_mutation() -> String {
    // If you need to mutate the same binding's value (same type) without
    // creating a new binding, mark it `mut`.
    let mut count = 0;
    let mut log = String::from("mut count:");
    for _ in 0..3 {
        count += 1;
        log.push_str(&format!(" {count}"));
    }
    log
}

fn main() {
    println!("=== Shadowing ===");
    println!("{}", demonstrate_shadowing());

    println!("\n=== Mutation ===");
    println!("{}", demonstrate_mutation());
}

// ============================================================================
// Tests (cargo test --bin shadowing)
// ============================================================================
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn shadowing_allows_type_changes() {
        let log = demonstrate_shadowing();
        assert!(log.contains("integer: 7"));
        assert!(log.contains("string: 7"));
        assert!(log.contains("usize: 1"));
    }

    #[test]
    fn mutation_requires_mut_binding() {
        let log = demonstrate_mutation();
        assert!(log.contains("mut count: 1 2 3"));
    }
}

The tests at the end are in a module marked #[cfg(test)]. The compiler builds that module only when you run cargo test. use super::*; brings the functions from the rest of the file into the test module. Each test calls a function and uses assert! to check that the log contains the expected text.

Run the program and its tests from the rust-interview-lab directory:

$ cargo run --bin shadowing
=== Shadowing ===
integer: 7
string: 7
usize: 1

=== Mutation ===
mut count: 1 2 3

$ cargo test --bin shadowing
running 2 tests
test tests::mutation_requires_mut_binding ... ok
test tests::shadowing_allows_type_changes ... ok

Now that you know where a function keeps its values, you can look at what happens when a function calls itself many times.

1.5 A function that calls itself

The Fibonacci numbers start with 0 and 1. Each later number is the sum of the two before it:

The definition can be written directly as a Rust function. A function that calls itself is recursive.

Listing 1.4 Fibonacci by recursion. src/bin/cs_fib.rs, lines 8 to 15

use std::time::{Duration, Instant};

/// Exponential: fib(n) recomputes fib(n - 1) and fib(n - 2) from scratch.
fn recursive(n: u64) -> u64 {
    if n < 2 {
        n
    } else {
        recursive(n - 1) + recursive(n - 2)
    }
}

For n of 0 or 1, the function returns n. This is the base case, the input that needs no further calls. For larger n, it calls itself twice and adds the results. The if is an expression, so its value is the function’s return value, and no return keyword is needed.

1.5.1 Counting the calls

Work out recursive(5) by hand. It calls recursive(4) and recursive(3). recursive(4) then calls recursive(3) again. Figure 1.3 draws every call.

The tree has 15 calls for n = 5. The tree for n contains the trees for n - 1 and n - 2, so the count grows by about 1.6 times per step. For n = 30, the function makes about 2.7 million calls. For n = 90, the count would be about 10¹⁹.

1.5.2 What each call uses on the stack

Every call gets its own stack frame, holding its n and the address to return to. A frame is removed when its call returns. So the stack does not hold all the calls at once, only the chain of calls that are waiting on each other. Figure 1.4 shows the deepest moment of recursive(4).

So the recursive version has two costs. Its time grows exponentially with n, because it repeats work. Its stack depth grows with n, which is small here but limits recursion on very deep inputs. Chapter 9 shows a list that crashes because of this second cost.

1.6 The same numbers with a loop

You only ever need the last two numbers to compute the next one. A loop can keep those two and move them forward one step at a time.

Listing 1.5 Fibonacci with a loop. src/bin/cs_fib.rs, lines 17 to 24

/// Linear time, constant space.
fn iterative(n: u64) -> u64 {
    let (mut previous, mut current) = (0u64, 1u64);
    for _ in 0..n {
        (previous, current) = (current, previous + current);
    }
    previous
}

let (mut previous, mut current) = (0u64, 1u64); declares two variables in one statement by matching a pair. The suffix u64 on each literal sets its type.

(previous, current) = (current, previous + current); assigns both variables at once. Rust evaluates the whole right-hand side first, using the old values, and only then writes both. Without the pair, you would need a temporary variable to avoid overwriting previous before it is used.

Trace iterative(5):

After five passes, previous is 5, which is fib(5). The loop runs n times and keeps two numbers, so its time grows in proportion to n and its memory stays constant.

1.7 Recursion with a memory

The loop is fast, but the recursive version matches the definition more closely. You can keep the recursion and remove the repeated work by saving each answer the first time you compute it. Saving answers this way is called memoization, and the table of saved answers is a cache.

Listing 1.6 Fibonacci with a cache. src/bin/cs_fib.rs, lines 26 to 41

/// Linear time, linear space: recursion plus a cache of subproblem answers.
fn memoized(n: u64) -> u64 {
    fn go(n: u64, cache: &mut [u64]) -> u64 {
        if n < 2 {
            return n;
        }
        let index = n as usize;
        if cache[index] == 0 {
            cache[index] = go(n - 1, cache) + go(n - 2, cache);
        }
        cache[index]
    }

    let mut cache = vec![0u64; n as usize + 1];
    go(n, &mut cache)
}

This listing uses three pieces of syntax you may not have used before:

• A function inside a function. go is declared inside memoized. Only memoized can call it. It is an ordinary function; it does not see memoized’s variables.
• vec![0u64; n as usize + 1]. This creates a Vec of n + 1 zeros. n as usize converts the u64 to usize, the type Rust uses for lengths and indexes.
• &mut [u64]. This is a mutable slice: a borrowed view of the vector’s elements that allows writing. go receives the cache this way, so every call shares one table instead of copying it.

go checks the base case first. Then it looks in the cache. A zero means “not computed yet”. In that case it computes the value with two recursive calls and stores it. Either way, it returns the saved value.

Zero can mark an empty slot here because fib(n) is never zero for n of 2 or more. Smaller values return before the cache is read. Figure 1.5 shows the cache after memoized(6).

With the cache, each value from 2 to n is computed once, so the time grows in proportion to n. The cache uses memory in proportion to n, and the recursion still uses n stack frames.

Animation 1.1 runs memoized(5) and recursive(5) side by side in time. The tree on the left gains a node per call, and the stack on the right holds only the calls that are still waiting.

1.8 Timing the three versions

To compare the versions, the program measures how long each call takes.

Listing 1.7 Timing a function and printing the result. src/bin/cs_fib.rs, lines 43 to 51

fn timed(label: &str, n: u64, operation: impl Fn(u64) -> u64) {
    let start = Instant::now();
    let value = operation(n);
    report(label, n, value, start.elapsed());
}

fn report(label: &str, n: u64, value: u64, elapsed: Duration) {
    println!("  {label:<10} fib({n:>2}) = {value:<20} in {elapsed:?}");
}

timed takes a parameter operation: impl Fn(u64) -> u64. This means “any function or closure that takes a u64 and returns a u64”. So main can pass recursive, iterative, or memoized by name.

Instant::now() reads a clock that only moves forward. start.elapsed() returns the time since then as a Duration.

report uses format specifiers inside the braces. {label:<10} pads the label to 10 characters, aligned left. {n:>2} right-aligns n in 2 characters. {elapsed:?} prints the Duration with its debug format, which chooses a unit such as µs or ms.

1.9 The complete Fibonacci program

Here is the whole program, including main. main times each version, then checks that all three agree.

Listing 1.8 The complete program. src/bin/cs_fib.rs

//! Three ways to compute Fibonacci: naive recursion, iteration, and memoization.
//! The first shows why exponential blowup happens; the other two fix it.
//!
//! Run with: cargo run --bin cs_fib

use std::time::{Duration, Instant};

/// Exponential: fib(n) recomputes fib(n - 1) and fib(n - 2) from scratch.
fn recursive(n: u64) -> u64 {
    if n < 2 {
        n
    } else {
        recursive(n - 1) + recursive(n - 2)
    }
}

/// Linear time, constant space.
fn iterative(n: u64) -> u64 {
    let (mut previous, mut current) = (0u64, 1u64);
    for _ in 0..n {
        (previous, current) = (current, previous + current);
    }
    previous
}

/// Linear time, linear space: recursion plus a cache of subproblem answers.
fn memoized(n: u64) -> u64 {
    fn go(n: u64, cache: &mut [u64]) -> u64 {
        if n < 2 {
            return n;
        }
        let index = n as usize;
        if cache[index] == 0 {
            cache[index] = go(n - 1, cache) + go(n - 2, cache);
        }
        cache[index]
    }

    let mut cache = vec![0u64; n as usize + 1];
    go(n, &mut cache)
}

fn timed(label: &str, n: u64, operation: impl Fn(u64) -> u64) {
    let start = Instant::now();
    let value = operation(n);
    report(label, n, value, start.elapsed());
}

fn report(label: &str, n: u64, value: u64, elapsed: Duration) {
    println!("  {label:<10} fib({n:>2}) = {value:<20} in {elapsed:?}");
}

fn main() {
    println!("small input, all three should agree");
    timed("recursive", 20, recursive);
    timed("iterative", 20, iterative);
    timed("memoized", 20, memoized);

    println!("\nrecursive cost grows quickly");
    timed("recursive", 30, recursive);
    timed("iterative", 30, iterative);

    println!("\nlarge input: recursion alone would not finish");
    timed("iterative", 90, iterative);
    timed("memoized", 90, memoized);

    for n in 0..20 {
        assert_eq!(recursive(n), iterative(n));
        assert_eq!(memoized(n), iterative(n));
    }
    assert_eq!(iterative(30), 832_040);
    assert_eq!(iterative(90), 2_880_067_194_370_816_120);

    println!("\nall checks passed");
}

The loop near the end of main compares the three versions for every n below 20. If any pair disagrees, assert_eq! stops the program with both values. The two final assertions check known values of fib(30) and fib(90).

This output comes from a debug build, the default for cargo run:

$ cargo run --bin cs_fib
small input, all three should agree
  recursive  fib(20) = 6765                 in 90.908µs
  iterative  fib(20) = 6765                 in 567ns
  memoized   fib(20) = 6765                 in 10.826µs

recursive cost grows quickly
  recursive  fib(30) = 832040               in 11.124774ms
  iterative  fib(30) = 832040               in 542ns

large input: recursion alone would not finish
  iterative  fib(90) = 2880067194370816120  in 937ns
  memoized   fib(90) = 2880067194370816120  in 5.749µs

all checks passed

Compare the two recursive timings. Going from n = 20 to n = 30, the time grows about 120 times. That matches the growth rate from section 1.5.1: 1.618 multiplied by itself 10 times is about 123. At that rate, recursive(90) would run for over a thousand years, so main does not call it.

The memoized version is slower than the loop, although both grow in proportion to n. It allocates a Vec and makes function calls, and the loop does neither.

Chapter 2 moves from computation to the operating system. You will read and write files, walk directories, and parse command-line arguments, and meet Result and ?, which every later chapter uses.

Exercises

1. Add a counter to recursive that records how many calls it makes. Print the count for n from 1 to 25, and check that each count is close to 1.6 times the previous one.
2. Rewrite memoized so the cache holds Option<u64> instead of using 0 as “empty”. Explain why the 0 marker is safe for Fibonacci but would not be safe for a function that can return 0.
3. Change iterative to return Option<u64> and use checked_add, so that iterative(94) returns None instead of overflowing.
4. Run cargo run --release --bin cs_fib and compare the timings with the debug build above.

Files, paths, and the command line

In chapter 1 your programs only computed values. In this chapter they talk to the operating system. They read and write files, look inside directories, and read the arguments you type after a program’s name.

Every one of these operations can fail. A file may not exist, or you may not have permission to read it. Rust reports such failures through a type called Result, so this chapter starts there. After that come paths, reading, writing, and directories. The chapter ends with two complete tools. One reads a file a page at a time. The other turns command-line arguments into typed options.

A few terms:

• The kernel is the core of the operating system. It controls the disk, memory, and devices.
• A system call is a request from a program to the kernel, such as “open this file” or “read 100 bytes”.
• A file descriptor is a small number the kernel gives your program for each open file. Later system calls use it to name that file.

2.1 What happens when you read a file

Your program cannot read the disk directly. It asks the kernel with system calls, and the kernel does the work. Figure 2.1 shows the steps for reading a small file.

The steps are:

1. open asks the kernel to open the file. The kernel checks permissions and returns a file descriptor.
2. read asks for bytes from that descriptor. The kernel copies them into a buffer in your program.
3. close tells the kernel you are done, so it can release the descriptor.

Rust’s standard library makes these calls for you. Each call can fail, and the library reports that with Result.

2.2 Result and the ? operator

Result is an enum with two variants:

enum Result<T, E> {
    Ok(T),    // the operation succeeded and produced a T
    Err(E),   // the operation failed with an error of type E
}

For file operations, the error type is std::io::Error, and io::Result<T> is a shorter name for Result<T, io::Error>. So fs::read_to_string(path) returns io::Result<String>: either the file’s text, or the reason it could not be read.

You can handle a Result with match. That gets long when a function makes several calls, each of which can fail. The ? operator shortens it. Put ? after an expression of type Result, and it does one of two things (figure 2.2):

• If the value is Ok(x), the expression evaluates to x and the function continues.
• If the value is Err(e), the function returns Err(e) immediately.

Because ? returns from the function, the function must return a Result too. That is why the programs in this chapter declare fn main() -> io::Result<()>. If main returns an Err, Rust prints the error and the program exits with status 1.

2.3 Paths

A path names a file or directory, such as /tmp/data.txt. Rust has two path types. &Path is a borrowed view of a path, and PathBuf is an owned path that can grow. They relate the same way &str relates to String (figure 2.3).

Listing 2.1 Building paths and taking them apart. src/bin/path_buff.rs

use std::path::{Path, PathBuf};

fn main() {
    let dir = Path::new("/tmp");
    let file = dir.join("data.txt");

    let mut buf = PathBuf::from(dir);
    buf.push("nested");
    buf.push("file.txt");

    println!("file: {}", file.display());
    println!("buf:  {}", buf.display());
    println!("parent: {:?}", buf.parent());
    println!("file_name: {:?}", buf.file_name());
    println!("ext: {:?}", buf.extension());
}

Path::new("/tmp") wraps a string as a path without copying it. dir.join("data.txt") builds a new PathBuf. PathBuf::from(dir) copies the path into an owned buffer, and each push adds one component.

$ cargo run --bin path_buff
file: /tmp/data.txt
buf:  /tmp/nested/file.txt
parent: Some("/tmp/nested")
file_name: Some("file.txt")
ext: Some("txt")

parent, file_name, and extension return Option, because some paths lack them: / has no parent. To print a path you call display(). On Linux and macOS a path is a sequence of bytes that need not be valid UTF-8. display() replaces any invalid bytes when it prints.

2.4 Reading a file

2.4.1 The whole file at once

The simplest read loads the whole file into one String.

Listing 2.2 Write a file, then read it back. src/bin/read_write_file.rs

use std::{
    fs,
    io,
    path::{Path, PathBuf},
};

// `&Path` accepts both a `&Path` and a `&PathBuf` argument; `&PathBuf` would not.
fn read_content_of_file(path: &Path) -> io::Result<String> {
    fs::read_to_string(path)
}

fn main() -> io::Result<()> {
    fs::write("hello.txt", "Hello, Rust!\n")?;

    // `join` builds a new PathBuf and leaves `base_dir` unchanged.
    let base_dir = PathBuf::from(".");
    let joined_path = base_dir.join("hello.txt");

    // `push` mutates the PathBuf in place instead of returning a new one.
    let mut mut_base_dir = PathBuf::from(".");
    mut_base_dir.push("hello.txt");

    let text = read_content_of_file(&joined_path)?;
    println!("File contents (via .join()):\n{}", text);

    let text_inplace = read_content_of_file(&mut_base_dir)?;
    println!("File contents (via .push()):\n{}", text_inplace);

    Ok(())
}

fs::write creates the file (or empties an existing one) and writes the text. fs::read_to_string opens, reads, and closes the file in one call. Both calls end with ?, so a failure in either one returns from main.

read_content_of_file takes &Path. The program calls it twice, with a path built by join and a path built by push. Both are PathBuf values that convert to &Path. The two calls print the same text.

read_to_string keeps the whole file in memory. That suits a small configuration file. For a log of several gigabytes, read one line at a time instead.

2.4.2 One line at a time

To read line by line, wrap the file in a BufReader. Figure 2.4 shows why the buffer helps.

Listing 2.3 Numbered lines through a buffered reader. src/bin/readfile_line_by_line.rs

use std::{
    fs::File,
    io::{BufRead, BufReader},
}; // BufRead brings `lines()` into scope.

fn main() -> std::io::Result<()> {
    let file = File::open("log.txt")?;
    let reader = BufReader::new(file);

    for (i, line) in reader.lines().enumerate() {
        let line = line?;
        println!("{}: {}", i + 1, line);
    }

    Ok(())
}

BufReader::new(file) takes ownership of the file and adds an 8 KiB buffer. The lines method comes from the BufRead trait, so the program imports that trait. Without the import, the method is not visible.

lines() yields one io::Result<String> per line, with the newline removed. Reading can fail partway through the file, so each line is a Result. let line = line?; replaces the Result with the String inside it, using the shadowing you saw in section 1.2. enumerate() pairs each line with its index, starting at 0, which is why the program prints i + 1.

Animation 2.1 runs this loop on a 12-byte file of three lines, and counts the read system calls. Then it runs the same lines through a reader with no buffer.

2.4.3 Reusing one buffer, and skipping bad lines

lines() allocates a new String for every line. For a very large file, you can read every line into the same String instead.

Listing 2.4 One reused buffer, with invalid lines skipped. src/bin/read_large_file.rs

use std::{
    fs::File,
    io::{self, BufRead, BufReader},
};

fn main() -> io::Result<()> {
    let file = File::open("large.txt")?;
    let mut reader = BufReader::new(file);
    let mut line = String::new();

    while match reader.read_line(&mut line) {
        Ok(0) => false, // EOF, stop
        Ok(_) => {
            process(line.trim_end());
            line.clear();
            true // keep reading
        }
        Err(e) if e.kind() == io::ErrorKind::InvalidData => {
            eprintln!("skipping bad line: {e}");
            line.clear();
            true
        }
        Err(e) => return Err(e), // return works inside the condition
    } {}

    Ok(())
}

fn process(line: &str) {
    println!("{line}");
}

reader.read_line(&mut line) appends the next line, including its newline, to line. It returns the number of bytes read. The loop is written in an unusual way: while match ... { ... } {}. The whole match is the loop’s condition, and the loop’s body, {}, is empty. Each arm of the match evaluates to true to continue or false to stop.

Table 2.1 lists the four outcomes.

Because read_line appends, the loop must call line.clear() after each line. Otherwise the buffer would grow to hold the whole file.

The InvalidData arm can continue safely because read_line has already consumed the invalid bytes. You can check this with a file whose second line holds two bytes that are not UTF-8:

$ printf 'ok\n\xff\xfebad\nfine\n' > large.txt
$ cargo run --bin read_large_file
ok
skipping bad line: stream did not contain valid UTF-8
fine

2.5 Writing and changing files

2.5.1 Appending

fs::write replaces a file’s contents. To add lines to the end of a log instead, open the file with OpenOptions.

Listing 2.5 Appending lines to a file. src/bin/append_to_file_open_options.rs

use std::{fs::OpenOptions, io::Write};

fn main() -> std::io::Result<()> {
    let mut file = OpenOptions::new()
        .create(true) // create if missing
        .append(true) // always write at the end
        .open("log.txt")?;

    writeln!(file, "New log line")?;
    writeln!(file, "Another line")?;

    Ok(())
}

OpenOptions collects settings, and open applies them. create(true) creates the file if it is missing. append(true) asks the kernel to move to the end of the file before every write. The kernel does that move and the write as one step. So two programs appending to the same log do not overwrite each other’s lines.

writeln! works like println!, but writes to any value that implements the std::io::Write trait, such as a File. The trait must be imported, as the second use line does.

2.5.2 Copying, renaming, and deleting

The standard library has one function for each of these file operations. The program copies a file, renames the copy, and deletes the original.

Listing 2.6 Copy, rename, remove. src/bin/copy_rename_delete_file.rs

use std::{fs, io};

fn main() -> io::Result<()> {
    fs::write("a.txt", "hello")?;

    fs::copy("a.txt", "b.txt")?;
    fs::rename("b.txt", "c.txt")?;
    fs::remove_file("a.txt")?;

    println!("Done");
    Ok(())
}

After the program runs, a.txt is gone and c.txt holds hello. Each call is one or two system calls.

fs::rename has a property you can build on. When both names are on the same disk, the rename is atomic. Any other program sees either the old name or the new one, never a half-renamed file. To update a file safely, write the new contents to a temporary file, then rename it over the old one. A crash in the middle leaves either the old file or the new file, never a partial one.

2.5.3 Telling one error from another

An io::Error carries a kind, an enum value such as NotFound or PermissionDenied. You can match on it to handle one failure and report the others.

Listing 2.7 Matching on the kind of an error. src/bin/file_error_handling.rs

use std::{fs, io};

fn read_file(path: &str) -> Result<String, io::Error> {
    fs::read_to_string(path)
}

fn main() {
    match read_file("missing.txt") {
        Ok(text) => println!("{}", text),
        Err(e) if e.kind() == io::ErrorKind::NotFound => {
            eprintln!("File not found");
        }
        Err(e) => eprintln!("Error: {}", e),
    }
}

The second arm has a match guard, the if after the pattern. It matches only errors whose kind is NotFound. Every other error falls through to the third arm. This main does not return a Result, so it cannot use ?; it handles every case itself. Run it where missing.txt does not exist, and it prints File not found.

2.6 Directories

A directory is a list of entries. Each entry has a name and a type: a file, a directory, or a symbolic link. A symbolic link is an entry that points to another path.

2.6.1 One level

A directory is a list of entries, each a name and a type. The program prints the entries of the current directory and marks which are directories.

Listing 2.8 Listing the current directory. src/bin/list_directory.rs

use std::{fs, io};

fn main() -> io::Result<()> {
    for entry in fs::read_dir(".")? {
        let entry = entry?;
        let path = entry.path();

        if path.is_dir() {
            println!("[DIR]  {}", path.display());
        } else {
            println!("[FILE] {}", path.display());
        }
    }
    Ok(())
}

fs::read_dir(".") returns an iterator over the entries of the current directory. Each item is a Result, because reading an entry can fail. path.is_dir() asks the kernel for the entry’s details. If the entry is a symbolic link, is_dir follows it and reports on the target.

2.6.2 Every level

To visit subdirectories, the function calls itself on each directory it finds, the recursion you met in section 1.5.

Listing 2.9 Walking a directory tree. src/bin/recusrive_directory_walk.rs

use std::{fs, io, path::Path};

fn walk(dir: &Path) -> io::Result<()> {
    for entry in fs::read_dir(dir)? {
        let entry = entry?;
        let path = entry.path();
        let file_type = entry.file_type()?;

        if file_type.is_dir() {
            println!("[DIR]  {}", path.display());
            walk(&path)?;
        } else {
            println!("[FILE] {}", path.display());
        }
    }
    Ok(())
}

fn main() -> io::Result<()> {
    walk(Path::new("."))?;
    Ok(())
}

walk uses entry.file_type() instead of path.is_dir(). The difference is how each treats symbolic links. file_type() does not follow them, so a link to a directory is reported as a link, and walk does not descend into it. That keeps the walk from looping forever through a link that points back to one of its own parent directories. On Linux, file_type() is usually also faster, because the kernel returns the type together with the name.

The recursion goes one level deeper per directory level. Real directory trees are shallow, so the stack is not a concern here.

2.7 Project: reading a large file one page at a time

Suppose a service stores millions of job records, one per line, in a file. A client asks for them a page at a time. With each page, the service returns a cursor, a value the client sends back to get the next page.

If the cursor is the byte position where the next page starts, the service needs no memory of past requests. Any copy of the service can read the next page from the cursor alone.

2.7.1 The page type

A page is the lines it holds, plus the cursor where the next page starts. The cursor is a byte offset into the file.

Listing 2.10 The Page type (lines 1 to 9). src/bin/file_pagination.rs

use std::{
    fs::File,
    io::{self, BufRead, BufReader, Seek, SeekFrom},
};

struct Page {
    jobs: Vec<String>,
    next_cursor: Option<u64>, // Byte offset where the next page starts
}

A Page holds the lines and an Option<u64> for the next cursor. None means there are no more pages.

2.7.2 Counting bytes to find the next cursor

The next cursor is the byte where this page ends. There is a trap in finding it. You might ask the file for its current position after reading three lines. That answer is wrong, because the BufReader read 8 KiB ahead on its first read, as figure 2.4 showed. The file’s position is past the buffered data, not after the third line (figure 2.5).

So read_page counts the bytes itself:

Listing 2.11 read_page (lines 11 to 38).

fn read_page(path: &str, cursor: u64, page_size: usize) -> io::Result<Page> {
    let mut file = File::open(path)?;
    file.seek(SeekFrom::Start(cursor))?;
    let mut reader = BufReader::new(file);

    // Optimization which preserves as large as the max mage size
    let mut jobs: Vec<String> = Vec::with_capacity(page_size);
    let mut offset = cursor;
    let mut line = String::new();

    while jobs.len() < page_size {
        // Clear the previously read line
        line.clear();

        match reader.read_line(&mut line)? {
            0 => break,
            bytes_read => {
                offset += bytes_read as u64;
                jobs.push(line.trim_end().to_string());
            }
        }
    }

    let at_end = reader.fill_buf()?.is_empty();
    let next_cursor = if at_end { None } else { Some(offset) };

    Ok(Page { jobs, next_cursor })
}

read_page opens the file and calls seek(SeekFrom::Start(cursor)), which moves the file’s read position to byte cursor. Then it wraps the file in a BufReader. Vec::with_capacity(page_size) reserves room for a full page, so pushing lines does not reallocate.

offset starts at cursor. Each read_line returns how many bytes it consumed, newline included, and offset grows by that amount. line.trim_end() removes the newline (and any trailing spaces) before the line is stored, but the count still includes them, so offset stays exact.

The last page needs care. If the file ends exactly after this page’s last line, the page should report no next cursor. reader.fill_buf() returns the bytes waiting in the buffer, reading more if the buffer is empty, without consuming them. If it returns nothing, the file has ended, and the cursor is None.

2.7.3 The complete program

main acts as a client. It asks for pages of three lines until the cursor is None.

Listing 2.12 The complete program. src/bin/file_pagination.rs

use std::{
    fs::File,
    io::{self, BufRead, BufReader, Seek, SeekFrom},
};

struct Page {
    jobs: Vec<String>,
    next_cursor: Option<u64>, // Byte offset where the next page starts
}

fn read_page(path: &str, cursor: u64, page_size: usize) -> io::Result<Page> {
    let mut file = File::open(path)?;
    file.seek(SeekFrom::Start(cursor))?;
    let mut reader = BufReader::new(file);

    // Optimization which preserves as large as the max mage size
    let mut jobs: Vec<String> = Vec::with_capacity(page_size);
    let mut offset = cursor;
    let mut line = String::new();

    while jobs.len() < page_size {
        // Clear the previously read line
        line.clear();

        match reader.read_line(&mut line)? {
            0 => break,
            bytes_read => {
                offset += bytes_read as u64;
                jobs.push(line.trim_end().to_string());
            }
        }
    }

    let at_end = reader.fill_buf()?.is_empty();
    let next_cursor = if at_end { None } else { Some(offset) };

    Ok(Page { jobs, next_cursor })
}

fn main() -> io::Result<()> {
    let mut cursor = 0;

    loop {
        let page = read_page("src/bin/large_file.txt", cursor, 3)?;

        println!("--- page ---");
        for job in &page.jobs {
            println!("{job}");
        }

        match page.next_cursor {
            Some(next) => cursor = next,
            None => break,
        }
    }

    Ok(())
}

The input file has thirteen lines, so the program prints four full pages and one page of one line:

$ cargo run --bin file_pagination
--- page ---
First Line
Second Line
Thrid Line
--- page ---
4
5
6
--- page ---
7
8
9
--- page ---
10
11
12
--- page ---
13

2.8 Project: command-line arguments

When you run command_line_args --name ada --count 2 --verbose, the operating system passes the program a list of strings (figure 2.6). The first string is the program’s own path. The rest are the arguments, in the order you typed them.

This program turns that list into a struct of typed options, or an error message.

2.8.1 The options and their defaults

The program’s settings live in one struct, with a default value for each setting the user does not give.

Listing 2.13 The options (lines 1 to 17). src/bin/command_line_args.rs

use std::{env::args, process::ExitCode};

/// The options this program understands.
#[derive(Debug, PartialEq)]
struct Options {
    name: String,
    count: u32,
    verbose: bool,
}

impl Default for Options {
    fn default() -> Self {
        Self {
            name: String::from("world"),
            count: 1,
            verbose: false,
        }
    }
}

Options has one field per option. The Default trait gives the values used when an option is not given. #[derive(Debug, PartialEq)] lets the tests print and compare Options values.

2.8.2 Parsing

Parsing walks the arguments one at a time and fills in the options. An unknown argument is an error. So is a flag with no value after it, and a count that is not a number.

Listing 2.14 parse (lines 21 to 47).

/// Turn the arguments after the program name into `Options`.
fn parse(arguments: impl IntoIterator<Item = String>) -> Result<Options, String> {
    let mut options = Options::default();
    let mut arguments = arguments.into_iter();

    while let Some(argument) = arguments.next() {
        match argument.as_str() {
            "--name" => {
                options.name = arguments
                    .next()
                    .ok_or("--name needs a value")?;
            }
            "--count" => {
                let value = arguments
                    .next()
                    .ok_or("--count needs a value")?;
                options.count = value
                    .parse()
                    .map_err(|_| format!("--count needs a number, got {value:?}"))?;
            }
            "--verbose" => options.verbose = true,
            other => return Err(format!("unknown argument {other:?}")),
        }
    }

    Ok(options)
}

parse takes impl IntoIterator<Item = String>, which means “anything that can produce Strings one at a time”. The program passes the real arguments. The tests pass short lists written in the test code.

The loop is while let Some(argument) = arguments.next(). It calls next() itself, rather than using for, because --name must take the next string from the same iterator as its value. A for loop holds the iterator for the whole loop, so the body could not call next() on it.

arguments.next().ok_or("--name needs a value")? does two steps. ok_or turns None into an Err with the message. Then ? returns that error from parse. The --count arm adds a third step. parse() converts the text to a number, and map_err replaces a parse error with a message that includes the text.

An argument the program does not know is an error, so a misspelled option is reported instead of ignored.

2.8.3 The exit code

main ties the pieces together: it parses the arguments, runs, and tells the shell whether it succeeded.

Listing 2.15 main (lines 49 to 68).

fn main() -> ExitCode {
    let options = match parse(args().skip(1)) {
        Ok(options) => options,
        Err(message) => {
            eprintln!("error: {message}");
            eprintln!("usage: command_line_args [--name NAME] [--count N] [--verbose]");
            return ExitCode::FAILURE;
        }
    };

    for index in 0..options.count {
        if options.verbose {
            println!("[{index}] hello, {}", options.name);
        } else {
            println!("hello, {}", options.name);
        }
    }

    ExitCode::SUCCESS
}

A program’s exit code is a number it returns to whoever started it. Zero means success. main returns ExitCode, so it can report failure after printing its own message. args().skip(1) drops the program’s path. On an error, main prints the message and a usage line to standard error with eprintln!, then returns ExitCode::FAILURE, which is 1.

2.8.4 The complete program

Listing 2.16 The complete program, with its tests. src/bin/command_line_args.rs

use std::{env::args, process::ExitCode};

/// The options this program understands.
#[derive(Debug, PartialEq)]
struct Options {
    name: String,
    count: u32,
    verbose: bool,
}

impl Default for Options {
    fn default() -> Self {
        Self {
            name: String::from("world"),
            count: 1,
            verbose: false,
        }
    }
}

/// Turn the arguments after the program name into `Options`.
fn parse(arguments: impl IntoIterator<Item = String>) -> Result<Options, String> {
    let mut options = Options::default();
    let mut arguments = arguments.into_iter();

    while let Some(argument) = arguments.next() {
        match argument.as_str() {
            "--name" => {
                options.name = arguments
                    .next()
                    .ok_or("--name needs a value")?;
            }
            "--count" => {
                let value = arguments
                    .next()
                    .ok_or("--count needs a value")?;
                options.count = value
                    .parse()
                    .map_err(|_| format!("--count needs a number, got {value:?}"))?;
            }
            "--verbose" => options.verbose = true,
            other => return Err(format!("unknown argument {other:?}")),
        }
    }

    Ok(options)
}

fn main() -> ExitCode {
    let options = match parse(args().skip(1)) {
        Ok(options) => options,
        Err(message) => {
            eprintln!("error: {message}");
            eprintln!("usage: command_line_args [--name NAME] [--count N] [--verbose]");
            return ExitCode::FAILURE;
        }
    };

    for index in 0..options.count {
        if options.verbose {
            println!("[{index}] hello, {}", options.name);
        } else {
            println!("hello, {}", options.name);
        }
    }

    ExitCode::SUCCESS
}

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

    fn parse_args(arguments: &[&str]) -> Result<Options, String> {
        parse(
            arguments
                .iter()
                .map(|value| value.to_string()),
        )
    }

    #[test]
    fn defaults_apply_when_there_are_no_arguments() {
        assert_eq!(parse_args(&[]).unwrap(), Options::default());
    }

    #[test]
    fn a_value_option_consumes_the_next_argument() {
        let options = parse_args(&["--name", "ada", "--count", "3"]).unwrap();
        assert_eq!(options.name, "ada");
        assert_eq!(options.count, 3);
    }

    #[test]
    fn verbose_is_a_flag() {
        assert!(
            parse_args(&["--verbose"])
                .unwrap()
                .verbose
        );
        assert!(!parse_args(&[]).unwrap().verbose);
    }

    #[test]
    fn a_value_option_without_a_value_is_an_error() {
        assert!(parse_args(&["--name"]).is_err());
        assert!(parse_args(&["--count"]).is_err());
    }

    #[test]
    fn a_non_numeric_count_is_an_error() {
        assert!(parse_args(&["--count", "many"]).is_err());
    }

    #[test]
    fn an_unknown_argument_is_an_error() {
        assert!(parse_args(&["--colour", "red"]).is_err());
        assert!(parse_args(&["extra"]).is_err());
    }
}

The helper parse_args in the test module converts a list of &str into Strings, so each test states its input in one line. The tests cover the defaults, each option, a missing value, a bad number, and an unknown argument.

$ cargo run --bin command_line_args -- --name ada --count 2 --verbose
[0] hello, ada
[1] hello, ada
$ cargo run --bin command_line_args -- --count many
error: --count needs a number, got "many"
usage: command_line_args [--name NAME] [--count N] [--verbose]
$ echo $?
1

The -- after cargo run --bin command_line_args tells Cargo that the rest of the line belongs to your program, not to Cargo.

Chapter 3 begins Part 2. It works with Rust’s main collections, Vec, String, and HashMap, on a series of problems about arrays and text.

Exercises

1. Rewrite walk without recursion. Keep a Vec<PathBuf> of directories still to visit, and count the files and total bytes for each file extension.
2. Write atomic_write(path, bytes). Write to a temporary file in the same directory, call sync_all() on it, and rename it over the target.
3. Add a version number to the pagination cursor, and return an error when the file changed between pages.
4. Let the argument parser accept --name=ada as well as --name ada.

Vectors, strings, and hash maps

This chapter begins Part 2. Part 2 is about data structures and the algorithms that use them. In this chapter you work with the three collections you will use most in Rust: Vec, String, and HashMap.

Before any problem, I spend a few sections on groundwork. First, a way to compare two solutions by how much work they do. Then a look at how each collection stores its data. With that in place, each problem in the rest of the chapter is short, and you can see why each solution is fast.

The problems are grouped by technique, not by topic. A technique is a pattern you can reuse. Two examples are “keep a stack of things not yet matched” and “move two indexes toward each other”. Table 3.1 lists them.

3.1 Counting the work an algorithm does

Two programs can give the same answer and take very different amounts of time. You saw this in chapter 1: the recursive Fibonacci took milliseconds where the loop took nanoseconds. To choose between solutions, you need a way to describe how their running time grows as the input grows.

The usual way is to count the basic steps a program takes for an input of size n. Here n is the length of the array or string. A basic step is something that takes a fixed amount of time, such as comparing two numbers or reading one element.

Consider three ways to answer questions about an array of n numbers:

• Reading the first element takes one step, whatever n is.
• Adding up all the elements takes n steps, one per element.
• Comparing every element with every other element takes about n × n steps.

Big-O notation is a short way to write how the count grows. You keep only the part that grows fastest and drop constant factors. So the three examples above are written O(1), O(n), and O(n²). You read O(n) as “order n”: the time grows in proportion to n.

Table 3.2 shows how different these are once n is large.

A modern processor does roughly a billion simple steps per second. At a million elements, an O(n) solution finishes in about a millisecond. An O(n²) solution takes about a quarter of an hour.

The same notation describes memory. A solution that uses O(n) extra memory stores something for each input element. A solution that uses O(1) extra memory uses a fixed amount, however large the input.

3.2 How a Vec stores its elements

A Vec<T> is a growable array. Its elements sit next to each other in one block of heap memory. The Vec value itself is small. It holds three numbers. The first is a pointer to the block. The second is the number of elements in use, its length. The third is how many elements the block has room for, its capacity. Figure 3.1 shows a vector of four i32 values with room for six.

Because the elements are next to each other, reading v[i] takes one step. The address of element i is the block’s address plus i times the size of one element. The length of the vector does not matter. So indexing a Vec is O(1).

When you push an element and the block is full, the vector needs a bigger block. Figure 3.2 shows what happens.

That copy costs O(n), but it happens rarely, because each growth doubles the capacity. Spread over all the pushes, each push costs a constant amount on average. This is called amortized O(1).

If you know how many elements you will push, Vec::with_capacity(n) allocates the whole block at once, and no copy happens at all. You will see this in several listings below.

3.3 How a String stores text

A String is a Vec<u8> with one extra rule. Its bytes must always be valid UTF-8. UTF-8 is the standard way of turning characters into bytes. An English letter takes one byte. Other characters take two, three, or four bytes. Figure 3.3 shows the four characters of "café".

This has three consequences you will meet in this chapter:

• s.len() counts bytes, not characters. "café".len() is 5.
• s.chars() walks the characters one at a time, decoding the bytes as it goes.
• You cannot index a String with s[3]. A byte index might fall in the middle of a character, as index 4 does in figure 3.3, so Rust does not allow it.

3.4 How a HashMap finds a key

A HashMap<K, V> stores pairs of a key and a value, and finds the value for a key quickly. It works in three steps (figure 3.4):

1. It runs the key through a hash function, which turns any key into a large number. The same key always gives the same number.
2. It uses some of the bits of that number to pick a bucket, one slot in an array of buckets.
3. It stores the pair in that bucket, or looks for it there.

Two keys can land in the same bucket, as 7 and 11 do in the figure. Then a lookup compares the keys in that bucket one by one. The map keeps the number of keys per bucket small by growing its bucket array as it fills. So on average, insert and get are O(1), however many keys the map holds.

Rust’s HashMap uses a hash function with a random starting value, chosen when the program starts. This stops an attacker from sending keys that all land in one bucket. It also means the order in which you iterate over a map changes from one run to the next.

Now you have the tools for the problems. Each one starts with the simplest correct idea, then shows how a collection makes it faster.

3.5 Finding two numbers that add up to a target

The problem. Given an array of numbers and a target, find two positions whose numbers add up to the target. For [2, 7, 11, 15] and target 9, the answer is positions 0 and 1, because 2 + 7 = 9.

The simple idea. Try every pair. For each position i, check every later position j. That is about n × n / 2 pairs, so O(n²).

A faster idea. Walk the array once. For each number, you know which partner it needs: target - num. If you have already seen that partner, you are done. To answer “have I seen it?” in one step, keep a HashMap from each number seen so far to its position.

Trace it on [2, 7, 11, 15] with target 9:

Listing 3.1 Two Sum with one pass and a hash map. src/problems/two_sum.rs

//! Two Sum: find the pair of indices whose values add up to a target.
//!
//! Use a `HashMap` for one pass: O(n) time, O(n) space.

use std::collections::HashMap;

pub fn two_sum(nums: &[i32], target: i32) -> Option<(usize, usize)> {
    let mut seen = HashMap::with_capacity(nums.len());
    for (idx, &num) in nums.iter().enumerate() {
        match seen.get(&(target - num)) {
            Some(&prev) => return Some((prev, idx)),
            None => {
                seen.insert(num, idx);
            }
        }
    }
    None
}

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

    #[test]
    fn finds_pair() {
        let nums = [2, 7, 11, 15];
        assert_eq!(two_sum(&nums, 9), Some((0, 1)));
    }

    #[test]
    fn returns_none_when_missing() {
        assert_eq!(two_sum(&[1, 2, 3], 100), None);
    }
}

Walk through the function:

• The parameter nums: &[i32] is a slice, a borrowed view of a sequence of i32 values. You can pass a Vec, an array, or part of either.
• HashMap::with_capacity(nums.len()) sizes the map for the worst case, so it never grows during the loop.
• nums.iter().enumerate() gives pairs of (position, reference to number). The pattern (idx, &num) copies the number out of the reference.
• seen.get(&(target - num)) looks up the partner. get takes a reference to the key, hence the &.
• If the partner is found, the function returns both positions. Otherwise it records this number.

The lookup comes before the insert. Think of target 4 with a single 2 in the array. If the insert came first, the 2 would find itself and pair with itself.

The function returns Option<(usize, usize)>: Some with the two positions, or None if no pair exists. It runs in O(n) time and uses O(n) extra memory for the map.

3.6 A vector used as a stack

A stack is a collection where you add and remove items at the same end, called the top. The last item you added is the first one you remove. A Vec works as a stack. push adds to the end, and pop removes the last item and returns it. last looks at the end without removing it. All three are O(1).

3.6.1 Checking brackets

The problem. A string of brackets is valid if every opening bracket is closed by the matching kind, in the right order. "{[()]}" is valid. "([)]" is not, because ] arrives while ( is still open.

The idea. Read the string from left to right. Push each opening bracket onto a stack. When a closing bracket arrives, the top of the stack must be its matching opener; pop it and continue. At the end, the stack must be empty. Figure 3.5 traces "{[()]}".

Listing 3.2 Valid Parentheses. src/problems/valid_parentheses.rs

//! Valid Parentheses: classic stack problem with idiomatic pattern matching.
//!
pub fn is_valid(s: &str) -> bool {
    use std::collections::HashMap;

    let mut stack = Vec::with_capacity(s.len());

    // Maps each closing delimiter to the opening delimiter it must match.
    let expected = HashMap::from([(')', '('), ('}', '{'), (']', '[')]);

    for ch in s.chars() {
        match ch {
            '(' | '[' | '{' => stack.push(ch),
            // Every other character, including one outside the six delimiters,
            // must close the top of the stack.
            _ => {
                if stack.pop().as_ref() != expected.get(&ch) {
                    return false;
                }
            }
        }
    }

    stack.is_empty()
}

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

    #[test]
    fn valid_cases() {
        assert!(is_valid("()"));
        assert!(is_valid("()[]{}"));
        assert!(is_valid("{[()]}"));
    }

    #[test]
    fn invalid_cases() {
        assert!(!is_valid("(]"));
        assert!(!is_valid("([)]"));
        assert!(!is_valid("("));
        assert!(!is_valid(")"));
        assert!(!is_valid("(("));
    }
}

The map expected records, for each closing bracket, the opener it needs. HashMap::from([...]) builds a map from an array of pairs.

The match has two arms. The first pushes any of the three openers. The second handles every other character and compares two Option values:

• stack.pop() removes the top and returns Some(opener), or None if the stack is empty. .as_ref() turns Option<char> into Option<&char>, so it can be compared with the next value.
• expected.get(&ch) returns Some(&opener) for a closing bracket.

If they differ, the string is invalid. An empty stack gives None, which differs from Some, so an extra closer is caught. After the loop, stack.is_empty() catches openers that were never closed.

The tests list valid and invalid examples, including "([)]", a lone ")", and "((".

3.6.2 A stack that knows its minimum

The problem. Build a stack that supports push, pop, top, and get_min, the smallest value currently in it, all in O(1).

The idea. Scanning the stack for the minimum takes O(n). Instead, keep a second stack beside the first. Each time you push a value, also push the minimum so far. Then the minimum of the whole stack is always on top of the second stack. When you pop, pop both.

Trace pushes of -2, 0, and -3:

Listing 3.3 Min Stack with a parallel stack of minimums. src/problems/min_stack.rs

//! Min Stack: O(1) push, pop, top, and get_min.
//!
//! We keep a parallel `mins` stack. Each push stores the current minimum at that
//! point in history, so pop is symmetric.

#[derive(Debug, Default)]
pub struct MinStack {
    values: Vec<i32>,
    mins: Vec<i32>,
}

impl MinStack {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn push(&mut self, val: i32) {
        match self.mins.last() {
            Some(&min) if min <= val => self.mins.push(min),
            _ => self.mins.push(val),
        }
        self.values.push(val);
    }

    pub fn pop(&mut self) -> Option<i32> {
        self.mins.pop();
        self.values.pop()
    }

    pub fn top(&self) -> Option<i32> {
        self.values.last().copied()
    }

    pub fn get_min(&self) -> Option<i32> {
        self.mins.last().copied()
    }
}

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

    #[test]
    fn stack_tracks_minimum() {
        let mut stack = MinStack::new();
        stack.push(-2);
        stack.push(0);
        stack.push(-3);
        assert_eq!(stack.get_min(), Some(-3));
        assert_eq!(stack.pop(), Some(-3));
        assert_eq!(stack.top(), Some(0));
        assert_eq!(stack.get_min(), Some(-2));
    }

    #[test]
    fn handles_duplicates() {
        let mut stack = MinStack::new();
        stack.push(1);
        stack.push(1);
        stack.pop();
        assert_eq!(stack.get_min(), Some(1));
    }
}

#[derive(Default)] gives MinStack a default() function that creates two empty vectors, and new calls it.

In push, self.mins.last() returns the current minimum, if any. The arm Some(&min) if min <= val has a guard, the if after the pattern. It pushes the old minimum again when the new value is not smaller. The _ arm covers both an empty stack and a new smaller value, and pushes val.

The guard uses <=, not <. When you push a value equal to the current minimum, the minimum is recorded again. So popping one copy leaves the other, and the minimum stays correct. The test handles_duplicates checks this case.

top and get_min use .copied() to turn Option<&i32> into Option<i32>, so the caller gets a plain number.

3.7 Two indexes moving toward each other

Some problems need you to look at both ends of an array at once. Keep one index at the start and one at the end, and move them toward each other. Each step moves at least one index, so the whole walk is O(n).

3.7.1 Reversing a string in place

The idea. Swap the first and last bytes, then the second and second-to-last, and stop when the indexes meet (figure 3.6).

There is a complication. As section 3.3 explained, a String must stay valid UTF-8, and swapping the bytes of a two-byte character would break it. So Rust does not let you change a String’s bytes directly in safe code. String::as_mut_vec gives you the bytes, but it is marked unsafe. unsafe marks code where the compiler cannot check a rule, so the programmer must. Here the rule is “the bytes are valid UTF-8 when you are done”.

Listing 3.4 The reversing function (lines 1 to 14). src/bin/reverse_string.rs

fn reverse_str(s: &mut String) {
    // SAFETY: s._as_mut_vec() is unsafe because it exposes the inner mutability to it's character buffer, and we must ensure
    // to leave valid UTF-8. We enforce ASCII only characters.
    assert!(s.is_ascii());
    let bytes = unsafe { s.as_mut_vec() };

    let (mut start, mut end) = (0, bytes.len() - 1);

    while start < end {
        bytes.swap(start, end);
        start += 1;
        end -= 1;
    }
}

The function keeps the rule by checking first: assert!(s.is_ascii()) stops the program unless every byte is a plain ASCII character. Reversing ASCII bytes gives ASCII, which is valid UTF-8. The unsafe block is then as small as possible, one call.

bytes.swap(start, end) exchanges two elements of the vector. The loop runs while start < end, so the middle element of an odd-length string stays where it is.

Listing 3.5 The complete program, with its tests. src/bin/reverse_string.rs

fn reverse_str(s: &mut String) {
    // SAFETY: s._as_mut_vec() is unsafe because it exposes the inner mutability to it's character buffer, and we must ensure
    // to leave valid UTF-8. We enforce ASCII only characters.
    assert!(s.is_ascii());
    let bytes = unsafe { s.as_mut_vec() };

    let (mut start, mut end) = (0, bytes.len() - 1);

    while start < end {
        bytes.swap(start, end);
        start += 1;
        end -= 1;
    }
}

fn main() {
    for value in ["abcd", "abc", "a", "rust"] {
        let mut s = String::from(value);
        reverse_str(&mut s);
        println!("{value:>6} -> {s}");
    }
}

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

    #[test]
    fn an_even_length_string_is_reversed() {
        let mut s = String::from("abcd");
        reverse_str(&mut s);
        assert_eq!(s, "dcba");
    }

    #[test]
    fn an_odd_length_string_keeps_its_middle_byte() {
        let mut s = String::from("abc");
        reverse_str(&mut s);
        assert_eq!(s, "cba");
    }

    #[test]
    fn a_single_byte_is_unchanged() {
        let mut s = String::from("a");
        reverse_str(&mut s);
        assert_eq!(s, "a");
    }

    #[test]
    fn the_buffer_is_reused() {
        let mut s = String::from("abcd");
        let capacity = s.capacity();
        let address = s.as_ptr();
        reverse_str(&mut s);
        assert_eq!(s.capacity(), capacity);
        assert_eq!(s.as_ptr(), address);
    }

    #[test]
    fn reversing_twice_restores_the_string() {
        let mut s = String::from("interview");
        reverse_str(&mut s);
        reverse_str(&mut s);
        assert_eq!(s, "interview");
    }

    #[test]
    #[should_panic]
    fn non_ascii_input_panics() {
        let mut s = String::from("café");
        reverse_str(&mut s);
    }
}

The test the_buffer_is_reused records the string’s capacity and the address of its bytes before the call, then checks both afterward. They are unchanged, so the reversal used no new memory. non_ascii_input_panics is marked #[should_panic]: it passes only if the call panics, which the assert! does for "café".

$ cargo run --bin reverse_string
  abcd -> dcba
   abc -> cba
     a -> a
  rust -> tsur

3.7.2 Three numbers that add up to a target

The problem. Find every set of three numbers in an array that adds up to a target, without listing the same set twice.

The idea. Sort the array first. Then fix the first number, and look for the other two in the rest of the array. Use two indexes: left starts right after the fixed number, and right starts at the end. Because the array is sorted, you know which index to move:

• If the sum is too small, move left right. That can only increase the sum.
• If the sum is too large, move right left. That can only decrease it.
• If the sum is right, record the three numbers, then move both.

Each fixed number costs one O(n) walk, and there are n fixed numbers, so the whole search is O(n²). Sorting costs O(n log n), which is smaller.

The function first sorts, then fixes each number in turn:

// Import the variants directly into scope
use std::cmp::Ordering::{Equal, Greater, Less};

pub fn three_sum(numbers: &mut [i32], target: i32) -> Vec<(i32, i32, i32)> {
    numbers.sort_unstable();

    let mut results = Vec::new();
    let target = i64::from(target);

    for i in 0..numbers.len() {
        // Skip a first value that was already used, so triplets stay unique.
        if i > 0 && numbers[i] == numbers[i - 1] {
            continue;
        }

        let (mut left, mut right) = (i + 1, numbers.len().saturating_sub(1));
        // ...
    }
}

• use std::cmp::Ordering::{Equal, Greater, Less}; lets the code write Less instead of Ordering::Less. The next excerpt matches on these three.
• The continue skips a fixed value equal to the previous one, so the same set is not found twice.
• numbers.len().saturating_sub(1) gives 0 instead of underflowing when the slice is empty.

For each fixed number, left and right close in from the two ends of the rest:

pub fn three_sum(numbers: &mut [i32], target: i32) -> Vec<(i32, i32, i32)> {
    // ...
    for i in 0..numbers.len() {
        // ...
        while left < right {
            // Widen to i64 so the sum of three i32 values cannot overflow.
            let current_sum = numbers[i] as i64 + numbers[left] as i64 + numbers[right] as i64;

            match current_sum.cmp(&target) {
                Less => left += 1,
                Greater => right -= 1,
                Equal => {
                    results.push((numbers[i], numbers[left], numbers[right]));

                    while left < right && numbers[left] == numbers[left + 1] {
                        left += 1;
                    }
                    while left < right && numbers[right] == numbers[right - 1] {
                        right -= 1;
                    }

                    left += 1;
                    right -= 1;
                }
            }
        }
    }
    // ...
}

• The sum is computed in i64. Three i32 values can add up to more than i32 can hold. The test does_not_overflow_on_extreme_values uses i32::MAX twice to check this.
• current_sum.cmp(&target) returns Less, Greater, or Equal, and the match turns each into the move from the list above.
• After a match, the two inner while loops step left and right past values equal to the ones in the match.

Listing 3.6 Three Sum, with its tests. src/problems/three_sum.rs

//! Three Sum: every unique triplet of values that adds up to a target.
//!
//! Sort, fix the first value, then close in on the other two with two pointers.
//! Sorts the caller's slice in place: O(n^2) time, no extra space beyond the result.

// Import the variants directly into scope
use std::cmp::Ordering::{Equal, Greater, Less};

pub fn three_sum(numbers: &mut [i32], target: i32) -> Vec<(i32, i32, i32)> {
    numbers.sort_unstable();

    let mut results = Vec::new();
    let target = i64::from(target);

    for i in 0..numbers.len() {
        // Skip a first value that was already used, so triplets stay unique.
        if i > 0 && numbers[i] == numbers[i - 1] {
            continue;
        }

        let (mut left, mut right) = (i + 1, numbers.len().saturating_sub(1));
        while left < right {
            // Widen to i64 so the sum of three i32 values cannot overflow.
            let current_sum = numbers[i] as i64 + numbers[left] as i64 + numbers[right] as i64;

            match current_sum.cmp(&target) {
                Less => left += 1,
                Greater => right -= 1,
                Equal => {
                    results.push((numbers[i], numbers[left], numbers[right]));

                    while left < right && numbers[left] == numbers[left + 1] {
                        left += 1;
                    }
                    while left < right && numbers[right] == numbers[right - 1] {
                        right -= 1;
                    }

                    left += 1;
                    right -= 1;
                }
            }
        }
    }

    results
}

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

    #[test]
    fn finds_all_unique_triplets() {
        let result = three_sum(&mut [-1, 0, 1, 2, -1, -4], 0);
        assert_eq!(result, vec![(-1, -1, 2), (-1, 0, 1)]);
    }

    #[test]
    fn skips_duplicates_on_every_position() {
        assert_eq!(three_sum(&mut [0, 0, 0, 0], 0), vec![(0, 0, 0)]);
        assert_eq!(three_sum(&mut [-2, 0, 0, 2, 2], 0), vec![(-2, 0, 2)]);
    }

    #[test]
    fn supports_a_non_zero_target() {
        assert_eq!(
            three_sum(&mut [1, 2, 3, 4, 5], 9),
            vec![(1, 3, 5), (2, 3, 4)]
        );
    }

    #[test]
    fn returns_nothing_when_no_triplet_exists() {
        assert!(three_sum(&mut [1, 2, 3], 100).is_empty());
        assert!(three_sum(&mut [1, 2], 3).is_empty());
        assert!(three_sum(&mut [], 0).is_empty());
    }

    #[test]
    fn does_not_overflow_on_extreme_values() {
        assert_eq!(
            three_sum(&mut [i32::MAX, i32::MAX, i32::MIN], i32::MAX - 1),
            vec![(i32::MIN, i32::MAX, i32::MAX)]
        );
    }
}

3.8 A window that slides along a string

The problem. Find the length of the longest piece of a string in which no character repeats. In "pwwkew", the answer is 3, for "wke" or "kew".

The idea. Keep a window, a range start..=end of the string with no repeated character. Move end forward one character at a time. When the new character already appears inside the window, move start to the position right after its earlier one. The window never contains a repeat, and the answer is the largest window seen.

To know where a character last appeared, keep a HashMap from each character to its last position. Figure 3.7 shows the moment in "pwwkew" when the second w arrives.

Listing 3.7 Longest substring without a repeated character. src/problems/sliding_window.rs

//! Longest substring without repeating characters.
//!
//! Sliding window with `HashMap<char, usize>`; the window start is monotonic.

use std::collections::HashMap;

pub fn length_of_longest_substring(s: &str) -> usize {
    let mut last_seen = HashMap::with_capacity(s.len());

    let (mut start, mut longest) = (0, 0);

    for (end, ch) in s.chars().enumerate() {
        if let Some(&previous) = last_seen.get(&ch) {
            start = start.max(previous + 1);
        }
        longest = longest.max(end - start + 1);
        last_seen.insert(ch, end);
    }

    longest
}

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

    #[test]
    fn examples() {
        assert_eq!(length_of_longest_substring("abcabcbb"), 3);
        assert_eq!(length_of_longest_substring("bbbbb"), 1);
        assert_eq!(length_of_longest_substring("pwwkew"), 3);
        assert_eq!(length_of_longest_substring(""), 0);
    }
}

if let Some(&previous) = last_seen.get(&ch) runs its block only when the character has been seen before. Then start = start.max(previous + 1) moves start past the earlier position. The max stops start from moving backward when the earlier position is already outside the window. For example, in "abba", the last a was seen at 0, but start is already at 2.

end - start + 1 is the current window’s length. Both start and end only move forward, so the loop does O(n) work.

The positions come from chars().enumerate(), so they count characters, not bytes. That is what the problem asks for.

3.9 Sort, then walk once: merging ranges

The problem. Given ranges such as [1,3] [2,6] [8,10] [15,18], merge every group that overlaps. The answer here is [1,6] [8,10] [15,18].

The idea. Sort the ranges by their start. Then walk them once. Each range either overlaps the last merged range, and extends it, or starts a new merged range (figure 3.8).

The file solves the problem three times: with a named struct, with plain tuples, and in place. First the struct and the first version:

Listing 3.8 Merging ranges held in a struct (lines 6 to 28). src/problems/merge_intervals.rs

#[derive(Debug, PartialEq, Clone, Copy)]
pub struct Interval {
    start: i32,
    end: i32,
}
pub fn merge_intervals(mut intervals: Vec<Interval>) -> Vec<Interval> {
    if intervals.is_empty() {
        return intervals;
    }

    intervals.sort_unstable_by_key(|interval| interval.start);

    let mut merged: Vec<Interval> = Vec::with_capacity(intervals.len());
    for Interval { start, end } in intervals {
        match merged.last_mut() {
            Some(previous) if start <= previous.end => {
                previous.end = previous.end.max(end);
            }
            _ => merged.push(Interval { start, end }),
        }
    }
    merged
}

sort_unstable_by_key(|interval| interval.start) sorts by start. “Unstable” means equal starts may change order, which does not affect the result and is slightly faster.

The loop header for Interval { start, end } in intervals takes each range apart into two variables.

merged.last_mut() returns a mutable reference to the last merged range, or None if there is none yet. The guard if start <= previous.end checks for overlap. When it holds, the code extends the range in place through the reference: previous.end = previous.end.max(end). The max handles a range that lies entirely inside the previous one. In every other case, the _ arm starts a new merged range.

The second version does the same with (i32, i32) tuples, so the end is written previous.1:

Listing 3.9 The same merge over tuples (lines 30 to 48).

pub fn merge_intervals2(mut intervals: Vec<(i32, i32)>) -> Vec<(i32, i32)> {
    if intervals.is_empty() {
        return intervals;
    }

    intervals.sort_unstable_by_key(|(start, _)| *start);

    let mut merged: Vec<(i32, i32)> = Vec::with_capacity(intervals.len());

    for &(start, end) in &intervals {
        match merged.last_mut() {
            Some(previous) if start <= previous.1 => {
                previous.1 = previous.1.max(end);
            }
            _ => merged.push((start, end)),
        }
    }
    merged
}

It works the same way. The struct version is easier to read, because previous.end says what previous.1 leaves to you to remember.

The third version needs no second vector. It writes the merged ranges into the front of the input vector:

Listing 3.10 Merging in place (lines 50 to 72).

/// In place: `last` is the last merged interval at the front of the vector.
/// O(1) extra space.
pub fn merge_intervals_in_place(intervals: &mut Vec<Interval>) {
    if intervals.is_empty() {
        return;
    }

    intervals.sort_unstable_by_key(|interval| interval.start);

    let mut last = 0;
    for i in 1..intervals.len() {
        match (intervals[last], intervals[i]) {
            (previous, current) if current.start <= previous.end => {
                intervals[last].end = previous.end.max(current.end);
            }
            (_, current) => {
                last += 1;
                intervals[last] = current;
            }
        }
    }
    intervals.truncate(last + 1);
}

last is the position of the last merged range. For each later range, the code either extends intervals[last], or moves last forward one place and copies the range there. At the end, truncate(last + 1) drops the leftovers. This version uses O(1) extra memory.

match (intervals[last], intervals[i]) copies both ranges out of the vector into a pair. That works because Interval derives Copy. Because the arms work on copies, they are free to write to intervals[last] without a borrowing conflict.

Listing 3.11 The tests (lines 74 to 106).

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

    #[test]
    fn merges_overlapping_and_adjacent() {
        let input = [(1, 3), (2, 6), (8, 10), (15, 18)].map(|(start, end)| Interval { start, end });
        let expected = [(1, 6), (8, 10), (15, 18)].map(|(start, end)| Interval { start, end });
        assert_eq!(merge_intervals(input.into()), expected);
    }

    #[test]
    fn handles_empty_and_disjoint() {
        assert_eq!(merge_intervals(vec![]), vec![]);
        let input = [(1, 2), (3, 4)].map(|(start, end)| Interval { start, end });
        let expected = [(1, 2), (3, 4)].map(|(start, end)| Interval { start, end });
        assert_eq!(merge_intervals(input.into()), expected);
    }

    #[test]
    fn merges_in_place() {
        let mut intervals: Vec<Interval> = [(8, 10), (1, 3), (15, 18), (2, 6)]
            .map(|(start, end)| Interval { start, end })
            .into();
        merge_intervals_in_place(&mut intervals);
        let expected = [(1, 6), (8, 10), (15, 18)].map(|(start, end)| Interval { start, end });
        assert_eq!(intervals, expected);

        let mut empty = vec![];
        merge_intervals_in_place(&mut empty);
        assert!(empty.is_empty());
    }
}

The tests build ranges from tuples with .map(|(start, end)| Interval { start, end }) on arrays. They cover overlapping ranges, an empty input, ranges that do not touch, and unsorted input for the in-place version.

All three versions merge ranges that only touch, such as [1,3] and [3,5], because the check is <=.

3.10 Halving the search: binary search

In a sorted array, you can find a value without looking at every element. Compare the value with the middle element. If the value is smaller, it can only be in the left half; if larger, only in the right half. Discard the other half and repeat. Figure 3.9 finds 23 in eight values in three steps.

The code in this section uses a half-open range low..high. low is the first position still in the range, and high is one past the last. The range is empty when low == high.

3.10.1 Searching a rotated array

The file solves a harder version. A sorted array has been rotated: some elements from the front were moved to the back, as in [4, 5, 6, 7, 0, 1, 2]. You still want O(log n).

The idea rests on one observation. If you split a rotated array at any middle position, at least one of the two halves is still sorted. You can tell which by comparing its end values. Then:

• If the left half is sorted and the target lies between its first and middle values, search the left half.
• If the right half is sorted and the target lies between its middle and last values, search the right half.
• Otherwise, search the other half.

Listing 3.12 Search in a rotated sorted array. src/problems/binary_search.rs

//! Binary search on a rotated sorted array.
//!
//! O(log n). The code uses explicit range bounds and
//! sorted-half checks; no recursion or nested `if` chains are required.

pub fn search_rotated(nums: &[i32], target: i32) -> Option<usize> {
    let mut low = 0usize;
    let mut high = nums.len();

    while low < high {
        let mid = low + (high - low) / 2;
        if nums[mid] == target {
            return Some(mid);
        }

        let left_is_sorted = nums[low] <= nums[mid];
        if left_is_sorted {
            if nums[low] <= target && target < nums[mid] {
                high = mid;
            } else {
                low = mid + 1;
            }
        } else if nums[mid] < target && target <= nums[high - 1] {
            low = mid + 1;
        } else {
            high = mid;
        }
    }

    None
}

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

    #[test]
    fn finds_target_in_rotated_array() {
        let nums = [4, 5, 6, 7, 0, 1, 2];
        assert_eq!(search_rotated(&nums, 0), Some(4));
        assert_eq!(search_rotated(&nums, 3), None);
        assert_eq!(search_rotated(&nums, 5), Some(1));
    }

    #[test]
    fn handles_unrotated_and_single() {
        assert_eq!(search_rotated(&[1, 2, 3, 4], 3), Some(2));
        assert_eq!(search_rotated(&[1], 1), Some(0));
        assert_eq!(search_rotated(&[1], 2), None);
    }
}

mid = low + (high - low) / 2 finds the middle. The shorter (low + high) / 2 can overflow when both are very large; this form cannot.

nums[low] <= nums[mid] means the left half is sorted. The test that the target is in it is nums[low] <= target && target < nums[mid]. The right-half test uses nums[high - 1], the last element, because high itself is one past the end.

3.11 Rotating a square grid in place

The problem. Rotate an n × n grid a quarter turn clockwise, without a second grid.

The idea. Do it in two simple steps (figure 3.11). First transpose the grid. That means swapping the element at row i, column j with the one at row j, column i. It flips the grid across its diagonal. Then reverse each row.

Listing 3.13 The complete program. src/bin/rotate_matrix.rs

fn rotate(m: &mut [Vec<i32>]) {
    let n = m.len();

    for i in 0..n {
        for j in i + 1..n {
            let tmp = m[i][j];
            m[i][j] = m[j][i];
            m[j][i] = tmp;
        }
    }

    for row in m.iter_mut() {
        row.reverse();
    }
}

fn main() {
    let mut m = vec![vec![1, 2, 3], vec![4, 5, 6], vec![7, 8, 9]];

    rotate(&mut m);

    for row in &m {
        println!("{:?}", row);
    }
}

The grid is a Vec<Vec<i32>>, a vector of rows. rotate takes it as &mut [Vec<i32>], a mutable slice of rows, because it changes cells but never adds or removes a row. The transpose loop starts j at i + 1, so it visits only the cells above the diagonal and swaps each pair once. Visiting every cell would swap each pair twice and undo the work.

The swap uses a temporary variable tmp. std::mem::swap needs two mutable references, and m[i][j] and m[j][i] are in different rows of the same outer vector. The borrow checker cannot see that they do not overlap, so it would reject taking both at once.

for row in m.iter_mut() gives a mutable reference to each row, and row.reverse() reverses it.

$ cargo run --bin rotate_matrix
[7, 4, 1]
[8, 5, 2]
[9, 6, 3]

3.12 Finding text inside text

The problem. Find the first position where a short string, the needle, appears in a longer one, the haystack.

The simple idea. Try each position of the haystack, and compare the needle character by character. On a mismatch, move one position right and start over. In the worst case this compares every needle character at every position. For a haystack of length n and a needle of length m, that is O(n × m).

The better idea. Suppose a mismatch comes after several matching characters. You already know what those characters were, because they are the start of the needle. Often a later part of them is also the start of the needle, so you can continue from there instead of starting over. The Knuth-Morris-Pratt algorithm (KMP) uses this. It never moves backward in the haystack, so it runs in O(n + m).

Figure 3.12 shows one such jump.

To know how far to jump, KMP first builds a table from the needle alone. For each position i, look at the piece needle[0..=i]. lps[i] is the length of the longest part of that piece that is both its start and its end. The whole piece does not count. The name “lps” stands for longest proper prefix that is also a suffix. For the needle in the figure:

For example, lps[4] = 2, because "aabaa" starts with "aa" and ends with "aa".

Listing 3.14 The search and the table (lines 1 to 58). src/bin/kmp_pattern_matching.rs

struct Solution {}
impl Solution {
    /// @param haystack the string to search in
    /// @param needle   the pattern to find
    /// @return         first index of needle in haystack, or -1
    pub fn str_str(haystack: String, needle: String) -> i32 {
        let (haystack, needle) = (haystack.as_bytes(), needle.as_bytes());
        if needle.is_empty() {
            return 0;
        }

        let lps = Self::build_lps(needle);
        // left walks the needle, and right walks the haystack.
        let (mut left, mut right) = (0, 0);

        while right < haystack.len() {
            if haystack[right] == needle[left] {
                left += 1;
                right += 1;
            } else if left > 0 {
                // Fall back, keeping the characters that still match.
                left = lps[left - 1];
            } else {
                // A mismatch at the start of the needle.
                right += 1;
            }

            if left == needle.len() {
                // The whole needle matched.
                return (right - left) as i32;
            }
        }
        -1
    }

    // LPS: longest proper prefix of needle[0..=right] that is also a suffix
    fn build_lps(needle: &[u8]) -> Vec<usize> {
        let mut lps = vec![0; needle.len()];
        let (mut left, mut right) = (0, 1);

        while right < needle.len() {
            if needle[right] == needle[left] {
                left += 1;
                lps[right] = left;
                right += 1;
            } else if left > 0 {
                left = lps[left - 1];
            } else {
                // lps[right] stays 0.
                right += 1;
            }
        }
        lps
    }
}

fn main() {
    let cases = [
    // ...
}

str_str works on bytes, from as_bytes(), so it can index directly. left counts how many needle characters currently match, and right walks the haystack. Each pass of the loop takes one of three branches:

1. The characters match: advance both.
2. They do not match, but some characters had matched: jump left back to lps[left - 1], keeping right where it is.
3. They do not match and nothing had matched: advance right.

When left reaches the needle’s length, the needle starts at right - left.

build_lps runs the same three-branch loop, comparing the needle against itself. Both loops only move forward, which gives the O(n + m) total.

Listing 3.15 The complete program. src/bin/kmp_pattern_matching.rs

struct Solution {}
impl Solution {
    /// @param haystack the string to search in
    /// @param needle   the pattern to find
    /// @return         first index of needle in haystack, or -1
    pub fn str_str(haystack: String, needle: String) -> i32 {
        let (haystack, needle) = (haystack.as_bytes(), needle.as_bytes());
        if needle.is_empty() {
            return 0;
        }

        let lps = Self::build_lps(needle);
        // left walks the needle, and right walks the haystack.
        let (mut left, mut right) = (0, 0);

        while right < haystack.len() {
            if haystack[right] == needle[left] {
                left += 1;
                right += 1;
            } else if left > 0 {
                // Fall back, keeping the characters that still match.
                left = lps[left - 1];
            } else {
                // A mismatch at the start of the needle.
                right += 1;
            }

            if left == needle.len() {
                // The whole needle matched.
                return (right - left) as i32;
            }
        }
        -1
    }

    // LPS: longest proper prefix of needle[0..=right] that is also a suffix
    fn build_lps(needle: &[u8]) -> Vec<usize> {
        let mut lps = vec![0; needle.len()];
        let (mut left, mut right) = (0, 1);

        while right < needle.len() {
            if needle[right] == needle[left] {
                left += 1;
                lps[right] = left;
                right += 1;
            } else if left > 0 {
                left = lps[left - 1];
            } else {
                // lps[right] stays 0.
                right += 1;
            }
        }
        lps
    }
}

fn main() {
    let cases = [
        ("sadbutsad", "sad"),
        ("leetcode", "leeto"),
        ("aabaaabaaac", "aabaaac"),
        ("hello", ""),
    ];

    for (haystack, needle) in cases {
        let result = Solution::str_str(haystack.to_string(), needle.to_string());
        println!("str_str({haystack:?}, {needle:?}) = {result}\n");
    }
}

$ cargo run --bin kmp_pattern_matching
str_str("sadbutsad", "sad") = 0

str_str("leetcode", "leeto") = -1

str_str("aabaaabaaac", "aabaaac") = 4

str_str("hello", "") = 0

The function returns -1 when the needle is absent, following the convention of the problem it solves. In your own code, Option<usize> states that more clearly. For everyday searching, the standard library’s str::find is also linear time.

3.13 The complete files

The sections above showed these files in excerpts. Here each one is whole.

Listing 3.16 Merging overlapping intervals, with its tests. src/problems/merge_intervals.rs

//! Merge Intervals: sort by start, then merge overlapping intervals in one pass.
//!
//! The `match out.last_mut()` pattern is intentionally clean: no deep nesting,
//! no confusing boolean flags.

#[derive(Debug, PartialEq, Clone, Copy)]
pub struct Interval {
    start: i32,
    end: i32,
}
pub fn merge_intervals(mut intervals: Vec<Interval>) -> Vec<Interval> {
    if intervals.is_empty() {
        return intervals;
    }

    intervals.sort_unstable_by_key(|interval| interval.start);

    let mut merged: Vec<Interval> = Vec::with_capacity(intervals.len());
    for Interval { start, end } in intervals {
        match merged.last_mut() {
            Some(previous) if start <= previous.end => {
                previous.end = previous.end.max(end);
            }
            _ => merged.push(Interval { start, end }),
        }
    }
    merged
}

pub fn merge_intervals2(mut intervals: Vec<(i32, i32)>) -> Vec<(i32, i32)> {
    if intervals.is_empty() {
        return intervals;
    }

    intervals.sort_unstable_by_key(|(start, _)| *start);

    let mut merged: Vec<(i32, i32)> = Vec::with_capacity(intervals.len());

    for &(start, end) in &intervals {
        match merged.last_mut() {
            Some(previous) if start <= previous.1 => {
                previous.1 = previous.1.max(end);
            }
            _ => merged.push((start, end)),
        }
    }
    merged
}

/// In place: `last` is the last merged interval at the front of the vector.
/// O(1) extra space.
pub fn merge_intervals_in_place(intervals: &mut Vec<Interval>) {
    if intervals.is_empty() {
        return;
    }

    intervals.sort_unstable_by_key(|interval| interval.start);

    let mut last = 0;
    for i in 1..intervals.len() {
        match (intervals[last], intervals[i]) {
            (previous, current) if current.start <= previous.end => {
                intervals[last].end = previous.end.max(current.end);
            }
            (_, current) => {
                last += 1;
                intervals[last] = current;
            }
        }
    }
    intervals.truncate(last + 1);
}

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

    #[test]
    fn merges_overlapping_and_adjacent() {
        let input = [(1, 3), (2, 6), (8, 10), (15, 18)].map(|(start, end)| Interval { start, end });
        let expected = [(1, 6), (8, 10), (15, 18)].map(|(start, end)| Interval { start, end });
        assert_eq!(merge_intervals(input.into()), expected);
    }

    #[test]
    fn handles_empty_and_disjoint() {
        assert_eq!(merge_intervals(vec![]), vec![]);
        let input = [(1, 2), (3, 4)].map(|(start, end)| Interval { start, end });
        let expected = [(1, 2), (3, 4)].map(|(start, end)| Interval { start, end });
        assert_eq!(merge_intervals(input.into()), expected);
    }

    #[test]
    fn merges_in_place() {
        let mut intervals: Vec<Interval> = [(8, 10), (1, 3), (15, 18), (2, 6)]
            .map(|(start, end)| Interval { start, end })
            .into();
        merge_intervals_in_place(&mut intervals);
        let expected = [(1, 6), (8, 10), (15, 18)].map(|(start, end)| Interval { start, end });
        assert_eq!(intervals, expected);

        let mut empty = vec![];
        merge_intervals_in_place(&mut empty);
        assert!(empty.is_empty());
    }
}

This chapter used iterators such as iter() and enumerate() without much comment. Chapter 4 looks at them closely, along with the references they hand you and the lifetimes that keep those references valid.

Exercises

1. Change two_sum to use i64 arithmetic so that it cannot overflow, and add a test with i32::MIN.
2. Fix is_valid so that characters other than brackets are rejected, and add a test for "a".
3. Make reverse_str handle an empty string, then write a version that reverses the characters of any UTF-8 string, including "café".
4. Write a plain binary search over a sorted slice that returns Option<usize>, and test it on arrays of length 0, 1, and 2.
5. Rotate the grid counterclockwise instead, using a transpose and one other reversal.

Iterators and references

Chapter 3 used iterators and references in almost every listing: nums.iter().enumerate(), s.chars(), seen.get(&key). I explained each use briefly and moved on. This chapter slows down and looks at them properly, because every later chapter depends on them.

The chapter has two halves. The first half is about iterators: what they are, how a for loop uses them, and how to chain them. The second half is about references and lifetimes. A lifetime is the part of a program during which a reference is guaranteed to point to valid data. You will see why Rust needs them, how to read them, and how to write a function whose signature uses one.

Both halves meet in one short program. It turns a list of users into a map from each user’s ID to that user, without copying any user.

4.1 What an iterator is

An iterator is a value that hands out items one at a time. It has one required method, next, which returns Some(item) while there are items left and None when there are none.

You can think of an iterator over a slice as a cursor that starts before the first element. Each call to next returns the element under the cursor and moves the cursor one step (figure 4.1).

You rarely call next yourself. A for loop calls it for you. This loop:

for x in [10, 20, 30].iter() {
    println!("{x}");
}

does the same as this:

let mut it = [10, 20, 30].iter();
while let Some(x) = it.next() {
    println!("{x}");
}

while let Some(x) = it.next() keeps looping as long as next returns Some, and binds the item to x. Section 2.8 used this form directly, because it needed to call next inside the loop body.

4.2 Three ways to walk a collection

A Vec<String> owns its strings. When you walk it, you have to decide what you get for each element: a shared reference, a mutable reference, or the string itself. Each choice has its own method (figure 4.2).

• iter() gives &T, a shared reference to each element. You can read the elements, and the collection is unchanged afterward.
• iter_mut() gives &mut T. You can change each element in place.
• into_iter() gives T, the element itself. The collection is moved into the iterator, so you cannot use it afterward.

A for loop chooses for you based on what you write after in. for x in &names means names.iter(). for x in &mut names means names.iter_mut(). for x in names means names.into_iter(), and names is gone after the loop.

4.3 Chaining iterators

An iterator adapter is a method that takes one iterator and returns another. filter keeps only the items for which a closure returns true. map replaces each item with the closure’s result. collect is different: it runs the whole chain and gathers the items into a collection, such as a Vec.

Figure 4.3 follows three numbers through a chain.

Adapters are lazy. iter().filter(...).map(...) only builds a description of the work. Nothing happens until something asks for items, as collect or a for loop does. Then each item goes through every stage before the next item starts. No temporary vector is created between stages.

Animation 4.1 runs functional_numbers_drill from listing 4.1 on [10, 15, 20, 25, 30]. The requests go backward, from collect toward the slice, and the items come forward one at a time.

4.4 References to references

Look closely at the chain in figure 4.3. slice.iter() yields items of type &i32. filter passes its closure a reference to each item, so that the closure can look at the item without taking it. So the closure receives &&i32: a reference to a reference to an i32 (figure 4.4).

A closure’s parameter can be a pattern, the same as the left side of a let. The pattern &x matches a reference and binds x to what it points to. So:

• .filter(|&&x| x % 2 == 0) removes both layers. Inside the closure, x is an i32.
• .map(|&x| x * 10) removes the one layer that map gives. map passes the item itself, not a reference to it.

This works for i32 because i32 is Copy: removing the reference copies the number. A String is not Copy. For it, a pattern like |&s| would try to move the value out of a reference, and the compiler rejects that. You would write |s| and use s as a reference instead.

4.5 The same work in two styles

The program for this chapter starts with a small User type and two functions that do similar work in two styles.

Listing 4.1 The User type and two ways to transform a slice (lines 1 to 23). src/bin/lifetime_reference_drill.rs

use std::collections::HashMap;

#[derive(Debug)]
struct User {
    id: u32,
    name: String,
}

fn functional_numbers_drill(slice: &[i32]) -> Vec<i32> {
    slice
        .iter()
        .filter(|&&x| x % 2 == 0)
        .map(|&x| x * 10)
        .collect()
}

fn imperative_numbers_map(slice: &[i32]) -> HashMap<i32, i32> {
    let mut map = HashMap::new();
    for &num in slice {
        map.insert(num, num * 100);
    }
    map
}

functional_numbers_drill is the chain from figure 4.3. collect() knows to build a Vec<i32> because that is the function’s return type. When the type is not clear from context, you write it, as in collect::<Vec<i32>>().

imperative_numbers_map uses a for loop and builds a HashMap from each number to that number times 100. for &num in slice removes the one reference that iterating a slice gives, so num is an i32.

Neither style is faster. Both compile to similar machine code. Iterator chains read well when the work is a sequence of steps. Loops read well when the body does several unrelated things.

With iterators covered, the rest of the chapter turns to the references they hand out, and to the rules that keep those references safe.

4.6 Lifetimes

A reference points to data owned by something else. If the owner is dropped while the reference is still in use, the reference points to freed memory. Reading through it would give garbage or crash the program. Figure 4.5 shows the smallest example.

To prevent this, the compiler tracks, for every reference, the part of the program where it is used. It also knows where each value is dropped. If a reference is used after its value is dropped, the program does not compile. The part of the program where a reference is valid is its lifetime.

Inside one function, the compiler works out all lifetimes on its own. Across function calls it needs help. Consider a function that takes a reference and returns one:

fn first_word(s: &str) -> &str { ... }

The caller needs to know how long the returned reference is valid. Here the only possible answer is “as long as s”, and the compiler assumes that without being told. These assumptions are called lifetime elision rules. For a function with one reference parameter, the returned reference gets that parameter’s lifetime.

When the rules cannot decide, or when you want to state a relationship yourself, you name lifetimes. A lifetime name is an apostrophe and a short name, usually 'a. You declare it in angle brackets after the function name, like a generic type, and then attach it to references:

fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { ... }

Read this as: “for some lifetime 'a, both inputs are valid for 'a, and so is the output”. The compiler then checks every caller. The returned reference may not be used after either input’s data is dropped.

A lifetime annotation does not change how long anything lives. It describes a relationship, and the compiler checks that the code keeps it.

4.7 A map that points into a slice

Now you have what you need to read the main functions of the program. The goal is to index a list of users by ID. You could copy each user into a HashMap<u32, User>. Or you could store only a reference to each user, in a HashMap<u32, &User>, and leave the users where they are. Figure 4.6 compares the two.

The map of references is cheaper. It also depends on the users staying alive while the map is used. The function’s signature states that dependency with a lifetime.

Listing 4.2 A map whose values point into the slice (lines 27 to 33).

fn struct_slice_to_map<'a>(slice: &'a [User]) -> HashMap<u32, &'a User> {
    let mut map = HashMap::new();
    for user in slice {
        map.insert(user.id, user);
    }
    map
}

Read the signature the way section 4.6 showed. For some lifetime 'a, the input is a slice of users valid for 'a. The output is a map whose values are references valid for 'a. Because both mention the same 'a, the map may not be used after the users are dropped. If you tried, the compiler would reject the program with the same error as figure 4.5.

Inside the function, for user in slice walks the slice by reference, so user is a &User. The map stores that reference. No User is cloned.

4.8 Two lifetimes in one type

The second function takes a different input. Instead of a slice of users, it takes a slice of references to users.

Listing 4.3 A map built from a slice of references (lines 35 to 41).

fn ref_slice_to_map<'a>(slice: &[&'a User]) -> HashMap<u32, &'a User> {
    let mut map = HashMap::new();
    for &user in slice {
        map.insert(user.id, user);
    }
    map
}

The type &[&'a User] has two references in it:

• The outer & is the slice itself, a short list of pointers. Its lifetime has no name here.
• The inner &'a User is each pointer in the list. Its lifetime 'a belongs to the users those pointers point to.

The returned map mentions only 'a. So the map depends on the users, not on the list of pointers. The list can be dropped right after the call, and the map stays valid (figure 4.7).

for &user in slice copies each pointer out of the slice. A reference is a Copy value, one machine word, so this copy is cheap.

4.9 The complete program

Listing 4.4 The complete program. src/bin/lifetime_reference_drill.rs

use std::collections::HashMap;

#[derive(Debug)]
struct User {
    id: u32,
    name: String,
}

fn functional_numbers_drill(slice: &[i32]) -> Vec<i32> {
    slice
        .iter()
        .filter(|&&x| x % 2 == 0)
        .map(|&x| x * 10)
        .collect()
}

fn imperative_numbers_map(slice: &[i32]) -> HashMap<i32, i32> {
    let mut map = HashMap::new();
    for &num in slice {
        map.insert(num, num * 100);
    }
    map
}

// The lifetime could be elided. It is written out because section 4.7 reads it.
#[allow(clippy::needless_lifetimes)]
fn struct_slice_to_map<'a>(slice: &'a [User]) -> HashMap<u32, &'a User> {
    let mut map = HashMap::new();
    for user in slice {
        map.insert(user.id, user);
    }
    map
}

fn ref_slice_to_map<'a>(slice: &[&'a User]) -> HashMap<u32, &'a User> {
    let mut map = HashMap::new();
    for &user in slice {
        map.insert(user.id, user);
    }
    map
}

fn main() {
    let vv = [1, 2, 3, 4, 5, 6];

    let filtered: Vec<i32> = vv
        .iter()
        .filter(|x| *x % 2 == 0)
        .copied()
        .collect();
    println!("Filtered : {:?}", filtered);

    println!("--- Ultra-Lean Inline Slice Drill ---\n");

    let processed_nums = functional_numbers_drill(&[10, 15, 20, 25, 30]);
    println!("1. Functional Numbers (Even * 10): {:?}", processed_nums);

    let num_map = imperative_numbers_map(&[10, 15, 20, 25, 30]);
    println!("2. Imperative Numbers Map: {:?}", num_map);

    // explicit reference binding holding the inline array literal
    let users: &[User] = &[
        User {
            id: 101,
            name: "Alice".to_string(),
        },
        User {
            id: 102,
            name: "Bob".to_string(),
        },
        User {
            id: 103,
            name: "Charlie".to_string(),
        },
    ];
    println!("\n3. Zero-Allocation Struct Map (From &[User]):");
    let struct_map = struct_slice_to_map(users);
    for (id, user_ref) in &struct_map {
        println!("   Key ID: {} -> Value Name: {}", id, user_ref.name);
    }

    // explicit reference binding holding the inline array of &User
    let user_refs: &[&User] = &[struct_map[&101], struct_map[&102]];
    println!("\n4. Zero-Allocation Ref Slice Map (From &[&User]):");
    let ref_slice_map = ref_slice_to_map(user_refs);
    for (id, user_ref) in &ref_slice_map {
        println!("   Key ID: {} -> Value Name: {}", id, user_ref.name);
    }

    println!("\n--- Drill Completed Successfully! ---");
}

main starts with one more iterator chain. vv.iter() yields &i32, and filter receives &&i32. This closure writes |x| and then *x % 2. The * removes one layer of reference, and the % operator works through the other. .copied() turns each &i32 into an i32, so collect builds a Vec<i32>.

Two lines in main use a rule you have not seen yet:

let users: &[User] = &[ User { ... }, User { ... }, User { ... } ];

&[ ... ] takes a reference to an array that was never given a name of its own. Such a value is a temporary, and a temporary is normally dropped at the end of the statement. That would leave users pointing to freed memory. Rust extends the temporary’s life to the end of the enclosing block when it is the direct value of a let. This is called temporary lifetime extension. It is why users and user_refs stay valid for the rest of main.

Run the program:

$ cargo run --bin lifetime_reference_drill
Filtered : [2, 4, 6]
--- Ultra-Lean Inline Slice Drill ---

1. Functional Numbers (Even * 10): [100, 200, 300]
2. Imperative Numbers Map: {20: 2000, 10: 1000, 25: 2500, 15: 1500, 30: 3000}

3. Zero-Allocation Struct Map (From &[User]):
   Key ID: 101 -> Value Name: Alice
   Key ID: 102 -> Value Name: Bob
   Key ID: 103 -> Value Name: Charlie

4. Zero-Allocation Ref Slice Map (From &[&User]):
   Key ID: 102 -> Value Name: Bob
   Key ID: 101 -> Value Name: Alice

--- Drill Completed Successfully! ---

Run it again and the map lines may come out in a different order. As section 3.4 explained, HashMap uses a randomly seeded hash, so its iteration order is not fixed. When you need a stable order, use a BTreeMap, which keeps its keys sorted, or sort the keys before printing.

Chapter 5 uses iterators and collections to solve problems with heaps and sorted collections, such as finding the most frequent words in a text.

Exercises

1. Rewrite imperative_numbers_map as an iterator chain that ends in collect::<HashMap<_, _>>().
2. Write fn longest<'a>(x: &'a str, y: &'a str) -> &'a str. Then write a main where calling it and using the result fails to compile, and read the error.
3. Change struct_slice_to_map to return a BTreeMap, and check that the output order is now stable.
4. Write a function that takes &mut [User] and uses iter_mut() to append “ (admin)“ to every name.

Heaps

Chapter 3 used vectors, strings, and hash maps. This chapter adds one more collection, the heap. A heap answers one question quickly: “what is the largest item right now?” It keeps answering it while items are added and removed.

That question comes up whenever you want the best few items from many. Two examples are the most frequent words in a text and the next job to run from a queue ordered by priority. You will build three programs. Two find the most frequent items. The third keeps the median of a stream of numbers.

As in chapter 3, I start with how the structure works, with pictures, and then show the code.

A few terms used throughout the chapter:

• A binary tree is a set of nodes where each node has at most two children, a left one and a right one. The node with no parent is the root.
• A max-heap is a binary tree where every parent is at least as large as each of its children. So the root holds the largest item.
• A min-heap is the same with “at least as large” replaced by “at most as large”. The root holds the smallest item.
• The median of a list of numbers is the middle value once they are sorted. For an even count, it is the average of the two middle values.

5.1 A tree stored in a vector

A heap is a tree, but it does not store pointers between nodes. It stores the nodes in a Vec, level by level: the root first, then its two children, then their four children, and so on. Figure 5.1 shows a max-heap of six numbers and the vector that holds it.

Because the nodes are packed level by level, simple arithmetic finds a node’s relatives. The children of index i are at 2i + 1 and 2i + 2. Its parent is at (i − 1) / 2, rounded down. In figure 5.1, the children of 7 (index 1) are at indexes 3 and 4, which hold 3 and 5.

The heap rule only compares parents with children. It says nothing about brothers or cousins. In figure 5.1, 7 is on the left and 8 on the right, and that is allowed. That weak rule keeps a heap cheap to maintain.

A tree with n nodes packed this way has about log₂ n levels. A heap of a million items is only about 20 levels deep.

5.2 Adding and removing

5.2.1 Push

To add an item, put it at the end of the vector, which is the next free spot on the bottom level. It may be larger than its parent, which breaks the rule. So swap it with its parent, and keep swapping upward until it is not larger than its parent, or it reaches the root. Figure 5.2 pushes 10.

Each swap moves the item one level up, and there are about log₂ n levels. So a push takes O(log n) steps.

5.2.2 Pop

To remove the largest item, take the root. That leaves a hole at the top. Fill it with the last item in the vector, which shrinks the vector by one. The moved item is probably too small for the top. So swap it with its larger child, and keep swapping downward until both its children are smaller. Figure 5.3 pops the 10 that figure 5.2 added.

It swaps with the larger child for a reason. That child is about to become the parent of the other one, and a parent must be at least as large as its children. Pop is also O(log n).

Looking at the largest item without removing it is O(1): it is always at index 0.

5.3 Heaps in Rust

Rust’s standard library provides std::collections::BinaryHeap<T>, a max-heap. Its main methods match the operations above:

To decide which item is larger, BinaryHeap uses the Ord trait, which types such as i32, String, and tuples implement.

5.3.1 How tuples compare

Tuples compare element by element, from the left. Two tuples are compared on their first elements, and only if those are equal does the second element decide. So (3, 1) > (2, 9), because 3 > 2, and the 9 is never looked at. And (3, 1) < (3, 2), because the first elements tie and 1 < 2.

This gives a way to choose what a heap orders by: put that field first in a tuple. A heap of (count, value) pairs orders by count, and breaks ties by value.

5.3.2 A min-heap with Reverse

BinaryHeap has no min-heap mode. Instead, the standard library provides a wrapper, std::cmp::Reverse<T>, whose comparison is the opposite of T’s. Reverse(3) > Reverse(5), because 3 < 5. So a BinaryHeap<Reverse<i32>> keeps the smallest number on top.

To put a value in, wrap it: heap.push(Reverse(x)). To get it out, unwrap it with a pattern: if let Some(Reverse(x)) = heap.pop().

Now you can read the three programs.

5.4 The k most frequent numbers

The problem. Given a list of numbers and a count k, return the k numbers that occur most often. For [1, 1, 1, 2, 2, 3] and k = 2, the answer is 1 and 2.

The idea. Count each number with a HashMap. Put every (count, number) pair into a max-heap. Pop k times.

Listing 5.1 Top k with a full heap. src/problems/top_k_frequent.rs

//! Top K Frequent Elements.
//!
//! Count occurrences with a HashMap, then use a max-heap (`BinaryHeap`) to pull
//! out the top k elements. O(n log n) worst case; acceptable and readable.

use std::collections::{BinaryHeap, HashMap};

pub fn top_k_frequent(nums: &[i32], k: usize) -> Vec<i32> {
    let mut counts: HashMap<i32, usize> = HashMap::with_capacity(nums.len());
    for &num in nums.iter() {
        *counts.entry(num).or_insert(0) += 1;
    }

    // BinaryHeap is a max-heap in Rust, so (count, num) keeps highest counts first.
    let mut heap: BinaryHeap<(usize, i32)> = counts
        .into_iter()
        .map(|(num, count)| (count, num))
        .collect();

    let mut result = Vec::with_capacity(k);
    while result.len() < k {
        match heap.pop() {
            Some((_, num)) => result.push(num),
            None => break,
        }
    }
    result
}

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

    #[test]
    fn returns_top_two() {
        let nums = [1, 1, 1, 2, 2, 3];
        let mut result = top_k_frequent(&nums, 2);
        result.sort_unstable();
        assert_eq!(result, vec![1, 2]);
    }

    #[test]
    fn k_larger_than_unique_values_returns_all() {
        let result = top_k_frequent(&[1, 2, 3], 10);
        assert_eq!(result.len(), 3);
    }
}

Step through it:

1. *counts.entry(num).or_insert(0) += 1; counts one occurrence. entry(num) finds the map slot for num, and or_insert(0) creates it with 0 if it is missing. Both steps return a mutable reference to the count, and * followed by += 1 adds one to the value it points to.
2. counts.into_iter().map(|(num, count)| (count, num)).collect() turns each map entry around, so the count comes first, and collects the pairs straight into a BinaryHeap. A BinaryHeap can be built with collect like a Vec.
3. The while loop pops until it has k numbers. If there are fewer than k distinct numbers, pop returns None and the loop stops early. The second test checks that case.

Counting takes O(n). Building the heap from u distinct numbers takes O(u), and k pops take O(k log u).

The first test sorts the result before comparing it. The order of numbers with equal counts depends on the map’s iteration order. That order changes between runs, so a test must not depend on it.

5.5 The k most frequent words, with a heap of size k

The first version puts every distinct number in the heap. If the input has millions of distinct words and you only want the top 3, most of that heap is wasted. The second version never lets the heap grow past k + 1 entries.

The idea. Use a min-heap. Push each (count, word) pair. Whenever the heap has more than k entries, pop once. A min-heap pops its smallest entry, which is the least frequent word seen so far, so the k most frequent words survive (figure 5.4).

The program first turns the text into words, then counts them, then runs the bounded heap.

Listing 5.2 The function (lines 1 to 41). src/bin/top_k_frequent_words.rs

use std::{
    cmp::Reverse as Rev,
    collections::{BinaryHeap, HashMap},
};

/// Returns vec!<(word, frequency)>, most frequent first.
fn top_k_frequent(sentence: &str, k: usize) -> Vec<(String, u32)> {
    // Split string by white spaces. Map it and trim any non alphanumeric characters. Finally,
    // filter all the empty strings and map everything to lowercase characters.
    let words: Vec<String> = sentence
        .split_whitespace()
        .map(|w| w.trim_matches(|c: char| !c.is_alphanumeric()))
        .filter(|w| !w.is_empty())
        .map(str::to_lowercase)
        .collect();

    // Build the frequency map...
    let mut frequencies = HashMap::<&str, u32>::new();
    for word in &words {
        *frequencies
            .entry(word.as_str())
            .or_default() += 1;
    }

    // Keep a min heap of size k. Reverse flips the max heap, so the least
    // frequent word sits on top and gets popped once we go over k.
    let mut min_heap = BinaryHeap::<Rev<(u32, &str)>>::new();
    for (&word, &frequency) in &frequencies {
        min_heap.push(Rev((frequency, word)));
        if min_heap.len() > k {
            min_heap.pop();
        }
    }

    // Ascending order of Reverse means most frequent first.
    min_heap
        .into_sorted_vec()
        .into_iter()
        .map(|Rev((frequency, word))| (word.to_string(), frequency))
        .collect()
}

Turning text into words. The chain splits on whitespace. Then it trims characters that are not letters or digits from both ends of each piece, so "sentence." becomes "sentence". It drops empty pieces, which a lone punctuation mark leaves behind, and lowercases each word. trim_matches takes a closure that decides which characters to trim. map(str::to_lowercase) passes a function by name instead of writing a closure.

Counting without copying. The map is HashMap<&str, u32>. Its keys are references into the words vector, so counting allocates nothing for each occurrence. or_default() inserts the type’s default value, 0 for u32, when the key is missing.

The bounded heap. use std::cmp::Reverse as Rev; gives Reverse a shorter name. Each entry is Rev((frequency, word)), so the heap’s top is the smallest (frequency, word) pair. After each push, if the heap has more than k entries, one pop removes that smallest pair.

The result. into_sorted_vec() returns the entries in ascending order of Rev, which is descending order of frequency. The final map unwraps each Rev with a pattern and copies the word into an owned String. The result must not borrow from words, because words is dropped when the function returns.

The heap holds at most k + 1 entries, so each push and pop costs O(log k). For u distinct words, the heap work is O(u log k) instead of O(u log u), and its memory is O(k) instead of O(u).

5.5.1 The complete program

Listing 5.3 The complete program, with its tests. src/bin/top_k_frequent_words.rs

use std::{
    cmp::Reverse as Rev,
    collections::{BinaryHeap, HashMap},
};

/// Returns vec!<(word, frequency)>, most frequent first.
fn top_k_frequent(sentence: &str, k: usize) -> Vec<(String, u32)> {
    // Split string by white spaces. Map it and trim any non alphanumeric characters. Finally,
    // filter all the empty strings and map everything to lowercase characters.
    let words: Vec<String> = sentence
        .split_whitespace()
        .map(|w| w.trim_matches(|c: char| !c.is_alphanumeric()))
        .filter(|w| !w.is_empty())
        .map(str::to_lowercase)
        .collect();

    // Build the frequency map...
    let mut frequencies = HashMap::<&str, u32>::new();
    for word in &words {
        *frequencies
            .entry(word.as_str())
            .or_default() += 1;
    }

    // Keep a min heap of size k. Reverse flips the max heap, so the least
    // frequent word sits on top and gets popped once we go over k.
    let mut min_heap = BinaryHeap::<Rev<(u32, &str)>>::new();
    for (&word, &frequency) in &frequencies {
        min_heap.push(Rev((frequency, word)));
        if min_heap.len() > k {
            min_heap.pop();
        }
    }

    // Ascending order of Reverse means most frequent first.
    min_heap
        .into_sorted_vec()
        .into_iter()
        .map(|Rev((frequency, word))| (word.to_string(), frequency))
        .collect()
}

fn main() {
    let sentence = r"This is a short sentence. We'll count words.
    Let us count words in this sentence
    ";

    let top_k = top_k_frequent(sentence, 3);
    println!("Top 3 frequency [(word, frequency)] : \n {:#?}", top_k);
}

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

    #[test]
    fn picks_most_frequent() {
        let result = top_k_frequent("a a a b b c", 2);
        assert_eq!(result, vec![("a".to_string(), 3), ("b".to_string(), 2)]);
    }

    #[test]
    fn ignores_case_and_punctuation() {
        let result = top_k_frequent("Hello, hello! HELLO world.", 1);
        assert_eq!(result, vec![("hello".to_string(), 3)]);
    }

    #[test]
    fn k_larger_than_word_count() {
        assert_eq!(top_k_frequent("x y", 10).len(), 2);
    }

    #[test]
    fn empty_input() {
        assert!(top_k_frequent("", 3).is_empty());
    }
}

The sentence in main is a raw string literal, written r"...". A raw string treats backslashes as ordinary characters, and this one also spans several lines. The tests cover the basic case, uppercase and punctuation, a k larger than the number of words, and an empty input.

$ cargo run --bin top_k_frequent_words
Top 3 frequency [(word, frequency)] :
 [
    (
        "words",
        2,
    ),
    (
        "this",
        2,
    ),
    (
        "sentence",
        2,
    ),
]

Four words occur twice in the sentence: “this”, “sentence”, “count”, and “words”. Only three fit, and “count” was evicted. When two entries have the same count, the tuple comparison falls to the word, and the min-heap evicts the alphabetically smallest one. So among equal counts, this version keeps the words that come last in alphabetical order.

5.6 The median of a stream

The problem. Numbers arrive one at a time. After each one, report the median of all the numbers so far.

The simple idea. Keep every number in a sorted Vec, and read the middle. Inserting into the middle of a sorted vector shifts the elements after it, which costs O(n) per number.

The idea with heaps. Split the numbers into two halves (figure 5.5):

• low, a max-heap holding the smaller half. Its top is the largest of the small numbers.
• high, a min-heap holding the larger half. Its top is the smallest of the large numbers.

Keep two rules. Every number in low is at most every number in high. And low has either the same number of items as high, or one more. Then the median is always at the tops. With an odd count, it is the top of low. With an even count, it is the average of the two tops.

5.6.1 Adding a number

Listing 5.4 The structure and add_num (lines 1 to 27). src/bin/median_finder.rs

use std::{cmp::Reverse, collections::BinaryHeap};

#[derive(Default)]
pub struct MedianFinder {
    low: BinaryHeap<i32>,
    high: BinaryHeap<Reverse<i32>>,
}

impl MedianFinder {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn add_num(&mut self, num: i32) {
        self.low.push(num);

        if let Some(val) = self.low.pop() {
            self.high.push(Reverse(val));
        }

        if self.high.len() > self.low.len()
            && let Some(Reverse(val)) = self.high.pop()
        {
            self.low.push(val);
        }
    }
    // ...
}

add_num keeps both rules with three moves, and never compares numbers itself:

1. Push the new number into low.
2. Pop the largest number from low and push it into high. This keeps the first rule: whatever high receives is at least as large as everything left in low.
3. If high now has more items than low, pop its smallest and push it back into low. This keeps the second rule.

Trace the first three numbers of the sample, 6, 10, and 2:

Each move is one heap operation, so adding a number is O(log n).

5.6.2 Reading the median

Listing 5.5 find_median (lines 28 to 37).

impl MedianFinder {
    // ...
    pub fn find_median(&self) -> Option<f64> {
        let max_low = *self.low.peek()?;

        if self.low.len() > self.high.len() {
            Some(max_low as f64)
        } else {
            let Reverse(min_high) = *self.high.peek()?;
            Some((max_low as f64 + min_high as f64) / 2.0)
        }
    }
}

*self.low.peek()? reads the top of low. The ? works on Option the same way it works on Result. If no number has been added, peek returns None, and so does the function. The function returns Option<f64>, a floating-point number, because the average of two integers can be a half.

let Reverse(min_high) = *self.high.peek()?; unwraps the Reverse in the let pattern itself.

5.6.3 The complete program

Listing 5.6 The complete program, with its tests. src/bin/median_finder.rs

use std::{cmp::Reverse, collections::BinaryHeap};

#[derive(Default)]
pub struct MedianFinder {
    low: BinaryHeap<i32>,
    high: BinaryHeap<Reverse<i32>>,
}

impl MedianFinder {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn add_num(&mut self, num: i32) {
        self.low.push(num);

        if let Some(val) = self.low.pop() {
            self.high.push(Reverse(val));
        }

        if self.high.len() > self.low.len()
            && let Some(Reverse(val)) = self.high.pop()
        {
            self.low.push(val);
        }
    }

    pub fn find_median(&self) -> Option<f64> {
        let max_low = *self.low.peek()?;

        if self.low.len() > self.high.len() {
            Some(max_low as f64)
        } else {
            let Reverse(min_high) = *self.high.peek()?;
            Some((max_low as f64 + min_high as f64) / 2.0)
        }
    }
}

const SAMPLE: [i32; 11] = [6, 10, 2, 6, 5, 0, 6, 3, 1, 0, 0];

fn main() {
    let mut finder = MedianFinder::new();

    for value in SAMPLE {
        finder.add_num(value);
        match finder.find_median() {
            Some(median) => println!("after {value:>2}: median {median}"),
            None => println!("after {value:>2}: no median"),
        }
    }
}

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

    /// The median of a sorted slice, computed directly.
    fn median_of_sorted(values: &[i32]) -> f64 {
        let middle = values.len() / 2;
        if values.len() % 2 == 1 {
            values[middle] as f64
        } else {
            (values[middle - 1] as f64 + values[middle] as f64) / 2.0
        }
    }

    #[test]
    fn an_empty_finder_has_no_median() {
        assert_eq!(MedianFinder::new().find_median(), None);
    }

    #[test]
    fn one_value_is_the_median() {
        let mut finder = MedianFinder::new();
        finder.add_num(7);
        assert_eq!(finder.find_median(), Some(7.0));
    }

    #[test]
    fn an_even_count_averages_the_middle_two() {
        let mut finder = MedianFinder::new();
        finder.add_num(1);
        finder.add_num(2);
        assert_eq!(finder.find_median(), Some(1.5));
    }

    #[test]
    fn three_values_are_ordered() {
        let mut finder = MedianFinder::new();
        for (value, median) in [1, 2, 3]
            .into_iter()
            .zip([1.0, 1.5, 2.0])
        {
            finder.add_num(value);
            assert_eq!(finder.find_median(), Some(median));
        }
    }

    #[test]
    fn duplicates_are_kept() {
        let mut finder = MedianFinder::new();
        for value in [4, 4, 4, 4] {
            finder.add_num(value);
        }
        assert_eq!(finder.find_median(), Some(4.0));
    }

    #[test]
    fn the_stream_matches_a_sort_on_every_step() {
        let mut finder = MedianFinder::new();
        let mut seen = Vec::new();

        for value in SAMPLE {
            finder.add_num(value);
            seen.push(value);
            seen.sort_unstable();

            assert_eq!(finder.find_median(), Some(median_of_sorted(&seen)));
        }
    }

    #[test]
    fn the_two_heaps_never_differ_by_more_than_one() {
        let mut finder = MedianFinder::new();

        for value in SAMPLE {
            finder.add_num(value);
            assert!(
                finder
                    .low
                    .len()
                    .abs_diff(finder.high.len())
                    <= 1
            );
        }
    }
}

main adds the eleven sample values and prints the median after each one.

$ cargo run --bin median_finder
after  6: median 6
after 10: median 8
after  2: median 6
after  6: median 6
after  5: median 6
after  0: median 5.5
after  6: median 6
after  3: median 5.5
after  1: median 5
after  0: median 4
after  0: median 3

Look at the test the_stream_matches_a_sort_on_every_step. After every added number, it sorts a copy of all the numbers so far. Then it computes the median the slow way, with the helper median_of_sorted. Then it checks that the heaps give the same answer. A test like this, which compares a fast method with a slow method you can trust, is called an oracle test. It catches mistakes that a few hand-picked examples miss.

The last test checks the second rule directly: after every number, the two heaps’ sizes differ by at most one.

Chapter 6 covers recursion and dynamic programming. You will solve problems by combining answers to smaller versions of themselves, and save those answers so none is computed twice.

Exercises

1. Implement a max-heap yourself on a Vec<i32>, with push, pop, and peek, using the index formulas from section 5.1. Test it against BinaryHeap on random input.
2. Change top_k_frequent_words to keep the alphabetically first words among ties, as the tip in section 5.5 describes, and add a test.
3. Add a method len to MedianFinder that returns how many numbers it holds.
4. Extend the running median to remove numbers as well, so it can report the median of the last 100 numbers only. Hint: remove lazily, by remembering which numbers are waiting to be deleted.

Recursion and dynamic programming

In chapter 1 you computed Fibonacci numbers three ways. The recursive version repeated work. The memoized version saved each answer in a table, and the loop version kept only the answers it still needed. That small example contains the whole idea of this chapter.

Dynamic programming is a way to solve a problem by answering smaller versions of the same problem first, saving those answers, and combining them. It applies when two things are true:

1. The answer for a large input can be built from the answers for smaller inputs.
2. The same smaller inputs come up again and again, so saving their answers avoids repeated work.

This chapter works through four problems. The first, making change with coins, is dynamic programming in its plainest form. The second, listing subsets, uses recursion without any saved answers. The last two combine dynamic programming with the sorting and searching you learned in chapter 3.

For each problem I first say, in one sentence, what one entry of the table means. That sentence is called the subproblem. Once it is written down, the code follows from it.

6.1 Making change with the fewest coins

The problem. You have coins of some values, as many of each as you like. What is the fewest number of coins that add up to a given amount? With coins 1, 2, and 5, the amount 11 needs three coins: 5 + 5 + 1. Some amounts cannot be made at all. With only a 2 coin, the amount 3 is impossible.

6.1.1 Why the obvious approach fails

A natural first try is to take the largest coin that fits, again and again. This is called a greedy approach. It works for 1, 2, and 5. It does not work for every set of coins (figure 6.1).

So the program has to consider every coin at every step. Trying every combination directly takes exponential time. Dynamic programming makes it fast.

6.1.2 The subproblem

Write down what one entry of the table means:

dp[t] is the fewest coins that add up to exactly t.

Now think about the last coin used to make t. If that coin is c, the coins before it add up to t - c, and the fewest coins for that is dp[t - c]. So using coin c last costs dp[t - c] + 1 coins. You do not know which coin is last in the best answer, so try every coin and keep the smallest:

dp[t] = the smallest of dp[t - c] + 1, over every coin c that is not larger than t.

The starting point is dp[0] = 0: zero coins make zero.

Fill the table by hand for the coins in figure 6.1, which are 1, 3, and 4, and the amount 6. Each row tries every coin that fits, and keeps the smallest count:

dp[6] is 2, from 3 + 3. Greedy needed three coins for the same amount, because it took the 4 first and never went back. The table records the best count for every smaller amount. Each new amount is then one lookup plus one.

Two properties must hold for that to work. The answers must overlap, so that saving them avoids work. dp[6] and dp[5] both read dp[1], and a longer table reads each entry many times. The best answer must also be built from best answers to smaller amounts. Taking the smallest of dp[t - c] + 1 relies on that. If some way of making t - c used fewer coins, dp[t - c] would hold that smaller number. When either property fails, the table gives a wrong answer.

Because dp[t] only uses entries for smaller amounts, you can fill the table from left to right. Figure 6.2 shows the table for coins 1, 2, and 5, and how dp[11] is computed.

6.1.3 The code

Listing 6.1 Coin change (lines 6 to 29). src/problems/dp.rs

pub fn coin_change(coins: &[i32], amount: i32) -> Option<i32> {
    if amount < 0 {
        return None;
    }

    let amount = amount as usize;
    let mut dp = vec![usize::MAX; amount + 1];
    dp[0] = 0;

    for total in 1..=amount {
        for &coin in coins {
            let coin = coin as usize;
            if coin > total || dp[total - coin] == usize::MAX {
                continue;
            }
            dp[total] = dp[total].min(dp[total - coin] + 1);
        }
    }

    match dp[amount] {
        usize::MAX => None,
        count => Some(count as i32),
    }
}

Read it against the recurrence:

• A negative amount is rejected first. After that check, amount as usize cannot produce a strange value.
• vec![usize::MAX; amount + 1] creates the table, one entry per amount from 0 to amount. usize::MAX, the largest usize, stands for “cannot be made yet”.
• dp[0] = 0 is the starting point.
• The outer loop fills amounts from 1 upward. The inner loop tries every coin.
• The continue skips a coin that is larger than the amount, or whose remainder cannot be made. The second check also prevents usize::MAX + 1, which would overflow.
• dp[total].min(dp[total - coin] + 1) keeps the smaller of the current best and the new option.

At the end, a match turns the table entry into the result. The pattern usize::MAX matches that exact value, meaning impossible, and returns None. Any other value is a count. So the function returns Option<i32>, and the caller cannot mistake “impossible” for a number of coins.

The table has amount + 1 entries and each one tries every coin. The cost is O(amount × coins) time and O(amount) memory.

Listing 6.2 The complete file. src/problems/dp.rs

//! Coin Change: minimum number of coins to make an amount.
//!
//! Classic dynamic programming. `Option<i32>` expresses "impossible" instead of
//! a magic `-1`.

pub fn coin_change(coins: &[i32], amount: i32) -> Option<i32> {
    if amount < 0 {
        return None;
    }

    let amount = amount as usize;
    let mut dp = vec![usize::MAX; amount + 1];
    dp[0] = 0;

    for total in 1..=amount {
        for &coin in coins {
            let coin = coin as usize;
            if coin > total || dp[total - coin] == usize::MAX {
                continue;
            }
            dp[total] = dp[total].min(dp[total - coin] + 1);
        }
    }

    match dp[amount] {
        usize::MAX => None,
        count => Some(count as i32),
    }
}

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

    #[test]
    fn computes_minimum_coins() {
        assert_eq!(coin_change(&[1, 2, 5], 11), Some(3)); // 5 + 5 + 1
        assert_eq!(coin_change(&[2], 3), None);
        assert_eq!(coin_change(&[1], 0), Some(0));
    }
}

Run the tests with cargo test --lib coin_change. The tests check the example from section 6.1, an impossible amount, and the amount 0.

6.2 Listing every subset

Not every recursive problem needs a table. Sometimes you need every possible answer, not the best one. Then recursion explores all the choices, and there is nothing to save.

The problem. List every subset of a set of distinct numbers. A subset is any selection of the elements, including none of them and all of them. [1, 2, 3] has eight subsets: [], [1], [2], [3], [1, 2], [1, 3], [2, 3], and [1, 2, 3].

The idea. Build subsets one element at a time. Start with the empty subset. From any subset, you can add one more element, as long as it comes later in the input than the elements already chosen. That rule is what stops [2, 1] from appearing as a copy of [1, 2]. Figure 6.3 draws the choices as a tree. Every node in the tree is one subset.

To visit the whole tree, the program walks it depth first, going down one branch as far as it can before trying the next. Going down means adding an element; coming back up means removing it. This way of exploring choices is called backtracking.

Listing 6.3 Subsets by backtracking. src/problems/backtracking.rs

//! Subsets: enumerate every subset of a set of distinct integers.
//!
//! Backtracking with clean `path.push(...)` + recursive exploration + `pop`.
//! `Vec<Vec<i32>>` is sorted in the tests to avoid order-dependent assertions.

pub fn subsets(nums: Vec<i32>) -> Vec<Vec<i32>> {
    let mut result = Vec::with_capacity(1 << nums.len());
    let mut path = Vec::new();

    fn backtrack(nums: &[i32], start: usize, path: &mut Vec<i32>, result: &mut Vec<Vec<i32>>) {
        result.push(path.clone());
        for idx in start..nums.len() {
            path.push(nums[idx]);
            backtrack(nums, idx + 1, path, result);
            path.pop();
        }
    }

    backtrack(&nums, 0, &mut path, &mut result);
    result
}

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

    #[test]
    fn generates_all_subsets() {
        let mut subsets = subsets(vec![1, 2, 3]);
        subsets.sort_unstable();
        assert_eq!(subsets.len(), 8);
        assert!(subsets.contains(&vec![]));
        assert!(subsets.contains(&vec![1, 2, 3]));
    }

    #[test]
    fn empty_input_has_one_subset() {
        assert_eq!(subsets(vec![]), vec![vec![]]);
    }
}

backtrack is a function defined inside subsets, as go was in chapter 1. It takes four things:

• nums, the input, borrowed.
• start, the first position it may choose from.
• path, the subset being built. Only one path vector exists for the whole search, passed as &mut.
• result, the list of finished subsets, also passed as &mut.

On entry, backtrack records path.clone() in the result. The current path is one subset, the node of the tree it has reached. Then, for each later position, it pushes that element, recurses to explore the subtree below, and pops the element. After the pop, path is exactly as it was before the push, ready for the next choice.

Trace the start of subsets(vec![1, 2, 3]):

Vec::with_capacity(1 << nums.len()) reserves exactly enough room. 1 << n means 2 to the power n, because shifting 1 left by n bits doubles it n times. A set of n elements has 2ⁿ subsets.

The work is O(n · 2ⁿ): there are 2ⁿ subsets and each clone copies up to n numbers. No algorithm can do better, because the output itself has that size.

6.3 The longest increasing run inside a list

The problem. In a list of numbers, pick some of them and keep their order. Each picked number must be larger than the one before. What is the most you can pick? The picked numbers are called an increasing subsequence. In [10, 9, 2, 5, 3, 7, 101, 18], you can pick 2, 3, 7, 18, so the answer is 4.

A subsequence may skip numbers. That is the difference from the substrings of chapter 3, which were contiguous.

The direct dynamic program. Let dp[i] be the length of the longest increasing subsequence that ends at position i. For each i, look at every earlier j with a smaller number, and take the best dp[j] + 1. That is O(n²), because each position looks at every earlier one.

A faster idea. Keep a different table, called tails. Its entries have this meaning:

The k-th smallest entry of tails is the smallest number that can end an increasing subsequence of length k.

Keeping the smallest possible ending number is useful because a smaller ending leaves more room for later numbers to extend it. When a new number arrives:

• If it is larger than every entry, it extends the longest subsequence found so far. Add it.
• Otherwise, find the smallest entry that is at least as large as it, and replace that entry with it. Some subsequence of that length can now end with a smaller number.

At the end, the number of entries is the answer. Figure 6.4 follows the example.

Look at the last row. tails is 2, 3, 7, 18, which happens to be a real increasing subsequence here. That is not true in general. tails can mix numbers from different subsequences. Only its length is meaningful.

The entries of tails are always in increasing order, so finding “the smallest entry at least as large” can use a sorted structure. The program uses a BTreeSet, a set that keeps its elements sorted.

Listing 6.4 The complete program. src/bin/longest_increasing_subsequence.rs

use std::collections::BTreeSet;

fn lis_len(nums: &[i32]) -> usize {
    let mut tails = BTreeSet::new();

    for &num in nums {
        if let Some(&ceiling) = tails.range(num..).next() {
            tails.remove(&ceiling);
        }
        tails.insert(num);
    }

    tails.len()
}

fn main() {
    println!("{}", lis_len(&[10, 9, 2, 5, 3, 7, 101, 18])); // 4
    println!("{}", lis_len(&[0, 1, 0, 3, 2, 3])); // 4
    println!("{}", lis_len(&[7, 7, 7, 7])); // 1
    println!("{}", lis_len(&[5, 4, 3, 2, 1])); // 1
    println!("{}", lis_len(&[1, 2, 3, 4, 5])); // 5
    println!("{}", lis_len(&[])); // 0
}

tails.range(num..) returns the elements from num upward, in sorted order. .next() takes the first of them, the smallest element that is at least num. If there is one, the program removes it. Then it inserts num in every case. Removing and inserting is how the set replaces one element with another.

The range num.. includes num itself, which handles repeated numbers. In [7, 7, 7, 7], the second 7 finds the first 7, removes it, and inserts itself again, so the answer stays 1. A run with a repeated number is not strictly increasing, so 1 is correct.

Each range, remove, and insert on a BTreeSet costs O(log n), so the whole program is O(n log n).

$ cargo run --bin longest_increasing_subsequence
4
4
1
1
5
0

The six outputs match the comments in main.

6.4 Choosing jobs that do not overlap

The problem. A machine can run one job at a time. Each job has a start time, an end time, and a profit. Choose jobs that do not overlap so that the total profit is as large as possible. Figure 6.5 shows the four sample jobs.

A job written [s, e) runs from time s up to, but not including, time e. So a job ending at 3 and a job starting at 3 do not overlap.

6.4.1 Building the subproblem

First sort the jobs by end time. Then any job that can come before job i in a schedule ends earlier, so it appears earlier in the sorted list. The subproblem is:

dp[i] is the best profit using only the first i jobs of the sorted list.

For job i there are two choices:

• Skip it. The best profit stays dp[i], the best without it.
• Take it. Then only jobs that end by its start time can come before it. Those jobs are a prefix of the sorted list, say the first prev jobs. The profit is dp[prev] + profit of job i.

So dp[i + 1] is the larger of the two. The last entry is the answer.

Finding prev is a search in a sorted list, so it can be a binary search, like chapter 3’s. The standard library provides one as partition_point. Given a condition that is true for a prefix of the list and false after it, partition_point returns the length of that prefix.

6.4.2 The code

A job is a small Copy struct: when it starts, when it ends, and what it pays.

#[derive(Debug, Default, Clone, Copy)]
struct Job {
    start: u32,
    end: u32,
    profit: u64,
}

Listing 6.5 The complete program. src/bin/job_scheduling_with_profit_and_deadline.rs

#[derive(Debug, Default, Clone, Copy)]
struct Job {
    start: u32,
    end: u32,
    profit: u64,
}

fn max_profit(mut jobs: Vec<Job>) -> u64 {
    // Sort by end time so every job that could come before
    // job `i` in a schedule sits somewhere in jobs[..i].
    jobs.sort_unstable_by_key(|job| job.end);

    // dp[i] = best profit achievable using only the first `i` jobs.
    let mut dp = vec![0; jobs.len() + 1];

    for (i, job) in jobs.iter().enumerate() {
        // Binary search for how many earlier jobs finish by the time
        // this one starts. Those are exactly the jobs compatible with it,
        // and since they form a prefix, dp[prev] is their best profit.
        let prev = jobs[..i].partition_point(|j| j.end <= job.start);

        // Either skip this job (keep dp[i]),
        // or take it on top of the best compatible prefix.
        dp[i + 1] = dp[i].max(dp[prev] + job.profit);
    }

    // After considering every job, the last entry holds the answer.
    dp[jobs.len()]
}

fn main() {
    let jobs = vec![
        Job {
            start: 1,
            end: 3,
            profit: 50,
        },
        Job {
            start: 2,
            end: 4,
            profit: 10,
        },
        Job {
            start: 3,
            end: 5,
            profit: 40,
        },
        Job {
            start: 3,
            end: 6,
            profit: 70,
        },
    ];

    println!("{}", max_profit(jobs)); // 120
}

The comments inside max_profit walk through the same reasoning as section 6.4.1, step by step. jobs[..i].partition_point(|j| j.end <= job.start) counts the jobs among the first i that end by this job’s start. Because the list is sorted by end time, those jobs come first, which is the condition partition_point needs.

Trace it on the sorted jobs A, B, C, D:

For C and D, prev is 1: only A ends by time 3. Sorting costs O(n log n), and each job does one binary search, so the whole program is O(n log n).

$ cargo run --bin job_scheduling_with_profit_and_deadline
120

6.5 Jobs that also need memory and cores

The problem. A cluster holds several GPUs. Each GPU has a fixed amount of memory and a fixed number of cores. Each job needs some of both, and it runs only on a GPU that has enough of each. A GPU runs one job at a time, as in section 6.4.

The program below answers a narrow question: which single GPU gives the best schedule? Section 6.5.4 measures what that leaves unused.

The sample cluster has two GPUs and the four jobs from section 6.4, with a memory need and a core need added.

gpu 0 has 80 GB and 108 cores, so all four jobs fit there. Only A and B fit on gpu 1, which has 16 GB and 40 cores.

6.5.1 The fit test, and the same table

The new step is one boolean. A job fits a GPU when the GPU has at least its memory and at least its cores.

The rest is the table from section 6.4. Sort the jobs by end time and find each job’s compatible prefix prev. Then fill dp with the better of skipping the job and taking it on top of dp[prev].

The fit test changes one line of that loop. A job that does not fit is skipped, as if it were not in the list at all. Its entry in dp copies the entry before it.

6.5.2 The code

A job carries its two resource needs beside its time and its profit. A GPU carries the same two numbers, and one method answers whether a job fits.

#[derive(Debug, Default, Clone, Copy)]
struct Gpu {
    mem_gb: u32,
    cores: u32,
}

#[derive(Debug, Default, Clone, Copy)]
struct Job {
    start: u32,
    end: u32,
    mem_gb: u32,
    cores: u32,
    profit: u64,
}

impl Gpu {
    /// A job fits when the GPU has at least its memory and at least its cores.
    fn fits(&self, job: &Job) -> bool {
        (0..=self.mem_gb).contains(&job.mem_gb) && (0..=self.cores).contains(&job.cores)
    }
}

Listing 6.6 The complete program. src/bin/gpu_job_schedule.rs

//! Choose non-overlapping jobs for a GPU, where each job needs memory and cores.
//!
//! A job runs only on a GPU with enough memory and enough cores. For one GPU the
//! task is weighted interval scheduling: sort by end time, then take or skip each
//! job. The same table is reused for every GPU, and the best GPU wins.

#[derive(Debug, Default, Clone, Copy)]
struct Gpu {
    mem_gb: u32,
    cores: u32,
}

#[derive(Debug, Default, Clone, Copy)]
struct Job {
    start: u32,
    end: u32,
    mem_gb: u32,
    cores: u32,
    profit: u64,
}

impl Gpu {
    /// A job fits when the GPU has at least its memory and at least its cores.
    fn fits(&self, job: &Job) -> bool {
        (0..=self.mem_gb).contains(&job.mem_gb) && (0..=self.cores).contains(&job.cores)
    }
}

/// The best profit from work that runs on one GPU.
///
/// Every job it picks runs on the same GPU. That is the right model when a workload
/// is pinned to one device. Spreading the jobs over several GPUs is a different
/// problem, and the chapter measures what it is worth on the sample data.
fn max_profit(gpus: &[Gpu], mut jobs: Vec<Job>) -> u64 {
    jobs.sort_unstable_by_key(|job| job.end);

    // prev[i] = how many jobs finish by the time job `i` starts. The end times
    // are sorted, so each count is the length of a prefix, found in one search.
    let prev: Vec<usize> = jobs
        .iter()
        .map(|job| jobs.partition_point(|earlier| earlier.end <= job.start))
        .collect();

    // dp[i] = best profit using only the first `i` jobs. Reused for every GPU.
    let mut dp = vec![0; jobs.len() + 1];

    let pick_jobs_dp = |gpu: &Gpu| {
        for index in 0..jobs.len() {
            let job = &jobs[index];
            dp[index + 1] = if gpu.fits(job) {
                dp[index].max(dp[prev[index]] + job.profit)
            } else {
                dp[index]
            };
        }
        dp[jobs.len()]
    };

    gpus.iter()
        .map(pick_jobs_dp)
        .max()
        .unwrap_or(0)
}

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

    fn large() -> Gpu {
        Gpu {
            mem_gb: 80,
            cores: 108,
        }
    }

    fn small() -> Gpu {
        Gpu {
            mem_gb: 16,
            cores: 40,
        }
    }

    fn sample_jobs() -> Vec<Job> {
        vec![
            Job {
                start: 1,
                end: 3,
                mem_gb: 12,
                cores: 20,
                profit: 50,
            },
            Job {
                start: 2,
                end: 4,
                mem_gb: 8,
                cores: 10,
                profit: 10,
            },
            Job {
                start: 3,
                end: 5,
                mem_gb: 40,
                cores: 60,
                profit: 40,
            },
            Job {
                start: 3,
                end: 6,
                mem_gb: 60,
                cores: 90,
                profit: 70,
            },
        ]
    }

    #[test]
    fn the_large_gpu_runs_the_best_pair() {
        assert_eq!(max_profit(&[large()], sample_jobs()), 120);
    }

    #[test]
    fn the_small_gpu_skips_what_does_not_fit() {
        assert_eq!(max_profit(&[small()], sample_jobs()), 50);
    }

    #[test]
    fn the_best_gpu_wins() {
        assert_eq!(max_profit(&[large(), small()], sample_jobs()), 120);
    }

    #[test]
    fn no_gpu_or_no_job_earns_nothing() {
        assert_eq!(max_profit(&[], sample_jobs()), 0);
        assert_eq!(max_profit(&[large()], Vec::new()), 0);
    }

    #[test]
    fn cores_alone_can_disqualify_a_job() {
        let jobs = vec![Job {
            start: 0,
            end: 1,
            mem_gb: 1,
            cores: 200,
            profit: 9,
        }];
        assert_eq!(max_profit(&[large()], jobs), 0);
    }
}

fn main() {
    let gpus = vec![
        Gpu {
            mem_gb: 80,
            cores: 108,
        },
        Gpu {
            mem_gb: 16,
            cores: 40,
        },
    ];

    let jobs = vec![
        Job {
            start: 1,
            end: 3,
            mem_gb: 12,
            cores: 20,
            profit: 50,
        },
        Job {
            start: 2,
            end: 4,
            mem_gb: 8,
            cores: 10,
            profit: 10,
        },
        Job {
            start: 3,
            end: 5,
            mem_gb: 40,
            cores: 60,
            profit: 40,
        },
        Job {
            start: 3,
            end: 6,
            mem_gb: 60,
            cores: 90,
            profit: 70,
        },
    ];

    println!("{}", max_profit(&gpus, jobs)); // 120
}

max_profit builds prev once and then reuses a single dp vector for each GPU. The closure pick_jobs_dp fills the table for one GPU and returns its last entry. gpus.iter().map(pick_jobs_dp) runs that closure for every GPU, and .max() keeps the best result.

Reusing dp is safe. The loop writes dp[i + 1] from dp[i] and dp[prev[i]]. Both indexes are at most i, so it reads values this pass has already written. Every pass overwrites all of dp except dp[0], which stays 0.

Animation 6.3 opens with the jobs out of order. It lifts them into end order, then shows each job’s arithmetic in a callout beside the table.

6.5.3 Two tables

gpu 0 has enough of both for every job, so its table is the one from section 6.4.

gpu 1 fails the fit test for C and D, so both are skipped and the table stops at 50.

The answer is max(120, 50) = 120.

$ cargo run --bin gpu_job_schedule
120

Sorting costs O(n log n), and each job finds its compatible prefix with one binary search. Each GPU then fills its table in O(n), and the same dp is reused, so memory is O(n).

6.5.4 What one GPU at a time costs

max returns one GPU’s schedule. The other GPU runs nothing in that answer, even when it has room.

The two schedules cannot be added, because they overlap. The best schedule for gpu 1 is A alone, which earns 50. That A is already part of the 120 on gpu 0, so adding the two totals counts A twice.

Sharing the jobs out does better. Put A and D on gpu 0, and B on gpu 1. Neither GPU runs two overlapping jobs, and the total is 120 + 10 = 130.

Finding that split is a different problem. It has to decide which GPU runs each job. A table per GPU cannot express that choice, because the GPUs are not independent. With many jobs and many GPUs the search grows quickly, and production schedulers use heuristics, bin packing, or an integer program instead.

Chapter 7 begins Part 3, on modeling data. You will build types that can only hold valid values, using structs, enums, and error types.

Exercises

1. Change coin_change to also return the coins it used. Store the last coin chosen for each amount, then follow those choices back from amount.
2. Write the O(n²) version of the longest increasing subsequence described in section 6.3, and check that it agrees with lis_len on random lists.
3. Generate all subsets without recursion. Count a number mask from 0 to 2ⁿ − 1, and include element i when bit i of mask is set.
4. Extend max_profit to return which jobs it chose, not only the total.
5. Change max_profit so the jobs may be split across the GPUs. Work out the best total for the two GPUs and four jobs in section 6.5 by hand. Then explain why one table per GPU cannot find it.

Types that refuse bad input

This chapter begins Part 3, on modeling data. So far your programs have used the types Rust provides: numbers, strings, vectors, and maps. In this chapter you design your own types, so that invalid values cannot be represented at all.

The examples come from a small command-line tool that manages jobs on a remote computer. The jobs are called workloads. Each workload asks for a number of GPUs, which must be between 1 and 64. A GPU is a graphics processor, and servers also use GPUs for general computation. A workload moves through states such as pending, running, and terminated. The tool reads commands typed by a user, such as create triton 4, which asks for a workload named triton with 4 GPUs. That is all you need to know about the tool.

Here is the problem this chapter solves. A GPU count arrives as text typed by a user. The program must reject 0, 99, and many, and it must do so before the count reaches the code that uses it. If each function checked the count itself, one forgotten check would let a bad value through. Instead, the program checks the count once, where the text enters, and stores the result in a type that can only hold valid counts. Every function that receives that type can rely on it without checking again.

The chapter builds this in order:

1. Section 7.1 explains traits, which the rest of the chapter implements.
2. Section 7.2 builds the GPU count type.
3. Section 7.3 gives it an error type.
4. Section 7.4 adds the standard conversions.
5. Section 7.5 builds an enum for commands and a parser for them.
6. Section 7.6 models the workload’s states and the moves between them.
7. Section 7.7 models the errors a server can return.

7.1 Traits

A trait is a set of methods that a type promises to provide. The standard library defines many traits. For example, the Display trait has one method, fmt, which writes a value as text for a person to read. println!("{}", x) works for any x whose type implements Display.

You implement a trait for your type with an impl block that names the trait:

impl fmt::Display for GpuCountError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "...")
    }
}

Some traits are so regular that the compiler can write them for you. #[derive(Debug, Clone, PartialEq)] placed above a struct asks the compiler to generate three traits. Debug prints with {:?}, Clone copies with .clone(), and PartialEq compares with ==. The derived versions work field by field.

Table 7.1 lists the traits this chapter uses.

7.2 A GPU count that is always valid

A newtype is a struct with one field, used to give a plain value a type of its own. Here the plain value is a u32, and the new type is GpuCount.

The trick is privacy. Fields in Rust are private by default. Code outside the module where the struct is defined cannot read or write them, and cannot build the struct with GpuCount(0). The only way to get a GpuCount is through the functions the module offers. If those functions check the value, every GpuCount in the program is valid. Figure 7.1 shows the design.

The module starts with a comment that lists its ideas:

Listing 7.1 The module comment (lines 1 to 12). src/problems/adt_idioms.rs

//! Small algebraic-data-type idioms.
//!
//! These patterns are short and cannot represent invalid states.
//!
//! - A newtype gives a primitive a name and a single validating constructor, so
//!   an out-of-range value cannot exist.
//! - An enum with data models a closed set of alternatives, and `match` forces
//!   every alternative to be handled.
//! - Typed errors carry the reason instead of a string, so the caller can react.
//! - `TryFrom` puts the validation on the type boundary, where it belongs.
//! - An iterator chain states the intent in one pass and removes index
//!   bookkeeping.

Here is the type:

Listing 7.2 GpuCount (lines 14 to 36).

use std::fmt;

/// A GPU count that is validated at construction.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct GpuCount(u32);

impl GpuCount {
    pub const MIN: u32 = 1;
    pub const MAX: u32 = 64;

    /// Validate a raw count.
    pub fn new(value: u32) -> Result<Self, GpuCountError> {
        if (Self::MIN..=Self::MAX).contains(&value) {
            Ok(Self(value))
        } else {
            Err(GpuCountError(value))
        }
    }

    pub fn get(self) -> u32 {
        self.0
    }
}

• pub struct GpuCount(u32); is a tuple struct: a struct whose field has no name, only a position. The struct is public, but its field is not.
• pub const MIN: u32 = 1; and MAX are associated constants, constants that belong to the type. You refer to them as GpuCount::MIN, or Self::MIN inside the impl.
• new is the gate. (Self::MIN..=Self::MAX) is the range 1 to 64, including both ends, and .contains(&value) checks the value. If it is in range, new returns Ok(Self(value)). If not, it returns Err(GpuCountError(value)), an error that carries the rejected value. Section 7.3 shows that type.
• get returns the number inside. It takes self by value, which is fine because GpuCount is Copy.

The long #[derive(...)] line gives GpuCount the same abilities as the u32 inside it. You can print it, copy it, compare it, sort it, and use it as a map key.

7.3 An error that says what went wrong

When new rejects a value, it returns a GpuCountError. Here is that type:

Listing 7.3 The error type (lines 38 to 54).

/// Why a raw GPU count was rejected.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GpuCountError(pub u32);

impl fmt::Display for GpuCountError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            formatter,
            "gpu count {} is outside {}..={}",
            self.0,
            GpuCount::MIN,
            GpuCount::MAX
        )
    }
}

impl std::error::Error for GpuCountError {}

GpuCountError(pub u32) keeps the rejected value. Its field is pub, so a caller can read which value was rejected.

The Display implementation writes the message a user sees. write! works like format!, but writes into the formatter. The message includes the value and the allowed range: gpu count 0 is outside 1..=64.

impl std::error::Error for GpuCountError {} is empty. The Error trait’s methods all have defaults, and it requires Debug and Display, which the type already has. Implementing it lets this error work with other error-handling code, such as Box<dyn std::error::Error>, which you will see in section 7.5.

7.4 Converting with From and TryFrom

The standard library has two traits for converting a value of one type into another:

• From<A> for B is for conversions that always succeed. Implementing it gives you B::from(a), and also a.into() wherever a B is expected.
• TryFrom<A> for B is for conversions that can fail. Its try_from returns a Result. Implementing it gives you B::try_from(a) and a.try_into().

Listing 7.4 The two conversions (lines 56 to 68).

impl TryFrom<u32> for GpuCount {
    type Error = GpuCountError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

impl From<GpuCount> for u32 {
    fn from(count: GpuCount) -> u32 {
        count.0
    }
}

Going from u32 to GpuCount can fail, so it is TryFrom. Its body calls new, so the check still lives in one place. type Error = GpuCountError; names the error type this conversion returns.

Going from GpuCount back to u32 cannot fail, so it is From. The body returns the field, count.0.

7.5 Commands: an enum that carries data

7.5.1 Why an enum

The tool accepts four commands. list takes no arguments. get and delete each take an ID. create takes a name and a GPU count. A first design might put all the possible fields in one struct:

struct Command {
    verb: String,
    id: Option<String>,        // only for get and delete
    name: Option<String>,      // only for create
    gpus: Option<u32>,         // only for create
}

This struct can hold a get without an ID, or a list with a GPU count. Every function that receives it has to check which fields make sense for the verb.

An enum whose variants each carry their own data cannot hold those combinations:

Listing 7.5 The command enum (lines 70 to 77).

/// A closed set of commands, each carrying exactly the data it needs.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Command {
    List,
    Get { id: String },
    Create { name: String, gpus: GpuCount },
    Delete { id: String },
}

A Create always has a name and a valid GpuCount, because Rust will not build one without them. A List has no fields, because it needs none.

In memory, every Command takes the same space, enough for its largest variant, as figure 7.2 shows.

7.5.2 The parser’s errors and helper

Before the parser, here is what it returns when a line is wrong. Each way a line can be malformed gets its own error variant, so the caller learns exactly what failed.

Listing 7.6 CommandError and argument (lines 119 to 148).

/// A typed parse failure, so callers can distinguish the cases.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CommandError {
    Empty,
    UnknownVerb(String),
    MissingArgument(&'static str),
    InvalidGpuCount(String),
}

impl fmt::Display for CommandError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => write!(formatter, "empty command"),
            Self::UnknownVerb(verb) => write!(formatter, "unknown verb {verb:?}"),
            Self::MissingArgument(name) => write!(formatter, "missing argument: {name}"),
            Self::InvalidGpuCount(raw) => write!(formatter, "invalid gpu count: {raw:?}"),
        }
    }
}

impl std::error::Error for CommandError {}

fn argument<'a>(
    parts: &mut impl Iterator<Item = &'a str>,
    name: &'static str,
) -> Result<&'a str, CommandError> {
    parts
        .next()
        .ok_or(CommandError::MissingArgument(name))
}

CommandError lists every way parsing can fail, and its Display writes a message for each. Because the errors are enum variants, a caller can match on them and react differently to each. A CLI could print usage help for MissingArgument and the allowed range for InvalidGpuCount. With a plain String error, the caller would have to read the message text to tell the cases apart.

argument takes the next word from the iterator, or fails with the argument’s name. Look at its first parameter, &mut impl Iterator<Item = &'a str>. It borrows the caller’s iterator mutably, so that each call consumes one more word. The lifetime 'a, which you met in chapter 4, says the returned &str points into the original line. So no text is copied until parse decides to keep it with to_string().

7.5.3 Parsing a line of text

Parsing turns one line of text into a Command, or into an error that says what was wrong with the line.

Listing 7.7 Command::parse and verb (lines 79 to 117).

impl Command {
    /// Parse one command line.
    pub fn parse(line: &str) -> Result<Self, CommandError> {
        let mut parts = line.split_whitespace();
        let verb = parts
            .next()
            .ok_or(CommandError::Empty)?;

        match verb {
            "list" => Ok(Self::List),
            "get" => Ok(Self::Get {
                id: argument(&mut parts, "id")?.to_string(),
            }),
            "delete" => Ok(Self::Delete {
                id: argument(&mut parts, "id")?.to_string(),
            }),
            "create" => {
                let name = argument(&mut parts, "name")?.to_string();
                let raw = argument(&mut parts, "gpu count")?;
                let value: u32 = raw
                    .parse()
                    .map_err(|_| CommandError::InvalidGpuCount(raw.to_string()))?;
                let gpus = GpuCount::new(value)
                    .map_err(|_| CommandError::InvalidGpuCount(raw.to_string()))?;
                Ok(Self::Create { name, gpus })
            }
            other => Err(CommandError::UnknownVerb(other.to_string())),
        }
    }

    pub fn verb(&self) -> &'static str {
        match self {
            Self::List => "list",
            Self::Get { .. } => "get",
            Self::Create { .. } => "create",
            Self::Delete { .. } => "delete",
        }
    }
}

parse returns Result<Self, CommandError>: a command, or the reason the line could not be parsed. Trace Command::parse("create triton 4") step by step:

Now try some bad inputs. An empty line fails at step 2, because there is no first word. ok_or turns the None into Err(CommandError::Empty), and ? returns it. The line create triton many fails at step 6, because "many" is not a number. The line create triton 0 passes step 6 and fails at step 7.

Animation 7.1 runs the good line and the three bad ones through the stages of the table.

Steps 6 and 7 can fail for different reasons, but both failures are reported the same way. .map_err(|_| CommandError::InvalidGpuCount(raw.to_string())) replaces whatever error came back with InvalidGpuCount, carrying the text the user typed. The user then sees their own input in the message.

verb goes the other way, from a command to its name. The patterns Self::Get { .. } match a variant and ignore its fields.

7.5.4 Adding up without an index

The file has one more small function:

Listing 7.8 summarize (lines 150 to 157).

/// Count and sum in one pass, without managing an index.
pub fn summarize(values: &[i32]) -> (usize, i64) {
    values
        .iter()
        .fold((0usize, 0i64), |(count, sum), value| {
            (count + 1, sum + i64::from(*value))
        })
}

fold walks the slice once and carries a value along. Here the value is a pair, (count, sum), starting at (0, 0). For each element, the closure returns the new pair. i64::from(*value) widens each i32 to i64. That conversion is a From, so it can never lose information.

7.5.5 The complete file

Listing 7.9 The complete file, with its tests. src/problems/adt_idioms.rs

//! Small algebraic-data-type idioms.
//!
//! These patterns are short and cannot represent invalid states.
//!
//! - A newtype gives a primitive a name and a single validating constructor, so
//!   an out-of-range value cannot exist.
//! - An enum with data models a closed set of alternatives, and `match` forces
//!   every alternative to be handled.
//! - Typed errors carry the reason instead of a string, so the caller can react.
//! - `TryFrom` puts the validation on the type boundary, where it belongs.
//! - An iterator chain states the intent in one pass and removes index
//!   bookkeeping.

use std::fmt;

/// A GPU count that is validated at construction.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct GpuCount(u32);

impl GpuCount {
    pub const MIN: u32 = 1;
    pub const MAX: u32 = 64;

    /// Validate a raw count.
    pub fn new(value: u32) -> Result<Self, GpuCountError> {
        if (Self::MIN..=Self::MAX).contains(&value) {
            Ok(Self(value))
        } else {
            Err(GpuCountError(value))
        }
    }

    pub fn get(self) -> u32 {
        self.0
    }
}

/// Why a raw GPU count was rejected.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct GpuCountError(pub u32);

impl fmt::Display for GpuCountError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(
            formatter,
            "gpu count {} is outside {}..={}",
            self.0,
            GpuCount::MIN,
            GpuCount::MAX
        )
    }
}

impl std::error::Error for GpuCountError {}

impl TryFrom<u32> for GpuCount {
    type Error = GpuCountError;

    fn try_from(value: u32) -> Result<Self, Self::Error> {
        Self::new(value)
    }
}

impl From<GpuCount> for u32 {
    fn from(count: GpuCount) -> u32 {
        count.0
    }
}

/// A closed set of commands, each carrying exactly the data it needs.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Command {
    List,
    Get { id: String },
    Create { name: String, gpus: GpuCount },
    Delete { id: String },
}

impl Command {
    /// Parse one command line.
    pub fn parse(line: &str) -> Result<Self, CommandError> {
        let mut parts = line.split_whitespace();
        let verb = parts
            .next()
            .ok_or(CommandError::Empty)?;

        match verb {
            "list" => Ok(Self::List),
            "get" => Ok(Self::Get {
                id: argument(&mut parts, "id")?.to_string(),
            }),
            "delete" => Ok(Self::Delete {
                id: argument(&mut parts, "id")?.to_string(),
            }),
            "create" => {
                let name = argument(&mut parts, "name")?.to_string();
                let raw = argument(&mut parts, "gpu count")?;
                let value: u32 = raw
                    .parse()
                    .map_err(|_| CommandError::InvalidGpuCount(raw.to_string()))?;
                let gpus = GpuCount::new(value)
                    .map_err(|_| CommandError::InvalidGpuCount(raw.to_string()))?;
                Ok(Self::Create { name, gpus })
            }
            other => Err(CommandError::UnknownVerb(other.to_string())),
        }
    }

    pub fn verb(&self) -> &'static str {
        match self {
            Self::List => "list",
            Self::Get { .. } => "get",
            Self::Create { .. } => "create",
            Self::Delete { .. } => "delete",
        }
    }
}

/// A typed parse failure, so callers can distinguish the cases.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CommandError {
    Empty,
    UnknownVerb(String),
    MissingArgument(&'static str),
    InvalidGpuCount(String),
}

impl fmt::Display for CommandError {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        match self {
            Self::Empty => write!(formatter, "empty command"),
            Self::UnknownVerb(verb) => write!(formatter, "unknown verb {verb:?}"),
            Self::MissingArgument(name) => write!(formatter, "missing argument: {name}"),
            Self::InvalidGpuCount(raw) => write!(formatter, "invalid gpu count: {raw:?}"),
        }
    }
}

impl std::error::Error for CommandError {}

fn argument<'a>(
    parts: &mut impl Iterator<Item = &'a str>,
    name: &'static str,
) -> Result<&'a str, CommandError> {
    parts
        .next()
        .ok_or(CommandError::MissingArgument(name))
}

/// Count and sum in one pass, without managing an index.
pub fn summarize(values: &[i32]) -> (usize, i64) {
    values
        .iter()
        .fold((0usize, 0i64), |(count, sum), value| {
            (count + 1, sum + i64::from(*value))
        })
}

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

    #[test]
    fn parses_each_command_variant() {
        assert_eq!(Command::parse("list"), Ok(Command::List));
        assert_eq!(
            Command::parse("get wl-7"),
            Ok(Command::Get { id: "wl-7".into() })
        );
        assert_eq!(
            Command::parse("create triton 4"),
            Ok(Command::Create {
                name: "triton".into(),
                gpus: GpuCount::new(4).expect("valid")
            })
        );
        assert_eq!(
            Command::parse("delete wl-7"),
            Ok(Command::Delete { id: "wl-7".into() })
        );
    }

    #[test]
    fn rejects_bad_input_with_typed_errors() {
        assert_eq!(Command::parse(""), Err(CommandError::Empty));
        assert_eq!(
            Command::parse("frobnicate"),
            Err(CommandError::UnknownVerb("frobnicate".into()))
        );
        assert_eq!(
            Command::parse("get"),
            Err(CommandError::MissingArgument("id"))
        );
        assert_eq!(
            Command::parse("create triton 0"),
            Err(CommandError::InvalidGpuCount("0".into()))
        );
        assert_eq!(
            Command::parse("create triton many"),
            Err(CommandError::InvalidGpuCount("many".into()))
        );
    }

    #[test]
    fn newtype_rejects_out_of_range_values() {
        assert!(GpuCount::new(1).is_ok());
        assert!(GpuCount::new(64).is_ok());
        assert!(GpuCount::new(0).is_err());
        assert!(GpuCount::new(65).is_err());
        assert_eq!(u32::from(GpuCount::try_from(8).expect("valid")), 8);
        assert!(GpuCount::try_from(0).is_err());
    }

    #[test]
    fn summarize_reports_count_and_sum() {
        assert_eq!(summarize(&[]), (0, 0));
        assert_eq!(summarize(&[1, 2, 3]), (3, 6));
        assert_eq!(summarize(&[-5, 5]), (2, 0));
    }

    #[test]
    fn errors_render_a_reason() {
        assert_eq!(
            Command::parse("create triton 0")
                .unwrap_err()
                .to_string(),
            "invalid gpu count: \"0\""
        );
        assert!(
            GpuCount::new(99)
                .unwrap_err()
                .to_string()
                .contains("outside")
        );
    }
}

Read the tests as a description of the behavior. parses_each_command_variant shows one valid line per variant. rejects_bad_input_with_typed_errors shows each failure, and compares the errors with assert_eq!. That comparison works because CommandError derives PartialEq. newtype_rejects_out_of_range_values tests both edges of the range, 1 and 64, and one step past each.

The tests run in parallel, so their order in the output can change from run to run:

$ cargo test --lib adt_idioms
running 5 tests
test problems::adt_idioms::tests::newtype_rejects_out_of_range_values ... ok
test problems::adt_idioms::tests::summarize_reports_count_and_sum ... ok
test problems::adt_idioms::tests::rejects_bad_input_with_typed_errors ... ok
test problems::adt_idioms::tests::parses_each_command_variant ... ok
test problems::adt_idioms::tests::errors_render_a_reason ... ok

test result: ok. 5 passed; 0 failed

The command enum describes what a user asks for. The next section uses an enum to describe something that changes over time.

7.6 The states of a workload

A workload is accepted (Pending), gets machines assigned (Provisioning), runs (Running), is shut down (Terminating), and ends (Terminated). Any of the active states can fail, and a failed workload can be tried again. A description like this, a set of states and the allowed moves between them, is called a state machine. Figure 7.3 draws it.

Listing 7.10 The states (lines 1 to 18). src/problems/state_machine.rs

//! Algebraic data types / enum state machines.
//!
//! Cloud SDKs model workloads as finite state machines. Rust `enum` is
//! perfect for this: invalid states are unrepresentable and transitions are
//! explicit `match` arms, not nested `if` chains.

use std::time::Duration;

/// Lifecycle of a GPU cloud workload exposed through an SDK/API.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorkloadState {
    Pending,
    Provisioning,
    Running,
    Terminating,
    Terminated,
    Failed,
}

Each state is a variant with no data. Such an enum is stored as a single byte, and it derives Copy, so you pass states around by value.

Listing 7.11 The allowed moves (lines 20 to 56).

impl WorkloadState {
    /// Returns an error string for impossible transitions, or `Ok(())`.
    pub fn can_transition_to(self, next: Self) -> Result<(), String> {
        match (self, next) {
            // Forward lifecycle.
            (Self::Pending, Self::Provisioning)
            | (Self::Pending, Self::Failed)
            | (Self::Provisioning, Self::Running)
            | (Self::Provisioning, Self::Failed)
            | (Self::Running, Self::Terminating)
            | (Self::Running, Self::Failed)
            | (Self::Terminating, Self::Terminated)
            | (Self::Terminating, Self::Failed) => Ok(()),

            // Retry loops allowed from failed states.
            (Self::Failed, Self::Pending) | (Self::Failed, Self::Provisioning) => Ok(()),

            // Everything else is invalid.
            _ => Err(format!("cannot transition from {self:?} to {next:?}")),
        }
    }

    pub fn is_terminal(self) -> bool {
        matches!(self, Self::Terminated | Self::Failed)
    }

    pub fn summary(self) -> &'static str {
        match self {
            Self::Pending => "workload accepted, waiting for scheduler",
            Self::Provisioning => "GPU resources being allocated",
            Self::Running => "workload is running",
            Self::Terminating => "cleanup in progress",
            Self::Terminated => "workload stopped and billing ended",
            Self::Failed => "workload failed; inspect logs",
        }
    }
}

can_transition_to checks one move, from self to next. It matches on the pair (self, next), so each pattern is one arrow in figure 7.3. Patterns joined with | share one arm: this is an or-pattern. The first arm lists the forward moves and the failure moves. The second lists the retries. The last arm, _, matches every other pair and returns an error.

That last arm decides what happens to moves nobody listed. With it, any move not written down is rejected. If someone adds a new state later, every move into or out of it is rejected until they list it. That is the safe default for a state machine.

is_terminal uses the matches! macro, which returns true when a value matches a pattern. Failed counts as terminal even though it can retry, because it holds no machines. summary returns a fixed message for each state. Its return type &'static str means the text lives for the whole program, because it is written into the program itself.

7.7 Errors from a server

The same file models the errors a server can send back. Here, different errors carry different information.

Listing 7.12 ApiError and its methods (lines 58 to 91).

/// API error modeled as an enum with associated data.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApiError {
    InvalidRequest(String),
    Unauthorized,
    RateLimited { retry_after: Duration },
    NotFound { resource_id: String },
    Server { status: u16, message: String },
}

impl ApiError {
    pub fn is_retryable(&self) -> bool {
        matches!(
            self,
            Self::RateLimited { .. }
                | Self::Server {
                    status: 500..=599,
                    ..
                }
        )
    }

    pub fn user_message(&self) -> String {
        match self {
            Self::InvalidRequest(msg) => format!("invalid request: {msg}"),
            Self::Unauthorized => "authentication required or token expired".to_string(),
            Self::RateLimited { retry_after } => {
                format!("rate limited, retry in {}ms", retry_after.as_millis())
            }
            Self::NotFound { resource_id } => format!("resource not found: {resource_id}"),
            Self::Server { status, message } => format!("server error {status}: {message}"),
        }
    }
}

A rate-limit error says how long to wait before trying again. A not-found error says which resource. A server error carries the HTTP status code and a message.

is_retryable answers a question every client asks after a failure: could trying again help? A rate limit will pass, and a server error in the 500s may be temporary, so both are retryable. A missing resource will still be missing. The whole rule is one pattern:

Self::RateLimited { .. } | Self::Server { status: 500..=599, .. }

status: 500..=599 inside the struct pattern matches any status from 500 to 599. .. ignores the other fields. Chapter 19 builds a retry loop around this method.

user_message turns each error into text for a person. retry_after.as_millis() converts the waiting time to milliseconds for the message.

Listing 7.13 A small parser (lines 93 to 101).

/// Typical SDK helper: never expose nested `if let` soup to callers.
pub fn parse_gpu_count(raw: &str) -> Result<u32, ApiError> {
    match raw.trim() {
        "" => Err(ApiError::InvalidRequest("gpuCount is empty".into())),
        parsed => parsed.parse::<u32>().map_err(|_| {
            ApiError::InvalidRequest(format!("gpuCount must be a number, got {raw:?}"))
        }),
    }
}

parse_gpu_count is a shorter version of the gate from section 7.2. It trims the text, handles the empty case with its own message, and converts the standard library’s parse error into ApiError::InvalidRequest. {raw:?} prints the text with quotes, so an empty or odd input is visible in the message.

Listing 7.14 The complete file, with its tests. src/problems/state_machine.rs

//! Algebraic data types / enum state machines.
//!
//! Cloud SDKs model workloads as finite state machines. Rust `enum` is
//! perfect for this: invalid states are unrepresentable and transitions are
//! explicit `match` arms, not nested `if` chains.

use std::time::Duration;

/// Lifecycle of a GPU cloud workload exposed through an SDK/API.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum WorkloadState {
    Pending,
    Provisioning,
    Running,
    Terminating,
    Terminated,
    Failed,
}

impl WorkloadState {
    /// Returns an error string for impossible transitions, or `Ok(())`.
    pub fn can_transition_to(self, next: Self) -> Result<(), String> {
        match (self, next) {
            // Forward lifecycle.
            (Self::Pending, Self::Provisioning)
            | (Self::Pending, Self::Failed)
            | (Self::Provisioning, Self::Running)
            | (Self::Provisioning, Self::Failed)
            | (Self::Running, Self::Terminating)
            | (Self::Running, Self::Failed)
            | (Self::Terminating, Self::Terminated)
            | (Self::Terminating, Self::Failed) => Ok(()),

            // Retry loops allowed from failed states.
            (Self::Failed, Self::Pending) | (Self::Failed, Self::Provisioning) => Ok(()),

            // Everything else is invalid.
            _ => Err(format!("cannot transition from {self:?} to {next:?}")),
        }
    }

    pub fn is_terminal(self) -> bool {
        matches!(self, Self::Terminated | Self::Failed)
    }

    pub fn summary(self) -> &'static str {
        match self {
            Self::Pending => "workload accepted, waiting for scheduler",
            Self::Provisioning => "GPU resources being allocated",
            Self::Running => "workload is running",
            Self::Terminating => "cleanup in progress",
            Self::Terminated => "workload stopped and billing ended",
            Self::Failed => "workload failed; inspect logs",
        }
    }
}

/// API error modeled as an enum with associated data.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ApiError {
    InvalidRequest(String),
    Unauthorized,
    RateLimited { retry_after: Duration },
    NotFound { resource_id: String },
    Server { status: u16, message: String },
}

impl ApiError {
    pub fn is_retryable(&self) -> bool {
        matches!(
            self,
            Self::RateLimited { .. }
                | Self::Server {
                    status: 500..=599,
                    ..
                }
        )
    }

    pub fn user_message(&self) -> String {
        match self {
            Self::InvalidRequest(msg) => format!("invalid request: {msg}"),
            Self::Unauthorized => "authentication required or token expired".to_string(),
            Self::RateLimited { retry_after } => {
                format!("rate limited, retry in {}ms", retry_after.as_millis())
            }
            Self::NotFound { resource_id } => format!("resource not found: {resource_id}"),
            Self::Server { status, message } => format!("server error {status}: {message}"),
        }
    }
}

/// Typical SDK helper: never expose nested `if let` soup to callers.
pub fn parse_gpu_count(raw: &str) -> Result<u32, ApiError> {
    match raw.trim() {
        "" => Err(ApiError::InvalidRequest("gpuCount is empty".into())),
        parsed => parsed.parse::<u32>().map_err(|_| {
            ApiError::InvalidRequest(format!("gpuCount must be a number, got {raw:?}"))
        }),
    }
}

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

    #[test]
    fn state_machine_rejects_invalid_transitions() {
        assert!(
            WorkloadState::Pending
                .can_transition_to(WorkloadState::Provisioning)
                .is_ok()
        );
        assert!(
            WorkloadState::Running
                .can_transition_to(WorkloadState::Running)
                .is_err()
        );
        assert!(
            WorkloadState::Terminated
                .can_transition_to(WorkloadState::Running)
                .is_err()
        );
        assert!(!WorkloadState::Terminating.is_terminal());
        assert!(WorkloadState::Terminated.is_terminal());
    }

    #[test]
    fn api_error_retry_policy() {
        let rate_limited = ApiError::RateLimited {
            retry_after: Duration::from_millis(100),
        };
        let not_found = ApiError::NotFound {
            resource_id: "gpu-123".into(),
        };
        let server = ApiError::Server {
            status: 503,
            message: "maintenance".into(),
        };

        assert!(rate_limited.is_retryable());
        assert!(!not_found.is_retryable());
        assert!(server.is_retryable());
    }

    #[test]
    fn parsing_returns_typed_errors() {
        assert_eq!(parse_gpu_count("4"), Ok(4));
        assert!(parse_gpu_count("").is_err());
        assert!(parse_gpu_count("abc").is_err());
    }
}

The tests check an allowed move and two forbidden ones, the retry rule for three errors, and the parser.

Every value in this chapter had exactly one owner. Chapter 8 covers the pointer types for data that needs several owners, or that must be shared between threads.

Exercises

1. Write a Port newtype for network ports that rejects 0, with a TryFrom<u16> implementation and its own error type.
2. Implement the FromStr trait for Command, so that "list".parse::<Command>() works. Its method can call Command::parse.
3. Add a Suspended state to WorkloadState that can be entered from Running and left back to Running, and add tests for both moves.
4. Give ApiError a Display implementation that uses user_message, then implement std::error::Error for it.

Ownership and the pointer types

In chapter 7 every value had exactly one owner. That is the normal case in Rust, and most code needs nothing more. But some structures cannot be described with one owner per value. A tree node wants to point back to its parent. A counter must be updated by several threads. An expression contains smaller expressions of its own type.

For each of these, the standard library has a pointer type. A pointer type holds the address of a value and adds a rule about who owns it. This chapter covers the main ones, one at a time. For each, I show where its data sits in memory and which problem it solves. The next four chapters, on linked lists, trees, and graphs, use every one of them.

I start by reviewing ownership itself, because each pointer type is a change to its rules.

8.1 Ownership and moves

Every value in Rust has one owner, the variable or structure that holds it. When the owner goes away, at the end of its scope, the value is dropped and its memory is freed.

Assigning a value to another variable moves it: ownership passes to the new variable, and the old one can no longer be used. Figure 8.1 shows a move of a String.

A move copies only the header on the stack, the pointer, length, and capacity. The text on the heap stays where it is. If both a and b were usable, both would try to free the same text when they went out of scope. The compiler prevents that by making a unusable after the move.

Instead of moving a value, you can borrow it with a reference. A shared reference &T lets you read. A mutable reference &mut T lets you change. The borrow rules say you may have either any number of &T or exactly one &mut T, but not both at once. And no reference may outlive its value.

These rules cover most programs. The pointer types in this chapter handle the cases they cannot.

The module for this chapter starts with a table that summarizes them:

Listing 8.1 The module comment and imports (lines 1 to 27). src/problems/smart_pointers.rs

//! Smart pointers and interior mutability.
//!
//! Each pointer type answers a different ownership question, and picking the
//! wrong one shows up as either a compile error or a runtime bug.
//!
//! | Type | Ownership | Mutation | Across threads |
//! |---|---|---|---|
//! | `Box<T>` | single | through `&mut` | if `T: Send` |
//! | `Rc<T>` | shared, non-atomic count | no | no |
//! | `Arc<T>` | shared, atomic count | no | if `T: Send + Sync` |
//! | `RefCell<T>` | single | runtime checked | no |
//! | `Mutex<T>` | single | blocking lock | yes |
//! | `Weak<T>` | non-owning | no | as `Arc` |
//! | `Cow<'a, T>` | borrow or own | no | as the borrow |
//!
//! Two rules cover most decisions. `Rc`/`RefCell` is for graphs and caches inside
//! one thread; `Arc`/`Mutex` is for state shared between threads. `Weak` exists to
//! break reference cycles, because two strong references in a cycle never reach a
//! count of zero and the memory is never freed.

use std::{
    borrow::Cow,
    cell::RefCell,
    rc::{Rc, Weak},
    sync::{Arc, Mutex},
    thread,
};

Do not try to memorize the table yet. Each section below covers one row.

8.2 Box: one owner, on the heap

A Box<T> puts a value of type T on the heap and owns it. The Box itself is one pointer, 8 bytes on a 64-bit machine. When the Box is dropped, it drops the value and frees the heap memory. So a Box behaves like an owned value that happens to live on the heap.

You need a Box most often for a type that contains itself. Consider an arithmetic expression: it is either a number, or the sum of two smaller expressions. Written directly, that type would have no size (figure 8.2).

To lay out a type, the compiler must know its size. An Add(Expr, Expr) contains two Expr values, each of which may be another Add. The size has no end, so the compiler rejects the type. Box<Expr> is always 8 bytes, whatever it points to, so Add(Box<Expr>, Box<Expr>) has a fixed size.

Listing 8.2 An expression tree (lines 29 to 43).

/// A recursive type needs indirection, because `Expr` cannot contain itself by
/// value. `Box` provides the fixed-size indirection.
#[derive(Debug, PartialEq, Eq)]
pub enum Expr {
    Lit(i64),
    Add(Box<Expr>, Box<Expr>),
}

/// Evaluate an expression tree.
pub fn eval(expr: &Expr) -> i64 {
    match expr {
        Expr::Lit(value) => *value,
        Expr::Add(left, right) => eval(left) + eval(right),
    }
}

eval computes the value of an expression. For a number, the value is the number. For a sum, it evaluates both sides and adds them. The call eval(left) passes a &Box<Expr> where the function expects &Expr. Rust converts it automatically, following the box to the value inside. This automatic conversion is called deref coercion.

To build 1 + 2, you write Expr::Add(Box::new(Expr::Lit(1)), Box::new(Expr::Lit(2))). Box::new allocates on the heap and moves the value there.

8.3 Rc: several owners, counted

Sometimes one value really has several owners, and none of them can be picked as the one that frees it. A node in a graph with several incoming edges is an example. For this, Rust has Rc<T>, short for reference counted.

Rc::new(value) puts the value on the heap together with a count of how many Rc handles point to it. Rc::clone(&rc) does not copy the value. It adds 1 to the count and returns another handle to the same value. Dropping a handle subtracts 1. When the count reaches zero, the value is dropped. Figure 8.3 shows two handles.

An Rc hands out only shared references to its value. With several owners, a &mut through one of them would break the rule that a &mut is the only reference. So by itself, a value inside an Rc cannot be changed. The next section adds that ability.

8.4 RefCell: changing a shared value, checked at run time

RefCell<T> holds a value and allows it to be changed through a shared reference. It keeps the borrow rules, but checks them while the program runs instead of at compile time. Figure 8.4 shows what it tracks.

• cell.borrow() returns a guard that acts like &T. Many can exist at once.
• cell.borrow_mut() returns a guard that acts like &mut T. It panics if any other borrow is active.
• When a guard is dropped, its borrow ends.

Rc and RefCell are used together: Rc<RefCell<T>> gives several owners who can each change the value.

Listing 8.3 Two handles to one counter (lines 45 to 55).

/// Shared mutation inside one thread, with `Rc` for aliasing and `RefCell` for
/// the runtime borrow check.
pub fn shared_counter_with_rc_refcell() -> i32 {
    let counter = Rc::new(RefCell::new(0));
    let alias = Rc::clone(&counter);

    *alias.borrow_mut() += 1;
    *counter.borrow_mut() += 10;

    *counter.borrow()
}

Step through it:

1. Rc::new(RefCell::new(0)) creates a counter holding 0, with a strong count of 1.
2. Rc::clone(&counter) makes a second handle, alias. The strong count is now 2. There is still one counter.
3. *alias.borrow_mut() += 1; borrows mutably through alias and adds 1. The guard is dropped at the end of the statement, so the borrow ends there.
4. *counter.borrow_mut() += 10; does the same through the other handle.
5. *counter.borrow() reads 11.

Animation 8.1 runs these steps, with the strong count and the RefCell flag drawn on the heap block.

Each borrow_mut ends before the next starts, so no panic occurs. If you stored the first guard in a variable and then called borrow_mut again while it was still alive, the program would panic.

8.5 Weak: a pointer that does not own

Counting has a weakness. If two values hold Rc handles to each other, each keeps the other’s count above zero. When you drop your own handles, both counts stay at 1, and neither value is ever freed. This is a reference cycle, and it leaks memory (figure 8.5, left).

The fix is a pointer that does not count as an owner. Weak<T> is made from an Rc with Rc::downgrade. It increases only the weak count, which does not keep the value alive. To use the value, you call upgrade(), which returns Some(Rc) if the value still exists and None if it has been dropped.

The usual pattern is that parents own children with Rc, and children point back to their parents with Weak.

Listing 8.4 A tree node with a weak parent pointer (lines 57 to 87).

/// A node whose parent link is weak, so a child does not keep its parent alive.
pub struct TreeNode {
    pub value: i32,
    parent: RefCell<Weak<TreeNode>>,
}

impl TreeNode {
    /// A node with no parent.
    pub fn root(value: i32) -> Rc<Self> {
        Rc::new(Self {
            value,
            parent: RefCell::new(Weak::new()),
        })
    }

    /// A node that points back weakly at `parent`.
    pub fn child_of(parent: &Rc<Self>, value: i32) -> Rc<Self> {
        Rc::new(Self {
            value,
            parent: RefCell::new(Rc::downgrade(parent)),
        })
    }

    /// The parent's value, or `None` once the parent has been dropped.
    pub fn parent_value(&self) -> Option<i32> {
        self.parent
            .borrow()
            .upgrade()
            .map(|parent| parent.value)
    }
}

• parent: RefCell<Weak<TreeNode>> stores the link to the parent. The RefCell allows the link to be changed after the node exists.
• root creates a node with Weak::new(), an empty weak pointer whose upgrade always returns None.
• child_of creates a node whose parent link is Rc::downgrade(parent).
• parent_value borrows the link, calls upgrade(), and reads the parent’s value if the parent still exists. Option::map applies the closure only when there is a value.

The test weak_parent_link_does_not_keep_the_parent_alive in listing 8.7 checks the behavior.

Animation 8.2 follows that test, then shows the cycle that Weak prevents.

The test creates a root and a child, drops the root, and then checks that the child’s parent_value() is None.

8.6 Arc and Mutex: sharing across threads

Arc<T> is Rc<T> with an atomic count. An atomic operation is one the processor completes as a single step. That stays true even when several cores run it on the same memory at the same moment. So Arc handles can be sent to other threads. Chapter 16 explains atomic operations in detail.

Mutex<T> is the thread-safe counterpart of RefCell. lock() returns a guard that gives access to the value. If another thread holds the lock, lock() waits until it is released, instead of panicking.

Listing 8.5 Several threads adding to one total (lines 89 to 110).

/// Shared mutation across threads, with `Arc` for ownership and `Mutex` for
/// exclusive access.
pub fn total_with_arc_mutex(threads: usize, per_thread: usize) -> usize {
    let total = Arc::new(Mutex::new(0usize));
    let mut handles = Vec::with_capacity(threads);

    for _ in 0..threads {
        let total = Arc::clone(&total);
        handles.push(thread::spawn(move || {
            for _ in 0..per_thread {
                let mut guard = total.lock().expect("mutex poisoned");
                *guard += 1;
            }
        }));
    }

    for handle in handles {
        handle.join().expect("worker panicked");
    }

    *total.lock().expect("mutex poisoned")
}

Step through it:

1. Arc::new(Mutex::new(0usize)) creates the shared total.
2. For each thread, Arc::clone(&total) makes a new handle, and thread::spawn(move || ...) moves that handle into the new thread. move means the closure takes ownership of what it uses.
3. Each thread locks the mutex, adds 1, and drops the guard, per_thread times.
4. handle.join() waits for each thread to finish.
5. The last line locks once more and reads the result.

lock() returns a Result, because a thread that panics while holding the lock leaves the mutex marked as poisoned. .expect("mutex poisoned") stops the program with that message in that case. Chapter 16 covers poisoning.

This function locks once for every single increment, so the threads spend most of their time waiting for each other. It is correct but slow. Chapter 16 measures faster ways to count across threads.

8.7 Cow: borrow when you can

Cow<'a, str> holds either a borrowed &'a str or an owned String. Its name stands for “clone on write”. It fits functions that usually return their input unchanged but sometimes need to change it.

Listing 8.6 Uppercase only when needed (lines 112 to 126).

/// Borrow when no change is needed, allocate only when there is one.
///
/// `Cow` is the idiomatic return type for a function that usually passes its
/// input through unchanged.
pub fn normalize(input: &str, uppercase: bool) -> Cow<'_, str> {
    if uppercase
        && input
            .bytes()
            .any(|byte| byte.is_ascii_lowercase())
    {
        Cow::Owned(input.to_uppercase())
    } else {
        Cow::Borrowed(input)
    }
}

normalize checks whether any byte is a lowercase letter. If there is nothing to change, it returns Cow::Borrowed(input), which costs nothing. Only when a change is needed does it allocate a new uppercase String and return Cow::Owned. The caller can use either variant as a &str.

8.8 The complete file

Listing 8.7 The complete file, with its tests. src/problems/smart_pointers.rs

//! Smart pointers and interior mutability.
//!
//! Each pointer type answers a different ownership question, and picking the
//! wrong one shows up as either a compile error or a runtime bug.
//!
//! | Type | Ownership | Mutation | Across threads |
//! |---|---|---|---|
//! | `Box<T>` | single | through `&mut` | if `T: Send` |
//! | `Rc<T>` | shared, non-atomic count | no | no |
//! | `Arc<T>` | shared, atomic count | no | if `T: Send + Sync` |
//! | `RefCell<T>` | single | runtime checked | no |
//! | `Mutex<T>` | single | blocking lock | yes |
//! | `Weak<T>` | non-owning | no | as `Arc` |
//! | `Cow<'a, T>` | borrow or own | no | as the borrow |
//!
//! Two rules cover most decisions. `Rc`/`RefCell` is for graphs and caches inside
//! one thread; `Arc`/`Mutex` is for state shared between threads. `Weak` exists to
//! break reference cycles, because two strong references in a cycle never reach a
//! count of zero and the memory is never freed.

use std::{
    borrow::Cow,
    cell::RefCell,
    rc::{Rc, Weak},
    sync::{Arc, Mutex},
    thread,
};

/// A recursive type needs indirection, because `Expr` cannot contain itself by
/// value. `Box` provides the fixed-size indirection.
#[derive(Debug, PartialEq, Eq)]
pub enum Expr {
    Lit(i64),
    Add(Box<Expr>, Box<Expr>),
}

/// Evaluate an expression tree.
pub fn eval(expr: &Expr) -> i64 {
    match expr {
        Expr::Lit(value) => *value,
        Expr::Add(left, right) => eval(left) + eval(right),
    }
}

/// Shared mutation inside one thread, with `Rc` for aliasing and `RefCell` for
/// the runtime borrow check.
pub fn shared_counter_with_rc_refcell() -> i32 {
    let counter = Rc::new(RefCell::new(0));
    let alias = Rc::clone(&counter);

    *alias.borrow_mut() += 1;
    *counter.borrow_mut() += 10;

    *counter.borrow()
}

/// A node whose parent link is weak, so a child does not keep its parent alive.
pub struct TreeNode {
    pub value: i32,
    parent: RefCell<Weak<TreeNode>>,
}

impl TreeNode {
    /// A node with no parent.
    pub fn root(value: i32) -> Rc<Self> {
        Rc::new(Self {
            value,
            parent: RefCell::new(Weak::new()),
        })
    }

    /// A node that points back weakly at `parent`.
    pub fn child_of(parent: &Rc<Self>, value: i32) -> Rc<Self> {
        Rc::new(Self {
            value,
            parent: RefCell::new(Rc::downgrade(parent)),
        })
    }

    /// The parent's value, or `None` once the parent has been dropped.
    pub fn parent_value(&self) -> Option<i32> {
        self.parent
            .borrow()
            .upgrade()
            .map(|parent| parent.value)
    }
}

/// Shared mutation across threads, with `Arc` for ownership and `Mutex` for
/// exclusive access.
pub fn total_with_arc_mutex(threads: usize, per_thread: usize) -> usize {
    let total = Arc::new(Mutex::new(0usize));
    let mut handles = Vec::with_capacity(threads);

    for _ in 0..threads {
        let total = Arc::clone(&total);
        handles.push(thread::spawn(move || {
            for _ in 0..per_thread {
                let mut guard = total.lock().expect("mutex poisoned");
                *guard += 1;
            }
        }));
    }

    for handle in handles {
        handle.join().expect("worker panicked");
    }

    *total.lock().expect("mutex poisoned")
}

/// Borrow when no change is needed, allocate only when there is one.
///
/// `Cow` is the idiomatic return type for a function that usually passes its
/// input through unchanged.
pub fn normalize(input: &str, uppercase: bool) -> Cow<'_, str> {
    if uppercase
        && input
            .bytes()
            .any(|byte| byte.is_ascii_lowercase())
    {
        Cow::Owned(input.to_uppercase())
    } else {
        Cow::Borrowed(input)
    }
}

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

    #[test]
    fn boxed_expression_evaluates() {
        let expr = Expr::Add(Box::new(Expr::Lit(1)), Box::new(Expr::Lit(2)));
        assert_eq!(eval(&expr), 3);
    }

    #[test]
    fn rc_refcell_shares_mutation_within_a_thread() {
        assert_eq!(shared_counter_with_rc_refcell(), 11);
    }

    #[test]
    fn weak_parent_link_does_not_keep_the_parent_alive() {
        let root = TreeNode::root(1);
        let child = TreeNode::child_of(&root, 2);

        assert_eq!(child.parent_value(), Some(1));
        drop(root);
        assert_eq!(child.parent_value(), None);
    }

    #[test]
    fn arc_mutex_sums_concurrent_updates() {
        assert_eq!(total_with_arc_mutex(8, 250), 2_000);
    }

    #[test]
    fn cow_borrows_and_owns_as_needed() {
        assert!(matches!(normalize("A100", true), Cow::Borrowed(_)));
        assert!(matches!(normalize("a100", true), Cow::Owned(_)));
        assert_eq!(normalize("a100", true), "A100");
        assert_eq!(normalize("a100", false), "a100");
    }
}

The tests check one behavior per pointer type. cow_borrows_and_owns_as_needed uses matches! to check which variant came back, not only the text. That is how a test shows that the unchanged case did not allocate. Run them with cargo test --lib smart_pointers.

Figure 8.6 turns the chapter into three questions you can ask when choosing a pointer type.

Chapter 9 puts these types to work. You will build linked lists with Box and see how dropping a very long one can crash. Then you will build a doubly linked list with Rc, RefCell, and Weak.

Exercises

1. Build the expression (1 + 2) + 3 with Expr and check that eval returns 6.
2. In shared_counter_with_rc_refcell, keep the first borrow_mut guard in a variable and call borrow_mut again. Run it and read the panic message.
3. Build a parent with two children that point back with Weak. Print Rc::strong_count and Rc::weak_count for the parent before and after creating the children.
4. Change total_with_arc_mutex so each thread counts in a local variable and adds its total to the mutex once. Compare the running time for 8 threads and one million increments each.

Linked lists

Chapter 8 introduced the pointer types. This chapter uses them to build the classic linked structure, the linked list. Linked lists are a good first test of ownership. Each operation moves a node from one owner to another, and the compiler checks every move.

The chapter goes from simple to hard. First a singly linked list, where each node points only to the next, and an algorithm that reverses it. Then four ways to write the same list, and a benchmark that compares them. The benchmark finds a size at which the list crashes the program when it is dropped. After explaining and fixing that, the chapter ends with a doubly linked list, where each node also points back to the one before.

9.1 What a linked list is

A linked list stores a sequence of values in separate nodes. Each node holds one value and a pointer to the next node. The list itself holds a pointer to the first node, called the head. The last node’s pointer is empty, which marks the end.

Figure 9.1 compares a linked list with a Vec holding the same three values.

The two structures are good at different things:

A linked list works like a treasure hunt. Each clue says where the next clue is hidden. To read the fifth clue, you must find the first four. To add a clue at the start, you write one new clue that names the old first one, and nothing else moves. A Vec works like a numbered row of lockers. Locker 5 is found in one step. A new locker at the front means renumbering the whole row.

In practice, a Vec is faster for most work. Its values are next to each other in memory, and the processor reads nearby memory quickly; chapter 15 measures that effect. The techniques you learn here for moving nodes between owners carry over to the trees and graphs of chapters 11 and 12.

In Rust, a node owns the next node through a Box, and the “empty” pointer at the end is None. So a node’s next field has type Option<Box<Node>>.

9.2 Moving nodes: take and replace

Every list operation moves a node from one owner to another. Rust has a rule that makes this tricky. You cannot move a value out of a place that you only borrowed. That would leave the place empty, and the owner would later find garbage there.

Two standard functions solve this by putting something valid in the place as they take the value out:

• option.take() returns the value inside an Option and leaves None in its place.
• std::mem::replace(&mut place, new_value) returns the old value and puts new_value in its place.

Figure 9.2 shows take on a node’s next field.

You will see these two calls in almost every listing of this chapter.

9.3 Reversing a list

The problem. Given the list 1 → 2 → 3 → 4, turn it into 4 → 3 → 2 → 1. Change the pointers; do not copy the values.

The idea. Walk the list from the front. Keep two variables: previous, the part already reversed, and current, the part not yet visited. At each step, take the first node of current, point it at previous, and make it the new front of previous. Figure 9.3 shows the state after two steps.

First, the node type and two helpers for building and reading lists:

Listing 9.1 The node and two helpers (lines 1 to 33). src/problems/linked_list.rs

//! Reverse a singly linked list, and remove nodes from it.
//!
//! Uses `Option<Box<ListNode>>` and a `while let` loop to move pointers in a
//! borrow-safe way. Removal walks a cursor: a mutable borrow of one link.

#[derive(Debug, PartialEq, Eq)]
pub struct ListNode {
    pub val: i32,
    pub next: Option<Box<ListNode>>,
}

impl ListNode {
    pub fn from_slice(values: &[i32]) -> Option<Box<ListNode>> {
        let mut head = None;
        for &value in values.iter().rev() {
            head = Some(Box::new(ListNode {
                val: value,
                next: head,
            }));
        }
        head
    }

    pub fn to_vec(head: Option<Box<ListNode>>) -> Vec<i32> {
        let mut result = Vec::new();
        let mut current = head;
        while let Some(node) = current {
            result.push(node.val);
            current = node.next;
        }
        result
    }
}

from_slice builds a list from a slice. It walks the slice backward, putting each value in front of the list built so far. The last value pushed is values[0], so it ends up first. Building from the back means it never needs a pointer to the end of the list.

to_vec reads a list into a Vec. It takes the list by value and consumes it. In while let Some(node) = current, each pass moves one box out of current. current = node.next then moves the rest of the list out of that node before the node is freed.

Animation 9.2 builds [1, 2, 3] with from_slice, reads it back with to_vec, and then shows what the loop does without .rev().

Now the reversal:

Listing 9.2 Reversing the list (lines 35 to 46).

pub fn reverse_list(head: Option<Box<ListNode>>) -> Option<Box<ListNode>> {
    let mut previous = None;
    let mut current = head;

    while let Some(mut node) = current {
        current = node.next.take();
        node.next = previous;
        previous = Some(node);
    }

    previous
}

Each pass through the loop does three moves:

1. current = node.next.take(); takes the rest of the list out of the node, as in figure 9.2.
2. node.next = previous; points the node at the reversed part.
3. previous = Some(node); makes the node the front of the reversed part.

Trace it on 1 → 2 → 3:

At no moment do two variables own the same node, which is why the compiler accepts the code. The function visits each node once, so it is O(n), and it uses O(1) extra memory.

The complete file is listing 9.20 at the end of the chapter. Its tests reverse a four-element list, an empty list, and a one-element list.

9.4 Removing nodes with a cursor

The problem. Remove every node whose value equals target, in one pass. The head may match, and so may several nodes in a row.

The idea. To unlink a node, you change the link that points at it. That link is either head or the next field of the node before. So the loop holds a link, not a node. It is a &mut Option<Box<ListNode>> called the cursor.

Think of the cursor as a finger on one arrow of the chain. If the arrow points at a match, you bend the arrow past that node, and the finger stays where it is. If not, the finger moves to the next arrow.

Listing 9.3 Removing every match (lines 48 to 71). src/problems/linked_list.rs

/// Remove every node whose value is `target`, in one pass.
///
/// `cursor` is a mutable borrow of a link: first `head`, then the `next` of
/// each node that stays. A matching node is unlinked by moving its `next` into
/// the link that pointed at it. The cursor does not move after a removal,
/// because the link it holds now points at a node not yet checked.
pub fn remove_all(mut head: Option<Box<ListNode>>, target: i32) -> Option<Box<ListNode>> {
    let mut cursor = &mut head;
    while cursor.is_some() {
        let node = cursor
            .as_mut()
            .expect("checked by is_some");
        if node.val == target {
            let next = node.next.take();
            *cursor = next;
        } else {
            cursor = &mut cursor
                .as_mut()
                .expect("checked by is_some")
                .next;
        }
    }
    head
}

The loop reads:

1. let mut cursor = &mut head; puts the cursor on the head link. The head is a link like any other, so removing the first node needs no extra code.
2. cursor.as_mut() borrows the node the link points at.
3. On a match, node.next.take() moves the rest of the list out of the node. *cursor = next writes it into the link. Nothing owns the old node any more, so it is freed there.
4. Otherwise, cursor = &mut cursor...next moves the cursor to that node’s next link.

The cursor does not move after a removal. The link now points at the node that slid into place, and that node has not been checked yet. Trace it on 2 → 1 → 2 → 2 → 3 with target 2:

Each node is checked once, so the function is O(n). It uses O(1) extra memory.

Animation 9.3 plays this trace, then three unhappy cases. The target may be absent, every node may match, or the cursor may move after a removal.

The tests check the cases that break removal code. They remove a match at the head and matches in a row. They also try a target that is absent, a list where every node matches, and an empty list.

9.5 A list written as an enum

The first list separated the node type from the Option that marks the end. Another way puts both into one enum: a list is either empty, or a node holding a value and the rest of the list.

Listing 9.4 The list type (lines 1 to 13). src/bin/singly_linked_list.rs

// Singly linked list using an algebraic data type.
//
//    List<T> = Empty
//            | Node { value: T, next: Link<T> }
//
// `Empty` is the end of the list.

type Link<T> = Box<List<T>>;

pub enum List<T> {
    Empty,
    Node { value: T, next: Link<T> },
}

List<T> is generic. The T is a placeholder for the type of the values, so the same code works for a list of numbers or of strings. type Link<T> = Box<List<T>>; gives the boxed rest of the list a short name.

Listing 9.5 Creating, checking, and measuring (lines 16 to 29).

impl<T> List<T> {
    pub fn new() -> Self {
        List::Empty
    }

    pub fn is_empty(&self) -> bool {
        matches!(self, List::Empty)
    }

    pub fn len(&self) -> usize {
        match self {
            List::Empty => 0,
            List::Node { next, .. } => 1 + next.len(),
        }
    }
    // ...
}

len counts the nodes recursively: an empty list has length 0, and a node adds 1 to the length of the rest. Each call waits for the next, so a list of n nodes uses n stack frames. Section 9.7 shows where that ends.

Listing 9.6 Adding and removing at the front (lines 31 to 49).

impl<T> List<T> {
    // ...
    /// O(1)
    pub fn push_front(&mut self, value: T) {
        let old = std::mem::replace(self, List::Empty);
        *self = List::Node {
            value,
            next: Link::new(old),
        };
    }

    /// O(1)
    pub fn pop_front(&mut self) -> Option<T> {
        match std::mem::replace(self, List::Empty) {
            List::Empty => None,
            List::Node { value, next } => {
                *self = *next;
                Some(value)
            }
        }
    }
}

Both methods take &mut self, so they change the list in place. They use std::mem::replace from section 9.2. The method cannot move the old list out of *self and assign a new one later. Between those two steps, *self would be empty. replace(self, List::Empty) puts a temporary Empty in place and hands back the old list in one step.

push_front wraps the old list in a new node with the new value, and writes it back into *self.

pop_front matches on the old list. If it was Empty, there is nothing to pop, and *self is already Empty again. If it was a Node, the method writes the rest of the list back into *self with *self = *next, and returns the value. *next moves the list out of its Box.

Animation 9.4 shows both methods, then the version without replace that the compiler refuses.

The complete program is listing 9.21 at the end of the chapter. Its main pushes three values and pops them back in reverse order, the last one pushed coming out first. A list that adds and removes at the same end behaves as a stack, like the Vec in chapter 3.

$ cargo run --bin singly_linked_list
ok

9.6 Four node layouts, measured

Section 9.3 wrote a node as a struct with an Option<Box<Node>>, and section 9.5 wrote the list as an enum. Which is faster? To answer, the benchmark in this section puts four versions of the same list behind one trait. Then one piece of code can measure them all.

9.6.1 One trait for four lists

The four list types are measured by one benchmark, so they share a trait with the operations the benchmark calls.

Listing 9.7 The trait every list implements. benchmarking_examples/lists/mod.rs

//! Singly linked lists in four variants, so one benchmark loop can cover all of
//! them.
//!
//! The variants differ only in how a node is stored and in how the list frees
//! itself. `boxed` and `enum_node` free a chain of boxes recursively, which
//! overflows the stack past roughly 265,000 nodes. `boxed_drop` and `enum_drop`
//! unlink iteratively and scale.

pub mod boxed;
pub mod boxed_drop;
pub mod enum_drop;
pub mod enum_node;

/// The operations every variant supports, so the benchmark can be written once.
pub trait SinglyList<T>: Sized {
    /// A new, empty list.
    fn new() -> Self;

    /// Adds `value` to the front of the list.
    fn push_front(&mut self, value: T);

    /// Removes and returns the front value, if there is one.
    fn pop_front(&mut self) -> Option<T>;

    /// Whether the list holds nothing.
    fn is_empty(&self) -> bool;

    /// The variant's name, for benchmark output and error messages.
    fn variant() -> &'static str;
}

The trait lists the operations: new, push_front, pop_front, is_empty, and variant, which returns a name for printing. SinglyList<T>: Sized limits the trait to types whose size is known at compile time. The benchmark uses the trait only through generic functions, so the limit costs nothing. The four pub mod lines declare the four versions, each in its own file.

The first two versions are the struct form and the enum form:

Listing 9.8 Option<Box<Node<T>>>: the types, push_front, and pop_front (lines 9 to 38). benchmarking_examples/lists/boxed.rs

struct Node<T> {
    value: T,
    next: Option<Box<Node<T>>>,
}

pub struct LinkedList<T> {
    head: Option<Box<Node<T>>>,
}

impl<T> SinglyList<T> for LinkedList<T> {
    fn new() -> Self {
        Self { head: None }
    }

    fn push_front(&mut self, value: T) {
        self.head = Some(Box::new(Node {
            value,
            // .take() leaves None in its place and extracts the old head
            next: self.head.take(),
        }));
    }

    fn pop_front(&mut self) -> Option<T> {
        self.head.take().map(|node| {
            // Point the list head to the next node in line
            self.head = node.next;
            // Return the unboxed value
            node.value
        })
    }
    // ...
}

Listing 9.9 enum ListNode<T>: the types, push_front, and pop_front (lines 9 to 44). benchmarking_examples/lists/enum_node.rs

enum ListNode<T> {
    Empty,
    Next(T, Box<ListNode<T>>),
}

pub struct LinkedList<T> {
    head: ListNode<T>,
}

impl<T> SinglyList<T> for LinkedList<T> {
    fn new() -> Self {
        Self {
            head: ListNode::Empty,
        }
    }

    fn push_front(&mut self, value: T) {
        // Extract the old head and leave Empty in its place
        let old_head = std::mem::replace(&mut self.head, ListNode::Empty);

        // Wrap the old head inside a Box behind the new value
        self.head = ListNode::Next(value, Box::new(old_head));
    }

    fn pop_front(&mut self) -> Option<T> {
        let old_head = std::mem::replace(&mut self.head, ListNode::Empty);

        match old_head {
            ListNode::Empty => None,
            ListNode::Next(value, next_node) => {
                // Point the list head to the next node in the sequence
                self.head = *next_node;
                Some(value)
            }
        }
    }
    // ...
}

Each file also has is_empty and variant, which are one line each. The two files implement the trait with impl<T> SinglyList<T> for LinkedList<T>. Each uses the tool from section 9.2 that fits its type: take() on the Option in the struct version, and mem::replace on the enum.

9.6.2 What each node costs in memory

Figure 9.4 draws both lists after pushing 10, 20, and 30.

On a 64-bit machine, with u64 values, each node is 16 bytes in both versions: 8 for the value and 8 for the pointer. Option<Box<Node>> is only 8 bytes, because a Box is never null, so Rust uses the null address to mean None. The enum gets the same treatment, using a null Box to mean Empty.

The versions still differ in two ways. The enum list keeps its first node, 16 bytes, inside the list value. So every push moves those 16 bytes into a new box, where the struct version moves one 8-byte pointer. And the enum chain ends with a boxed Empty. Both lists make one allocation per push, but one of the enum’s boxes holds no value.

Animation 9.5 pushes 10, 20, and 30 onto both lists, pops one value, and then pops from two empty lists.

Two small demo programs, list_box.rs and list_enum.rs, push and pop on each version. They import the lists from the crate’s library with use systems_lab::lists::..., so every program shares one compiled copy of the list code. Both are listed at the end of the chapter.

9.7 When dropping a list crashes

Here is a short program built on the struct version:

let mut list = boxed::LinkedList::new();
for value in 0..270_000u64 {
    list.push_front(value);
}
// list goes out of scope here and is dropped

It builds the list without trouble, and then it crashes at the closing brace:

thread 'main' has overflowed its stack
fatal runtime error: stack overflow, aborting

None of the list’s methods is recursive. The recursion is in the code the compiler generates to drop the list. To drop the list, Rust drops head. To drop a Box<Node>, it drops the node, which means dropping its fields, including next, another Box<Node>. That drops the next node, and so on. Each step is a function call nested inside the previous one, so each node adds one stack frame (figure 9.5, left).

Animation 9.6 runs both. Watch the stack on the right: one frame per node for the default drop, and never more than three for the loop.

The main thread’s stack is 8 MiB on most systems. The crash happened between 260,000 and 270,000 nodes, so each level of nesting used about 32 bytes of stack. A thread you start with std::thread::spawn gets a 2 MiB stack by default. On such a thread the limit would be about a quarter as many nodes.

The fix is to write the list’s Drop yourself, as a loop. Drop is a trait. Rust calls its drop method when a value goes out of scope. If you implement it, your code runs before the fields are dropped.

Listing 9.10 The struct version's Drop (lines 46 to 55). benchmarking_examples/lists/boxed_drop.rs

impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        // Walk the chain and unlink each node before it is freed, so no node's
        // drop has to carry the rest of the list on the stack.
        let mut current = self.head.take();
        while let Some(mut node) = current {
            current = node.next.take();
        }
    }
}

The file boxed_drop.rs repeats the types and operations of listing 9.8. Only this Drop implementation is new. Its loop reads:

1. let mut current = self.head.take(); takes the whole chain out of the list.
2. while let Some(mut node) = current moves the first box out of current.
3. current = node.next.take(); moves the rest of the chain out of that node.
4. At the end of the loop body, node goes out of scope and is freed. Its next is already None, so freeing it frees nothing else.

The loop runs in one stack frame, whatever the length of the list.

Listing 9.11 The enum version's Drop (lines 52 to 62). benchmarking_examples/lists/enum_drop.rs

impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        // Take the chain out of the list first, then step it forward one node at
        // a time. Each node has already lost its `next` by the time it is freed,
        // so the drop stays on the heap.
        let mut current = std::mem::replace(&mut self.head, ListNode::Empty);
        while let ListNode::Next(_, next) = current {
            current = *next;
        }
    }
}

The enum version does the same with mem::replace and a while let ListNode::Next(_, next) = current loop. current = *next; moves the rest of the chain out of the box. Assigning to current drops its old value, a Next whose box has already been emptied, so again nothing nests.

A third demo builds a list of five million nodes and drops it:

Listing 9.12 Five million nodes, dropped with a loop. benchmarking_examples/list_drop.rs

//! Demo of the iterative `Drop` in `lists::boxed_drop`.
//!
//! The same program against `lists::boxed` aborts with a stack overflow at this
//! size, because that variant frees its chain recursively.
//!
//! Run with: cargo run --release --bin list_drop

use systems_lab::lists::{SinglyList, boxed_drop::LinkedList};

fn main() {
    const N: u64 = 5_000_000;

    let mut list = LinkedList::new();
    for value in 0..N {
        list.push_front(value);
    }
    println!("built a list of {N} nodes");

    list.pop_front();
    println!("dropping the remaining {} nodes", N - 1);

    drop(list);
    println!("dropped without recursing");
}

9.8 The benchmark

The benchmark program measures all four versions with one generic function. The full program also measures the caches of chapter 13, and is listed there. This is the part that measures the lists.

Listing 9.13 The list benchmark (lines 160 to 236). benchmarking_examples/benchmark.rs

use std::{
    hint::black_box,
    time::{Duration, Instant},
};

use systems_lab::{
    cache::{Cache, arena::LruCache as ArenaCache, rc_list::LruCache as RcCache},
    lists::{SinglyList, boxed, boxed_drop, enum_drop, enum_node},
};

// ---------------------------------------------------------------------------
// Lists: four variants, one loop
// ---------------------------------------------------------------------------

fn list_benchmark(variant: Option<&str>, elements: usize) {
    println!(
        "Singly linked list: push {} values, pop them back in order, then drop a full list",
        with_thousands(elements as u64)
    );
    println!("Best of {LIST_RUNS} runs per variant, allocator warmed up.\n");
    println!(
        "  {:<10} {:>12} {:>13} {:>13}",
        "variant", "elements", "push", "drop"
    );
    println!("  {}", "-".repeat(52));

    match variant {
        Some("box") => run_list::<boxed::LinkedList<u64>>(elements),
        Some("enum") => run_list::<enum_node::LinkedList<u64>>(elements),
        Some("box+drop") => run_list::<boxed_drop::LinkedList<u64>>(elements),
        Some("enum+drop") => run_list::<enum_drop::LinkedList<u64>>(elements),
        _ => {
            run_list::<boxed::LinkedList<u64>>(elements);
            run_list::<enum_node::LinkedList<u64>>(elements);
            run_list::<boxed_drop::LinkedList<u64>>(elements);
            run_list::<enum_drop::LinkedList<u64>>(elements);
        }
    }
}

fn run_list<L: SinglyList<u64>>(elements: usize) {
    // Warm the allocator first: without this the first variant in a process pays
    // for fresh heap pages and looks several times slower than an identical one.
    let mut warm_up = L::new();
    for value in 0..elements as u64 {
        warm_up.push_front(value);
    }
    drop(warm_up);

    let mut best_push = Duration::MAX;
    let mut best_drop = Duration::MAX;

    for _ in 0..LIST_RUNS {
        let mut list = L::new();

        let start = Instant::now();
        for value in 0..elements as u64 {
            list.push_front(value);
        }
        best_push = best_push.min(start.elapsed());

        // Pop every value back and check the order, so a broken list cannot post
        // a fast time.
        let mut expected = elements as u64;
        while let Some(value) = list.pop_front() {
            expected -= 1;
            assert_eq!(value, expected, "{} lost LIFO order", L::variant());
        }
        assert_eq!(expected, 0);
        black_box(expected);

        // Rebuild, then time the drop of a full list. This is where the
        // recursive variants overflow the stack.
        for value in 0..elements as u64 {
            list.push_front(value);
        }
        let start = Instant::now();
        drop(list);
        best_drop = best_drop.min(start.elapsed());
    }

    println!(
        "  {:<10} {:>12} {best_push:>13.2?} {best_drop:>13.2?}",
        L::variant(),
        with_thousands(elements as u64)
    );
}

The whole file is listing 13.16. Chapter 13 adds the cache benchmarks to it, and shows it complete there.

run_list::<L: SinglyList<u64>> is generic over the list type L. The compiler generates a separate copy of the function for each list type. So each list is measured with its own code.

The function follows three rules that apply to any small benchmark:

1. Warm up first. The first time a program allocates a lot of memory, the operating system has to supply fresh pages, which is slow. A warm-up pass pays that cost before timing starts.
2. Run several times and keep the fastest. Other programs can slow a run down but never speed it up. So the fastest run is the closest to the true cost.
3. Check the result before trusting the time. Every run pops all the values and checks their order. A broken list cannot report a fast time.

std::hint::black_box(expected) tells the compiler to treat the value as used, so it cannot delete the loop that computed it.

These results come from a release build on an 8-core aarch64 development board:

  variant        elements          push          drop
  ----------------------------------------------------
  box             200,000        2.40ms        3.23ms
  enum            200,000        3.42ms        3.20ms
  box+drop        200,000        2.32ms        2.91ms
  enum+drop       200,000        3.62ms        2.52ms

  box+drop      5,000,000       58.11ms       72.32ms
  enum+drop     5,000,000       90.98ms       67.51ms

Read the table this way:

• A push costs about 12 nanoseconds for the struct node and about 17 for the enum node. Section 9.6.2 gave two differences that could explain the gap. The benchmark does not measure them separately.
• box and box+drop share the same push code, and their push times agree, 2.40 against 2.32 ms. That agreement is a sign the measurement is stable.
• The loop drop is not much faster than the recursive one. Its purpose is to remove the size limit, not to save time.

You can reproduce the crash and the fix:

cargo run --release --bin benchmark list box 260000   # completes
cargo run --release --bin benchmark list box 270000   # crashes
cargo run --release --bin list_drop                   # five million nodes, no crash

9.9 A doubly linked list

In a doubly linked list, each node points to the next node and also back to the previous one. That lets you add and remove at both ends in O(1), and walk the list in either direction.

In Rust this creates an ownership problem. Every node in the middle is pointed to twice: by the previous node’s next and by the following node’s prev. A Box has exactly one owner, so it cannot express this.

The solution uses the three types from chapter 8. Nodes live in Rc<RefCell<Node>>, so they can have more than one handle and still be changed. The forward links, next, are strong Rc handles, so the list owns its nodes from front to back. The backward links, prev, are Weak handles, so they do not create reference cycles (figure 9.6).

9.9.1 The types

A node of the doubly linked list has a value and two links. The link forward owns the next node; the link back is weak, so the two directions do not keep each other alive.

Listing 9.14 Type names, the node, and the list (lines 1 to 25). src/bin/ll.rs

// ============================================================================
// Type aliases for clarity.
// ============================================================================
use std::cell::{Ref, RefCell}; // Ref is needed for peek return types
use std::rc::{Rc, Weak};

type NodeRef<T> = Rc<RefCell<Node<T>>>;
type WeakNodeRef<T> = Weak<RefCell<Node<T>>>;
type OptNodeRef<T> = Option<NodeRef<T>>;
type OptWeakNodeRef<T> = Option<WeakNodeRef<T>>;

// ============================================================================
// Node and LinkedList definitions.
// ============================================================================
struct Node<T> {
    data: T,
    next: OptNodeRef<T>,
    prev: OptWeakNodeRef<T>,
}

pub struct LinkedList<T> {
    head: OptNodeRef<T>,
    tail: OptNodeRef<T>,
    len: usize,
}

The full type of a link is Option<Rc<RefCell<Node<T>>>>. It appears in almost every function, so the file names it once, OptNodeRef<T>, with a type alias. The list keeps a head, a tail, and its length.

9.9.2 Adding at either end

A new node at the front must point forward to the old head, and the old head must point back to it. The back of the list works the same way, mirrored.

Listing 9.15 new, len, and push_front (lines 28 to 69).

impl<T> LinkedList<T> {
    /// Creates an empty list.
    pub fn new() -> Self {
        LinkedList {
            head: None,
            tail: None,
            len: 0,
        }
    }

    pub fn len(&self) -> usize {
        self.len
    }
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    // --------------------------------------------------------------------
    // push_front
    // --------------------------------------------------------------------
    pub fn push_front(&mut self, data: T) {
        let new_node = Rc::new(RefCell::new(Node {
            data,
            next: None,
            prev: None,
        }));

        // take() moves the old head out of the Option, leaving None.
        match self.head.take() {
            Some(old_head) => {
                // Link old head back to new node (weakly).
                old_head.borrow_mut().prev = Some(Rc::downgrade(&new_node));
                // Link new node forward to old head.
                new_node.borrow_mut().next = Some(old_head);
            }
            None => {
                // List was empty: new node is also the tail.
                self.tail = Some(new_node.clone());
            }
        }
        self.head = Some(new_node);
        self.len += 1;
    }
    // ...
}

push_front creates the new node, then looks at the old head with self.head.take():

• If there was an old head, its prev becomes a weak link to the new node, made with Rc::downgrade. The new node’s next becomes the old head.
• If there was no old head, the list was empty, so the new node is also the tail. new_node.clone() makes a second strong handle for tail.

Finally the new node becomes the head, and the length grows by one. borrow_mut() is the RefCell method from section 8.4. Each call is released at the end of its statement, so no two borrows of the same node overlap.

Listing 9.16 push_back (lines 71 to 93).

impl<T> LinkedList<T> {
    // ...
    // --------------------------------------------------------------------
    // push_back
    // --------------------------------------------------------------------
    pub fn push_back(&mut self, data: T) {
        let new_node = Rc::new(RefCell::new(Node {
            data,
            next: None,
            // self.tail.as_ref() gives Option<&NodeRef<T>>,
            // map(Rc::downgrade) turns it into Option<WeakNodeRef<T>>.
            prev: self.tail.as_ref().map(Rc::downgrade),
        }));

        match self.tail.take() {
            Some(old_tail) => {
                old_tail.borrow_mut().next = Some(new_node.clone());
            }
            None => {
                self.head = Some(new_node.clone());
            }
        }
        self.tail = Some(new_node);
        self.len += 1;
    }
    // ...
}

push_back mirrors it at the other end. The new node’s prev is set as it is created: self.tail.as_ref().map(Rc::downgrade). as_ref() turns Option<Rc<...>> into Option<&Rc<...>>, so the tail is looked at without being moved. map(Rc::downgrade) turns that reference into a weak link.

9.9.3 Removing from either end

Removing the front node means unlinking it from its neighbor and moving its value out to the caller.

Listing 9.17 pop_front (lines 95 to 125).

impl<T> LinkedList<T> {
    // ...
    // --------------------------------------------------------------------
    // pop_front
    // --------------------------------------------------------------------
    pub fn pop_front(&mut self) -> Option<T> {
        self.head.take().map(|old_head| {
            // Take ownership of the next node (if any).
            let next = old_head.borrow_mut().next.take();

            match next {
                Some(next_node) => {
                    // Disconnect the new head's prev pointer.
                    next_node.borrow_mut().prev = None;
                    self.head = Some(next_node);
                }
                None => {
                    self.tail = None; // list becomes empty
                }
            }

            self.len -= 1;

            // Safely extract the data. At this point, old_head is the only
            // strong reference (because we removed it from the list and the
            // new head's prev doesn't point to it).
            let node = Rc::try_unwrap(old_head)
                .ok()
                .unwrap()
                .into_inner();
            node.data
        })
    }
    // ...
}

pop_front must return the value by ownership, not a reference. To move the value out, the node itself must be moved out of its Rc, and Rc::try_unwrap does that. It succeeds only if the handle is the last strong one. So the method first removes every other strong link to the node:

1. self.head.take() removes the list’s link to it.
2. The next node’s prev is set to None. That link was weak, so it did not count anyway.
3. If there was no next node, the list is now empty, so self.tail is cleared, removing the tail’s link.

Now Rc::try_unwrap(old_head) succeeds, and .into_inner() moves the Node out of its RefCell.

The call is written .ok().unwrap() rather than .unwrap(). Result::unwrap needs to print the error if it fails, which requires the error type to implement Debug. Here the error type is the Rc itself, and Node does not implement Debug, so .unwrap() would not compile. .ok() turns the Result into an Option, whose unwrap needs no Debug.

Animation 9.7 builds the list of figure 9.6 and pops its front. The badge on each node is its strong count. The last part makes prev strong, to show the leak that Weak prevents.

Listing 9.18 pop_back (lines 127 to 157).

impl<T> LinkedList<T> {
    // ...
    // --------------------------------------------------------------------
    // pop_back
    // --------------------------------------------------------------------
    pub fn pop_back(&mut self) -> Option<T> {
        self.tail.take().map(|old_tail| {
            // Get the previous node (upgrade the weak reference).
            let prev = old_tail
                .borrow_mut()
                .prev
                .take()
                .and_then(|w| w.upgrade());

            match prev {
                Some(prev_node) => {
                    prev_node.borrow_mut().next = None;
                    self.tail = Some(prev_node);
                }
                None => {
                    self.head = None; // list becomes empty
                }
            }

            self.len -= 1;

            let node = Rc::try_unwrap(old_tail)
                .ok()
                .unwrap()
                .into_inner();
            node.data
        })
    }
    // ...
}

pop_back mirrors pop_front. It follows the weak prev link with upgrade(), which returns None if the previous node is gone, then clears that node’s next.

Animation 9.8 runs pop_back on 10, 30, 40. Then it pops down to one node, and pops once more from the empty list.

9.9.4 Looking without removing

Looking at the front value must not move it out of the list. The caller gets a borrow of the value instead.

Listing 9.19 peek_front and peek_back (lines 159 to 180).

impl<T> LinkedList<T> {
    // ...
    // --------------------------------------------------------------------
    // peek_front: returns a guarded reference to the front data.
    // The returned Ref<'_, T> holds the borrow of the RefCell until it goes
    // out of scope, ensuring the reference stays valid.
    // --------------------------------------------------------------------
    pub fn peek_front(&self) -> Option<Ref<'_, T>> {
        // self.head.as_ref() -> Option<&NodeRef<T>>
        self.head.as_ref().map(|node| {
            // node.borrow() returns Ref<'_, Node<T>>.
            // Ref::map projects that to a Ref<'_, T> pointing to the data field.
            Ref::map(node.borrow(), |n| &n.data)
        })
    }

    // --------------------------------------------------------------------
    // peek_back: similar to peek_front.
    // --------------------------------------------------------------------
    pub fn peek_back(&self) -> Option<Ref<'_, T>> {
        self.tail
            .as_ref()
            .map(|node| Ref::map(node.borrow(), |n| &n.data))
    }
}

peek_front returns Option<Ref<'_, T>>, not Option<&T>. The value is inside a RefCell, and a reference to it is only safe while the cell’s borrow is active. A Ref is the guard that keeps the borrow active, as section 8.4 showed. Ref::map narrows a guard for the whole node into a guard for its data field. The caller reads the value with *, as main does.

9.9.5 Running it

The complete program, with its tests, is listing 9.28 at the end of the chapter. Running it:

$ cargo run --bin ll
Length: 4
Front: 20
Back: 40
Pop front: Some(20)
Pop back:  Some(40)
Popped: 10
Popped: 30
Empty? true

The test alternating_push_pop_keeps_invariants pushes 100 values at each end, then pops from both ends and checks every value. The comment block at the end of the file lists each standard-library method the file uses, with a one-line description.

This list costs more than the singly linked list. Each node needs a heap block, two counts, and a borrow flag, and every access is checked. It also keeps the recursive drop from section 9.7, because dropping the head drops the next Rc, which drops the next node. Chapter 13 avoids both costs for an LRU cache by storing its nodes in a Vec and linking them by index.

9.10 The complete files

Each file below is shown whole, in the order the chapter used it.

Listing 9.20 The node, the helpers, reverse_list, and remove_all, with tests. src/problems/linked_list.rs

//! Reverse a singly linked list, and remove nodes from it.
//!
//! Uses `Option<Box<ListNode>>` and a `while let` loop to move pointers in a
//! borrow-safe way. Removal walks a cursor: a mutable borrow of one link.

#[derive(Debug, PartialEq, Eq)]
pub struct ListNode {
    pub val: i32,
    pub next: Option<Box<ListNode>>,
}

impl ListNode {
    pub fn from_slice(values: &[i32]) -> Option<Box<ListNode>> {
        let mut head = None;
        for &value in values.iter().rev() {
            head = Some(Box::new(ListNode {
                val: value,
                next: head,
            }));
        }
        head
    }

    pub fn to_vec(head: Option<Box<ListNode>>) -> Vec<i32> {
        let mut result = Vec::new();
        let mut current = head;
        while let Some(node) = current {
            result.push(node.val);
            current = node.next;
        }
        result
    }
}

pub fn reverse_list(head: Option<Box<ListNode>>) -> Option<Box<ListNode>> {
    let mut previous = None;
    let mut current = head;

    while let Some(mut node) = current {
        current = node.next.take();
        node.next = previous;
        previous = Some(node);
    }

    previous
}

/// Remove every node whose value is `target`, in one pass.
///
/// `cursor` is a mutable borrow of a link: first `head`, then the `next` of
/// each node that stays. A matching node is unlinked by moving its `next` into
/// the link that pointed at it. The cursor does not move after a removal,
/// because the link it holds now points at a node not yet checked.
pub fn remove_all(mut head: Option<Box<ListNode>>, target: i32) -> Option<Box<ListNode>> {
    let mut cursor = &mut head;
    while cursor.is_some() {
        let node = cursor
            .as_mut()
            .expect("checked by is_some");
        if node.val == target {
            let next = node.next.take();
            *cursor = next;
        } else {
            cursor = &mut cursor
                .as_mut()
                .expect("checked by is_some")
                .next;
        }
    }
    head
}

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

    #[test]
    fn reverses_list() {
        let head = ListNode::from_slice(&[1, 2, 3, 4]);
        assert_eq!(ListNode::to_vec(reverse_list(head)), vec![4, 3, 2, 1]);
    }

    #[test]
    fn removes_head_middle_and_consecutive_matches() {
        let head = ListNode::from_slice(&[2, 1, 2, 2, 3, 2]);
        assert_eq!(ListNode::to_vec(remove_all(head, 2)), vec![1, 3]);
    }

    #[test]
    fn remove_all_edge_cases() {
        let absent = ListNode::from_slice(&[1, 3]);
        assert_eq!(ListNode::to_vec(remove_all(absent, 2)), vec![1, 3]);
        let every = ListNode::from_slice(&[7, 7, 7]);
        assert_eq!(remove_all(every, 7), None);
        assert_eq!(remove_all(None, 7), None);
    }

    #[test]
    fn handles_empty_and_single() {
        assert_eq!(reverse_list(None), None);
        assert_eq!(
            ListNode::to_vec(reverse_list(ListNode::from_slice(&[42]))),
            vec![42]
        );
    }
}

Listing 9.21 The enum list and its main. src/bin/singly_linked_list.rs

// Singly linked list using an algebraic data type.
//
//    List<T> = Empty
//            | Node { value: T, next: Link<T> }
//
// `Empty` is the end of the list.

type Link<T> = Box<List<T>>;

pub enum List<T> {
    Empty,
    Node { value: T, next: Link<T> },
}

impl<T> List<T> {
    pub fn new() -> Self {
        List::Empty
    }

    pub fn is_empty(&self) -> bool {
        matches!(self, List::Empty)
    }

    pub fn len(&self) -> usize {
        match self {
            List::Empty => 0,
            List::Node { next, .. } => 1 + next.len(),
        }
    }

    /// O(1)
    pub fn push_front(&mut self, value: T) {
        let old = std::mem::replace(self, List::Empty);
        *self = List::Node {
            value,
            next: Link::new(old),
        };
    }

    /// O(1)
    pub fn pop_front(&mut self) -> Option<T> {
        match std::mem::replace(self, List::Empty) {
            List::Empty => None,
            List::Node { value, next } => {
                *self = *next;
                Some(value)
            }
        }
    }
}

fn main() {
    let mut list = List::new();
    list.push_front(2);
    list.push_front(1);
    list.push_front(0);

    assert_eq!(list.len(), 3);
    assert_eq!(list.pop_front(), Some(0));
    assert_eq!(list.pop_front(), Some(1));
    assert_eq!(list.pop_front(), Some(2));
    println!("ok");
}

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

    #[test]
    fn push_pop_works() {
        let mut list = List::new();
        list.push_front(1);
        list.push_front(2);
        assert_eq!(list.pop_front(), Some(2));
        assert_eq!(list.pop_front(), Some(1));
        assert_eq!(list.pop_front(), None);
    }

    #[test]
    fn len_works() {
        let mut list = List::new();
        assert_eq!(list.len(), 0);
        list.push_front(1);
        list.push_front(2);
        assert_eq!(list.len(), 2);
    }
}

Listing 9.22 The Option<Box<Node>> list. benchmarking_examples/lists/boxed.rs

//! `Option<Box<Node<T>>>`: one heap allocation per node.
//!
//! Pushing takes the old head and boxes it inside the new node. Freeing the head
//! frees its `next`, which frees its `next`, so the drop recurses once per
//! element and overflows the stack on a long list.

use super::SinglyList;

struct Node<T> {
    value: T,
    next: Option<Box<Node<T>>>,
}

pub struct LinkedList<T> {
    head: Option<Box<Node<T>>>,
}

impl<T> SinglyList<T> for LinkedList<T> {
    fn new() -> Self {
        Self { head: None }
    }

    fn push_front(&mut self, value: T) {
        self.head = Some(Box::new(Node {
            value,
            // .take() leaves None in its place and extracts the old head
            next: self.head.take(),
        }));
    }

    fn pop_front(&mut self) -> Option<T> {
        self.head.take().map(|node| {
            // Point the list head to the next node in line
            self.head = node.next;
            // Return the unboxed value
            node.value
        })
    }

    fn is_empty(&self) -> bool {
        self.head.is_none()
    }

    fn variant() -> &'static str {
        "box"
    }
}

Listing 9.23 The enum list behind the trait. benchmarking_examples/lists/enum_node.rs

//! `enum ListNode<T> { Empty, Next(T, Box<ListNode<T>>) }`.
//!
//! Same shape as the boxed variant, written with an enum instead of an
//! `Option`. The enum cannot contain itself by value, so the recursive arm holds
//! a `Box`. The drop is recursive for the same reason.

use super::SinglyList;

enum ListNode<T> {
    Empty,
    Next(T, Box<ListNode<T>>),
}

pub struct LinkedList<T> {
    head: ListNode<T>,
}

impl<T> SinglyList<T> for LinkedList<T> {
    fn new() -> Self {
        Self {
            head: ListNode::Empty,
        }
    }

    fn push_front(&mut self, value: T) {
        // Extract the old head and leave Empty in its place
        let old_head = std::mem::replace(&mut self.head, ListNode::Empty);

        // Wrap the old head inside a Box behind the new value
        self.head = ListNode::Next(value, Box::new(old_head));
    }

    fn pop_front(&mut self) -> Option<T> {
        let old_head = std::mem::replace(&mut self.head, ListNode::Empty);

        match old_head {
            ListNode::Empty => None,
            ListNode::Next(value, next_node) => {
                // Point the list head to the next node in the sequence
                self.head = *next_node;
                Some(value)
            }
        }
    }

    fn is_empty(&self) -> bool {
        matches!(self.head, ListNode::Empty)
    }

    fn variant() -> &'static str {
        "enum"
    }
}

Listing 9.24 The demo of the boxed list. benchmarking_examples/list_box.rs

//! Demo of the `Option<Box<Node<T>>>` list in `lists::boxed`.
//!
//! Run with: cargo run --bin list_box

use systems_lab::lists::{SinglyList, boxed::LinkedList};

fn main() {
    let mut list = LinkedList::new();

    list.push_front(10);
    list.push_front(20);
    list.push_front(30);

    assert_eq!(list.pop_front(), Some(30));
    assert_eq!(list.pop_front(), Some(20));
    assert_eq!(list.pop_front(), Some(10));
    assert_eq!(list.pop_front(), None);
    assert!(list.is_empty());

    println!("All tests passed successfully!");
}

Listing 9.25 The demo of the enum list. benchmarking_examples/list_enum.rs

//! Demo of the `enum ListNode<T>` list in `lists::enum_node`.
//!
//! Run with: cargo run --bin list_enum

use systems_lab::lists::{SinglyList, enum_node::LinkedList};

fn main() {
    let mut list = LinkedList::new();
    list.push_front(42);
    list.push_front(100);

    assert_eq!(list.pop_front(), Some(100));
    assert_eq!(list.pop_front(), Some(42));
    assert_eq!(list.pop_front(), None);
    assert!(list.is_empty());
}

Listing 9.26 The boxed list with its own Drop. benchmarking_examples/lists/boxed_drop.rs

//! `Option<Box<Node<T>>>` with an iterative `Drop`.
//!
//! Push and pop are identical to [`boxed`](super::boxed); only freeing changes.
//! Dropping a node would otherwise drop its `next` and recurse once per element,
//! so the list is unlinked in a loop before any node is freed.

use super::SinglyList;

struct Node<T> {
    value: T,
    next: Option<Box<Node<T>>>,
}

pub struct LinkedList<T> {
    head: Option<Box<Node<T>>>,
}

impl<T> SinglyList<T> for LinkedList<T> {
    fn new() -> Self {
        Self { head: None }
    }

    fn push_front(&mut self, value: T) {
        self.head = Some(Box::new(Node {
            value,
            next: self.head.take(),
        }));
    }

    fn pop_front(&mut self) -> Option<T> {
        self.head.take().map(|node| {
            self.head = node.next;
            node.value
        })
    }

    fn is_empty(&self) -> bool {
        self.head.is_none()
    }

    fn variant() -> &'static str {
        "box+drop"
    }
}

impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        // Walk the chain and unlink each node before it is freed, so no node's
        // drop has to carry the rest of the list on the stack.
        let mut current = self.head.take();
        while let Some(mut node) = current {
            current = node.next.take();
        }
    }
}

Listing 9.27 The enum list with its own Drop. benchmarking_examples/lists/enum_drop.rs

//! `enum ListNode<T>` with an iterative `Drop`.
//!
//! Push and pop are identical to [`enum_node`](super::enum_node); only freeing
//! changes. The recursive arm holds a `Box`, so the default drop walks the chain
//! on the stack. This one replaces the head with `Empty`, then takes the box out
//! of each node in turn.

use super::SinglyList;

enum ListNode<T> {
    Empty,
    Next(T, Box<ListNode<T>>),
}

pub struct LinkedList<T> {
    head: ListNode<T>,
}

impl<T> SinglyList<T> for LinkedList<T> {
    fn new() -> Self {
        Self {
            head: ListNode::Empty,
        }
    }

    fn push_front(&mut self, value: T) {
        let old_head = std::mem::replace(&mut self.head, ListNode::Empty);
        self.head = ListNode::Next(value, Box::new(old_head));
    }

    fn pop_front(&mut self) -> Option<T> {
        let old_head = std::mem::replace(&mut self.head, ListNode::Empty);

        match old_head {
            ListNode::Empty => None,
            ListNode::Next(value, next_node) => {
                self.head = *next_node;
                Some(value)
            }
        }
    }

    fn is_empty(&self) -> bool {
        matches!(self.head, ListNode::Empty)
    }

    fn variant() -> &'static str {
        "enum+drop"
    }
}

impl<T> Drop for LinkedList<T> {
    fn drop(&mut self) {
        // Take the chain out of the list first, then step it forward one node at
        // a time. Each node has already lost its `next` by the time it is freed,
        // so the drop stays on the heap.
        let mut current = std::mem::replace(&mut self.head, ListNode::Empty);
        while let ListNode::Next(_, next) = current {
            current = *next;
        }
    }
}

Listing 9.28 The doubly linked list, with its tests. src/bin/ll.rs

// ============================================================================
// Type aliases for clarity.
// ============================================================================
use std::cell::{Ref, RefCell}; // Ref is needed for peek return types
use std::rc::{Rc, Weak};

type NodeRef<T> = Rc<RefCell<Node<T>>>;
type WeakNodeRef<T> = Weak<RefCell<Node<T>>>;
type OptNodeRef<T> = Option<NodeRef<T>>;
type OptWeakNodeRef<T> = Option<WeakNodeRef<T>>;

// ============================================================================
// Node and LinkedList definitions.
// ============================================================================
struct Node<T> {
    data: T,
    next: OptNodeRef<T>,
    prev: OptWeakNodeRef<T>,
}

pub struct LinkedList<T> {
    head: OptNodeRef<T>,
    tail: OptNodeRef<T>,
    len: usize,
}

impl<T> LinkedList<T> {
    /// Creates an empty list.
    pub fn new() -> Self {
        LinkedList {
            head: None,
            tail: None,
            len: 0,
        }
    }

    pub fn len(&self) -> usize {
        self.len
    }
    pub fn is_empty(&self) -> bool {
        self.len == 0
    }

    // --------------------------------------------------------------------
    // push_front
    // --------------------------------------------------------------------
    pub fn push_front(&mut self, data: T) {
        let new_node = Rc::new(RefCell::new(Node {
            data,
            next: None,
            prev: None,
        }));

        // take() moves the old head out of the Option, leaving None.
        match self.head.take() {
            Some(old_head) => {
                // Link old head back to new node (weakly).
                old_head.borrow_mut().prev = Some(Rc::downgrade(&new_node));
                // Link new node forward to old head.
                new_node.borrow_mut().next = Some(old_head);
            }
            None => {
                // List was empty: new node is also the tail.
                self.tail = Some(new_node.clone());
            }
        }
        self.head = Some(new_node);
        self.len += 1;
    }

    // --------------------------------------------------------------------
    // push_back
    // --------------------------------------------------------------------
    pub fn push_back(&mut self, data: T) {
        let new_node = Rc::new(RefCell::new(Node {
            data,
            next: None,
            // self.tail.as_ref() gives Option<&NodeRef<T>>,
            // map(Rc::downgrade) turns it into Option<WeakNodeRef<T>>.
            prev: self.tail.as_ref().map(Rc::downgrade),
        }));

        match self.tail.take() {
            Some(old_tail) => {
                old_tail.borrow_mut().next = Some(new_node.clone());
            }
            None => {
                self.head = Some(new_node.clone());
            }
        }
        self.tail = Some(new_node);
        self.len += 1;
    }

    // --------------------------------------------------------------------
    // pop_front
    // --------------------------------------------------------------------
    pub fn pop_front(&mut self) -> Option<T> {
        self.head.take().map(|old_head| {
            // Take ownership of the next node (if any).
            let next = old_head.borrow_mut().next.take();

            match next {
                Some(next_node) => {
                    // Disconnect the new head's prev pointer.
                    next_node.borrow_mut().prev = None;
                    self.head = Some(next_node);
                }
                None => {
                    self.tail = None; // list becomes empty
                }
            }

            self.len -= 1;

            // Safely extract the data. At this point, old_head is the only
            // strong reference (because we removed it from the list and the
            // new head's prev doesn't point to it).
            let node = Rc::try_unwrap(old_head)
                .ok()
                .unwrap()
                .into_inner();
            node.data
        })
    }

    // --------------------------------------------------------------------
    // pop_back
    // --------------------------------------------------------------------
    pub fn pop_back(&mut self) -> Option<T> {
        self.tail.take().map(|old_tail| {
            // Get the previous node (upgrade the weak reference).
            let prev = old_tail
                .borrow_mut()
                .prev
                .take()
                .and_then(|w| w.upgrade());

            match prev {
                Some(prev_node) => {
                    prev_node.borrow_mut().next = None;
                    self.tail = Some(prev_node);
                }
                None => {
                    self.head = None; // list becomes empty
                }
            }

            self.len -= 1;

            let node = Rc::try_unwrap(old_tail)
                .ok()
                .unwrap()
                .into_inner();
            node.data
        })
    }

    // --------------------------------------------------------------------
    // peek_front: returns a guarded reference to the front data.
    // The returned Ref<'_, T> holds the borrow of the RefCell until it goes
    // out of scope, ensuring the reference stays valid.
    // --------------------------------------------------------------------
    pub fn peek_front(&self) -> Option<Ref<'_, T>> {
        // self.head.as_ref() -> Option<&NodeRef<T>>
        self.head.as_ref().map(|node| {
            // node.borrow() returns Ref<'_, Node<T>>.
            // Ref::map projects that to a Ref<'_, T> pointing to the data field.
            Ref::map(node.borrow(), |n| &n.data)
        })
    }

    // --------------------------------------------------------------------
    // peek_back: similar to peek_front.
    // --------------------------------------------------------------------
    pub fn peek_back(&self) -> Option<Ref<'_, T>> {
        self.tail
            .as_ref()
            .map(|node| Ref::map(node.borrow(), |n| &n.data))
    }
}

// ============================================================================
// Demonstration with main().
// ============================================================================
fn main() {
    let mut list = LinkedList::new();

    list.push_front(10);
    list.push_front(20);
    list.push_back(30);
    list.push_back(40);

    println!("Length: {}", list.len());

    // Peek returns a Ref; we can dereference it with *.
    if let Some(front) = list.peek_front() {
        println!("Front: {}", *front);
    }
    if let Some(back) = list.peek_back() {
        println!("Back: {}", *back);
    }

    println!("Pop front: {:?}", list.pop_front()); // 20
    println!("Pop back:  {:?}", list.pop_back()); // 40

    // Drain the list.
    while let Some(val) = list.pop_front() {
        println!("Popped: {}", val);
    }
    println!("Empty? {}", list.is_empty());
}

// ============================================================================
// Tests (cargo test --bin ll)
// ============================================================================
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn new_list_is_empty() {
        let list: LinkedList<i32> = LinkedList::new();
        assert!(list.is_empty());
        assert_eq!(list.len(), 0);
        assert!(list.peek_front().is_none());
        assert!(list.peek_back().is_none());
    }

    #[test]
    fn push_front_back_and_len() {
        let mut list = LinkedList::new();
        list.push_back(1);
        list.push_back(2);
        list.push_front(0);

        assert_eq!(list.len(), 3);
        assert_eq!(*list.peek_front().unwrap(), 0);
        assert_eq!(*list.peek_back().unwrap(), 2);
    }

    #[test]
    fn pop_front_and_back_work_in_order() {
        let mut list = LinkedList::new();
        list.push_back(10);
        list.push_back(20);
        list.push_back(30);

        assert_eq!(list.pop_front(), Some(10));
        assert_eq!(list.pop_back(), Some(30));
        assert_eq!(list.pop_front(), Some(20));
        assert_eq!(list.pop_front(), None);
        assert_eq!(list.pop_back(), None);
        assert!(list.is_empty());
    }

    #[test]
    fn popping_last_item_empties_the_list() {
        let mut list = LinkedList::new();
        list.push_back(42);
        assert_eq!(list.peek_front().map(|x| *x), Some(42));
        assert_eq!(list.pop_back(), Some(42));
        assert!(list.is_empty());
    }

    #[test]
    fn alternating_push_pop_keeps_invariants() {
        let mut list = LinkedList::new();
        for i in 0..100 {
            list.push_back(i);
            list.push_front(-i);
        }
        assert_eq!(list.len(), 200);
        for i in (0..100).rev() {
            assert_eq!(list.pop_front(), Some(-i));
            assert_eq!(list.pop_back(), Some(i));
        }
        assert!(list.is_empty());
    }
}

// ============================================================================
// Explanation of key methods used:
//
// - Rc::new / RefCell::new        : create a reference-counted, mutable cell.
// - borrow() / borrow_mut()       : borrow the RefCell's contents (immutably/mutably).
// - Rc::downgrade()               : turn an Rc into a Weak (no ownership).
// - Weak::upgrade()               : attempt to get an Rc from a Weak (returns Option).
// - Option::take()                : take the value out of an Option, leaving None.
// - Option::as_ref()              : convert Option<T> to Option<&T> without moving.
// - Option::map()                 : apply a function to the inner value if Some.
// - Option::and_then()            : like map but returns an Option (for chaining).
// - Rc::try_unwrap()              : move the value out of the Rc if it's the only strong ref.
// - Ref::map()                    : project a Ref to a subfield, keeping the borrow alive.
// ============================================================================

Chapter 10 uses the singly linked list from section 9.3 to merge many sorted lists into one, and compares eleven ways of doing it.

Exercises

1. Write len for the enum list of section 9.5 with a loop instead of recursion.
2. Implement Iterator for the struct list of section 9.3, with an iter() method that yields &i32.
3. Implement Drop for the doubly linked list, and test it with one million nodes.
4. Build a doubly linked list whose nodes live in a Vec, with Option<usize> indexes as links. Compare its push and pop times with the Rc version.

Merging k sorted lists

Chapter 9 built singly linked lists and moved their nodes between owners with take. Here you have k linked lists, each already sorted, and you want one sorted list that contains all their nodes.

Section 10.2 compares three orders of merging. Sections 10.3 to 10.6 implement them, and section 10.7 lists the time and memory each program needs. Appendix C keeps the first, much longer version of this chapter, with eleven programs.

Two letters appear throughout. k is the number of lists. N is the total number of nodes across all of them.

10.1 Merging two sorted lists

Every program in this chapter merges two sorted lists at a time. Compare the front nodes of the two lists. Move the smaller one to the end of the output. Repeat until one list is empty, then attach the other list whole. Figure 10.1 works through an example.

With linked lists, “move a node to the output” does not copy the value. It detaches the node from the front of

10.2 Three strategies for k lists

Figure 10.2 shows three ways to extend two-list merging to k lists.

One at a time. Merge list 2 into list 1, then list 3 into the result, and so on. Each merge walks the whole result so far, which keeps growing. The first nodes are walked k times, so the total is about O(kN).

Pairwise rounds. Merge the lists in pairs, like the rounds of a tournament. After the first round there are k / 2 lists, after the second k / 4, and so on. In every round, each node takes part in exactly one merge. There are about log₂ k rounds, so the total is O(N log k).

A heap of heads. Put the front node of each list into a min-heap, the structure from chapter 5. Pop the smallest, append it to the output, and push the next node from the same list. Each node goes through one push and one pop on a heap of at most k entries. Each costs O(log k), so the total is again O(N log k).

Animation 10.1 counts node moves for eight lists of three nodes: pairwise rounds against one list at a time.

For 100 lists of 10,000 nodes each, N is a million. O(kN) is about 100 million steps. O(N log k) is about 7 million.

The pairwise strategy has a compact in-place form. It keeps the lists in a Vec and merges positions that are a growing interval apart (figure 10.3). The code in section 10.3 calls the interval gap.

In each round, the list at position i absorbs the list at i + interval. The position i runs through 0, 2 × interval, 4 × interval, and so on. The odd list out, number 4 here, waits until the interval is large enough to reach it.

10.3 Merging with the lists swapped by value

The merge builds its output after a placeholder node, the dummy head, so the first real node needs no special case. tail always points at the last node of the output (figure 10.4).

merge_two takes both lists by value. When the right list has the smaller front node, the two lists swap, so left always holds the node to move. The only mutable reference is tail. This keeps the loop readable and reduces the mutable borrow fatigue: there is one borrow to follow.

Listing 10.1 The node type and merge_two (lines 4 to 27). src/bin/merge_k_sorted_lists_owned.rs

type Link = Option<Box<Node>>;

struct Node {
    val: i32,
    next: Link,
}

/// Merge two sorted lists. O(n) time, O(1) extra memory.
fn merge_two(mut left: Link, mut right: Link) -> Link {
    let mut dummy = Box::new(Node { val: 0, next: None });
    let mut tail = &mut dummy;

    while let (Some(l), Some(r)) = (&left, &right) {
        if r.val < l.val {
            (left, right) = (right, left); // left now holds the smaller front
        }
        let mut node = left.unwrap(); // safe: checked by while let
        left = node.next.take();
        tail = tail.next.insert(node);
    }

    tail.next = left.or(right);
    dummy.next
}

while let (Some(l), Some(r)) = (&left, &right) runs while both lists have a node. &left and &right are shared references, used only to read the two front values.

If the right front is smaller, (left, right) = (right, left) swaps the two lists. The assignment moves the two Option values; no node moves, and no reference is taken. After it, the smaller front node is always in left.

left.unwrap() moves that list out of left. It cannot fail, because the while let checked that left is Some. node.next.take() cuts the front node off, and the rest of the list goes back into left.

tail.next.insert(node) attaches the node at the end of the output and returns a mutable reference to it. That node is the new tail.

When the loop ends, one list is empty. left.or(right) returns the other one, and tail.next takes it whole.

Animation 10.2 runs merge_two one line at a time on the lists of the trace below. The table beside the lists shows what each variable owns or borrows after every line. The last part reads l after the swap, which does not compile.

Trace the merge of 1 → 4 with 2 → 3 → 5:

Each pass moves one node, so merging n nodes takes O(n) time. The merge uses O(1) extra memory, and allocates only the dummy node.

Listing 10.2 merge_k (lines 29 to 47).

/// Merge k sorted lists in place: round 1 merges lists 1 apart, round 2 lists
/// 2 apart, and so on. O(N log k) time, O(1) extra memory.
fn merge_k(mut lists: Vec<Link>) -> Link {
    if lists.is_empty() {
        return None;
    }

    let size = lists.len();
    let mut gap = 1;
    while gap < size {
        let mut i = 0;
        while i + gap < size {
            lists[i] = merge_two(lists[i].take(), lists[i + gap].take());
            i += gap * 2;
        }
        gap *= 2;
    }
    lists[0].take()
}

merge_k follows figure 10.3. The outer while doubles gap. The inner while steps i by gap * 2 and merges position i with position i + gap. lists[i].take() moves each list out of its slot and leaves None, so merge_two receives two owned lists.

Animation 10.3 runs the merge of the trace. The last part leaves out the line after the loop.

$ cargo run --bin merge_k_sorted_lists_owned
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
[1, 1, 1, 3, 5]
[]

The complete program is listing 10.5 at the end of the chapter.

10.4 Borrowing two elements of one Vec

merge_k moves both lists out of the vector before the call. A merge that takes two &mut lists instead cannot be called on two slots of the same vector:

merge_two(&mut lists[i], &mut lists[i + gap]) // does not compile

Both &mut borrows are borrows of the whole vector lists, and Rust allows only one mutable borrow of a value at a time. The compiler does not reason about the two indexes being different.

split_at_mut(i + gap) splits the vector into two slices that do not overlap: the part before position i + gap, and the rest. It returns a mutable borrow of each. In the long version of this chapter, listing C.1 merges this way:

                let (left, right) = lists.split_at_mut(i + interval);
                left[i] = Self::merge_two(&mut left[i], &mut right[0]);

Now left[i] and right[0] come from different slices, and borrowing both is allowed. Section 10.6 uses split_at_mut to split a slice of lists in half.

10.5 A heap of list heads

This is the third strategy from figure 10.2. The heap does not hold nodes. It holds pairs of (front value, list number), wrapped in Reverse to make it a min-heap, as in chapter 5. Storing the list number instead of the node keeps the nodes in their lists, and avoids needing an ordering on nodes.

Listing 10.3 merge_k_lists (lines 10 to 33). src/bin/merge_k_sorted_lists_heap.rs

fn merge_k_lists(mut lists: Vec<Link>) -> Link {
    let mut heap = BinaryHeap::new();
    for (i, list) in lists.iter().enumerate() {
        if let Some(node) = list {
            heap.push(Reverse((node.data, i)));
        }
    }

    let mut dummy = Box::new(ListNode {
        data: 0,
        next: None,
    });
    let mut tail = &mut dummy;

    while let Some(Reverse((_, i))) = heap.pop() {
        let mut node = lists[i].take().unwrap();
        lists[i] = node.next.take();
        if let Some(next) = &lists[i] {
            heap.push(Reverse((next.data, i)));
        }
        tail = tail.next.insert(node);
    }
    dummy.next
}

Each pass of the loop:

1. Pops the smallest pair. Its second field, i, says which list holds that value.
2. Takes the front node out of lists[i] and puts the rest of that list back.
3. If the list still has a node, pushes that node’s value with i.
4. Attaches the taken node to the output with tail.next.insert(node), as in listing 10.1.

When two fronts have equal values, the pairs compare by list number, so the lower-numbered list goes first.

The heap needs only the current front of each list. That makes this strategy the right one when the lists are too large to hold in memory. One example is k sorted files read line by line.

$ cargo run --bin merge_k_sorted_lists_heap
1 1 2 3 4 4 5 6

The complete program is listing 10.6 at the end of the chapter.

10.6 Recursion on halves

This version merges from the top down. It splits the lists into two halves, merges each half recursively, and merges the two results. Its node holds an i32 named val, and List is the alias for a whole list:

#[derive(Debug)]
struct ListNode {
    val: i32,
    next: Option<Box<ListNode>>,
}

type List = Option<Box<ListNode>>;

Listing 10.4 The merge and the recursion on a slice (lines 11 to 34). src/bin/merge_k_sorted_lists_halves.rs

fn merge(a: List, b: List) -> List {
    match (a, b) {
        (None, rest) | (rest, None) => rest,
        (Some(mut left), Some(mut right)) => {
            if left.val > right.val {
                mem::swap(&mut left, &mut right);
            }
            left.next = merge(left.next.take(), Some(right));
            Some(left)
        }
    }
}

fn merge_k_slice(lists: &mut [List]) -> List {
    match lists.len() {
        0 => None,
        1 => lists[0].take(),
        _ => {
            let mid = lists.len() / 2;
            let (left_half, right_half) = lists.split_at_mut(mid);
            merge(merge_k_slice(left_half), merge_k_slice(right_half))
        }
    }
}

The first arm of merge, (None, rest) | (rest, None) => rest, handles an empty list on either side: the other list is the answer. In the second arm, mem::swap makes left the list with the smaller front. Its node stays at the front, and its next becomes the merge of the rest of left with right. No node is allocated; the boxes move.

merge_k_slice works on a slice, &mut [List], and splits it with split_at_mut from section 10.4. Splitting a slice creates two views of the same memory, so nothing is allocated to split.

merge calls itself once for each node of its output. The last merge outputs all N nodes, so the stack reaches O(N) frames. In section 9.6, a recursive drop overflowed the 8 MiB main-thread stack between 260,000 and 270,000 nodes. For long lists, use the loop of section 10.3.

$ cargo run --bin merge_k_sorted_lists_halves
Input lists:
[1 -> 4 -> 5]
[1 -> 3 -> 4]
[2 -> 6]

Merged list:
[1 -> 1 -> 2 -> 3 -> 4 -> 4 -> 5 -> 6]

The complete program is listing 10.7 at the end of the chapter.

10.7 The three programs side by side

In the table, N is the total number of nodes and k the number of lists. The extra memory column counts memory beyond the input Vec and the nodes. The stack column is the deepest the call stack goes, in frames.

• Time. Each node moves about log₂ k times: O(N log k). The “one at a time” strategy of figure 10.2 would be O(kN).
• Extra memory. The heap holds one entry per list: O(k). The other two programs reuse the input Vec.
• Stack. The recursive merge makes one call per node of its output, so its stack reaches O(N) frames. The loop and the heap use a fixed number of frames.
• Allocations. The gap rounds allocate one dummy node per merge, k - 1 in total. The recursive merge allocates nothing.

10.8 The complete files

Listing 10.5 Gap rounds with the lists swapped by value. src/bin/merge_k_sorted_lists_owned.rs

//! Merge k sorted lists: the gap loop, and a merge that swaps the two lists by
//! value so that `left` always holds the smaller front node.

type Link = Option<Box<Node>>;

struct Node {
    val: i32,
    next: Link,
}

/// Merge two sorted lists. O(n) time, O(1) extra memory.
fn merge_two(mut left: Link, mut right: Link) -> Link {
    let mut dummy = Box::new(Node { val: 0, next: None });
    let mut tail = &mut dummy;

    while let (Some(l), Some(r)) = (&left, &right) {
        if r.val < l.val {
            (left, right) = (right, left); // left now holds the smaller front
        }
        let mut node = left.unwrap(); // safe: checked by while let
        left = node.next.take();
        tail = tail.next.insert(node);
    }

    tail.next = left.or(right);
    dummy.next
}

/// Merge k sorted lists in place: round 1 merges lists 1 apart, round 2 lists
/// 2 apart, and so on. O(N log k) time, O(1) extra memory.
fn merge_k(mut lists: Vec<Link>) -> Link {
    if lists.is_empty() {
        return None;
    }

    let size = lists.len();
    let mut gap = 1;
    while gap < size {
        let mut i = 0;
        while i + gap < size {
            lists[i] = merge_two(lists[i].take(), lists[i + gap].take());
            i += gap * 2;
        }
        gap *= 2;
    }
    lists[0].take()
}

fn build(values: &[i32]) -> Link {
    let mut head = None;
    for &val in values.iter().rev() {
        head = Some(Box::new(Node { val, next: head }));
    }
    head
}

fn to_vec(mut current: Link) -> Vec<i32> {
    let mut out = Vec::new();
    while let Some(node) = current {
        out.push(node.val);
        current = node.next;
    }
    out
}

fn main() {
    let lists = vec![
        build(&[1, 4, 7]),
        build(&[2, 5, 8]),
        build(&[0, 3, 6, 9]),
        None,
    ];
    println!("{:?}", to_vec(merge_k(lists))); // [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
    println!(
        "{:?}",
        to_vec(merge_k(vec![build(&[1, 1, 5]), build(&[1, 3])]))
    ); // [1, 1, 1, 3, 5]
    println!("{:?}", to_vec(merge_k(vec![]))); // []
}

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

    #[test]
    fn merges_two_lists_keeping_duplicates() {
        let merged = merge_two(build(&[1, 1, 5]), build(&[1, 3]));
        assert_eq!(to_vec(merged), vec![1, 1, 1, 3, 5]);
    }

    #[test]
    fn merges_with_empty_lists() {
        assert_eq!(to_vec(merge_two(None, build(&[2, 4]))), vec![2, 4]);
        assert_eq!(to_vec(merge_two(build(&[2, 4]), None)), vec![2, 4]);
        assert!(merge_two(None, None).is_none());
        assert!(merge_k(vec![]).is_none());
        assert!(merge_k(vec![None, None]).is_none());
    }

    #[test]
    fn merges_an_odd_number_of_lists() {
        let five = vec![
            build(&[9]),
            build(&[1, 5]),
            build(&[3]),
            build(&[2, 8]),
            build(&[4]),
        ];
        assert_eq!(to_vec(merge_k(five)), vec![1, 2, 3, 4, 5, 8, 9]);
    }

    #[test]
    fn merges_many_long_lists() {
        let lists: Vec<Link> = (0..7)
            .map(|k| {
                build(
                    &(0..100)
                        .map(|i| i * 7 + k)
                        .collect::<Vec<_>>(),
                )
            })
            .collect();
        let expected: Vec<i32> = (0..700).collect();
        assert_eq!(to_vec(merge_k(lists)), expected);
    }
}

Listing 10.6 A heap of list heads. src/bin/merge_k_sorted_lists_heap.rs

use std::{cmp::Reverse, collections::BinaryHeap};

struct ListNode {
    data: u32,
    next: Option<Box<ListNode>>,
}

type Link = Option<Box<ListNode>>;

fn merge_k_lists(mut lists: Vec<Link>) -> Link {
    let mut heap = BinaryHeap::new();
    for (i, list) in lists.iter().enumerate() {
        if let Some(node) = list {
            heap.push(Reverse((node.data, i)));
        }
    }

    let mut dummy = Box::new(ListNode {
        data: 0,
        next: None,
    });
    let mut tail = &mut dummy;

    while let Some(Reverse((_, i))) = heap.pop() {
        let mut node = lists[i].take().unwrap();
        lists[i] = node.next.take();
        if let Some(next) = &lists[i] {
            heap.push(Reverse((next.data, i)));
        }
        tail = tail.next.insert(node);
    }
    dummy.next
}

fn main() {
    let mut lists = Vec::new();
    for values in [vec![1, 4, 5], vec![1, 3, 4], vec![2, 6]] {
        let mut head = None;
        for data in values.into_iter().rev() {
            head = Some(Box::new(ListNode { data, next: head }));
        }
        lists.push(head);
    }

    let mut cur = merge_k_lists(lists);
    while let Some(node) = cur {
        print!("{} ", node.data);
        cur = node.next;
    }
    println!();
}

Listing 10.7 Recursion on halves. src/bin/merge_k_sorted_lists_halves.rs

use std::mem;

#[derive(Debug)]
struct ListNode {
    val: i32,
    next: Option<Box<ListNode>>,
}

type List = Option<Box<ListNode>>;

fn merge(a: List, b: List) -> List {
    match (a, b) {
        (None, rest) | (rest, None) => rest,
        (Some(mut left), Some(mut right)) => {
            if left.val > right.val {
                mem::swap(&mut left, &mut right);
            }
            left.next = merge(left.next.take(), Some(right));
            Some(left)
        }
    }
}

fn merge_k_slice(lists: &mut [List]) -> List {
    match lists.len() {
        0 => None,
        1 => lists[0].take(),
        _ => {
            let mid = lists.len() / 2;
            let (left_half, right_half) = lists.split_at_mut(mid);
            merge(merge_k_slice(left_half), merge_k_slice(right_half))
        }
    }
}

fn create_list(arr: &[i32]) -> List {
    let mut head = None;
    let mut tail = &mut head;

    for &val in arr {
        *tail = Some(Box::new(ListNode { val, next: None }));
        if let Some(node) = tail {
            tail = &mut node.next;
        }
    }

    head
}

fn print_list(mut list: &List) {
    let mut elements = Vec::new();
    while let Some(node) = list {
        elements.push(node.val.to_string());
        list = &node.next;
    }
    println!("[{}]", elements.join(" -> "));
}

fn main() {
    let mut lists = vec![
        create_list(&[1, 4, 5]),
        create_list(&[1, 3, 4]),
        create_list(&[2, 6]),
    ];

    println!("Input lists:");
    for list in &lists {
        print_list(list);
    }

    let merged = merge_k_slice(&mut lists);

    println!("\nMerged list:");
    print_list(&merged);
}

Chapter 11 moves from lists to trees, where each node has up to two children. It ends with tries, where each node has one child per letter.

Exercises

1. Write the “one at a time” merge and time it against listing 10.5 on 200 lists of 5,000 nodes each.
2. Make merge_two from listing 10.1 generic over any T: Ord.
3. Write a k-way merge of sorted text files with the heap strategy, keeping only one line per file in memory.
4. Rewrite merge from listing 10.4 as a loop with the swap of listing 10.1. Test it on two lists of a million nodes each.

Trees and tries

In a linked list, each node points to at most one next node. In a tree, each node can point to several nodes, called its children. Trees describe anything organized as a hierarchy. Examples are folders on a disk, the parts of an expression, and a sorted set of numbers arranged for fast search.

Trees are easier to write in Rust than the doubly linked list of chapter 9. Each node has exactly one parent, so a parent can own its children outright, with Box or with a Vec. No Rc or RefCell is needed. The harder parts are elsewhere: replacing a node from inside a method, and choosing between recursion and an explicit stack or queue.

The chapter starts with vocabulary, then binary trees, then binary search trees, then trees with any number of children, and ends with the trie.

11.1 Tree vocabulary

Figure 11.1 names the parts of a tree.

• The root is the one node with no parent. Trees are drawn with the root at the top.
• A leaf is a node with no children.
• The subtree of a node is that node and everything below it. Every subtree is a tree itself. So a function on a tree can call itself on each subtree, which is recursion.
• The depth of a tree is the number of levels from the root down to its deepest leaf.

A binary tree is a tree in which each node has at most two children, called the left child and the right child.

11.2 A binary tree as an enum

A binary tree is either empty, or a node holding a value and two smaller binary trees. That sentence translates directly into an enum:

Listing 11.1 The tree type (lines 1 to 16). src/problems/binary_tree.rs

//! Binary tree as an algebraic data type.
//!
//! ```text
//! Tree = Empty
//!      | Node { value, left: Box<Tree>, right: Box<Tree> }
//! ```

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Tree {
    Empty,
    Node {
        value: i32,
        left: Box<Tree>,
        right: Box<Tree>,
    },
}

The children are Box<Tree> for the reason chapter 8 gave. A Tree cannot contain two Tree values directly, because its size would have no end. A Box is one pointer, so a node has a fixed size.

11.2.1 Depth and inversion

Listing 11.2 Depth and inversion (lines 19 to 35).

impl Tree {
    pub fn max_depth(&self) -> usize {
        match self {
            Tree::Empty => 0,
            Tree::Node { left, right, .. } => 1 + left.max_depth().max(right.max_depth()),
        }
    }

    pub fn invert(&mut self) {
        match self {
            Tree::Empty => {}
            Tree::Node { left, right, .. } => {
                left.invert();
                right.invert();
                std::mem::swap(left, right);
            }
        }
    }
    // ...
}

Each method is a match with two arms. The Empty arm is the base case, the input small enough to answer directly. The Node arm calls the method on the children and combines the results.

max_depth reads as a definition. An empty tree has depth 0. A node has depth 1 plus the larger depth of its two subtrees. For the tree in figure 11.1: the leaves have depth 1, node 20 has depth 2, and the root has depth 3.

invert swaps every node’s left and right children, so the tree becomes its mirror image. It inverts both subtrees first and then calls std::mem::swap(left, right). The pattern binds left and right as mutable references to the boxes, so the swap exchanges two pointers and moves no nodes.

11.2.2 The three depth-first orders

Visiting every node of a tree once is called a traversal. Going down one branch as far as possible before trying the next is depth-first traversal. There are three common depth-first orders. They differ only in when a node is visited relative to its children (figure 11.2).

• Pre-order visits the node first, then its left subtree, then its right subtree.
• In-order visits the left subtree, then the node, then the right subtree.
• Post-order visits both subtrees, then the node.

Listing 11.3 The public traversal methods (lines 37 to 53).

impl Tree {
    // ...
    pub fn preorder(&self) -> Vec<i32> {
        let mut out = Vec::new();
        self.collect_preorder(&mut out);
        out
    }

    pub fn inorder(&self) -> Vec<i32> {
        let mut out = Vec::new();
        self.collect_inorder(&mut out);
        out
    }

    pub fn postorder(&self) -> Vec<i32> {
        let mut out = Vec::new();
        self.collect_postorder(&mut out);
        out
    }
    // ...
}

Each public method creates an empty Vec, passes it to a private helper, and returns it. Creating the vector once and passing it down avoids building a new vector at every node.

Listing 11.4 The recursive helpers (lines 55 to 86).

impl Tree {
    // ...
    fn collect_preorder(&self, out: &mut Vec<i32>) {
        match self {
            Tree::Empty => {}
            Tree::Node { value, left, right } => {
                out.push(*value);
                left.collect_preorder(out);
                right.collect_preorder(out);
            }
        }
    }

    fn collect_inorder(&self, out: &mut Vec<i32>) {
        match self {
            Tree::Empty => {}
            Tree::Node { value, left, right } => {
                left.collect_inorder(out);
                out.push(*value);
                right.collect_inorder(out);
            }
        }
    }

    fn collect_postorder(&self, out: &mut Vec<i32>) {
        match self {
            Tree::Empty => {}
            Tree::Node { value, left, right } => {
                left.collect_postorder(out);
                right.collect_postorder(out);
                out.push(*value);
            }
        }
    }
}

The three helpers are identical except for one line: where out.push(*value) appears relative to the two recursive calls. *value copies the i32 out of the reference.

Listing 11.5 The complete file, with its tests. src/problems/binary_tree.rs

//! Binary tree as an algebraic data type.
//!
//! ```text
//! Tree = Empty
//!      | Node { value, left: Box<Tree>, right: Box<Tree> }
//! ```

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Tree {
    Empty,
    Node {
        value: i32,
        left: Box<Tree>,
        right: Box<Tree>,
    },
}

impl Tree {
    pub fn max_depth(&self) -> usize {
        match self {
            Tree::Empty => 0,
            Tree::Node { left, right, .. } => 1 + left.max_depth().max(right.max_depth()),
        }
    }

    pub fn invert(&mut self) {
        match self {
            Tree::Empty => {}
            Tree::Node { left, right, .. } => {
                left.invert();
                right.invert();
                std::mem::swap(left, right);
            }
        }
    }

    pub fn preorder(&self) -> Vec<i32> {
        let mut out = Vec::new();
        self.collect_preorder(&mut out);
        out
    }

    pub fn inorder(&self) -> Vec<i32> {
        let mut out = Vec::new();
        self.collect_inorder(&mut out);
        out
    }

    pub fn postorder(&self) -> Vec<i32> {
        let mut out = Vec::new();
        self.collect_postorder(&mut out);
        out
    }

    fn collect_preorder(&self, out: &mut Vec<i32>) {
        match self {
            Tree::Empty => {}
            Tree::Node { value, left, right } => {
                out.push(*value);
                left.collect_preorder(out);
                right.collect_preorder(out);
            }
        }
    }

    fn collect_inorder(&self, out: &mut Vec<i32>) {
        match self {
            Tree::Empty => {}
            Tree::Node { value, left, right } => {
                left.collect_inorder(out);
                out.push(*value);
                right.collect_inorder(out);
            }
        }
    }

    fn collect_postorder(&self, out: &mut Vec<i32>) {
        match self {
            Tree::Empty => {}
            Tree::Node { value, left, right } => {
                left.collect_postorder(out);
                right.collect_postorder(out);
                out.push(*value);
            }
        }
    }
}

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

    fn leaf(value: i32) -> Tree {
        Tree::Node {
            value,
            left: Box::new(Tree::Empty),
            right: Box::new(Tree::Empty),
        }
    }

    fn node(value: i32, left: Tree, right: Tree) -> Tree {
        Tree::Node {
            value,
            left: Box::new(left),
            right: Box::new(right),
        }
    }

    fn sample() -> Tree {
        node(3, leaf(9), node(20, leaf(15), leaf(7)))
    }

    #[test]
    fn max_depth_works() {
        assert_eq!(Tree::Empty.max_depth(), 0);
        assert_eq!(leaf(1).max_depth(), 1);
        assert_eq!(sample().max_depth(), 3);
    }

    #[test]
    fn invert_swaps_subtrees() {
        let mut tree = sample();
        tree.invert();

        match &tree {
            Tree::Node { left, right, .. } => {
                match left.as_ref() {
                    Tree::Node { value, .. } => assert_eq!(*value, 20),
                    _ => panic!("expected left node"),
                }
                match right.as_ref() {
                    Tree::Node { value, .. } => assert_eq!(*value, 9),
                    _ => panic!("expected right node"),
                }
            }
            _ => panic!("expected node"),
        }
    }

    #[test]
    fn traversals_work() {
        let tree = sample();
        assert_eq!(tree.preorder(), vec![3, 9, 20, 15, 7]);
        assert_eq!(tree.inorder(), vec![9, 3, 15, 20, 7]);
        assert_eq!(tree.postorder(), vec![9, 15, 7, 20, 3]);
    }
}

The test module defines two small helpers, leaf and node, so a test tree can be built in one readable expression. sample() builds the tree of figure 11.1. The traversal test checks all three orders from figure 11.2.

11.3 Binary search trees

A binary search tree (BST) is a binary tree with an ordering rule. For every node, all values in its left subtree are smaller than the node’s value, and all values in its right subtree are larger.

The rule makes searching fast. To find a value, compare it with the root. If it is smaller, it can only be in the left subtree; if larger, only in the right. Each comparison discards one subtree (figure 11.3).

The code for this chapter has two implementations of the same BST. They agree on inserting and searching, and differ in how they remove values and answer range queries. I’ll go through the first fully, then the parts where the second differs.

11.3.1 The type, insertion, and search

Listing 11.6 The type (lines 1 to 14). src/bin/bst_clean.rs

use std::cmp::Ordering;

type TreeLink<T> = Box<BST<T>>;

#[derive(Debug, Clone, Default)]
pub enum BST<T> {
    #[default]
    Empty,
    Node {
        value: T,
        left: TreeLink<T>,
        right: TreeLink<T>,
    },
}

BST<T> is generic over the value type. The methods require T: Ord, meaning values of type T can be ordered, which a search tree needs. #[default] on Empty makes an empty tree the default value, which the removal code uses.

Listing 11.7 Creating, inserting, and searching (lines 17 to 47).

impl<T: Ord> BST<T> {
    pub fn new() -> Self {
        Self::Empty
    }

    pub fn insert(&mut self, val: T) {
        match self {
            Self::Empty => {
                *self = Self::Node {
                    value: val,
                    left: Box::new(Self::Empty),
                    right: Box::new(Self::Empty),
                };
            }
            Self::Node { value, left, right } => match val.cmp(value) {
                Ordering::Less => left.insert(val),
                Ordering::Greater => right.insert(val),
                Ordering::Equal => {}
            },
        }
    }

    pub fn contains(&self, val: &T) -> bool {
        match self {
            Self::Empty => false,
            Self::Node { value, left, right } => match val.cmp(value) {
                Ordering::Less => left.contains(val),
                Ordering::Greater => right.contains(val),
                Ordering::Equal => true,
            },
        }
    }
    // ...
}

insert takes &mut self because it changes the tree in place. It walks down with recursive calls. When it reaches an Empty tree, it replaces that spot with a new leaf: *self = Self::Node { ... }. On the way down, val.cmp(value) compares the new value with the node’s and returns Ordering::Less, Greater, or Equal. A value equal to one already in the tree is ignored, so the tree holds each value once.

contains follows the same path without changing anything.

11.3.2 Removal

Removing a value is the hardest operation, because the tree must keep its ordering rule. There are three cases (figure 11.4).

1. No left child. Replace the node with its right subtree.
2. No right child. Replace the node with its left subtree.
3. Two children. Keep the node, but give it a new value: the smallest value in its right subtree. That value is larger than everything on the left and smaller than everything else on the right, so the rule still holds. Then remove that smallest value from the right subtree. The smallest value has no left child, so its removal is case 1.

Listing 11.8 Removal (lines 49 to 90).

impl<T: Ord> BST<T> {
    // ...
    pub fn remove(&mut self, val: &T) -> bool {
        match self {
            Self::Empty => false,
            Self::Node { value, left, right } => match val.cmp(value) {
                Ordering::Less => left.remove(val),
                Ordering::Greater => right.remove(val),
                Ordering::Equal => {
                    if left.is_empty() && right.is_empty() {
                        *self = Self::Empty;
                        return true;
                    }
                    if left.is_empty() {
                        *self = *std::mem::take(right);
                        return true;
                    }
                    if right.is_empty() {
                        *self = *std::mem::take(left);
                        return true;
                    }
                    let min_val = right.remove_min().unwrap();
                    *value = min_val;
                    true
                }
            },
        }
    }

    fn remove_min(&mut self) -> Option<T> {
        match self {
            Self::Empty => None,
            Self::Node { left, .. } if left.is_empty() => {
                let node = std::mem::take(self);
                if let Self::Node { value, right, .. } = node {
                    *self = *right;
                    Some(value)
                } else {
                    unreachable!()
                }
            }
            Self::Node { left, .. } => left.remove_min(),
        }
    }
    // ...
}

The first two cases need to replace *self with one of its own children. That is not straightforward, because right is a reference into *self. You cannot move a subtree out through right and assign it to *self in one step. std::mem::take(right) solves it: it moves the subtree out and leaves the default value, an empty tree, in its place. Then *self = *std::mem::take(right) assigns the subtree, and the * moves it out of its Box. take needs Default, which is why the type derives it.

The code also handles a leaf, a node with no children, separately. Case 1 would already cover it.

For case 3, remove_min removes and returns the smallest value of the right subtree. It walks left until it reaches a node whose left child is empty, using a match guard: Self::Node { left, .. } if left.is_empty(). That node holds the smallest value. The method takes the whole node out with std::mem::take(self), puts its right subtree in its place, and returns its value. The if let ... else { unreachable!() } is there because the compiler cannot see that the value taken from a Node arm is a Node. unreachable!() panics if that ever turns out false.

remove returns true if the value was found and removed, and false otherwise, so a caller can tell the two apart.

11.3.3 Range queries

A range query returns every value between a low and a high bound, in order. A BST can answer it without visiting subtrees that cannot contain an answer.

Listing 11.9 Range queries (lines 92 to 114).

impl<T: Ord> BST<T> {
    // ...
    pub fn range(&self, low: &T, high: &T) -> Vec<&T> {
        let mut result = Vec::new();
        self.range_helper(low, high, &mut result);
        result
    }

    // Explicit lifetime 'a ties the references in the vector to the lifetime of &self.
    fn range_helper<'a>(&'a self, low: &T, high: &T, acc: &mut Vec<&'a T>) {
        match self {
            Self::Empty => {}
            Self::Node { value, left, right } => {
                if value < low {
                    right.range_helper(low, high, acc);
                } else if value > high {
                    left.range_helper(low, high, acc);
                } else {
                    left.range_helper(low, high, acc);
                    acc.push(value);
                    right.range_helper(low, high, acc);
                }
            }
        }
    }
    // ...
}

range_helper collects matching values into an accumulator, acc. Its three branches skip work:

• If the node’s value is below low, everything in its left subtree is lower still, so only the right subtree is searched.
• If the value is above high, only the left subtree is searched.
• Otherwise, the helper searches the left subtree, adds the value, and searches the right subtree. That order is in-order traversal, so the results come out sorted.

The signature has an explicit lifetime: fn range_helper<'a>(&'a self, ..., acc: &mut Vec<&'a T>). The references pushed into acc point into the tree, so they must live as long as the tree borrow &'a self. Without the named 'a, the elision rules from chapter 4 would give self and the vector’s elements separate lifetimes. The push would then not compile.

Listing 11.10 The complete program. src/bin/bst_clean.rs

use std::cmp::Ordering;

type TreeLink<T> = Box<BST<T>>;

#[derive(Debug, Clone, Default)]
pub enum BST<T> {
    #[default]
    Empty,
    Node {
        value: T,
        left: TreeLink<T>,
        right: TreeLink<T>,
    },
}

impl<T: Ord> BST<T> {
    pub fn new() -> Self {
        Self::Empty
    }

    pub fn insert(&mut self, val: T) {
        match self {
            Self::Empty => {
                *self = Self::Node {
                    value: val,
                    left: Box::new(Self::Empty),
                    right: Box::new(Self::Empty),
                };
            }
            Self::Node { value, left, right } => match val.cmp(value) {
                Ordering::Less => left.insert(val),
                Ordering::Greater => right.insert(val),
                Ordering::Equal => {}
            },
        }
    }

    pub fn contains(&self, val: &T) -> bool {
        match self {
            Self::Empty => false,
            Self::Node { value, left, right } => match val.cmp(value) {
                Ordering::Less => left.contains(val),
                Ordering::Greater => right.contains(val),
                Ordering::Equal => true,
            },
        }
    }

    pub fn remove(&mut self, val: &T) -> bool {
        match self {
            Self::Empty => false,
            Self::Node { value, left, right } => match val.cmp(value) {
                Ordering::Less => left.remove(val),
                Ordering::Greater => right.remove(val),
                Ordering::Equal => {
                    if left.is_empty() && right.is_empty() {
                        *self = Self::Empty;
                        return true;
                    }
                    if left.is_empty() {
                        *self = *std::mem::take(right);
                        return true;
                    }
                    if right.is_empty() {
                        *self = *std::mem::take(left);
                        return true;
                    }
                    let min_val = right.remove_min().unwrap();
                    *value = min_val;
                    true
                }
            },
        }
    }

    fn remove_min(&mut self) -> Option<T> {
        match self {
            Self::Empty => None,
            Self::Node { left, .. } if left.is_empty() => {
                let node = std::mem::take(self);
                if let Self::Node { value, right, .. } = node {
                    *self = *right;
                    Some(value)
                } else {
                    unreachable!()
                }
            }
            Self::Node { left, .. } => left.remove_min(),
        }
    }

    pub fn range(&self, low: &T, high: &T) -> Vec<&T> {
        let mut result = Vec::new();
        self.range_helper(low, high, &mut result);
        result
    }

    // Explicit lifetime 'a ties the references in the vector to the lifetime of &self.
    fn range_helper<'a>(&'a self, low: &T, high: &T, acc: &mut Vec<&'a T>) {
        match self {
            Self::Empty => {}
            Self::Node { value, left, right } => {
                if value < low {
                    right.range_helper(low, high, acc);
                } else if value > high {
                    left.range_helper(low, high, acc);
                } else {
                    left.range_helper(low, high, acc);
                    acc.push(value);
                    right.range_helper(low, high, acc);
                }
            }
        }
    }

    fn is_empty(&self) -> bool {
        matches!(self, Self::Empty)
    }
}

fn main() {
    let mut bst = BST::new();
    bst.insert(10);
    bst.insert(5);
    bst.insert(15);
    bst.insert(3);
    bst.insert(7);
    bst.insert(12);
    bst.insert(18);

    println!("Contains 7: {}", bst.contains(&7));
    println!("Contains 12: {}", bst.contains(&12));

    let range = bst.range(&4, &16);
    println!("Values in [4, 16]: {:?}", range);

    println!("Remove 5: {}", bst.remove(&5));
    println!("Remove 10: {}", bst.remove(&10));
    println!("Remove 99: {}", bst.remove(&99));

    println!("After removals: {:#?}", bst);
}

$ cargo run --bin bst_clean
Contains 7: true
Contains 12: true
Values in [4, 16]: [5, 7, 10, 12, 15]
Remove 5: true
Remove 10: true
Remove 99: false
After removals: Node {
    value: 12,
    left: Node {
        value: 7,
        left: Node {
            value: 3,
            left: Empty,
            right: Empty,
        },
        right: Empty,
    },
    right: Node {
        value: 15,
        left: Empty,
        right: Node {
            value: 18,
            left: Empty,
            right: Empty,
        },
    },
}

Follow the two removals by hand. Node 5 has two children, 3 and 7. So it takes 7, the smallest value on its right, and the old 7 leaf is removed. Node 10 also has two children, so the root takes 12, the smallest value in its right subtree. The printed tree shows 12 at the root and 7 where 5 was.

11.3.4 A second BST, with an iterative minimum

The second implementation writes removal and range queries differently.

Listing 11.11 Removal and pop_min (lines 49 to 84). src/bin/bst_easy.rs

use std::{
    cmp::Ordering::{Equal, Greater, Less},
    mem,
};

impl<T: Ord> BST<T> {
    // ...
    pub fn remove(&mut self, val: &T) {
        match self {
            Self::Empty => {}
            Self::Node { value, left, right } => match val.cmp(value) {
                Less => left.remove(val),
                Greater => right.remove(val),
                Equal => {
                    if left.is_empty() {
                        *self = right.take();
                    } else if right.is_empty() {
                        *self = left.take();
                    } else {
                        *value = right.pop_min().unwrap();
                    }
                }
            },
        }
    }

    pub fn pop_min(&mut self) -> Option<T> {
        let mut node = self;

        while node.has_left() {
            if let Self::Node { left, .. } = node {
                node = left;
            }
        }

        match node.take() {
            Self::Empty => None,
            Self::Node { value, right, .. } => {
                *node = *right;
                Some(value)
            }
        }
    }
    // ...
}

This remove uses a helper take, defined at the end of the file, that swaps in Empty with mem::replace. So the type does not need Default. right.take() reaches through the Box automatically and returns the tree inside.

pop_min finds the smallest value with a loop instead of recursion. It moves a mutable reference, node, down the left side of the tree:

let mut node = self;
while node.has_left() {
    if let Self::Node { left, .. } = node {
        node = left;
    }
}

When the loop ends, node refers to the leftmost node. match node.take() splits it into its value and its right subtree, with no unreachable!. The loop uses one stack frame however deep the tree is. pop_min is also public, so the tree can serve as a queue that always returns the smallest value.

Listing 11.12 A range query that returns a new vector (lines 86 to 102).

impl<T: Ord> BST<T> {
    // ...
    pub fn range(&self, from: &T, to: &T) -> Vec<&T> {
        let mut result = Vec::new();

        if let Self::Node { value, left, right } = self {
            if from < value {
                result.extend(left.range(from, to));
            }
            if from <= value && value <= to {
                result.push(value);
            }
            if value < to {
                result.extend(right.range(from, to));
            }
        }

        result
    }
    // ...
}

This range returns a new Vec from each call and joins the children’s results with extend. It is shorter than the accumulator version, and it allocates a vector at every node it visits, where the accumulator version allocates one.

Listing 11.13 The complete program. src/bin/bst_easy.rs

use std::{
    cmp::Ordering::{Equal, Greater, Less},
    mem,
};

#[derive(Debug, Clone)]
pub enum BST<T> {
    Empty,
    Node {
        value: T,
        left: Box<BST<T>>,
        right: Box<BST<T>>,
    },
}

impl<T: Ord> BST<T> {
    pub fn new() -> Self {
        Self::Empty
    }

    pub fn insert(&mut self, val: T) {
        match self {
            Self::Empty => {
                *self = Self::Node {
                    value: val,
                    left: Box::new(Self::Empty),
                    right: Box::new(Self::Empty),
                };
            }
            Self::Node { value, left, right } => match val.cmp(value) {
                Less => left.insert(val),
                Greater => right.insert(val),
                Equal => {}
            },
        }
    }

    pub fn contains(&self, val: &T) -> bool {
        match self {
            Self::Empty => false,
            Self::Node { value, left, right } => match val.cmp(value) {
                Less => left.contains(val),
                Greater => right.contains(val),
                Equal => true,
            },
        }
    }

    pub fn remove(&mut self, val: &T) {
        match self {
            Self::Empty => {}
            Self::Node { value, left, right } => match val.cmp(value) {
                Less => left.remove(val),
                Greater => right.remove(val),
                Equal => {
                    if left.is_empty() {
                        *self = right.take();
                    } else if right.is_empty() {
                        *self = left.take();
                    } else {
                        *value = right.pop_min().unwrap();
                    }
                }
            },
        }
    }

    pub fn pop_min(&mut self) -> Option<T> {
        let mut node = self;

        while node.has_left() {
            if let Self::Node { left, .. } = node {
                node = left;
            }
        }

        match node.take() {
            Self::Empty => None,
            Self::Node { value, right, .. } => {
                *node = *right;
                Some(value)
            }
        }
    }

    pub fn range(&self, from: &T, to: &T) -> Vec<&T> {
        let mut result = Vec::new();

        if let Self::Node { value, left, right } = self {
            if from < value {
                result.extend(left.range(from, to));
            }
            if from <= value && value <= to {
                result.push(value);
            }
            if value < to {
                result.extend(right.range(from, to));
            }
        }

        result
    }

    fn is_empty(&self) -> bool {
        match self {
            Self::Empty => true,
            Self::Node { .. } => false,
        }
    }

    fn has_left(&self) -> bool {
        match self {
            Self::Empty => false,
            Self::Node { left, .. } => !left.is_empty(),
        }
    }

    fn take(&mut self) -> Self {
        mem::replace(self, Self::Empty)
    }
}

fn main() {
    let mut bst = BST::new();

    bst.insert(10);
    bst.insert(5);
    bst.insert(15);
    bst.insert(3);
    bst.insert(7);
    bst.insert(12);

    println!("Contains 7: {}", bst.contains(&7));
    println!("Range 4 to 12: {:?}", bst.range(&4, &12));

    bst.remove(&10);
    println!("After removing 10: {:?}", bst.range(&0, &100));

    println!("Pop min: {:?}", bst.pop_min());
    println!("{:#?}", bst);
}

$ cargo run --bin bst_easy
Contains 7: true
Range 4 to 12: [5, 7, 10, 12]
After removing 10: [3, 5, 7, 12, 15]
Pop min: Some(3)

11.4 Trees with any number of children

Many real trees are not binary. A folder can hold any number of files and folders. A node that owns a Vec<TreeNode<T>> of children describes such a tree. It needs no Box, because the Vec already keeps its elements on the heap, so the node’s own size is fixed.

11.4.1 Depth first and breadth first

Figure 11.5 shows the two basic ways to visit such a tree. A depth-first visit goes down one branch completely before starting the next, as in section 11.2.2. A breadth-first visit goes level by level: the root, then all its children, then all their children.

Depth first is naturally recursive. Breadth first needs a queue: a collection where items leave in the order they arrived. You put the root in the queue. Then, repeatedly, you take the node at the front, visit it, and add its children at the back. Because children join at the back, every node of one level leaves the queue before any node of the next.

A node owns its value and a Vec of child nodes. The children are stored inside the vector itself, not behind pointers, so a node can have any number of them:

use std::collections::VecDeque;

struct TreeNode<T> {
    value: T,
    children: Vec<TreeNode<T>>, // Owned children directly inline
}

Listing 11.14 The complete program. src/bin/test_tree.rs

use std::collections::VecDeque;

struct TreeNode<T> {
    value: T,
    children: Vec<TreeNode<T>>, // Owned children directly inline
}

impl<T> TreeNode<T>
where
    T: Clone + std::fmt::Display,
{
    /// Recursive DFS (Pre-order) - No callbacks
    pub fn dfs(&self) {
        println!("{}", self.value);
        for child in self.children.iter() {
            child.dfs();
        }
    }

    /// Level Order BFS - Idiomatic VecDeque::from([self])
    pub fn bfs(&self) {
        let mut queue = VecDeque::from([self]); // Idiomatic initialization

        while let Some(node) = queue.pop_front() {
            println!("{}", node.value);

            for child in &node.children {
                queue.push_back(child);
            }
        }
    }
}

fn main() {
    // --- Inline Construction (No variables, no push) ---

    let root = TreeNode {
        value: 1,
        children: vec![
            TreeNode {
                value: 2,
                children: vec![
                    TreeNode {
                        value: 4,
                        children: vec![],
                    },
                    TreeNode {
                        value: 5,
                        children: Vec::new(),
                    },
                ],
            },
            TreeNode {
                value: 3,
                children: vec![TreeNode {
                    value: 6,
                    children: Vec::new(),
                }],
            },
        ],
    };

    println!("=== DFS ===");
    root.dfs();
    // Output: 1, 2, 4, 5, 3, 6

    println!("\n=== BFS ===");
    root.bfs();
    // Output: 1, 2, 3, 4, 5, 6
}

dfs prints the node and then calls itself on each child, which is pre-order.

bfs uses a VecDeque as the queue. VecDeque::from([self]) starts it with the root. The queue holds references, &TreeNode<T>, so no node is moved or copied. pop_front takes from the front, and push_back adds each child at the back.

The tree in main is written as one nested value. The shape of the code matches the shape of the tree, which makes test data easy to check.

$ cargo run --bin test_tree
=== DFS ===
1
2
4
5
3
6

=== BFS ===
1
2
3
4
5
6

11.4.2 Grouping values by level

A common variation returns the values grouped by level, as a list of lists. The first list holds the root’s value, the second the values of its children, and so on. The file solves it twice.

Listing 11.15 The type and the first version (lines 1 to 20). src/bin/tree_under_pressure.rs

use std::collections::VecDeque;

#[derive(Debug)]
struct TreeNode<T> {
    value: T,
    children: Vec<TreeNode<T>>,
}

fn level_order<T>(root: &TreeNode<T>) -> Vec<Vec<&T>> {
    let mut result = Vec::new();
    let mut level = vec![root];
    while !level.is_empty() {
        result.push(level.iter().map(|n| &n.value).collect());
        level = level
            .iter()
            .flat_map(|n| &n.children)
            .collect();
    }
    result
}

level_order keeps one whole level in level, a Vec of references to nodes. Each pass of the loop does two things. It adds the values of this level to the result. Then it builds the next level from all the children of all the nodes in this level: level.iter().flat_map(|n| &n.children).collect(). flat_map turns each node into its children and joins all those children into one sequence. The loop ends when a level has no nodes.

Listing 11.16 The second version, with a queue (lines 22 to 40).

fn level_order_readable<T>(root: &TreeNode<T>) -> Vec<Vec<&T>> {
    let mut result = Vec::new();
    let mut queue = VecDeque::from([(root)]);

    while !queue.is_empty() {
        let current_size = queue.len();
        let mut level = Vec::with_capacity(current_size);

        for _ in 1..=current_size {
            let Some(node) = queue.pop_front() else { break };

            level.push(&node.value);
            queue.extend(&node.children);
        }

        result.push(level);
    }
    result
}

level_order_readable uses one queue, as bfs did. The trick is queue.len() at the start of each round. At that moment, the queue holds exactly one level. So the loop pops exactly that many nodes, collecting their values, while their children pile up behind them for the next round.

let Some(node) = queue.pop_front() else { break }; is a let-else statement. It binds node if the pattern matches, and runs the else block, which must leave the loop or the function, if it does not. queue.extend(&node.children) adds references to all the children at once.

Listing 11.17 The complete program. src/bin/tree_under_pressure.rs

use std::collections::VecDeque;

#[derive(Debug)]
struct TreeNode<T> {
    value: T,
    children: Vec<TreeNode<T>>,
}

fn level_order<T>(root: &TreeNode<T>) -> Vec<Vec<&T>> {
    let mut result = Vec::new();
    let mut level = vec![root];
    while !level.is_empty() {
        result.push(level.iter().map(|n| &n.value).collect());
        level = level
            .iter()
            .flat_map(|n| &n.children)
            .collect();
    }
    result
}

fn level_order_readable<T>(root: &TreeNode<T>) -> Vec<Vec<&T>> {
    let mut result = Vec::new();
    let mut queue = VecDeque::from([(root)]);

    while !queue.is_empty() {
        let current_size = queue.len();
        let mut level = Vec::with_capacity(current_size);

        for _ in 1..=current_size {
            let Some(node) = queue.pop_front() else { break };

            level.push(&node.value);
            queue.extend(&node.children);
        }

        result.push(level);
    }
    result
}

fn main() {
    let root: TreeNode<String> = TreeNode {
        value: "root".into(),
        children: vec![
            TreeNode {
                value: "branch_a".into(),
                children: vec![
                    TreeNode {
                        value: "leaf_1".into(),
                        children: vec![],
                    },
                    TreeNode {
                        value: "leaf_2".into(),
                        children: vec![],
                    },
                ],
            },
            TreeNode {
                value: "branch_b".into(),
                children: vec![TreeNode {
                    value: "leaf_3".into(),
                    children: vec![],
                }],
            },
        ],
    };

    let levels = level_order(&root);
    println!("Tree\n {:#?}", root);

    for level in levels {
        println!("{:?}", level);
    }

    println!("one queue, one level per round:");
    for level in level_order_readable(&root) {
        println!("{:?}", level);
    }
}

main prints the tree with {:#?}, then the levels from each version. Both give the same three levels:

["root"]
["branch_a", "branch_b"]
["leaf_1", "leaf_2", "leaf_3"]
one queue, one level per round:
["root"]
["branch_a", "branch_b"]
["leaf_1", "leaf_2", "leaf_3"]

Both functions return Vec<Vec<&T>>, references into the tree, and both run in O(n).

11.5 Saving a tree to a file and loading it back

To save a tree, you turn it into a flat sequence of text. Later, you rebuild exactly the same tree from that text. Turning a structure into a flat sequence is called serialization.

A list of values in pre-order is not enough, because it does not say where one node’s children end. The file’s format adds, after each value, the number of children that follow (figure 11.6). A reader can then rebuild the tree: read a value and a count, then read that many subtrees.

Listing 11.18 The tree type, and writing the pairs (lines 1 to 47). src/bin/tree_serializ_deserialize_into_file.rs

use std::{collections::VecDeque, fs, io, str::FromStr};

#[derive(Debug)]
struct TreeNode<T> {
    value: T,
    children: Vec<TreeNode<T>>,
}

impl<T> TreeNode<T> {
    // ...
    fn serialize(&self) -> Vec<String>
    where
        T: ToString,
    {
        let mut serialized = Vec::new();
        let mut stack = vec![self];

        while let Some(node) = stack.pop() {
            serialized.push(node.value.to_string());
            serialized.push(node.children.len().to_string());

            for child in node.children.iter().rev() {
                stack.push(child);
            }
        }

        serialized
    }
    // ...
}

TreeNode<T> is the same shape as in section 11.4: a value and a Vec of child nodes. A node can have any number of children.

serialize walks the tree in pre-order without recursion, using a Vec as a stack: the last item pushed is the first popped. It pushes the children in reverse order, with iter().rev(), so that the first child is on top and is popped first. For each node it writes the value and the child count as strings.

The line where T: ToString sits on the method, not on the whole impl. So a tree of any type exists, and only a tree whose values can become strings gets a serialize method.

Listing 11.19 Reading the pairs back (lines 49 to 63).

impl<T> TreeNode<T> {
    // ...
    fn deserialize(serialized: &[String], pos: &mut usize) -> Option<Self>
    where
        T: FromStr,
    {
        let value = serialized.get(*pos)?.parse().ok()?;
        let child_count: usize = serialized.get(*pos + 1)?.parse().ok()?;
        *pos += 2;

        let mut children = Vec::new();
        for _ in 0..child_count {
            children.push(Self::deserialize(serialized, pos)?);
        }

        Some(TreeNode { value, children })
    }
    // ...
}

deserialize is recursive. pos is a &mut usize, a position in the token list shared by all the calls. Each call reads a value and a count at pos, advances pos by two, and then calls itself child_count times to read the children.

Every step that can fail uses ? on an Option. The failures are a missing token, a value that does not parse, and a count that is not a number. .parse().ok()? first turns the parse Result into an Option. Any failure makes the whole function return None.

Listing 11.20 The complete program. src/bin/tree_serializ_deserialize_into_file.rs

use std::{collections::VecDeque, fs, io, str::FromStr};

#[derive(Debug)]
struct TreeNode<T> {
    value: T,
    children: Vec<TreeNode<T>>,
}

impl<T> TreeNode<T> {
    fn level_order(&self) -> Vec<Vec<&T>> {
        let mut result = Vec::new();
        let mut queue = VecDeque::from([self]);

        while !queue.is_empty() {
            let current_size = queue.len();
            let mut level = Vec::with_capacity(current_size);

            for _ in 1..=current_size {
                let Some(node) = queue.pop_front() else { break };
                level.push(&node.value);
                queue.extend(&node.children);
            }

            result.push(level);
        }

        result
    }

    fn serialize(&self) -> Vec<String>
    where
        T: ToString,
    {
        let mut serialized = Vec::new();
        let mut stack = vec![self];

        while let Some(node) = stack.pop() {
            serialized.push(node.value.to_string());
            serialized.push(node.children.len().to_string());

            for child in node.children.iter().rev() {
                stack.push(child);
            }
        }

        serialized
    }

    fn deserialize(serialized: &[String], pos: &mut usize) -> Option<Self>
    where
        T: FromStr,
    {
        let value = serialized.get(*pos)?.parse().ok()?;
        let child_count: usize = serialized.get(*pos + 1)?.parse().ok()?;
        *pos += 2;

        let mut children = Vec::new();
        for _ in 0..child_count {
            children.push(Self::deserialize(serialized, pos)?);
        }

        Some(TreeNode { value, children })
    }

    fn save(&self, path: &str) -> io::Result<()>
    where
        T: ToString,
    {
        fs::write(path, self.serialize().join("\n"))
    }

    fn load(path: &str) -> Option<Self>
    where
        T: FromStr,
    {
        let text = fs::read_to_string(path).ok()?;
        let serialized: Vec<String> = text.lines().map(String::from).collect();
        Self::deserialize(&serialized, &mut 0)
    }
}

fn main() -> io::Result<()> {
    let root = TreeNode {
        value: "root".to_string(),
        children: vec![
            TreeNode {
                value: "a".to_string(),
                children: vec![
                    TreeNode {
                        value: "a1".to_string(),
                        children: vec![],
                    },
                    TreeNode {
                        value: "a2".to_string(),
                        children: vec![],
                    },
                ],
            },
            TreeNode {
                value: "b".to_string(),
                children: vec![TreeNode {
                    value: "b1".to_string(),
                    children: vec![],
                }],
            },
        ],
    };

    root.save("tree.bin")?;

    let Some(loaded) = TreeNode::<String>::load("tree.bin") else {
        println!("invalid tree file");
        return Ok(());
    };

    for level in loaded.level_order() {
        println!("{:?}", level);
    }

    Ok(())
}

save joins the tokens with newlines and writes the file. load reads the file, splits it into lines, and starts reading at position 0 with &mut 0. main saves a tree, loads it back, and prints its levels to show the shape survived:

$ cargo run --bin tree_serializ_deserialize_into_file
["root"]
["a", "b"]
["a1", "a2", "b1"]

The format breaks if a value contains a newline, because the reader splits on newlines. For arbitrary text, write each value’s length before it, or use a serialization library such as serde.

11.6 A trie for finding words by prefix

A trie (usually pronounced “try”) stores a set of words by sharing their common beginnings. Each edge is one character. Walking from the root along the characters of a word leads to the node for that word. A flag on the node marks whether a stored word ends there (figure 11.7).

A prefix is the beginning of a word: "gp" is a prefix of "gpu". A trie answers “is any stored word starting with this prefix?” by walking the prefix’s characters. That makes it the usual structure behind autocompletion.

A trie is one root node. Each node maps a character to the child node for that character, and terminal marks a node where a stored word ends:

pub struct Trie {
    root: Node,
}

#[derive(Default)]
struct Node {
    children: HashMap<char, Node>,
    terminal: bool,
}

Listing 11.21 The complete file. src/problems/trie.rs

//! Trie / prefix tree.
//!
//! Used for autocomplete, command completion, and prefix matching.

use std::collections::HashMap;

#[derive(Default)]
pub struct Trie {
    root: Node,
}

#[derive(Default)]
struct Node {
    children: HashMap<char, Node>,
    terminal: bool,
}

impl Trie {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn insert(&mut self, word: &str) {
        let mut node = &mut self.root;
        for ch in word.chars() {
            node = node.children.entry(ch).or_default();
        }
        node.terminal = true;
    }

    pub fn search(&self, word: &str) -> bool {
        self.find_node(word)
            .is_some_and(|node| node.terminal)
    }

    pub fn starts_with(&self, prefix: &str) -> bool {
        self.find_node(prefix).is_some()
    }

    fn find_node(&self, word: &str) -> Option<&Node> {
        let mut node = &self.root;
        for ch in word.chars() {
            node = node.children.get(&ch)?;
        }
        Some(node)
    }
}

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

    #[test]
    fn trie_insert_search_and_prefix() {
        let mut trie = Trie::new();
        trie.insert("gpu");
        trie.insert("gpucloud");

        assert!(trie.search("gpu"));
        assert!(trie.search("gpucloud"));
        assert!(!trie.search("gp"));
        assert!(!trie.search("gpucloudapi"));

        assert!(trie.starts_with("gp"));
        assert!(trie.starts_with("gpucloud"));
        assert!(!trie.starts_with("cpu"));
    }
}

Each Node has a HashMap from a character to a child node, and a terminal flag. Both types derive Default, so an empty node is Node::default().

insert walks a mutable cursor, node, down the word, one character per line:

node = node.children.entry(ch).or_default();

entry(ch).or_default() finds the child for ch, creating an empty one if it is missing, and returns a mutable reference to it. Assigning that to node moves the cursor down one level. After the last character, the node is marked terminal.

find_node walks the same way without changing anything. node.children.get(&ch)? returns None from the function at the first missing character. search then checks that the node exists and is terminal, with is_some_and. starts_with only checks that the node exists.

Searching for a word of m characters takes m steps, whatever the number of stored words. A HashMap per node is flexible but uses a lot of memory. For words of lowercase English letters only, an array of 26 child pointers per node is faster and smaller.

Chapter 12 generalizes trees to graphs, where any node can connect to any other, and cycles are possible.

Exercises

1. Write an in-order traversal of the binary tree from listing 11.1 without recursion, using a Vec of references as a stack.
2. Add a height method to one of the BSTs. Insert the numbers 1 to 1,000 in order, then in shuffled order, and compare the heights.
3. Serialize a binary tree using a marker such as # for each empty child, and write the matching reader.
4. Add words_with_prefix(&self, prefix: &str) -> Vec<String> to the trie.

Graphs

In chapter 11, every node had exactly one parent, and no path could lead back to where it started. A graph drops both rules. Any node can connect to any other node, and a path can come back to its start.

Graphs describe many real systems. Roads between cities form a graph. So do links between web pages, and network links between machines. Courses and their prerequisites form a graph, and so do build steps and their inputs.

The freedom has a cost. A traversal that follows edges can reach the same node many times, or walk around a loop forever. Every algorithm in this chapter therefore keeps a record of which nodes it has already handled. The record is a Vec<bool>, a HashSet, or a HashMap of states.

12.1 Graph vocabulary

Figure 12.1 names the parts of a graph.

• A node, also called a vertex, is one of the things in the graph.
• An edge connects two nodes. In a directed graph, an edge goes one way, from one node to another. In an undirected graph, an edge works both ways, like a two-way road.
• The neighbors of a node are the nodes its edges lead to.
• A weight is a number on an edge, such as a distance or a cost.
• A path is a sequence of edges that you can follow one after another.
• A cycle is a path that ends at the node where it started.

A directed graph with no cycles is called a directed acyclic graph, or DAG. A tree is a special graph: it has no cycles, and every node except the root has exactly one parent.

12.2 Storing a graph

The most common way to store a graph is an adjacency list. For every node, you keep a list of its outgoing edges. Each edge is stored as a pair: the neighbor, and the weight of the edge.

The code in this chapter uses two forms of adjacency list (figure 12.2).

In the index form, the nodes are numbered 0, 1, 2, and so on. The graph is a Vec<Vec<(usize, u32)>>. graph[i] is the list of edges out of node i, and each edge is a (neighbor, weight) pair. Finding a node’s edges is one array index. The record of visited nodes can be a Vec<bool> with one entry per node.

In the map form, nodes can be any type that can be hashed, such as names. The graph is a HashMap from a node to its edges. Finding a node’s edges means hashing the key. The visited record becomes a HashSet.

The index form is faster, and the map form is more convenient when nodes have natural names. Several files in this chapter solve the same problem both ways, so you can compare them side by side.

The map form in graph_bfs.rs has a type alias:

use std::{
    collections::{HashMap, HashSet, VecDeque},
    hash::Hash,
};

/// Adjacency list keyed by node: each node maps to its `(neighbor, weight)` edges.
pub type GraphAdjList<'a, Node> = HashMap<Node, &'a [(Node, u32)]>;

GraphAdjList<'a, Node> is a HashMap whose values are borrowed slices, &'a [(Node, u32)]. The map does not own the edges. They live somewhere else for at least the lifetime 'a, and the map points at them. The tests keep the edges in constant arrays, which live for the whole program.

12.3 Breadth-first search

Breadth-first search (BFS) visits the start node first, then every node one edge away, then every node two edges away, and so on. It works the same way as the level-order tree traversal of section 11.4: a queue holds the nodes waiting to be visited.

Unlike a tree, a graph can offer two paths to the same node. In the sample graph, A reaches C directly, and also through B. Without a record, C would enter the queue twice. So BFS marks a node as seen when it first enters the queue, and never adds it again.

The top half of figure 12.3 follows the queue step by step.

12.3.1 BFS with numbered nodes

Listing 12.1 BFS over the index form (lines 18 to 36). src/problems/graph_bfs.rs

/// BFS over an index-based adjacency list. Returns nodes in visiting order.
pub fn bfs_vec(graph: &[Vec<(usize, u32)>], start_node: usize) -> Vec<usize> {
    let mut visited = vec![false; graph.len()];
    let mut queue = VecDeque::from([start_node]);
    let mut result = vec![];

    visited[start_node] = true;

    while let Some(current_node) = queue.pop_front() {
        result.push(current_node);
        for &(neighbor, _) in &graph[current_node] {
            if !visited[neighbor] {
                visited[neighbor] = true;
                queue.push_back(neighbor);
            }
        }
    }
    result
}

The function sets up three things. visited has one false per node. queue holds the start node. result collects the nodes in the order they are visited.

The loop takes the front node, records it, and looks at its edges. The pattern &(neighbor, _) takes each edge apart: it copies out the neighbor and ignores the weight with _. Each neighbor that has not been seen is marked and added to the back of the queue.

Every node enters the queue at most once, and every edge is looked at once. So BFS runs in O(V + E) time, where V is the number of nodes and E the number of edges. Nodes that cannot be reached from the start never enter the queue, and are not in the result.

12.3.2 BFS with any node type

Listing 12.2 BFS over the map form (lines 38 to 59).

/// BFS over a `HashMap` adjacency list. Returns nodes in visiting order.
pub fn bfs<Node>(graph: &GraphAdjList<Node>, start_node: Node) -> Vec<Node>
where
    Node: Copy + Eq + Hash,
{
    let mut visited = HashSet::new();
    let mut queue = VecDeque::from([start_node]);
    let mut result = vec![];

    visited.insert(start_node);

    while let Some(current_node) = queue.pop_front() {
        result.push(current_node);
        // slice iter yields &(Node, u32); `&` destructures it
        for &(neighbor, _) in graph[&current_node] {
            if visited.insert(neighbor) {
                queue.push_back(neighbor);
            }
        }
    }
    result
}

The steps are the same. Three things change:

• The function is generic over Node. The where clause asks for Copy, so a node can be copied into the queue and the result. It also asks for Eq + Hash, so a node can be a key in a HashSet.
• graph[&current_node] looks up the edges by key. Indexing a HashMap panics if the key is missing, so every node needs an entry, even a node with no edges.
• visited.insert(neighbor) does the check and the marking in one call. insert returns true if the value was not in the set before.

The tests at the end of the file build the sample graph in both forms and check that the two functions agree:

$ cargo test --lib problems::graph_bfs
running 5 tests
test problems::graph_bfs::tests::vec_variant_skips_unreachable_nodes ... ok
test problems::graph_bfs::tests::vec_variant_visits_level_by_level ... ok
test problems::graph_bfs::tests::vec_variant_handles_cycles ... ok
test problems::graph_bfs::tests::both_variants_agree ... ok
test problems::graph_bfs::tests::map_variant_visits_level_by_level ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 132 filtered out

Tests run in parallel, so the order of the lines can change from run to run.

12.4 Depth-first search

Depth-first search (DFS) follows one path as far as it can before it tries another. You can write it with recursion, as the tree traversals of chapter 11 were. The versions here use a Vec as an explicit stack instead. An explicit stack has no depth limit other than memory, while deep recursion can overflow the thread’s stack.

Listing 12.3 DFS over the index form (lines 16 to 33). src/problems/graph_dfs.rs

use std::{collections::HashSet, hash::Hash};

use crate::problems::graph_bfs::GraphAdjList;

/// DFS over an index-based adjacency list. Returns nodes in visiting order.
pub fn dfs_vec(graph: &[Vec<(usize, u32)>], start_node: usize) -> Vec<usize> {
    let mut visited = vec![false; graph.len()];
    let mut stack = vec![start_node];
    let mut result = vec![];

    while let Some(current_node) = stack.pop() {
        if visited[current_node] {
            continue;
        }
        visited[current_node] = true;
        result.push(current_node);
        for &(neighbor, _) in &graph[current_node] {
            stack.push(neighbor);
        }
    }
    result
}

Compare this with listing 12.1. The queue became a stack, so pop_front became pop. The other change is when a node is marked. BFS marked a node when it was added. DFS marks a node when it is taken off the stack, and skips it if it was already visited.

Marking late gives the true depth-first order, at a small cost. A node can sit on the stack more than once, as C and D do in the lower half of figure 12.3. The stack can hold up to one entry per edge, and the duplicates are skipped with continue when they come off.

The neighbors are pushed in list order, so the last neighbor pushed is the first taken. From A, the stack receives B and then C, so C is explored first. The visit order is A, C, D, B.

Listing 12.4 DFS over the map form (lines 35 to 54).

/// DFS over a `HashMap` adjacency list. Returns nodes in visiting order.
pub fn dfs<Node>(graph: &GraphAdjList<Node>, start_node: Node) -> Vec<Node>
where
    Node: Copy + Eq + Hash,
{
    let mut visited = HashSet::new();
    let mut stack = vec![start_node];
    let mut result = vec![];

    while let Some(current_node) = stack.pop() {
        if !visited.insert(current_node) {
            continue;
        }
        result.push(current_node);
        for &(neighbor, _) in graph[&current_node] {
            stack.push(neighbor);
        }
    }
    result
}

Here if !visited.insert(current_node) is the “already visited” check. If insert returns false, the node was in the set, and the loop moves on.

The file starts with use crate::problems::graph_bfs::GraphAdjList;, so both files share one type alias.

12.4.1 A stack of references

When the graph is a tree, DFS needs no visited record, because no node can be reached twice. The following program walks a tree with a stack of references.

Listing 12.5 The complete program. src/bin/rust_interview_hacks_graph.rs

#[derive(Debug)]
struct Node {
    value: i32,
    children: Vec<Node>,
}

fn visit_iter(root: &Node) {
    let mut stack = Vec::<&Node>::from([root]);

    while let Some(node) = stack.pop() {
        println!("{:?}", node);
        // Idiomatic and concise way to extend stack with neighbour iterator
        stack.extend(node.children.iter());
    }
}

fn main() {
    let tree = Node {
        value: 1,
        children: vec![
            Node {
                value: 2,
                children: vec![],
            },
            Node {
                value: 3,
                children: vec![Node {
                    value: 4,
                    children: vec![],
                }],
            },
        ],
    };

    visit_iter(&tree);
    println!("still own it: {}", tree.value); // tree wasn't moved
}

The stack has type Vec<&Node>. It holds borrowed references into the tree, so the loop moves no nodes and copies none. stack.extend(node.children.iter()) pushes a reference to each child. The last line of main uses tree.value after the walk, which shows that tree still owns its nodes.

$ cargo run --bin rust_interview_hacks_graph
Node { value: 1, children: [Node { value: 2, children: [] }, Node { value: 3, children: [Node { value: 4, children: [] }] }] }
Node { value: 3, children: [Node { value: 4, children: [] }] }
Node { value: 4, children: [] }
Node { value: 2, children: [] }
still own it: 1

{:?} prints each node with all its children, so the first line shows the whole tree. The order is 1, 3, 4, 2, because the last child pushed is the first popped.

12.5 A graph with named nodes

Programs often receive a graph as pairs of names, such as ("A", "B"). A common way to handle names is to give each name a number the first time you see it. The algorithm then runs on numbers, with the fast index form. Assigning numbers to names this way is called interning.

The graph keeps two things: ids, which interns each name as a number, and adj, the adjacency list indexed by those numbers:

use std::collections::{HashMap, HashSet, VecDeque};

#[derive(Default)]
struct Graph {
    ids: HashMap<String, usize>,
    adj: Vec<Vec<usize>>,
}

Listing 12.6 The complete program. src/bin/graph_bfs.rs

use std::collections::{HashMap, HashSet, VecDeque};

#[derive(Default)]
struct Graph {
    ids: HashMap<String, usize>,
    adj: Vec<Vec<usize>>,
}

impl Graph {
    fn id(&mut self, name: &str) -> usize {
        *self
            .ids
            .entry(name.to_owned())
            .or_insert_with(|| {
                self.adj.push(vec![]);
                self.adj.len() - 1
            })
    }

    fn add_edge(&mut self, from: &str, to: &str) {
        let (u, v) = (self.id(from), self.id(to));
        self.adj[u].push(v);
    }

    fn bfs(&self, start: &str) -> Vec<usize> {
        let mut visited = HashSet::new();
        let mut queue = VecDeque::from([self.ids[start]]);
        let mut order = Vec::new();

        while let Some(node) = queue.pop_front() {
            if !visited.insert(node) {
                continue;
            }
            order.push(node);
            queue.extend(self.adj[node].iter());
        }
        order
    }
}

fn main() {
    let mut g = Graph::default();
    g.add_edge("A", "B");
    g.add_edge("A", "C");
    g.add_edge("B", "D");
    g.add_edge("C", "E");
    g.add_edge("D", "F");

    println!("{:?}", g.bfs("A")); // [0, 1, 2, 3, 4, 5]
}

Graph has two fields. ids maps a name to its number, and adj is an index-form adjacency list without weights.

The id method does the interning in one expression. self.ids.entry(name.to_owned()) looks up the name. or_insert_with runs its closure only if the name is new. The closure adds an empty edge list to adj and returns its index, which becomes the name’s number. Either way, the expression returns a reference to the number, and the * at the front copies it out.

The closure changes self.adj while self.ids is borrowed by the entry. The compiler allows this because a closure borrows only the fields it uses, here self.adj. The two borrows touch different fields, so they do not conflict.

This bfs marks nodes when they leave the queue, as the DFS of section 12.4 did. A node can enter the queue more than once, and the second copy is skipped. queue.extend(self.adj[node].iter()) adds all neighbors at once.

$ cargo run --bin graph_bfs
[0, 1, 2, 3, 4, 5]

The result is numbers, not names. A to F were numbered 0 to 5 in the order they first appeared.

12.6 Finding cycles

Many problems need to know whether a directed graph has a cycle. A build system cannot build a file that depends on itself. A course plan cannot require a course before itself.

A visited flag is not enough to find cycles. Look at the diamond on the right of figure 12.4. DFS reaches D through B, and later reaches D again through C. That second visit does not mean there is a loop. It only means two paths join.

The fix is to give each node one of three states:

• Unvisited: DFS has not reached the node yet.
• Visiting: the node is on the path DFS is currently following. DFS has entered it and not yet finished it.
• Done: DFS has explored everything reachable from the node.

An edge that leads to a Visiting node goes back to an earlier point on the current path, so it closes a loop. Such an edge is called a back edge. An edge that leads to a Done node joins a path that was already fully explored, and cannot close a loop.

12.6.1 A graph that owns its node data

Listing 12.7 The graph and its states (lines 1 to 30). src/bin/cyclic_graph.rs

use std::collections::VecDeque;

type NodeId = usize;

struct Graph<T> {
    nodes: Vec<T>,
    adj: Vec<Vec<NodeId>>, // adj[i] = nodes that i points to
}

#[derive(Clone, Copy)]
enum State {
    Unvisited,
    Visiting,
    Done,
}

impl<T> Graph<T> {
    fn new() -> Self {
        Self {
            nodes: Vec::new(),
            adj: Vec::new(),
        }
    }

    fn add_node(&mut self, data: T) -> NodeId {
        self.nodes.push(data);
        self.adj.push(Vec::new());
        self.nodes.len() - 1
    }

    fn add_edge(&mut self, from: NodeId, to: NodeId) {
        self.adj[from].push(to);
    }

    fn neighbors(&self, id: NodeId) -> impl Iterator<Item = NodeId> + '_ {
        self.adj[id].iter().copied()
    }
    // ...
}

This Graph<T> keeps the node data in nodes, and the edges in adj, as numbers. NodeId is a type alias for usize, so signatures say what a number means. add_node returns the new node’s number, and the caller uses that number to add edges.

Storing numbers instead of references is the usual way to build graphs in Rust. A cycle of references between nodes would need Rc and RefCell, as chapter 9’s doubly linked list did. Numbers into a Vec have no ownership problems at all.

neighbors returns impl Iterator<Item = NodeId> + '_. That return type means “some iterator of node numbers”. The + '_ says the iterator borrows from self, so it cannot outlive the graph. .copied() turns the &usize items of the slice iterator into usize values.

Listing 12.8 BFS and DFS (lines 39 to 74).

impl<T> Graph<T> {
    // ...
    fn bfs(&self, start: NodeId) -> Vec<NodeId> {
        let mut visited = vec![false; self.nodes.len()];
        let mut queue = VecDeque::from([start]);
        let mut order = Vec::new();
        visited[start] = true;

        while let Some(node) = queue.pop_front() {
            order.push(node);
            for next in self.neighbors(node) {
                if !visited[next] {
                    visited[next] = true;
                    queue.push_back(next);
                }
            }
        }
        order
    }

    fn dfs(&self, start: NodeId) -> Vec<NodeId> {
        let mut visited = vec![false; self.nodes.len()];
        let mut stack = vec![start];
        let mut order = Vec::new();

        while let Some(node) = stack.pop() {
            if visited[node] {
                continue;
            }
            visited[node] = true;
            order.push(node);
            stack.extend(
                self.neighbors(node)
                    .filter(|&n| !visited[n]),
            );
        }
        order
    }
    // ...
}

These are the algorithms of sections 12.3 and 12.4, written with neighbors. The DFS filters out visited neighbors before pushing them, with .filter(|&n| !visited[n]). The filter keeps the stack smaller, but the check after pop is still needed. A node can be pushed by two different nodes before either copy is popped.

Listing 12.9 Cycle detection (lines 76 to 94).

impl<T> Graph<T> {
    // ...
    fn has_cycle(&self) -> bool {
        let mut state = vec![State::Unvisited; self.nodes.len()];
        (0..self.nodes.len()).any(|n| self.visit(n, &mut state))
    }

    fn visit(&self, node: NodeId, state: &mut [State]) -> bool {
        match state[node] {
            State::Visiting => true, // back edge: cycle found
            State::Done => false,
            State::Unvisited => {
                state[node] = State::Visiting;
                let found = self.adj[node]
                    .iter()
                    .any(|&n| self.visit(n, state));
                state[node] = State::Done;
                found
            }
        }
    }
}

visit is a recursive DFS that returns true as soon as it finds a cycle. It reads the node’s state:

• Visiting means this edge is a back edge, so the answer is true.
• Done means the node was explored before and no cycle was found through it, so the answer is false.
• Unvisited means this is the first visit. The node becomes Visiting, and visit recurses into each neighbor. any stops at the first neighbor that reports a cycle. Then the node becomes Done.

has_cycle calls visit from every node, because a cycle might not be reachable from node 0. All the calls share one state vector, so each node is fully explored only once, and the whole check runs in O(V + E).

Listing 12.10 The complete program. src/bin/cyclic_graph.rs

use std::collections::VecDeque;

type NodeId = usize;

struct Graph<T> {
    nodes: Vec<T>,
    adj: Vec<Vec<NodeId>>, // adj[i] = nodes that i points to
}

#[derive(Clone, Copy)]
enum State {
    Unvisited,
    Visiting,
    Done,
}

impl<T> Graph<T> {
    fn new() -> Self {
        Self {
            nodes: Vec::new(),
            adj: Vec::new(),
        }
    }

    fn add_node(&mut self, data: T) -> NodeId {
        self.nodes.push(data);
        self.adj.push(Vec::new());
        self.nodes.len() - 1
    }

    fn add_edge(&mut self, from: NodeId, to: NodeId) {
        self.adj[from].push(to);
    }

    fn neighbors(&self, id: NodeId) -> impl Iterator<Item = NodeId> + '_ {
        self.adj[id].iter().copied()
    }

    fn bfs(&self, start: NodeId) -> Vec<NodeId> {
        let mut visited = vec![false; self.nodes.len()];
        let mut queue = VecDeque::from([start]);
        let mut order = Vec::new();
        visited[start] = true;

        while let Some(node) = queue.pop_front() {
            order.push(node);
            for next in self.neighbors(node) {
                if !visited[next] {
                    visited[next] = true;
                    queue.push_back(next);
                }
            }
        }
        order
    }

    fn dfs(&self, start: NodeId) -> Vec<NodeId> {
        let mut visited = vec![false; self.nodes.len()];
        let mut stack = vec![start];
        let mut order = Vec::new();

        while let Some(node) = stack.pop() {
            if visited[node] {
                continue;
            }
            visited[node] = true;
            order.push(node);
            stack.extend(
                self.neighbors(node)
                    .filter(|&n| !visited[n]),
            );
        }
        order
    }

    fn has_cycle(&self) -> bool {
        let mut state = vec![State::Unvisited; self.nodes.len()];
        (0..self.nodes.len()).any(|n| self.visit(n, &mut state))
    }

    fn visit(&self, node: NodeId, state: &mut [State]) -> bool {
        match state[node] {
            State::Visiting => true, // back edge: cycle found
            State::Done => false,
            State::Unvisited => {
                state[node] = State::Visiting;
                let found = self.adj[node]
                    .iter()
                    .any(|&n| self.visit(n, state));
                state[node] = State::Done;
                found
            }
        }
    }
}

fn main() {
    let mut g = Graph::new();
    let a = g.add_node("A");
    let b = g.add_node("B");
    let c = g.add_node("C");

    g.add_edge(a, b);
    g.add_edge(b, c);
    g.add_edge(c, a); // closes the cycle

    let names = |ids: Vec<NodeId>| -> Vec<&str> {
        ids.into_iter()
            .map(|i| g.nodes[i])
            .collect()
    };

    println!("BFS:   {:?}", names(g.bfs(a))); // ["A", "B", "C"]
    println!("DFS:   {:?}", names(g.dfs(a))); // ["A", "B", "C"]
    println!("Cycle: {}", g.has_cycle()); // true
}

main builds the loop A to B to C to A. The closure names converts a list of numbers back into names for printing.

$ cargo run --bin cyclic_graph
BFS:   ["A", "B", "C"]
DFS:   ["A", "B", "C"]
Cycle: true

12.6.2 The same graph with a HashMap

The second version stores the graph as a map from a node to its neighbors, with no numbering step.

The cycle check marks each node with a State: Visiting while its descendants are being explored, and Done after. The graph is a map from a node to its neighbors, generic over any Copy node type:

#[derive(Clone, Copy)]
enum State {
    Visiting,
    Done,
}

#[derive(Default)]
struct Graph<T> {
    adj: HashMap<T, Vec<T>>,
}

Listing 12.11 The complete program. src/bin/cyclic_graph_map.rs

use std::{
    collections::{HashMap, HashSet, VecDeque},
    hash::Hash,
};

#[derive(Clone, Copy)]
enum State {
    Visiting,
    Done,
}

#[derive(Default)]
struct Graph<T> {
    adj: HashMap<T, Vec<T>>,
}

impl<T: Copy + Eq + Hash> Graph<T> {
    fn add_edge(&mut self, u: T, v: T) {
        self.adj.entry(v).or_default();
        self.adj.entry(u).or_default().push(v);
    }

    fn bfs(&self, start: T) -> Vec<T> {
        let mut seen = HashSet::from([start]);
        let mut queue = VecDeque::from([start]);
        let mut order = vec![];

        while let Some(u) = queue.pop_front() {
            order.push(u);
            for &v in &self.adj[&u] {
                if seen.insert(v) {
                    queue.push_back(v);
                }
            }
        }
        order
    }

    fn has_cycle(&self) -> bool {
        fn dfs<T: Copy + Eq + Hash>(g: &Graph<T>, u: T, state: &mut HashMap<T, State>) -> bool {
            match state.get(&u) {
                Some(State::Visiting) => return true,
                Some(State::Done) => return false,
                None => {}
            }

            state.insert(u, State::Visiting);
            let found = g.adj[&u]
                .iter()
                .any(|&v| dfs(g, v, state));
            state.insert(u, State::Done);
            found
        }

        let mut state = HashMap::new();
        self.adj
            .keys()
            .any(|&u| dfs(self, u, &mut state))
    }
}

fn main() {
    let mut g = Graph::default();
    g.add_edge("A", "B");
    g.add_edge("B", "C");
    g.add_edge("C", "A");

    println!("{:?}", g.bfs("A"));
    println!("{}", g.has_cycle()); // true
}

Three details differ from listing 12.10:

• State has only Visiting and Done. A node that is not in the state map is unvisited, so the map itself plays the role of the third state.
• add_edge inserts the target v as a key too, with entry(v).or_default(). Every node therefore has an entry, and self.adj[&u] cannot panic on a node that has no outgoing edges.
• The recursive helper is a function declared inside has_cycle. A nested fn cannot use the local variables of the function around it, so it receives the graph and the state map as arguments.

$ cargo run --bin cyclic_graph_map
["A", "B", "C"]
true

12.7 A grid is a graph

A grid of cells is a graph too, even though it is not stored as one. Each cell is a node, and each cell has an edge to the cells directly above, below, left, and right of it. The edges are computed from the coordinates when needed, not stored.

The classic grid problem counts islands. The grid holds land and water. An island is a group of land cells connected up, down, left, or right. Diagonal neighbors do not count.

The method is to scan every cell. When the scan finds a land cell that no earlier search has reached, that cell starts a new island. The count goes up by one, and a BFS from that cell marks every cell of the island. Filling a connected area this way is called a flood fill (figure 12.5).

Listing 12.12 Counting islands (lines 27 to 72). src/bin/count_islands.rs

use std::collections::{HashSet, VecDeque};

fn count_islands<T: PartialEq>(grid: &[&[T]], land: T) -> usize {
    if grid.is_empty() || grid[0].is_empty() {
        return 0;
    }

    let rows = grid.len();
    let cols = grid[0].len();
    let mut visited = HashSet::new();
    let mut count = 0;
    let dirs = [(0, 1), (1, 0), (0, -1), (-1, 0)];

    // BFS closure: flood-fill one island starting from a known land cell.
    // Passing `visited` explicitly avoids borrow-checker friction when calling
    // the closure from the outer loop.
    let bfs = |start: (usize, usize), visited: &mut HashSet<(usize, usize)>| {
        let mut queue = VecDeque::new();
        queue.push_back(start);
        visited.insert(start);

        while let Some((cr, cc)) = queue.pop_front() {
            for &(dr, dc) in &dirs {
                let nr = cr as i32 + dr;
                let nc = cc as i32 + dc;

                if (0..rows as i32).contains(&nr) && (0..cols as i32).contains(&nc) {
                    let (ur, uc) = (nr as usize, nc as usize);
                    if grid[ur][uc] == land && !visited.contains(&(ur, uc)) {
                        visited.insert((ur, uc));
                        queue.push_back((ur, uc));
                    }
                }
            }
        }
    };

    for r in 0..rows {
        for c in 0..cols {
            if grid[r][c] == land && !visited.contains(&(r, c)) {
                count += 1;
                bfs((r, c), &mut visited);
            }
        }
    }

    count
}

The grid has type &[&[T]], a slice of rows, where each row is a slice of cells. The function is generic, so cells can be characters, booleans, or numbers. land: T says which value counts as land, and T: PartialEq lets the code compare a cell with it.

dirs lists the four moves as (row change, column change) pairs. The BFS adds each move to the current cell’s coordinates. The coordinates are usize, which cannot be negative, and a move up from row 0 would go below zero. So the code converts to i32 first. It checks that the new position is inside the grid with (0..rows as i32).contains(&nr), and only then converts back to usize.

The BFS is a closure stored in bfs. It reads grid, dirs, rows, cols, and land from the function around it. It does not capture visited, though. It takes visited as a parameter instead. If the closure captured visited mutably, that borrow would last as long as the closure. The outer loop could then not call visited.contains while the closure exists. Passing it in on each call keeps the borrow short.

Each cell is looked at a constant number of times, so the function runs in O(rows × cols). A Vec<bool> with one entry per cell would be faster than the HashSet of coordinates, because it avoids hashing.

Listing 12.13 The complete program, with tests. src/bin/count_islands.rs

// ============================================================================
// Count Islands
//
// Ported from the Rust playground repo.
//
// Problem: given a grid of cells, count the number of connected "land"
// regions. Two land cells are connected when they are adjacent horizontally
// or vertically (4-directional). Water cells are not traversable.
//
// Where this shape appears in practice:
//   - "Islands" are connected-component counting, the same shape used to find
//     connected machines, failure domains, network partitions, or storage
//     groups in distributed systems.
//   - The generic implementation accepts any land type (char, u8, bool) and
//     uses BFS with an explicit visited set, which is easy to reason about.
//
// Time complexity: O(rows * cols)
// Space complexity: O(rows * cols) for the visited set and BFS queue.
// ============================================================================

use std::collections::{HashSet, VecDeque};

/// Counts 4-directionally connected components of `land` in a rectangular grid.
///
/// The grid is generic over cell values so callers can use `'1'/'0'`,
/// `true/false`, `1u8/0u8`, or any other PartialEq value.
fn count_islands<T: PartialEq>(grid: &[&[T]], land: T) -> usize {
    if grid.is_empty() || grid[0].is_empty() {
        return 0;
    }

    let rows = grid.len();
    let cols = grid[0].len();
    let mut visited = HashSet::new();
    let mut count = 0;
    let dirs = [(0, 1), (1, 0), (0, -1), (-1, 0)];

    // BFS closure: flood-fill one island starting from a known land cell.
    // Passing `visited` explicitly avoids borrow-checker friction when calling
    // the closure from the outer loop.
    let bfs = |start: (usize, usize), visited: &mut HashSet<(usize, usize)>| {
        let mut queue = VecDeque::new();
        queue.push_back(start);
        visited.insert(start);

        while let Some((cr, cc)) = queue.pop_front() {
            for &(dr, dc) in &dirs {
                let nr = cr as i32 + dr;
                let nc = cc as i32 + dc;

                if (0..rows as i32).contains(&nr) && (0..cols as i32).contains(&nc) {
                    let (ur, uc) = (nr as usize, nc as usize);
                    if grid[ur][uc] == land && !visited.contains(&(ur, uc)) {
                        visited.insert((ur, uc));
                        queue.push_back((ur, uc));
                    }
                }
            }
        }
    };

    for r in 0..rows {
        for c in 0..cols {
            if grid[r][c] == land && !visited.contains(&(r, c)) {
                count += 1;
                bfs((r, c), &mut visited);
            }
        }
    }

    count
}

// ============================================================================
// Runnable demonstration
// ============================================================================
fn main() {
    let grid = [
        &['1', '1', '0', '0', '0'][..],
        &['1', '1', '0', '0', '0'][..],
        &['0', '0', '1', '0', '0'][..],
        &['0', '0', '0', '1', '1'][..],
    ];

    println!("Islands: {}", count_islands(&grid, '1'));

    let boolean_grid = [
        &[true, true, false][..],
        &[false, false, false][..],
        &[false, true, true][..],
    ];
    println!("Boolean islands: {}", count_islands(&boolean_grid, true));
}

// ============================================================================
// Tests (cargo test --bin count_islands)
// ============================================================================
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn empty_grid_has_zero_islands() {
        let empty: [&[char]; 0] = [];
        assert_eq!(count_islands(&empty, '1'), 0);

        let no_cols: [&[char]; 2] = [&[], &[]];
        assert_eq!(count_islands(&no_cols, '1'), 0);
    }

    #[test]
    fn counts_classic_example() {
        let grid = [
            &['1', '1', '0', '0', '0'][..],
            &['1', '1', '0', '0', '0'][..],
            &['0', '0', '1', '0', '0'][..],
            &['0', '0', '0', '1', '1'][..],
        ];
        assert_eq!(count_islands(&grid, '1'), 3);
    }

    #[test]
    fn all_water_is_zero() {
        let grid = [&['0', '0'][..], &['0', '0'][..]];
        assert_eq!(count_islands(&grid, '1'), 0);
    }

    #[test]
    fn generic_bool_grid_works() {
        let grid = [
            &[true, false, false][..],
            &[true, false, true][..],
            &[false, false, true][..],
        ];
        assert_eq!(count_islands(&grid, true), 2);
    }

    #[test]
    fn single_row_and_column() {
        let row = [&['1', '0', '1', '1'][..]];
        assert_eq!(count_islands(&row, '1'), 2);

        let col = [&['1'][..], &['1'][..], &['0'][..], &['1'][..]];
        assert_eq!(count_islands(&col, '1'), 2);
    }
}

$ cargo run --bin count_islands
Islands: 3
Boolean islands: 2

$ cargo test --bin count_islands
running 5 tests
test tests::empty_grid_has_zero_islands ... ok
test tests::all_water_is_zero ... ok
test tests::generic_bool_grid_works ... ok
test tests::single_row_and_column ... ok
test tests::counts_classic_example ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

12.8 Putting tasks in order

Suppose you have tasks, and some tasks must finish before others can start. A topological order lists every task so that each one comes after all of its prerequisites. Build tools, package managers, and course planners all compute one.

Draw an arrow from each task to the tasks that depend on it. The indegree of a node is the number of arrows coming into it: the number of prerequisites it is still waiting for.

Kahn’s algorithm builds the order step by step (figure 12.6):

1. Put every node with indegree 0 in a queue. They have no prerequisites.
2. Take a node from the queue and add it to the order.
3. For each arrow out of that node, lower the target’s indegree by one. The target has one fewer prerequisite to wait for. If its indegree reaches 0, add it to the queue.
4. Repeat until the queue is empty.

If the graph has a cycle, the nodes on the cycle wait for each other forever. Their indegrees never reach 0, so they never enter the order. The order then comes out shorter than the number of nodes, and that is how the algorithm detects a cycle.

12.8.1 Kahn’s algorithm on numbered nodes

The input is a node count and a slice of (from, to) edges. The first step builds the adjacency list and counts each node’s indegree at the same time:

use std::collections::VecDeque;

pub fn topological_sort(num_nodes: usize, edges: &[(usize, usize)]) -> Option<Vec<usize>> {
    let mut graph = vec![Vec::new(); num_nodes];
    let mut indegree = vec![0usize; num_nodes];

    for &(from, to) in edges {
        graph[from].push(to);
        indegree[to] += 1;
    }
    // ...
}

The starting queue comes from one iterator chain:

pub fn topological_sort(num_nodes: usize, edges: &[(usize, usize)]) -> Option<Vec<usize>> {
    // ...
    let mut queue: VecDeque<usize> = (0..num_nodes)
        .filter(|&n| indegree[n] == 0)
        .collect();
    let mut order = Vec::with_capacity(num_nodes);
    // ...
}

(0..num_nodes) produces every node number. .filter(|&n| indegree[n] == 0) keeps the nodes with no prerequisites, and .collect() builds the VecDeque.

The loop is Kahn’s algorithm itself:

pub fn topological_sort(num_nodes: usize, edges: &[(usize, usize)]) -> Option<Vec<usize>> {
    // ...
    while let Some(node) = queue.pop_front() {
        order.push(node);

        for &next in &graph[node] {
            indegree[next] -= 1;
            if indegree[next] == 0 {
                queue.push_back(next);
            }
        }
    }

    (order.len() == num_nodes).then_some(order)
}

Each node taken from the queue goes into order. Removing it removes its outgoing edges, so each neighbor’s indegree drops by one. A neighbor whose indegree reaches 0 has no prerequisites left, and joins the queue.

The last line returns the answer. bool::then_some(order) gives Some(order) if the condition is true, and None if it is false. So the function returns None exactly when a cycle kept some nodes out of the order. The nodes on a cycle never reach indegree 0.

Listing 12.14 The complete file. src/problems/graph_topology.rs

//! Topological sort (Kahn's algorithm).
//!
//! Common in scheduling problems: prerequisite graphs, pipeline
//! stages, and build or job dependency ordering.

use std::collections::VecDeque;

pub fn topological_sort(num_nodes: usize, edges: &[(usize, usize)]) -> Option<Vec<usize>> {
    let mut graph = vec![Vec::new(); num_nodes];
    let mut indegree = vec![0usize; num_nodes];

    for &(from, to) in edges {
        graph[from].push(to);
        indegree[to] += 1;
    }

    let mut queue: VecDeque<usize> = (0..num_nodes)
        .filter(|&n| indegree[n] == 0)
        .collect();
    let mut order = Vec::with_capacity(num_nodes);

    while let Some(node) = queue.pop_front() {
        order.push(node);

        for &next in &graph[node] {
            indegree[next] -= 1;
            if indegree[next] == 0 {
                queue.push_back(next);
            }
        }
    }

    (order.len() == num_nodes).then_some(order)
}

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

    #[test]
    fn returns_order_for_dag() {
        // 0 -> 1, 0 -> 2, 1 -> 3, 2 -> 3
        let edges = [(0, 1), (0, 2), (1, 3), (2, 3)];
        let order = topological_sort(4, &edges).expect("DAG has an order");
        assert_eq!(order.len(), 4);
        assert!(
            order
                .iter()
                .position(|&n| n == 0)
                .unwrap()
                < order
                    .iter()
                    .position(|&n| n == 1)
                    .unwrap()
        );
        assert!(
            order
                .iter()
                .position(|&n| n == 1)
                .unwrap()
                < order
                    .iter()
                    .position(|&n| n == 3)
                    .unwrap()
        );
    }

    #[test]
    fn detects_cycle() {
        // 0 -> 1 -> 0 is a cycle.
        let edges = [(0, 1), (1, 0)];
        assert_eq!(topological_sort(2, &edges), None);
    }

    #[test]
    fn disconnected_nodes_are_included() {
        let edges = [(0, 1)];
        let order = topological_sort(3, &edges).expect("DAG has an order");
        assert_eq!(order.len(), 3);
    }
}

The tests check positions rather than one exact order. A graph usually has several valid topological orders, and the tests only require that each edge’s source comes before its target.

$ cargo test --lib problems::graph_topology
running 3 tests
test problems::graph_topology::tests::disconnected_nodes_are_included ... ok
test problems::graph_topology::tests::returns_order_for_dag ... ok
test problems::graph_topology::tests::detects_cycle ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 134 filtered out

12.8.2 Kahn’s algorithm on named courses

The second version takes courses with names and lists of prerequisites, the way the data might arrive from a file.

A course has a name and a list of prerequisites, the names of the courses that must come before it:

use std::collections::{HashMap, VecDeque};

#[derive(Clone)]
struct Course {
    name: String,
    depends_on: Vec<String>,
}

Listing 12.15 The complete program. src/bin/dependency_resolutiom.rs

use std::collections::{HashMap, VecDeque};

#[derive(Clone)]
struct Course {
    name: String,
    depends_on: Vec<String>,
}

fn topo_sort(courses: &[Course]) -> Vec<String> {
    let mut adj: HashMap<String, Vec<String>> = HashMap::new();
    let mut indegree: HashMap<String, usize> = HashMap::new();

    for Course { name, depends_on } in courses {
        indegree.insert(name.clone(), depends_on.len());
        adj.entry(name.clone()).or_default();
        for dep in depends_on {
            adj.entry(dep.clone())
                .or_default()
                .push(name.clone());
            indegree.entry(dep.clone()).or_insert(0);
        }
    }

    let mut queue: VecDeque<_> = indegree
        .iter()
        .filter(|&(_, deg)| *deg == 0)
        .map(|(name, _)| name.clone())
        .collect();

    let mut order = Vec::new();
    while let Some(node) = queue.pop_front() {
        for next in &adj[&node] {
            let d = indegree.get_mut(next).unwrap();
            *d -= 1;
            if *d == 0 {
                queue.push_back(next.clone());
            }
        }
        order.push(node);
    }

    if order.len() == indegree.len() {
        order
    } else {
        Vec::new()
    }
}

fn main() {
    let courses = vec![
        Course {
            name: "algos".into(),
            depends_on: vec!["datastructs".into()],
        },
        Course {
            name: "compilers".into(),
            depends_on: vec!["algos".into(), "os".into()],
        },
        Course {
            name: "os".into(),
            depends_on: vec!["datastructs".into()],
        },
    ];

    println!("{:?}", topo_sort(&courses));
}

The input describes edges backward from the way the algorithm needs them. Each course lists its prerequisites, but Kahn’s algorithm follows arrows from a prerequisite to the courses that need it. The loop turns them around. For each prerequisite dep of course name, it adds name to adj[dep].

A course’s indegree is the length of its depends_on list. A prerequisite that is never listed as a course, like datastructs here, still needs an entry. indegree.entry(dep.clone()).or_insert(0) adds it with indegree 0, and or_insert leaves an existing entry alone.

for Course { name, depends_on } in courses takes each course apart in the loop header. Because courses is a slice reference, name and depends_on are references to the fields.

If a cycle keeps some courses out of the order, the function returns an empty Vec. With Option as in listing 12.14, the caller could tell “no courses” from “a cycle”.

$ cargo run --bin dependency_resolutiom
["datastructs", "algos", "os", "compilers"]

The starting queue is built by iterating over a HashMap, and that order changes between runs. This input has only one course with no prerequisites, so the output is always the same. With several such courses, the order among them could change from run to run.

12.9 Shortest paths

In a weighted graph, the cost of a path is the sum of its edge weights. The shortest path from A to D is the path with the lowest cost. It is not always the one with the fewest edges.

BFS finds the path with the fewest edges, which is a different question. Dijkstra’s algorithm finds the lowest cost from one start node to every other node, as long as no weight is negative.

12.9.1 How Dijkstra’s algorithm works

The algorithm keeps two things:

• dist, the lowest cost found so far to each node. At the start, only the start node has a cost, 0.
• A min-heap of (cost, node) entries, so the cheapest entry is always taken next. Chapter 5 built min-heaps with BinaryHeap and Reverse.

Each step takes the cheapest entry from the heap. For each edge out of that node, it computes the cost of reaching the neighbor through this node. If that cost beats the neighbor’s recorded cost, the new cost is recorded and pushed onto the heap. Updating a recorded cost to a lower one is called relaxing the edge.

When a node is taken from the heap with its recorded cost, that cost is final. Every other entry in the heap costs at least as much, and weights are never negative. So no path found later can come back cheaper.

A node can be in the heap several times. When a cheaper path to B is found, the old entry for B stays in the heap. BinaryHeap has no way to find and update it. When the old entry is eventually taken, its cost is higher than B’s recorded cost, and the code skips it. Such an entry is called stale.

Figure 12.7 follows every step on a four-node graph.

Read the table row by row. Taking A records B at 4 and C at 1. Taking C finds B at 1 + 2 = 3, which beats 4, so B is recorded at 3 and pushed again. The old (4, B) entry is now stale. Taking B at 3 finds D at 4, which beats the 6 recorded through C. Later, (4, B) and (6, D) come off the heap, and each is skipped because its cost is higher than the recorded one.

12.9.2 Two versions side by side

Listing 12.16 Dijkstra over the index form (lines 23 to 44). src/problems/graph_dijkstra.rs

use std::{
    cmp::Reverse,
    collections::{BinaryHeap, HashMap},
    hash::Hash,
};

use crate::problems::graph_bfs::GraphAdjList;

/// Shortest distances from `start_node` over an index-based adjacency list.
pub fn dijkstra_vec(graph: &[Vec<(usize, u32)>], start_node: usize) -> Vec<Option<u32>> {
    let mut distances = vec![None; graph.len()];
    let mut min_heap = BinaryHeap::from([Reverse((0, start_node))]);

    distances[start_node] = Some(0);

    while let Some(Reverse((current_cost, current_node))) = min_heap.pop() {
        // stale heap entry, a shorter path was already recorded
        if distances[current_node].is_some_and(|best| current_cost > best) {
            continue;
        }
        for &(neighbor, weight) in &graph[current_node] {
            let new_distance = current_cost + weight;
            if distances[neighbor].is_none_or(|best| new_distance < best) {
                distances[neighbor] = Some(new_distance);
                min_heap.push(Reverse((new_distance, neighbor)));
            }
        }
    }
    distances
}

The distances are a Vec<Option<u32>>, where None means “no path found yet”. Two methods of Option read well here:

• is_some_and(|best| current_cost > best) is true only if there is a recorded cost and the popped cost is higher. That is the stale check.
• is_none_or(|best| new_distance < best) is true if there is no recorded cost, or the new cost is lower. That is the relax check.

The heap holds Reverse((cost, node)). BinaryHeap pops the largest item, and Reverse flips the comparison, so the smallest cost comes out first. Tuples compare by their first field, then by their second, so the cost decides and the node number breaks ties.

Listing 12.17 Dijkstra over the map form (lines 46 to 73).

/// Shortest distances from `start_node` over a `HashMap` adjacency list.
pub fn dijkstra<Node>(graph: &GraphAdjList<Node>, start_node: Node) -> HashMap<Node, u32>
where
    Node: Copy + Eq + Hash + Ord,
{
    let mut distances = HashMap::from([(start_node, 0)]);
    let mut min_heap = BinaryHeap::from([Reverse((0, start_node))]);

    while let Some(Reverse((current_cost, current_node))) = min_heap.pop() {
        // stale heap entry, a shorter path was already recorded
        if current_cost > distances[&current_node] {
            continue;
        }
        for &(neighbor, weight) in graph[&current_node] {
            let new_distance = current_cost + weight;

            if new_distance
                < *distances
                    .get(&neighbor)
                    .unwrap_or(&u32::MAX)
            {
                distances.insert(neighbor, new_distance);
                min_heap.push(Reverse((new_distance, neighbor)));
            }
        }
    }
    distances
}

In this version, distances is a HashMap that contains only nodes that have been reached. Node also needs Ord, because nodes sit inside the tuples that the heap compares.

distances[&current_node] cannot panic here. A node is pushed onto the heap only after its distance is inserted, so every popped node has an entry. distances.get(&neighbor).unwrap_or(&u32::MAX) treats a missing entry as the largest possible cost, so any real cost beats it.

Each edge can push one heap entry, and each heap operation takes O(log E). The whole algorithm runs in O(E log E), which is the same as O(E log V) for simple graphs.

$ cargo test --lib problems::graph_dijkstra
running 4 tests
test problems::graph_dijkstra::tests::vec_variant_finds_shorter_multi_hop_paths ... ok
test problems::graph_dijkstra::tests::vec_variant_marks_unreachable_nodes ... ok
test problems::graph_dijkstra::tests::map_variant_omits_unreachable_nodes ... ok
test problems::graph_dijkstra::tests::map_variant_finds_shorter_multi_hop_paths ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 133 filtered out

12.9.3 Edges as a struct

The next three programs use a named Edge struct instead of a (neighbor, weight) tuple, and u64 costs. They show three steps of the same function: it first clones node names, then borrows them, and finally handles missing nodes and overflow.

An Edge holds the node it leads to and its weight. AdjMap is an alias for the graph: each node, with the list of edges that leave it. Both are generic over the node type:

#[derive(Debug)]
struct Edge<Node> {
    to: Node,
    weight: u64,
}

type AdjMap<Node> = HashMap<Node, Vec<Edge<Node>>>;

Listing 12.18 The complete program. src/bin/dijkstra.rs

use std::{
    cmp::Reverse,
    collections::{BinaryHeap, HashMap},
    hash::Hash,
};

#[derive(Debug)]
struct Edge<Node> {
    to: Node,
    weight: u64,
}

type AdjMap<Node> = HashMap<Node, Vec<Edge<Node>>>;

fn dijkstra_ssmd_shortest<Node>(graph: &AdjMap<Node>, start: Node) -> HashMap<Node, u64>
where
    Node: Clone + Hash + Ord,
{
    let mut dist = HashMap::from([(start.clone(), 0)]);
    let mut heap = BinaryHeap::from([Reverse((0, start))]);

    while let Some(Reverse((cost, node))) = heap.pop() {
        if cost > dist[&node] {
            continue; // stale entry
        }
        for edge in &graph[&node] {
            let new_cost = cost + edge.weight;
            if dist
                .get(&edge.to)
                .is_none_or(|&d| new_cost < d)
            {
                dist.insert(edge.to.clone(), new_cost);
                heap.push(Reverse((new_cost, edge.to.clone())));
            }
        }
    }
    dist
}

fn main() {
    let graph: AdjMap<&str> = HashMap::from([
        (
            "A",
            vec![Edge { to: "B", weight: 4 }, Edge { to: "C", weight: 1 }],
        ),
        ("B", vec![Edge { to: "D", weight: 1 }]),
        (
            "C",
            vec![Edge { to: "B", weight: 2 }, Edge { to: "D", weight: 5 }],
        ),
        ("D", vec![]),
    ]);

    println!("{:#?}", graph);
    let dist = dijkstra_ssmd_shortest(&graph, "A");
    println!("{:#?}", dist); // {"A": 0, "C": 1, "B": 3, "D": 4} (order varies)
}

edge.to and edge.weight read better than .0 and .1. The node type needs Clone instead of Copy, so it could be a String. The function clones a node each time it stores one in dist or on the heap.

graph[&node] panics if a node has no entry in the map. main includes "D" with an empty list, so every node has one.

$ cargo run --bin dijkstra
{
    "B": [
        Edge {
            to: "D",
            weight: 1,
        },
    ],
    ...
}
{
    "B": 3,
    "C": 1,
    "A": 0,
    "D": 4,
}

The first print shows the graph and is cut short here. A HashMap does not keep its entries in any order. The lines of both prints can come out in a different order on your machine.

Listing 12.19 The graph types, and borrowing nodes instead of cloning them (lines 1 to 47). src/bin/dijkstra_with_lifetime.rs

use std::{
    cmp::Reverse,
    collections::{BinaryHeap, HashMap},
    hash::Hash,
};

#[derive(Debug)]
struct Edge<Node> {
    to: Node,
    weight: u64,
}

type AdjMap<Node> = HashMap<Node, Vec<Edge<Node>>>;

fn dijkstra_ssmd_shortest<'a, Node>(
    graph: &'a AdjMap<Node>,
    start: &'a Node,
) -> HashMap<&'a Node, u64>
where
    Node: Hash + Ord,
{
    let mut dist = HashMap::from([(start, 0u64)]);
    let mut heap = BinaryHeap::from([Reverse((0u64, start))]);

    while let Some(Reverse((cost, node))) = heap.pop() {
        if cost > dist[node] {
            continue; // stale entry
        }
        let Some(edges) = graph.get(node) else {
            continue;
        };

        for edge in edges {
            let Some(new_cost) = cost.checked_add(edge.weight) else {
                continue;
            };
            if dist
                .get(&edge.to)
                .is_none_or(|&d| new_cost < d)
            {
                dist.insert(&edge.to, new_cost);
                heap.push(Reverse((new_cost, &edge.to)));
            }
        }
    }
    dist
}

The types are generic over Node, the type that names a node, such as &str or u32. An Edge<Node> holds the node it leads to and a weight. AdjMap<Node> is an alias for the adjacency map: each node, and the list of edges that leave it.

This version stores references to nodes, &'a Node, in dist and in the heap, so Node does not need Clone. With String nodes, that saves an allocation per clone.

The lifetime 'a ties everything together. The graph and the start node are both borrowed for 'a, and the returned map holds &'a Node keys. The compiler therefore keeps the graph alive as long as the result is in use. Every reference pushed onto the heap, &edge.to, points into the graph, so it lives long enough.

Two let ... else lines make the function safer than listing 12.18:

• let Some(edges) = graph.get(node) else { continue }; handles a node that has no entry in the map. main leaves "D" out of the map, and the function still works.
• let Some(new_cost) = cost.checked_add(edge.weight) else { continue }; skips an edge whose total cost would overflow. checked_add returns None on overflow instead of panicking or wrapping around.

Listing 12.20 The complete program. src/bin/dijkstra_with_lifetime.rs

use std::{
    cmp::Reverse,
    collections::{BinaryHeap, HashMap},
    hash::Hash,
};

#[derive(Debug)]
struct Edge<Node> {
    to: Node,
    weight: u64,
}

type AdjMap<Node> = HashMap<Node, Vec<Edge<Node>>>;

fn dijkstra_ssmd_shortest<'a, Node>(
    graph: &'a AdjMap<Node>,
    start: &'a Node,
) -> HashMap<&'a Node, u64>
where
    Node: Hash + Ord,
{
    let mut dist = HashMap::from([(start, 0u64)]);
    let mut heap = BinaryHeap::from([Reverse((0u64, start))]);

    while let Some(Reverse((cost, node))) = heap.pop() {
        if cost > dist[node] {
            continue; // stale entry
        }
        let Some(edges) = graph.get(node) else {
            continue;
        };

        for edge in edges {
            let Some(new_cost) = cost.checked_add(edge.weight) else {
                continue;
            };
            if dist
                .get(&edge.to)
                .is_none_or(|&d| new_cost < d)
            {
                dist.insert(&edge.to, new_cost);
                heap.push(Reverse((new_cost, &edge.to)));
            }
        }
    }
    dist
}

fn main() {
    let graph: AdjMap<String> = HashMap::from([
        (
            "A".into(),
            vec![
                Edge {
                    to: "B".into(),
                    weight: 4,
                },
                Edge {
                    to: "C".into(),
                    weight: 1,
                },
            ],
        ),
        (
            "B".into(),
            vec![Edge {
                to: "D".into(),
                weight: 1,
            }],
        ),
        (
            "C".into(),
            vec![
                Edge {
                    to: "B".into(),
                    weight: 2,
                },
                Edge {
                    to: "D".into(),
                    weight: 5,
                },
            ],
        ),
    ]);

    println!("Graph => {:#?}", graph);

    let start = "A".into();
    println!(
        "Shortest path {:#?}",
        dijkstra_ssmd_shortest(&graph, &start)
    ); // A:0, C:1, B:3, D:4
}

In main, let start = "A".into(); makes a String in its own variable, because the function needs a reference that lives as long as the graph borrow.

$ cargo run --bin dijkstra_with_lifetime
Graph => {
    ...
}
Shortest path {
    "A": 0,
    "B": 3,
    "D": 4,
    "C": 1,
}

The last version keeps the owned, cloning style of listing 12.18 and adds the two safety checks.

Listing 12.21 The complete program. src/bin/dijkstra_bruce_lee.rs

use std::{
    cmp::Reverse,
    collections::{BinaryHeap, HashMap},
    hash::Hash,
};

struct Edge<Node> {
    to: Node,
    weight: u64,
}

type AdjMap<Node> = HashMap<Node, Vec<Edge<Node>>>;

fn dijkstra_ssmd_shortest<Node>(graph: &AdjMap<Node>, start: Node) -> HashMap<Node, u64>
where
    Node: Clone + Hash + Ord,
{
    let mut dist = HashMap::from([(start.clone(), 0)]);
    let mut heap = BinaryHeap::from([Reverse((0u64, start))]);

    while let Some(Reverse((cost, node))) = heap.pop() {
        if cost > dist[&node] {
            continue; // stale entry
        }
        let Some(edges) = graph.get(&node) else {
            continue;
        }; // node with no outgoing edges

        for edge in edges {
            let Some(new_cost) = cost.checked_add(edge.weight) else {
                continue;
            }; // overflow
            if dist
                .get(&edge.to)
                .is_none_or(|&d| new_cost < d)
            {
                dist.insert(edge.to.clone(), new_cost);
                heap.push(Reverse((new_cost, edge.to.clone())));
            }
        }
    }
    dist
}

fn main() {
    let graph: AdjMap<&str> = HashMap::from([
        (
            "A",
            vec![Edge { to: "B", weight: 4 }, Edge { to: "C", weight: 1 }],
        ),
        ("B", vec![Edge { to: "D", weight: 1 }]),
        (
            "C",
            vec![Edge { to: "B", weight: 2 }, Edge { to: "D", weight: 5 }],
        ),
    ]); // "D" has no entry now, and it no longer panics

    println!("{:?}", dijkstra_ssmd_shortest(&graph, "A"));
}

$ cargo run --bin dijkstra_bruce_lee
{"B": 3, "C": 1, "D": 4, "A": 0}

Table 12.1 compares the five versions.

Table 12.1 The five Dijkstra implementations

12.10 Connecting every node at the lowest cost

The last problem uses an undirected, weighted graph. Think of the nodes as buildings and the weights as the cost of laying cable between two buildings. You want to connect every building, directly or indirectly, at the lowest total cost.

A set of edges that connects all the nodes without forming a cycle is a spanning tree. A spanning tree with the lowest total weight is a minimum spanning tree (MST). With n nodes, a spanning tree has exactly n − 1 edges. One edge fewer would leave a node disconnected, and one edge more would close a loop.

Kruskal’s algorithm builds an MST by taking edges from lightest to heaviest. It keeps an edge if the edge joins two groups of nodes that are not yet connected. It skips an edge whose two ends are already connected, because that edge would close a loop.

12.10.1 Union-find

Kruskal’s algorithm needs to answer one question fast: are these two nodes already connected? A union-find structure, also called a disjoint set, answers it.

Union-find keeps nodes in groups. Each group is a small tree stored in a parent array, where parent[i] is the node that i points to. The node at the top of a group points to itself and is called the group’s root. Two nodes are in the same group when they have the same root.

There are two operations:

• find(x) follows parent links from x up to the root.
• union(x, y) finds both roots. If the roots differ, it makes one root point to the other, which joins the two groups.

Listing 12.22 Union-find (lines 10 to 49). src/bin/kruskals_algorithm.rs

use std::cmp::Ordering::{Equal, Greater, Less};

struct DisjointSet {
    parent: Vec<usize>,
    rank: Vec<usize>,
}

impl DisjointSet {
    fn new(n: usize) -> Self {
        Self {
            parent: (0..n).collect(),
            rank: vec![0; n],
        }
    }

    fn find(&mut self, elem: usize) -> usize {
        if self.parent[elem] != elem {
            self.parent[elem] = self.find(self.parent[elem]);
        }

        self.parent[elem]
    }

    fn union(&mut self, x: usize, y: usize) -> bool {
        let (x, y) = (self.find(x), self.find(y));

        if x == y {
            return false;
        }

        match self.rank[x].cmp(&self.rank[y]) {
            Less => self.parent[x] = y,
            Greater => self.parent[y] = x,
            Equal => {
                self.parent[x] = y;
                self.rank[y] += 1;
            }
        }

        true
    }
}

new makes every node its own group: parent is [0, 1, 2, ...], built with (0..n).collect().

find is recursive. On the way back from the root, it sets parent[elem] to the root directly. The next find on that node then takes one step instead of many. This trick is called path compression.

union returns false if both nodes already have the same root. Otherwise it joins the groups using rank, a rough measure of each group’s height. The shorter group goes under the taller one, so the trees stay flat. If both have the same rank, either can go under the other, and the new root’s rank grows by one. This is called union by rank.

With both tricks, find and union take nearly constant time in practice.

12.10.2 Kruskal’s algorithm

Listing 12.23 The edge type and Kruskal's algorithm (lines 3 to 65).

#[derive(Debug)]
struct Edge {
    u: usize,
    v: usize,
    w: u32,
}

fn kruskals(n: usize, mut edges: Vec<Edge>) -> Vec<Edge> {
    // Kruskal's algorithm is greedy: it takes the cheapest edges first.
    edges.sort_by_key(|e| e.w);

    let mut uf = DisjointSet::new(n);
    let mut mst = Vec::new();

    for edge in edges {
        if uf.union(edge.u, edge.v) {
            mst.push(edge);
        }
    }

    mst
}

An Edge joins nodes u and v, numbered from 0, with weight w. The graph is undirected, so the order of u and v does not matter.

edges.sort_by_key(|e| e.w) sorts the edges by weight. Then each edge is offered to union. If union returns true, the edge joined two groups, and it goes into the tree. The edge is moved into mst, not copied, because for edge in edges takes ownership of each one.

Sorting dominates the running time, so the algorithm runs in O(E log E).

Figure 12.8 follows the parent array through every edge of the program’s graph.

sort_by_key is a stable sort: edges with equal weights keep their input order. So 1-3 comes before 3-4, and 0-1 comes before 2-3.

Listing 12.24 The complete program. src/bin/kruskals_algorithm.rs

use std::cmp::Ordering::{Equal, Greater, Less};

#[derive(Debug)]
struct Edge {
    u: usize,
    v: usize,
    w: u32,
}

struct DisjointSet {
    parent: Vec<usize>,
    rank: Vec<usize>,
}

impl DisjointSet {
    fn new(n: usize) -> Self {
        Self {
            parent: (0..n).collect(),
            rank: vec![0; n],
        }
    }

    fn find(&mut self, elem: usize) -> usize {
        if self.parent[elem] != elem {
            self.parent[elem] = self.find(self.parent[elem]);
        }

        self.parent[elem]
    }

    fn union(&mut self, x: usize, y: usize) -> bool {
        let (x, y) = (self.find(x), self.find(y));

        if x == y {
            return false;
        }

        match self.rank[x].cmp(&self.rank[y]) {
            Less => self.parent[x] = y,
            Greater => self.parent[y] = x,
            Equal => {
                self.parent[x] = y;
                self.rank[y] += 1;
            }
        }

        true
    }
}

fn kruskals(n: usize, mut edges: Vec<Edge>) -> Vec<Edge> {
    // Kruskal's algorithm is greedy: it takes the cheapest edges first.
    edges.sort_by_key(|e| e.w);

    let mut uf = DisjointSet::new(n);
    let mut mst = Vec::new();

    for edge in edges {
        if uf.union(edge.u, edge.v) {
            mst.push(edge);
        }
    }

    mst
}

fn main() {
    let edges = vec![
        Edge { u: 0, v: 1, w: 4 },
        Edge { u: 0, v: 2, w: 3 },
        Edge { u: 1, v: 2, w: 1 },
        Edge { u: 1, v: 3, w: 2 },
        Edge { u: 2, v: 3, w: 4 },
        Edge { u: 3, v: 4, w: 2 },
    ];

    let mst = kruskals(5, edges);
    let total: u32 = mst.iter().map(|e| e.w).sum();

    for e in &mst {
        println!("{} - {} ({})", e.u, e.v, e.w);
    }
    println!("total: {total}");
}

$ cargo run --bin kruskals_algorithm
1 - 2 (1)
1 - 3 (2)
3 - 4 (2)
0 - 2 (3)
total: 8

The tree has four edges for five nodes, as expected.

12.11 The complete files

The sections above showed these files in excerpts. Here each one is whole.

Listing 12.25 Breadth-first search, with its tests. src/problems/graph_bfs.rs

//! Breadth-first search.
//!
//! Two variants of the same algorithm:
//!
//! - `bfs_vec`: nodes are `usize` indices and the graph is `Vec<Vec<(usize, u32)>>`,
//!   so `visited` is a plain `Vec<bool>`. This is the version to write first.
//! - `bfs`: nodes are any `Copy + Eq + Hash` type and the graph is a `HashMap`
//!   from a node to a slice of `(neighbor, weight)` edges.

use std::{
    collections::{HashMap, HashSet, VecDeque},
    hash::Hash,
};

/// Adjacency list keyed by node: each node maps to its `(neighbor, weight)` edges.
pub type GraphAdjList<'a, Node> = HashMap<Node, &'a [(Node, u32)]>;

/// BFS over an index-based adjacency list. Returns nodes in visiting order.
pub fn bfs_vec(graph: &[Vec<(usize, u32)>], start_node: usize) -> Vec<usize> {
    let mut visited = vec![false; graph.len()];
    let mut queue = VecDeque::from([start_node]);
    let mut result = vec![];

    visited[start_node] = true;

    while let Some(current_node) = queue.pop_front() {
        result.push(current_node);
        for &(neighbor, _) in &graph[current_node] {
            if !visited[neighbor] {
                visited[neighbor] = true;
                queue.push_back(neighbor);
            }
        }
    }
    result
}

/// BFS over a `HashMap` adjacency list. Returns nodes in visiting order.
pub fn bfs<Node>(graph: &GraphAdjList<Node>, start_node: Node) -> Vec<Node>
where
    Node: Copy + Eq + Hash,
{
    let mut visited = HashSet::new();
    let mut queue = VecDeque::from([start_node]);
    let mut result = vec![];

    visited.insert(start_node);

    while let Some(current_node) = queue.pop_front() {
        result.push(current_node);
        // slice iter yields &(Node, u32); `&` destructures it
        for &(neighbor, _) in graph[&current_node] {
            if visited.insert(neighbor) {
                queue.push_back(neighbor);
            }
        }
    }
    result
}

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

    /// A -> B (1), A -> C (4), B -> C (2), B -> D (5), C -> D (1)
    fn sample_vec() -> Vec<Vec<(usize, u32)>> {
        vec![
            vec![(1, 1), (2, 4)],
            vec![(2, 2), (3, 5)],
            vec![(3, 1)],
            vec![],
        ]
    }

    fn sample_map() -> HashMap<&'static str, &'static [(&'static str, u32)]> {
        HashMap::from([
            ("A", &[("B", 1), ("C", 4)][..]),
            ("B", &[("C", 2), ("D", 5)][..]),
            ("C", &[("D", 1)][..]),
            ("D", &[][..]),
        ])
    }

    #[test]
    fn vec_variant_visits_level_by_level() {
        assert_eq!(bfs_vec(&sample_vec(), 0), vec![0, 1, 2, 3]);
    }

    #[test]
    fn vec_variant_skips_unreachable_nodes() {
        let graph = vec![vec![(1, 1)], vec![], vec![(0, 1)]];
        assert_eq!(bfs_vec(&graph, 0), vec![0, 1]);
    }

    #[test]
    fn vec_variant_handles_cycles() {
        let graph = vec![vec![(1, 1)], vec![(0, 1)]];
        assert_eq!(bfs_vec(&graph, 0), vec![0, 1]);
    }

    #[test]
    fn map_variant_visits_level_by_level() {
        assert_eq!(bfs(&sample_map(), "A"), vec!["A", "B", "C", "D"]);
    }

    #[test]
    fn both_variants_agree() {
        let names = ["A", "B", "C", "D"];
        let from_vec: Vec<&str> = bfs_vec(&sample_vec(), 0)
            .into_iter()
            .map(|index| names[index])
            .collect();
        assert_eq!(from_vec, bfs(&sample_map(), "A"));
    }
}

Listing 12.26 Depth-first search, with its tests. src/problems/graph_dfs.rs

//! Iterative depth-first search with an explicit stack.
//!
//! Two variants of the same algorithm:
//!
//! - `dfs_vec`: nodes are `usize` indices and the graph is `Vec<Vec<(usize, u32)>>`.
//! - `dfs`: nodes are any `Copy + Eq + Hash` type and the graph is a `HashMap`.
//!
//! A node is marked visited when it is popped, not when it is pushed, so it may
//! sit on the stack more than once. Neighbors are pushed in order, which means the
//! last neighbor is explored first.

use std::{collections::HashSet, hash::Hash};

use crate::problems::graph_bfs::GraphAdjList;

/// DFS over an index-based adjacency list. Returns nodes in visiting order.
pub fn dfs_vec(graph: &[Vec<(usize, u32)>], start_node: usize) -> Vec<usize> {
    let mut visited = vec![false; graph.len()];
    let mut stack = vec![start_node];
    let mut result = vec![];

    while let Some(current_node) = stack.pop() {
        if visited[current_node] {
            continue;
        }
        visited[current_node] = true;
        result.push(current_node);
        for &(neighbor, _) in &graph[current_node] {
            stack.push(neighbor);
        }
    }
    result
}

/// DFS over a `HashMap` adjacency list. Returns nodes in visiting order.
pub fn dfs<Node>(graph: &GraphAdjList<Node>, start_node: Node) -> Vec<Node>
where
    Node: Copy + Eq + Hash,
{
    let mut visited = HashSet::new();
    let mut stack = vec![start_node];
    let mut result = vec![];

    while let Some(current_node) = stack.pop() {
        if !visited.insert(current_node) {
            continue;
        }
        result.push(current_node);
        for &(neighbor, _) in graph[&current_node] {
            stack.push(neighbor);
        }
    }
    result
}

#[cfg(test)]
mod tests {
    use std::collections::HashMap;

    use super::*;

    /// A -> B (1), A -> C (4), B -> C (2), B -> D (5), C -> D (1)
    fn sample_vec() -> Vec<Vec<(usize, u32)>> {
        vec![
            vec![(1, 1), (2, 4)],
            vec![(2, 2), (3, 5)],
            vec![(3, 1)],
            vec![],
        ]
    }

    fn sample_map() -> HashMap<&'static str, &'static [(&'static str, u32)]> {
        HashMap::from([
            ("A", &[("B", 1), ("C", 4)][..]),
            ("B", &[("C", 2), ("D", 5)][..]),
            ("C", &[("D", 1)][..]),
            ("D", &[][..]),
        ])
    }

    #[test]
    fn vec_variant_explores_the_last_neighbor_first() {
        // Pop 0, push 1 and 2; pop 2, push 3; pop 3; pop 1.
        assert_eq!(dfs_vec(&sample_vec(), 0), vec![0, 2, 3, 1]);
    }

    #[test]
    fn vec_variant_handles_cycles() {
        let graph = vec![vec![(1, 1)], vec![(2, 1)], vec![(0, 1)]];
        assert_eq!(dfs_vec(&graph, 0), vec![0, 1, 2]);
    }

    #[test]
    fn map_variant_explores_the_last_neighbor_first() {
        assert_eq!(dfs(&sample_map(), "A"), vec!["A", "C", "D", "B"]);
    }

    #[test]
    fn both_variants_agree() {
        let names = ["A", "B", "C", "D"];
        let from_vec: Vec<&str> = dfs_vec(&sample_vec(), 0)
            .into_iter()
            .map(|index| names[index])
            .collect();
        assert_eq!(from_vec, dfs(&sample_map(), "A"));
    }
}

Listing 12.27 Dijkstra's algorithm, with its tests. src/problems/graph_dijkstra.rs

//! Dijkstra's shortest paths with a binary min-heap.
//!
//! Two variants of the same algorithm:
//!
//! - `dijkstra_vec`: nodes are `usize` indices and distances are a
//!   `Vec<Option<u32>>`, where `None` means unreachable.
//! - `dijkstra`: nodes are any `Copy + Eq + Hash + Ord` type and distances are a
//!   `HashMap` containing only the reachable nodes.
//!
//! Edge weights must be non-negative, which `u32` guarantees. `BinaryHeap` is a
//! max-heap, so entries are wrapped in `Reverse` to pop the smallest cost first.
//! A node can be in the heap several times; an entry whose cost is larger than the
//! recorded distance is stale and skipped.

use std::{
    cmp::Reverse,
    collections::{BinaryHeap, HashMap},
    hash::Hash,
};

use crate::problems::graph_bfs::GraphAdjList;

/// Shortest distances from `start_node` over an index-based adjacency list.
pub fn dijkstra_vec(graph: &[Vec<(usize, u32)>], start_node: usize) -> Vec<Option<u32>> {
    let mut distances = vec![None; graph.len()];
    let mut min_heap = BinaryHeap::from([Reverse((0, start_node))]);

    distances[start_node] = Some(0);

    while let Some(Reverse((current_cost, current_node))) = min_heap.pop() {
        // stale heap entry, a shorter path was already recorded
        if distances[current_node].is_some_and(|best| current_cost > best) {
            continue;
        }
        for &(neighbor, weight) in &graph[current_node] {
            let new_distance = current_cost + weight;
            if distances[neighbor].is_none_or(|best| new_distance < best) {
                distances[neighbor] = Some(new_distance);
                min_heap.push(Reverse((new_distance, neighbor)));
            }
        }
    }
    distances
}

/// Shortest distances from `start_node` over a `HashMap` adjacency list.
pub fn dijkstra<Node>(graph: &GraphAdjList<Node>, start_node: Node) -> HashMap<Node, u32>
where
    Node: Copy + Eq + Hash + Ord,
{
    let mut distances = HashMap::from([(start_node, 0)]);
    let mut min_heap = BinaryHeap::from([Reverse((0, start_node))]);

    while let Some(Reverse((current_cost, current_node))) = min_heap.pop() {
        // stale heap entry, a shorter path was already recorded
        if current_cost > distances[&current_node] {
            continue;
        }
        for &(neighbor, weight) in graph[&current_node] {
            let new_distance = current_cost + weight;

            if new_distance
                < *distances
                    .get(&neighbor)
                    .unwrap_or(&u32::MAX)
            {
                distances.insert(neighbor, new_distance);
                min_heap.push(Reverse((new_distance, neighbor)));
            }
        }
    }
    distances
}

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

    /// A -> B (1), A -> C (4), B -> C (2), B -> D (5), C -> D (1)
    fn sample_vec() -> Vec<Vec<(usize, u32)>> {
        vec![
            vec![(1, 1), (2, 4)],
            vec![(2, 2), (3, 5)],
            vec![(3, 1)],
            vec![],
        ]
    }

    fn sample_map() -> HashMap<&'static str, &'static [(&'static str, u32)]> {
        HashMap::from([
            ("A", &[("B", 1), ("C", 4)][..]),
            ("B", &[("C", 2), ("D", 5)][..]),
            ("C", &[("D", 1)][..]),
            ("D", &[][..]),
        ])
    }

    #[test]
    fn vec_variant_finds_shorter_multi_hop_paths() {
        // A -> C directly costs 4, A -> B -> C costs 3; D is reached via C for 4.
        assert_eq!(
            dijkstra_vec(&sample_vec(), 0),
            vec![Some(0), Some(1), Some(3), Some(4)]
        );
    }

    #[test]
    fn vec_variant_marks_unreachable_nodes() {
        let graph = vec![vec![(1, 7)], vec![], vec![(0, 1)]];
        assert_eq!(dijkstra_vec(&graph, 0), vec![Some(0), Some(7), None]);
    }

    #[test]
    fn map_variant_finds_shorter_multi_hop_paths() {
        let distances = dijkstra(&sample_map(), "A");
        assert_eq!(
            distances,
            HashMap::from([("A", 0), ("B", 1), ("C", 3), ("D", 4)])
        );
    }

    #[test]
    fn map_variant_omits_unreachable_nodes() {
        let graph: HashMap<u8, &[(u8, u32)]> =
            HashMap::from([(0, &[(1, 2)][..]), (1, &[][..]), (2, &[(0, 1)][..])]);
        assert_eq!(dijkstra(&graph, 0), HashMap::from([(0, 0), (1, 2)]));
    }
}

Chapter 13 builds an LRU cache, which combines a hash map with a linked list. It brings back the ownership questions of chapters 8 and 9.

Exercises

1. Change bfs_vec in listing 12.1 to also return, for each node, the number of edges on the shortest path from the start.
2. Extend dijkstra_vec to record each node’s predecessor on its shortest path. Then write a function that rebuilds the path from the start to a given node.
3. Rewrite count_islands with a Vec<bool> for visited, and with a DFS stack instead of a BFS queue. Check that the tests still pass.
4. Change topo_sort in listing 12.15 to return Option<Vec<String>>, and add a test with a cycle.
5. Rewrite find in listing 12.22 with a loop instead of recursion, keeping path compression.

An LRU cache

A cache keeps a limited number of recent results close at hand, so a program does not have to compute or fetch them again. A web browser caches images. A database caches disk pages in memory. A CPU caches memory in small, fast storage next to its cores, which chapter 15 looks at.

A cache has a fixed size. When it is full and a new entry arrives, it must remove, or evict, an old entry. The rule for choosing which entry to evict is the cache’s eviction policy.

This chapter builds a cache with the least recently used (LRU) policy: evict the entry that has gone longest without being used. The idea is that an entry used recently is likely to be used again soon.

You have already built both parts of an LRU cache. Chapter 3 covered HashMap, and chapters 8 and 9 covered linked lists and Rc. This chapter combines them, four ways, and then measures two of them.

13.1 What an LRU cache does

An LRU cache has two operations:

• get(key) returns the value for key, or nothing if the key is not cached. A successful get counts as a use, so the key becomes the most recently used.
• put(key, value) stores the value. The key becomes the most recently used. If the cache was full and the key is new, the least recently used entry is evicted.

Figure 13.1 follows five calls on a cache with room for two entries.

The third call changes the outcome. Without get(A), A would be the least recent entry, and put(C, 3) would evict A. Because get(A) counted as a use, B is evicted instead.

13.1.1 What a cache saves

A cache pays off when a hit is much cheaper than the work it replaces. Suppose a lookup in the cache takes 100 ns, and a miss means a database query that takes 1 ms, ten thousand times longer. The average cost of a request is then set almost entirely by the misses:

Going from 90% to 99% makes the average ten times smaller. The hit rate depends on what stays in the cache, and the eviction policy decides that.

Here is a longer trace. The cache holds three entries, and eight requests arrive: A, B, A, C, A, D, A, B. A request for a cached key is a hit; any other request is a miss, which fetches the value and stores it. The table follows the LRU rule, and a simpler rule for comparison. FIFO, first in, first out, evicts the entry that arrived earliest, and ignores use. The order is shown most recent first.

LRU scores 3 hits, and FIFO 2. A is used most, and LRU never evicts it: every use moves it back to the front. FIFO evicts A at the sixth request because A arrived first, and the very next request misses on A.

Animation 13.1 plays the same trace, with a robot for the cache and one for the slow store behind it.

LRU works when the recent past predicts the near future, which holds for most workloads. One pattern breaks it: a scan that reads many keys once each. Every key in the scan becomes the most recent, and the scan pushes out the entries that were in steady use. Databases defend against this with variants that admit a key fully only on its second use.

A cache needs to answer two questions fast:

1. Is this key cached, and what is its value? A HashMap answers that in O(1).
2. Which entry is the least recently used? This needs an order that changes on every call.

Keeping the order in a Vec would be slow. Moving an entry from the middle to the front shifts every element between, which is O(n). The four versions in this chapter keep the order in structures where each step is O(1).

13.2 Version 1: stamped events in a queue

The first version avoids a linked list entirely. Its idea is to record each use as an event, and to sort out which events still count only when something must be evicted.

The cache has a counter called generation that goes up by one on every call. Each call stamps the key with the current generation in two places (figure 13.2):

• The map stores each key’s value and its latest stamp: HashMap<K, (V, u64)>.
• A queue, recency, receives a (key, stamp) event at the back on every use.

The queue is in the order of use, oldest at the front. A key used several times has several events in it. Only the event whose stamp matches the map is current. The others are stale, the same idea as the stale heap entries of Dijkstra’s algorithm in section 12.9.

To evict, the cache pops events from the front. It skips stale events, and removes the key of the first current event. That key is the least recently used one.

Listing 13.1 The type (lines 10 to 24). src/problems/lru_cache.rs

use std::{
    collections::{HashMap, VecDeque},
    hash::Hash,
};

pub struct LruCache<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{
    capacity: usize,
    map: HashMap<K, (V, u64)>,
    recency: VecDeque<(K, u64)>,
    generation: u64,
}

The key must be Clone, because a copy of it goes into the queue with every event. The value must be Clone, because get returns a copy of it.

Listing 13.2 get and put (lines 49 to 71).

impl<K, V> LruCache<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{
    // ...
    pub fn get(&mut self, key: &K) -> Option<V> {
        let (value, _) = self.map.get(key)?.clone();
        self.generation += 1;
        self.recency
            .push_back((key.clone(), self.generation));
        self.map
            .insert(key.clone(), (value.clone(), self.generation));
        Some(value)
    }

    pub fn put(&mut self, key: K, value: V) {
        self.generation += 1;
        let is_new = self
            .map
            .insert(key.clone(), (value, self.generation))
            .is_none();
        self.recency
            .push_back((key, self.generation));

        if is_new {
            self.evict_if_needed();
        }
    }
    // ...
}

get looks up the key and returns early with None if it is missing: self.map.get(key)?. Then it advances the generation, records an event, and stores the value again with the new stamp.

put stores the value with a new stamp, and records an event. HashMap::insert returns the old value if the key was already present, or None if it was new. Only a new key can make the map too large, so only a new key triggers eviction.

Listing 13.3 Eviction (lines 73 to 87).

impl<K, V> LruCache<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{
    // ...
    fn evict_if_needed(&mut self) {
        while self.map.len() > self.capacity {
            let Some((key, generation)) = self.recency.pop_front() else {
                break;
            };

            match self.map.get(&key) {
                Some((_, current)) if *current == generation => {
                    self.map.remove(&key);
                    break;
                }
                _ => {}
            }
        }
    }
}

The loop runs while the map holds more keys than the capacity. Each pass pops the oldest event. The match guard Some((_, current)) if *current == generation accepts the event only if its stamp matches the key’s stamp in the map. A match removes the key and ends the loop. A stale event matches the _ arm and is dropped.

Each event is pushed once and popped at most once. So the total work over many calls is proportional to the number of calls, and each call costs O(1) on average. A cost measured this way, averaged over a sequence of calls, is called amortized.

Animation 13.2 runs the four calls of figure 13.2 with a capacity of 2, then a run of hits.

13.3 Version 2: a linked list inside a Vec

The classic LRU design keeps the entries in a doubly linked list, ordered from most to least recently used. A doubly linked list can move an entry to the front in O(1). Removing the last entry and adding one at the front are O(1) too. The map stores, for each key, where that key’s node is.

Chapter 9 showed that a doubly linked list of Rc<RefCell<_>> nodes is awkward in Rust. Each node is owned jointly, every change goes through runtime borrow checks, and the back links must be Weak to avoid leaks.

This version uses a different approach. All nodes live in one Vec, and a link is the index of another node in that Vec. A Vec used as a pool of nodes this way is called an arena. Figure 13.3 shows one.

An index is a plain usize. The borrow checker does not track it, so a node can be “pointed to” by several other nodes with no Rc and no RefCell. The cost is that the compiler cannot catch a wrong index. The code must keep the links correct by itself.

Listing 13.4 The node and the cache (lines 20 to 45). src/problems/lru_cache_easy.rs

use std::{collections::HashMap, hash::Hash};

/// A single cache entry, linked into the recency list by index.
struct Node<K, V> {
    /// Retained so we can delete the corresponding map entry when evicting.
    key: K,
    value: V,
    /// Neighbour closer to the MRU end (or `None` if this is `head`).
    prev: Option<usize>,
    /// Neighbour closer to the LRU end (or `None` if this is `tail`).
    next: Option<usize>,
}

/// Fixed-capacity LRU cache.
pub struct LruCache<K, V> {
    /// Maximum number of entries; `>= 1` (enforced by `new`).
    cap: usize,
    /// Key → arena index. The single source of truth for "is this key cached?".
    lookup_table: HashMap<K, usize>,
    /// Arena of nodes; indices are the "pointers" of the linked list.
    nodes: Vec<Node<K, V>>,
    /// Arena index of the most recently used entry.
    head: Option<usize>,
    /// Arena index of the least recently used entry (next to be evicted).
    tail: Option<usize>,
}

Each node stores its key as well as its value. When a node is evicted, the cache reads the key from the node to remove the key from lookup_table.

prev and next are Option<usize>, where None means “no neighbor on that side”. head is the index of the most recently used node, and tail is the index of the least recently used one.

13.3.1 Moving a node to the front

Every get and put ends by moving one node to the front of the list. The method touch does it in two steps (figure 13.4):

1. Detach the node: make its two neighbors point at each other, so the list skips it.
2. Push it to the front: make it point at the old head, and make it the new head.

Animation 13.3 runs touch on a list of four entries. The Vec sits underneath and never moves. Only the links above it change. Watch the arrows: when C is lifted out, A’s next swings over to D.

Listing 13.5 new and touch (lines 51 to 101).

impl<K, V> LruCache<K, V>
where
    K: Hash + Eq + Clone,
{
    /// Create a cache holding at most `cap` entries.
    ///
    /// # Panics
    /// Panics if `cap == 0`, since a zero-capacity cache cannot store anything.
    pub fn new(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be > 0");
        Self {
            cap,
            lookup_table: HashMap::new(),
            nodes: Vec::new(),
            head: None,
            tail: None,
        }
    }

    /// Promote node `i` to `head` (MRU).
    ///
    /// Handles both cases in one pass:
    /// * **Already linked** — detach from its current neighbours first.
    /// * **Brand new** — the node has `prev = next = None` and is not yet
    ///   referenced by `head`/`tail`, so the detach step is skipped.
    fn touch(&mut self, i: usize) {
        let (prev, next) = (self.nodes[i].prev, self.nodes[i].next);

        // A node is "linked" if any of its four references exist.
        let linked =
            prev.is_some() || next.is_some() || self.head == Some(i) || self.tail == Some(i);

        if linked {
            // Splice `i` out of the list.
            match prev {
                Some(p) => self.nodes[p].next = next,
                None => self.head = next,
            }
            match next {
                Some(n) => self.nodes[n].prev = prev,
                None => self.tail = prev,
            }
        }

        // Splice `i` in at the front.
        self.nodes[i].prev = None;
        self.nodes[i].next = self.head;
        if let Some(h) = self.head {
            self.nodes[h].prev = Some(i);
        }
        self.head = Some(i);
        if self.tail.is_none() {
            self.tail = Some(i);
        }
    }
    // ...
}

touch first copies the node’s prev and next into local variables. Option<usize> is Copy, so this reads the values without keeping a borrow of self.nodes.

A brand-new node is not in the list yet, so there is nothing to detach. touch tells the two cases apart with linked. A node is in the list if it has a neighbor, or if it is the head or the tail. A list with one node has no neighbors, so the head and tail checks are needed for that case.

The detach step handles the ends of the list. If the node has no prev, it was the head, so the head moves to its next. If it has no next, it was the tail, so the tail moves to its prev.

The push step sets the node’s links, points the old head back at it, and makes it the head. If the list was empty, the node is also the tail.

13.3.2 get and put

Listing 13.6 get and put (lines 103 to 147).

impl<K, V> LruCache<K, V>
where
    K: Hash + Eq + Clone,
{
    // ...
    /// Look up `key`, promoting it to MRU on a hit.
    ///
    /// Returns `None` if the key is not cached.
    pub fn get(&mut self, key: &K) -> Option<&V> {
        let i = *self.lookup_table.get(key)?;
        self.touch(i);
        Some(&self.nodes[i].value)
    }

    /// Insert or update `key`. Promotes it to MRU. Evicts the LRU entry if
    /// the cache is full.
    pub fn put(&mut self, key: K, value: V) {
        // Case 1: key already present → update value, promote.
        if let Some(&i) = self.lookup_table.get(&key) {
            self.nodes[i].value = value;
            self.touch(i);
            return;
        }

        // Case 2: room to grow → append a fresh node.
        if self.nodes.len() < self.cap {
            let i = self.nodes.len();
            self.nodes.push(Node {
                key: key.clone(),
                value,
                prev: None,
                next: None,
            });
            self.lookup_table.insert(key, i);
            self.touch(i);
            return;
        }

        // Case 3: at capacity → reuse the LRU slot.
        // `tail` is guaranteed to be `Some` here because `cap >= 1` and the
        // arena is full, but we still handle `None` gracefully.
        if let Some(i) = self.tail {
            let old_key = std::mem::replace(&mut self.nodes[i].key, key);
            self.nodes[i].value = value;
            self.lookup_table.remove(&old_key);
            self.lookup_table
                .insert(self.nodes[i].key.clone(), i);
            self.touch(i);
        }
    }
}

get finds the index, touches the node, and returns a reference to the value. The return type Option<&V> borrows from the cache. Because get takes &mut self, the cache stays mutably borrowed while you hold that reference.

put has three cases:

1. The key is present. Replace the value and touch the node.
2. There is room. Push a new node onto the end of the Vec, record its index, and touch it.
3. The cache is full. Reuse the tail node’s slot for the new entry.

The third case is the arena’s advantage. Eviction does not free anything, and insertion does not allocate. The tail slot receives the new key and value, and touch moves it to the front.

std::mem::replace(&mut self.nodes[i].key, key) puts the new key into the node and returns the old key, in one step. The old key is then removed from lookup_table. The new key was moved into the node, so the map receives a clone of it.

Animation 13.4 plays the three cases in order. It fills the cache, updates an entry, and then evicts the tail by reusing its slot. The last run leaves out the remove of the old key.

The file src/bin/lru_cache_arena.rs has the same cache with a main function:

Listing 13.7 The main function (lines 150 to 165). src/bin/lru_cache_arena.rs

use std::{collections::HashMap, hash::Hash};

fn main() {
    let mut cache = LruCache::new(2);

    cache.put("A", 10);
    cache.put("B", 20);
    println!("get A = {:?}", cache.get(&"A")); // Some(10), A now MRU

    cache.put("C", 30); // evicts B (LRU)

    println!("get B = {:?}", cache.get(&"B")); // None
    println!("get A = {:?}", cache.get(&"A")); // Some(10)
    println!("get C = {:?}", cache.get(&"C")); // Some(30)

    cache.put("A", 99);
    println!("get A = {:?}", cache.get(&"A")); // Some(99)
}

$ cargo run --bin lru_cache_arena
get A = Some(10)
get B = None
get A = Some(10)
get C = Some(30)
get A = Some(99)

13.4 Version 3: one operation per method

touch in version 2 does two jobs, and must first work out which situation it is in. Version 3 splits it into three methods, each with a stated precondition. A precondition is something that must be true when a function is called. The compiler cannot check these preconditions, so the doc comments state them.

This version also fixes the key and value types to i32. i32 is Copy, so the code never clones a key.

Listing 13.8 The link operations (lines 63 to 94). src/bin/lru_cache_modular.rs

use std::collections::HashMap;

impl LruCache {
    // ...
    /// Unlink node `i` from the list. `i` must currently be linked.
    fn detach(&mut self, i: usize) {
        let (prev, next) = (self.nodes[i].prev, self.nodes[i].next);
        match prev {
            Some(p) => self.nodes[p].next = next,
            None => self.head = next,
        }
        match next {
            Some(n) => self.nodes[n].prev = prev,
            None => self.tail = prev,
        }
    }

    /// Link node `i` in at the MRU end. `i` must currently be unlinked.
    fn push_front(&mut self, i: usize) {
        self.nodes[i].prev = None;
        self.nodes[i].next = self.head;
        match self.head {
            Some(h) => self.nodes[h].prev = Some(i),
            None => self.tail = Some(i), // list was empty
        }
        self.head = Some(i);
    }

    /// Promote an already-linked node to MRU.
    fn promote_to_front(&mut self, i: usize) {
        if self.head == Some(i) {
            return; // already MRU
        }
        self.detach(i);
        self.push_front(i);
    }
    // ...
}

• detach unlinks a node. Its precondition is that the node is in the list.
• push_front links a node at the head. Its precondition is that the node is not in the list.
• promote_to_front combines them for a node that is in the list. If the node is already the head, it does nothing.

Each method now does one thing, with no linked check. put calls push_front for a new node and promote_to_front for an existing one, so each call satisfies its precondition.

$ cargo run --bin lru_cache_modular
get 1 = Some(10)
get 2 = None
get 1 = Some(10)
get 3 = Some(30)
get 1 = Some(99)

13.5 Version 4: measuring the arena against Rc<RefCell<_>>

Is the arena faster than a list of Rc<RefCell<_>> nodes, and by how much? The only reliable answer is to measure. This section builds both caches behind one trait, and runs the same requests through each.

13.5.1 One trait, two caches

Listing 13.9 The trait. benchmarking_examples/cache/mod.rs

//! Two LRU caches of the same design, stored differently, so one benchmark loop
//! can cover both.
//!
//! [`arena`] keeps nodes in a `Vec` and links them by `usize` index.
//! [`rc_list`] allocates an `Rc<RefCell<_>>` per node and links them by pointer.

pub mod arena;
pub mod rc_list;

use std::hash::Hash;

/// The operations every cache supports.
pub trait Cache<K, V>
where
    K: Hash + Eq + Clone,
    V: Copy,
{
    /// A cache that holds at most `capacity` entries.
    ///
    /// # Panics
    /// Panics if `capacity == 0`, since a zero-capacity cache cannot store
    /// anything.
    fn new(capacity: usize) -> Self;

    /// Looks up `key`, promoting it to most recently used on a hit.
    fn get(&mut self, key: &K) -> Option<V>;

    /// Inserts or updates `key`, evicting the least recently used entry when
    /// the cache is full.
    fn put(&mut self, key: K, value: V);

    /// How many entries are cached.
    fn len(&self) -> usize;

    /// Whether the cache holds no entries.
    fn is_empty(&self) -> bool {
        self.len() == 0
    }

    /// The variant's name, for benchmark output.
    fn variant() -> &'static str;
}

The trait Cache<K, V> lists what the benchmark needs. new is part of the trait, so generic code can create a cache with C::new(capacity) without knowing which type C is. variant has no self parameter. It is called on the type, and gives each cache a name for the output.

V: Copy lets get return the value itself, Option<V>, instead of a reference. The benchmark stores u64 values, which are Copy.

The arena cache is version 2, split into two impl blocks. touch stays in an ordinary impl, because it is not part of the trait. The trait methods go in impl<K, V> Cache<K, V> for LruCache<K, V>, and their bodies are the get and put of section 13.3.2:

Listing 13.10 The arena cache's trait methods (lines 91 to 154). benchmarking_examples/cache/arena.rs

impl<K, V> Cache<K, V> for LruCache<K, V>
where
    K: Hash + Eq + Clone,
    V: Copy,
{
    fn new(capacity: usize) -> Self {
        assert!(capacity > 0, "capacity must be > 0");
        Self {
            cap: capacity,
            lookup_table: HashMap::new(),
            nodes: Vec::new(),
            head: None,
            tail: None,
        }
    }

    fn get(&mut self, key: &K) -> Option<V> {
        let i = *self.lookup_table.get(key)?;
        self.touch(i);
        Some(self.nodes[i].value)
    }

    fn put(&mut self, key: K, value: V) {
        // Case 1: key already present, update the value and promote.
        if let Some(&i) = self.lookup_table.get(&key) {
            self.nodes[i].value = value;
            self.touch(i);
            return;
        }

        // Case 2: room to grow, append a fresh node.
        if self.nodes.len() < self.cap {
            let i = self.nodes.len();
            self.nodes.push(Node {
                key: key.clone(),
                value,
                prev: None,
                next: None,
            });
            self.lookup_table.insert(key, i);
            self.touch(i);
            return;
        }

        // Case 3: at capacity, reuse the LRU slot. `tail` is `Some` here because
        // `cap >= 1` and the arena is full, but handle `None` anyway.
        if let Some(i) = self.tail {
            let old_key = std::mem::replace(&mut self.nodes[i].key, key);
            self.nodes[i].value = value;
            self.lookup_table.remove(&old_key);
            self.lookup_table
                .insert(self.nodes[i].key.clone(), i);
            self.touch(i);
        }
    }

    fn len(&self) -> usize {
        self.lookup_table.len()
    }

    fn variant() -> &'static str {
        "arena (Vec + indices)"
    }
}

Listing 13.20, at the end of the chapter, has the whole file.

13.5.2 The Rc<RefCell<_>> list

Listing 13.11 The node and the cache (lines 10 to 33). benchmarking_examples/cache/rc_list.rs

use std::{
    cell::RefCell,
    collections::HashMap,
    hash::Hash,
    rc::{Rc, Weak},
};

use super::Cache;

type Link<K, V> = Option<Rc<RefCell<Node<K, V>>>>;

struct Node<K, V> {
    key: K,
    value: V,
    prev: Weak<RefCell<Node<K, V>>>,
    next: Link<K, V>,
}

pub struct LruCache<K, V> {
    cap: usize,
    map: HashMap<K, Rc<RefCell<Node<K, V>>>>,
    head: Link<K, V>,
    tail: Link<K, V>,
}

This is the doubly linked list of chapter 9. A node is Rc<RefCell<Node>>: Rc so several owners can hold it, and RefCell so it can be changed through those shared handles. next is a strong link, and prev is a Weak link, so two neighbors do not keep each other alive forever. The map holds one more Rc to every node.

Listing 13.12 detach and push_front (lines 35 to 69).

impl<K, V> LruCache<K, V>
where
    K: Hash + Eq + Clone,
    V: Copy,
{
    fn detach(&mut self, node: &Rc<RefCell<Node<K, V>>>) {
        let (prev, next) = {
            let entry = node.borrow();
            (entry.prev.clone(), entry.next.clone())
        };

        match prev.upgrade() {
            Some(previous) => previous.borrow_mut().next = next.clone(),
            None => self.head = next.clone(),
        }
        match &next {
            Some(following) => following.borrow_mut().prev = prev,
            None => self.tail = prev.upgrade(),
        }
    }

    fn push_front(&mut self, node: Rc<RefCell<Node<K, V>>>) {
        let head = self.head.clone();
        {
            let mut entry = node.borrow_mut();
            entry.prev = Weak::new();
            entry.next = head.clone();
        }
        match &head {
            Some(previous) => previous.borrow_mut().prev = Rc::downgrade(&node),
            None => self.tail = Some(node.clone()),
        }
        self.head = Some(node);
    }
}

The logic matches listing 13.8, with pointers instead of indices. The difference is in the ceremony around each step:

• detach reads the node’s links inside a small block. node.borrow() returns a guard that holds a shared borrow of the RefCell. The block ends before any neighbor is changed, so the guard is dropped early. A RefCell panics if a borrow_mut happens while another borrow of the same cell is alive.
• prev.upgrade() turns the Weak link into an Rc, if the node still exists.
• Each .clone() of an Rc or a Weak increases a reference count, and each drop decreases one.

Listing 13.13 The trait methods and Drop (lines 71 to 139).

impl<K, V> Cache<K, V> for LruCache<K, V>
where
    K: Hash + Eq + Clone,
    V: Copy,
{
    fn new(capacity: usize) -> Self {
        assert!(capacity > 0, "capacity must be > 0");
        Self {
            cap: capacity,
            map: HashMap::new(),
            head: None,
            tail: None,
        }
    }

    fn get(&mut self, key: &K) -> Option<V> {
        let node = self.map.get(key)?.clone();
        self.detach(&node);
        self.push_front(node.clone());
        Some(node.borrow().value)
    }

    fn put(&mut self, key: K, value: V) {
        if let Some(node) = self.map.get(&key).cloned() {
            node.borrow_mut().value = value;
            self.detach(&node);
            self.push_front(node);
            return;
        }

        if self.map.len() >= self.cap
            && let Some(victim) = self.tail.clone()
        {
            let old_key = victim.borrow().key.clone();
            self.map.remove(&old_key);
            self.detach(&victim);
        }

        let node = Rc::new(RefCell::new(Node {
            key: key.clone(),
            value,
            prev: Weak::new(),
            next: None,
        }));
        self.map.insert(key, node.clone());
        self.push_front(node);
    }

    fn len(&self) -> usize {
        self.map.len()
    }

    fn variant() -> &'static str {
        "Rc<RefCell> list"
    }
}

impl<K, V> Drop for LruCache<K, V> {
    fn drop(&mut self) {
        // Unlink iteratively: dropping a million-node chain recursively overflows
        // the stack.
        let mut current = self.head.take();
        while let Some(node) = current {
            let next = node.borrow_mut().next.take();
            node.borrow_mut().prev = Weak::new();
            current = next;
        }
    }
}

On a miss with a full cache, put removes the tail node from the map and detaches it. When victim goes out of scope, the last Rc to that node is dropped, and its memory is freed. Then Rc::new allocates a new node for the new key. So every eviction frees one heap block and allocates another.

The Drop implementation is the fix from chapter 9. Dropping a long chain of next links recursively uses one stack frame per node, and a large cache would overflow the stack. The loop breaks the links one node at a time. The map drops its Rc handles afterward, and each drop then frees a single node.

Figure 13.5 compares where the two caches keep their nodes.

The arena’s node is 48 bytes: the key and value take 8 bytes each, and each Option<usize> takes 16. The Rc node is 32 bytes. The heap block around it adds a strong count, a weak count, and the RefCell flag, for 56 bytes. The memory sizes are close. What differs is the number of allocations and where the nodes sit in memory.

13.5.3 The benchmark

Listing 13.14 The request stream and the timed loop (lines 52 to 106). benchmarking_examples/benchmark.rs

use std::{
    hint::black_box,
    time::{Duration, Instant},
};

use systems_lab::{
    cache::{Cache, arena::LruCache as ArenaCache, rc_list::LruCache as RcCache},
    lists::{SinglyList, boxed, boxed_drop, enum_drop, enum_node},
};

// ---------------------------------------------------------------------------
// Cache: arena vs Rc<RefCell> linked list
// ---------------------------------------------------------------------------

/// Request stream with realistic locality: four requests in five come from a hot
/// set of 1% of the keys, the rest from the whole space.
fn key_at(state: u64) -> u64 {
    let mixed = state >> 17;
    if (state >> 33) % 100 < 80 {
        mixed % (KEY_SPACE / 100)
    } else {
        mixed % KEY_SPACE
    }
}

/// The fastest of `CACHE_RUNS` timed passes, with the hit count and final size
/// from the last one. Each pass starts from an empty cache, so the stream is the
/// same every time.
fn best_cache_run<C: Cache<u64, u64>>() -> (Duration, u64, usize) {
    let mut best = Duration::MAX;
    let mut hits = 0;
    let mut len = 0;

    for _ in 0..CACHE_RUNS {
        let mut cache = C::new(CACHE_CAPACITY);
        let (elapsed, run_hits) = cache_workload(&mut cache);
        best = best.min(elapsed);
        hits = run_hits;
        len = cache.len();
    }
    (best, hits, len)
}

/// The same request stream against any cache.
fn cache_workload<C: Cache<u64, u64>>(cache: &mut C) -> (Duration, u64) {
    let mut state = 0x9e37_79b9_7f4a_7c15u64;
    let mut hits = 0u64;

    let start = Instant::now();
    for _ in 0..OPERATIONS {
        state = state
            .wrapping_mul(6_364_136_223_846_793_005)
            .wrapping_add(1_442_695_040_888_963_407);
        let key = key_at(state);

        match cache.get(&key) {
            Some(value) => {
                hits += 1;
                black_box(value);
            }
            None => cache.put(key, key.rotate_left(17)),
        }
    }
    (start.elapsed(), hits)
}

A fair comparison needs both caches to see exactly the same requests. The program makes its own request stream from a number called state. Each step multiplies and adds two fixed constants, so the same starting state always produces the same sequence. A generator of this kind is called a linear congruential generator.

key_at shapes the stream to look like real traffic. Real caches see some keys far more often than others. Here, 80% of requests pick from a hot set of 1% of the keys, and the rest pick from all 131,072 keys. The capacity, 65,536, is half the key space.

Each request calls get. On a miss, it calls put, the way a program fills a cache after it computes a missing value. black_box tells the compiler to treat the value as used, so the optimizer cannot remove the work.

Listing 13.15 Running and checking both caches (lines 108 to 158).

fn cache_benchmark() {
    println!(
        "LRU cache: {} entries, {} requests over {} keys",
        with_thousands(CACHE_CAPACITY as u64),
        with_thousands(OPERATIONS),
        with_thousands(KEY_SPACE)
    );
    println!("A miss inserts and evicts the least recently used entry.");
    println!("Best of {CACHE_RUNS} runs per cache.\n");

    let (arena_time, arena_hits, arena_len) = best_cache_run::<ArenaCache<u64, u64>>();
    let (list_time, list_hits, list_len) = best_cache_run::<RcCache<u64, u64>>();

    // Same population and same hit count, or this compares nothing.
    assert_eq!(arena_len, list_len);
    assert_eq!(
        arena_hits, list_hits,
        "the two runs saw different request streams"
    );

    println!(
        "  hit rate: {:.1}%  ({} hits, {} inserts)\n",
        arena_hits as f64 * 100.0 / OPERATIONS as f64,
        with_thousands(arena_hits),
        with_thousands(OPERATIONS - arena_hits)
    );

    let per_request = |elapsed: Duration| elapsed.as_nanos() as f64 / OPERATIONS as f64;

    // `{:.2?}` uses Duration's own Debug format, rounded to two decimals.
    println!("  {:<22} {:>12} {:>13}", "storage", "total", "per request");
    println!("  {}", "-".repeat(48));
    for (name, elapsed) in [
        (
            <ArenaCache<u64, u64> as Cache<u64, u64>>::variant(),
            arena_time,
        ),
        (<RcCache<u64, u64> as Cache<u64, u64>>::variant(), list_time),
    ] {
        println!(
            "  {name:<22} {elapsed:>12.2?} {:>8.0} ns",
            per_request(elapsed)
        );
    }

    let speedup = list_time.as_secs_f64() / arena_time.as_secs_f64();
    println!(
        "\n  the arena is {speedup:.2}x faster on the same requests: {arena_time:.2?} against {list_time:.2?}"
    );
    println!("  the arena reuses the evicted slot; the list frees a node and allocates another");
}

best_cache_run::<ArenaCache<u64, u64>>() runs the generic function with the arena cache, and the next line runs it with the Rc cache. The ::<...> syntax, called the turbofish, names the type parameter explicitly.

Before printing any times, the function checks that both caches finished with the same size and the same number of hits. Two correct LRU caches given the same requests make the same decisions. If the counts differed, one cache would have a bug, and its time would mean nothing.

<ArenaCache<u64, u64> as Cache<u64, u64>>::variant() is the fully qualified way to call a trait function that has no self. It names both the type and the trait.

Listing 13.16 The complete benchmark program. benchmarking_examples/benchmark.rs

//! One main for every benchmark in the lab.
//!
//! Usage:
//!   cargo run --release --bin benchmark                    # cache, then lists
//!   cargo run --release --bin benchmark cache              # cache only
//!   cargo run --release --bin benchmark list               # all four variants
//!   cargo run --release --bin benchmark list enum 500000   # one variant, one size
//!
//! The recursive list variants abort with a stack overflow past roughly 265,000
//! nodes, so run them below that size or on their own.

use std::{
    hint::black_box,
    time::{Duration, Instant},
};

use systems_lab::{
    cache::{Cache, arena::LruCache as ArenaCache, rc_list::LruCache as RcCache},
    lists::{SinglyList, boxed, boxed_drop, enum_drop, enum_node},
};

const CACHE_CAPACITY: usize = 65_536;
const KEY_SPACE: u64 = 131_072;
const OPERATIONS: u64 = 10_000_000;
const DEFAULT_LIST_ELEMENTS: usize = 200_000;
/// Timed passes per cache; the fastest is reported, since a slow pass is noise.
const CACHE_RUNS: usize = 3;
/// Timed passes per list variant.
const LIST_RUNS: usize = 3;

fn main() {
    let arguments: Vec<String> = std::env::args().skip(1).collect();

    match arguments.first().map(String::as_str) {
        Some("cache") => cache_benchmark(),
        Some("list") => {
            let variant = arguments.get(1).map(String::as_str);
            let elements = arguments
                .get(2)
                .and_then(|value| value.parse().ok())
                .unwrap_or(DEFAULT_LIST_ELEMENTS);
            list_benchmark(variant, elements);
        }
        _ => {
            cache_benchmark();
            println!();
            list_benchmark(None, DEFAULT_LIST_ELEMENTS);
        }
    }
}

// ---------------------------------------------------------------------------
// Cache: arena vs Rc<RefCell> linked list
// ---------------------------------------------------------------------------

/// Request stream with realistic locality: four requests in five come from a hot
/// set of 1% of the keys, the rest from the whole space.
fn key_at(state: u64) -> u64 {
    let mixed = state >> 17;
    if (state >> 33) % 100 < 80 {
        mixed % (KEY_SPACE / 100)
    } else {
        mixed % KEY_SPACE
    }
}

/// The fastest of `CACHE_RUNS` timed passes, with the hit count and final size
/// from the last one. Each pass starts from an empty cache, so the stream is the
/// same every time.
fn best_cache_run<C: Cache<u64, u64>>() -> (Duration, u64, usize) {
    let mut best = Duration::MAX;
    let mut hits = 0;
    let mut len = 0;

    for _ in 0..CACHE_RUNS {
        let mut cache = C::new(CACHE_CAPACITY);
        let (elapsed, run_hits) = cache_workload(&mut cache);
        best = best.min(elapsed);
        hits = run_hits;
        len = cache.len();
    }
    (best, hits, len)
}

/// The same request stream against any cache.
fn cache_workload<C: Cache<u64, u64>>(cache: &mut C) -> (Duration, u64) {
    let mut state = 0x9e37_79b9_7f4a_7c15u64;
    let mut hits = 0u64;

    let start = Instant::now();
    for _ in 0..OPERATIONS {
        state = state
            .wrapping_mul(6_364_136_223_846_793_005)
            .wrapping_add(1_442_695_040_888_963_407);
        let key = key_at(state);

        match cache.get(&key) {
            Some(value) => {
                hits += 1;
                black_box(value);
            }
            None => cache.put(key, key.rotate_left(17)),
        }
    }
    (start.elapsed(), hits)
}

fn cache_benchmark() {
    println!(
        "LRU cache: {} entries, {} requests over {} keys",
        with_thousands(CACHE_CAPACITY as u64),
        with_thousands(OPERATIONS),
        with_thousands(KEY_SPACE)
    );
    println!("A miss inserts and evicts the least recently used entry.");
    println!("Best of {CACHE_RUNS} runs per cache.\n");

    let (arena_time, arena_hits, arena_len) = best_cache_run::<ArenaCache<u64, u64>>();
    let (list_time, list_hits, list_len) = best_cache_run::<RcCache<u64, u64>>();

    // Same population and same hit count, or this compares nothing.
    assert_eq!(arena_len, list_len);
    assert_eq!(
        arena_hits, list_hits,
        "the two runs saw different request streams"
    );

    println!(
        "  hit rate: {:.1}%  ({} hits, {} inserts)\n",
        arena_hits as f64 * 100.0 / OPERATIONS as f64,
        with_thousands(arena_hits),
        with_thousands(OPERATIONS - arena_hits)
    );

    let per_request = |elapsed: Duration| elapsed.as_nanos() as f64 / OPERATIONS as f64;

    // `{:.2?}` uses Duration's own Debug format, rounded to two decimals.
    println!("  {:<22} {:>12} {:>13}", "storage", "total", "per request");
    println!("  {}", "-".repeat(48));
    for (name, elapsed) in [
        (
            <ArenaCache<u64, u64> as Cache<u64, u64>>::variant(),
            arena_time,
        ),
        (<RcCache<u64, u64> as Cache<u64, u64>>::variant(), list_time),
    ] {
        println!(
            "  {name:<22} {elapsed:>12.2?} {:>8.0} ns",
            per_request(elapsed)
        );
    }

    let speedup = list_time.as_secs_f64() / arena_time.as_secs_f64();
    println!(
        "\n  the arena is {speedup:.2}x faster on the same requests: {arena_time:.2?} against {list_time:.2?}"
    );
    println!("  the arena reuses the evicted slot; the list frees a node and allocates another");
}

// ---------------------------------------------------------------------------
// Lists: four variants, one loop
// ---------------------------------------------------------------------------

fn list_benchmark(variant: Option<&str>, elements: usize) {
    println!(
        "Singly linked list: push {} values, pop them back in order, then drop a full list",
        with_thousands(elements as u64)
    );
    println!("Best of {LIST_RUNS} runs per variant, allocator warmed up.\n");
    println!(
        "  {:<10} {:>12} {:>13} {:>13}",
        "variant", "elements", "push", "drop"
    );
    println!("  {}", "-".repeat(52));

    match variant {
        Some("box") => run_list::<boxed::LinkedList<u64>>(elements),
        Some("enum") => run_list::<enum_node::LinkedList<u64>>(elements),
        Some("box+drop") => run_list::<boxed_drop::LinkedList<u64>>(elements),
        Some("enum+drop") => run_list::<enum_drop::LinkedList<u64>>(elements),
        _ => {
            run_list::<boxed::LinkedList<u64>>(elements);
            run_list::<enum_node::LinkedList<u64>>(elements);
            run_list::<boxed_drop::LinkedList<u64>>(elements);
            run_list::<enum_drop::LinkedList<u64>>(elements);
        }
    }
}

fn run_list<L: SinglyList<u64>>(elements: usize) {
    // Warm the allocator first: without this the first variant in a process pays
    // for fresh heap pages and looks several times slower than an identical one.
    let mut warm_up = L::new();
    for value in 0..elements as u64 {
        warm_up.push_front(value);
    }
    drop(warm_up);

    let mut best_push = Duration::MAX;
    let mut best_drop = Duration::MAX;

    for _ in 0..LIST_RUNS {
        let mut list = L::new();

        let start = Instant::now();
        for value in 0..elements as u64 {
            list.push_front(value);
        }
        best_push = best_push.min(start.elapsed());

        // Pop every value back and check the order, so a broken list cannot post
        // a fast time.
        let mut expected = elements as u64;
        while let Some(value) = list.pop_front() {
            expected -= 1;
            assert_eq!(value, expected, "{} lost LIFO order", L::variant());
        }
        assert_eq!(expected, 0);
        black_box(expected);

        // Rebuild, then time the drop of a full list. This is where the
        // recursive variants overflow the stack.
        for value in 0..elements as u64 {
            list.push_front(value);
        }
        let start = Instant::now();
        drop(list);
        best_drop = best_drop.min(start.elapsed());
    }

    println!(
        "  {:<10} {:>12} {best_push:>13.2?} {best_drop:>13.2?}",
        L::variant(),
        with_thousands(elements as u64)
    );
}

fn with_thousands(value: u64) -> String {
    let digits = value.to_string();
    let mut out = String::with_capacity(digits.len() + digits.len() / 3);
    for (index, digit) in digits.chars().enumerate() {
        if index > 0 && (digits.len() - index).is_multiple_of(3) {
            out.push(',');
        }
        out.push(digit);
    }
    out
}

The list half of this file was explained in section 9.8. Run only the cache half with the cache argument, and always with --release. A debug build is not optimized, and its times do not show how the code performs.

$ cargo run --release --bin benchmark cache
LRU cache: 65,536 entries, 10,000,000 requests over 131,072 keys
A miss inserts and evicts the least recently used entry.
Best of 3 runs per cache.

  hit rate: 89.8%  (8,979,314 hits, 1,020,686 inserts)

  storage                       total   per request
  ------------------------------------------------
  arena (Vec + indices)      587.49ms       59 ns
  Rc<RefCell> list              1.86s      186 ns

  the arena is 3.16x faster on the same requests: 587.49ms against 1.86s
  the arena reuses the evicted slot; the list frees a node and allocates another

On this machine, the arena handled a request in 59 ns on average, and the Rc list took 186 ns. Your numbers will differ, but the ratio should be similar on most machines.

The two caches do the same O(1) work per request. Three differences in how they do it add up:

• Allocation. About one request in ten is a miss, and each miss in the Rc list frees a node and allocates another. The arena reuses the tail slot.
• Bookkeeping. The Rc list updates reference counts on every clone and drop, and checks the RefCell borrow flag on every access. The arena reads and writes plain integers.
• Location. The arena’s nodes sit side by side in one block. The Rc nodes sit wherever the allocator put them. Chapter 15 explains why nearby memory is faster to reach.

This benchmark measures the total, and does not separate the three costs. Exercise 4 suggests a way to separate them.

13.6 The complete files

The sections above showed these files in excerpts. Here each one is whole.

Listing 13.17 Version 1, stamped events, with tests. src/problems/lru_cache.rs

//! LRU cache without a linked list.
//!
//! Design: `HashMap<K, (V, generation)>` + `VecDeque<(K, generation)>`.
//!
//! Each access pushes a new `(key, generation)` event to the back. On eviction
//! we pop old events until we find the newest generation for a key, then remove
//! it. Stale events are skipped. This keeps amortized O(1) operations while
//! preserving true LRU semantics.

use std::{
    collections::{HashMap, VecDeque},
    hash::Hash,
};

pub struct LruCache<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{
    capacity: usize,
    map: HashMap<K, (V, u64)>,
    recency: VecDeque<(K, u64)>,
    generation: u64,
}

impl<K, V> LruCache<K, V>
where
    K: Eq + Hash + Clone,
    V: Clone,
{
    pub fn new(capacity: usize) -> Self {
        assert!(capacity > 0, "LRU cache capacity must be > 0");
        Self {
            capacity,
            map: HashMap::new(),
            recency: VecDeque::new(),
            generation: 0,
        }
    }

    pub fn len(&self) -> usize {
        self.map.len()
    }

    pub fn is_empty(&self) -> bool {
        self.map.is_empty()
    }

    pub fn get(&mut self, key: &K) -> Option<V> {
        let (value, _) = self.map.get(key)?.clone();
        self.generation += 1;
        self.recency
            .push_back((key.clone(), self.generation));
        self.map
            .insert(key.clone(), (value.clone(), self.generation));
        Some(value)
    }

    pub fn put(&mut self, key: K, value: V) {
        self.generation += 1;
        let is_new = self
            .map
            .insert(key.clone(), (value, self.generation))
            .is_none();
        self.recency
            .push_back((key, self.generation));

        if is_new {
            self.evict_if_needed();
        }
    }

    fn evict_if_needed(&mut self) {
        while self.map.len() > self.capacity {
            let Some((key, generation)) = self.recency.pop_front() else {
                break;
            };

            match self.map.get(&key) {
                Some((_, current)) if *current == generation => {
                    self.map.remove(&key);
                    break;
                }
                _ => {}
            }
        }
    }
}

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

    #[test]
    fn put_get_and_len() {
        let mut cache = LruCache::new(2);
        cache.put("a".to_string(), 1);
        cache.put("b".to_string(), 2);

        assert_eq!(cache.len(), 2);
        assert_eq!(cache.get(&"a".to_string()), Some(1));
        assert_eq!(cache.get(&"missing".to_string()), None);
    }

    #[test]
    fn evicts_least_recently_used() {
        let mut cache = LruCache::new(2);
        cache.put("a".to_string(), 1);
        cache.put("b".to_string(), 2);
        cache.put("c".to_string(), 3);

        assert_eq!(cache.get(&"a".to_string()), None);
        assert_eq!(cache.get(&"b".to_string()), Some(2));
        assert_eq!(cache.get(&"c".to_string()), Some(3));
    }

    #[test]
    fn get_updates_recency() {
        let mut cache = LruCache::new(2);
        cache.put("a".to_string(), 1);
        cache.put("b".to_string(), 2);

        // Access "a" so it becomes most recently used.
        assert_eq!(cache.get(&"a".to_string()), Some(1));

        cache.put("c".to_string(), 3); // evicts "b"
        assert_eq!(cache.get(&"b".to_string()), None);
        assert_eq!(cache.get(&"a".to_string()), Some(1));
        assert_eq!(cache.get(&"c".to_string()), Some(3));
    }

    #[test]
    fn updating_existing_key_moves_it_to_mru() {
        let mut cache = LruCache::new(2);
        cache.put("a".to_string(), 1);
        cache.put("b".to_string(), 2);

        // Update "a"; it becomes MRU, so "b" should be evicted next.
        cache.put("a".to_string(), 10);
        cache.put("c".to_string(), 3);

        assert_eq!(cache.get(&"a".to_string()), Some(10));
        assert_eq!(cache.get(&"b".to_string()), None);
        assert_eq!(cache.get(&"c".to_string()), Some(3));
    }
}

The tests cover the cases of figure 13.1. They check plain eviction, a get that saves an entry, and a put to an existing key, which also counts as a use.

Listing 13.18 Version 2, the arena, with tests. src/problems/lru_cache_easy.rs

//! A fixed-capacity LRU (Least Recently Used) cache.
//!
//! ## Design
//!
//! Two structures cooperate to give O(1) `get` and `put`:
//!
//! * `map: HashMap<K, usize>` — key → index into the arena.
//! * `nodes: Vec<Node<K, V>>` — an **arena** of nodes; indices play the role
//!   of pointers, sidestepping `Rc<RefCell<…>>` and its borrow-checker pain.
//!
//! The arena is stitched into a doubly linked list through `head`/`tail`:
//!
//! ```text
//!   MRU  →  head → … → tail  →  LRU
//! ```
//!
//! On eviction we **reuse the tail slot** instead of removing it, so no node
//! is ever deallocated mid-life. That keeps the arena dense and index-stable.

use std::{collections::HashMap, hash::Hash};

/// A single cache entry, linked into the recency list by index.
struct Node<K, V> {
    /// Retained so we can delete the corresponding map entry when evicting.
    key: K,
    value: V,
    /// Neighbour closer to the MRU end (or `None` if this is `head`).
    prev: Option<usize>,
    /// Neighbour closer to the LRU end (or `None` if this is `tail`).
    next: Option<usize>,
}

/// Fixed-capacity LRU cache.
pub struct LruCache<K, V> {
    /// Maximum number of entries; `>= 1` (enforced by `new`).
    cap: usize,
    /// Key → arena index. The single source of truth for "is this key cached?".
    lookup_table: HashMap<K, usize>,
    /// Arena of nodes; indices are the "pointers" of the linked list.
    nodes: Vec<Node<K, V>>,
    /// Arena index of the most recently used entry.
    head: Option<usize>,
    /// Arena index of the least recently used entry (next to be evicted).
    tail: Option<usize>,
}

impl<K, V> LruCache<K, V>
where
    K: Hash + Eq + Clone,
{
    /// Create a cache holding at most `cap` entries.
    ///
    /// # Panics
    /// Panics if `cap == 0`, since a zero-capacity cache cannot store anything.
    pub fn new(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be > 0");
        Self {
            cap,
            lookup_table: HashMap::new(),
            nodes: Vec::new(),
            head: None,
            tail: None,
        }
    }

    /// Promote node `i` to `head` (MRU).
    ///
    /// Handles both cases in one pass:
    /// * **Already linked** — detach from its current neighbours first.
    /// * **Brand new** — the node has `prev = next = None` and is not yet
    ///   referenced by `head`/`tail`, so the detach step is skipped.
    fn touch(&mut self, i: usize) {
        let (prev, next) = (self.nodes[i].prev, self.nodes[i].next);

        // A node is "linked" if any of its four references exist.
        let linked =
            prev.is_some() || next.is_some() || self.head == Some(i) || self.tail == Some(i);

        if linked {
            // Splice `i` out of the list.
            match prev {
                Some(p) => self.nodes[p].next = next,
                None => self.head = next,
            }
            match next {
                Some(n) => self.nodes[n].prev = prev,
                None => self.tail = prev,
            }
        }

        // Splice `i` in at the front.
        self.nodes[i].prev = None;
        self.nodes[i].next = self.head;
        if let Some(h) = self.head {
            self.nodes[h].prev = Some(i);
        }
        self.head = Some(i);
        if self.tail.is_none() {
            self.tail = Some(i);
        }
    }

    /// Look up `key`, promoting it to MRU on a hit.
    ///
    /// Returns `None` if the key is not cached.
    pub fn get(&mut self, key: &K) -> Option<&V> {
        let i = *self.lookup_table.get(key)?;
        self.touch(i);
        Some(&self.nodes[i].value)
    }

    /// Insert or update `key`. Promotes it to MRU. Evicts the LRU entry if
    /// the cache is full.
    pub fn put(&mut self, key: K, value: V) {
        // Case 1: key already present → update value, promote.
        if let Some(&i) = self.lookup_table.get(&key) {
            self.nodes[i].value = value;
            self.touch(i);
            return;
        }

        // Case 2: room to grow → append a fresh node.
        if self.nodes.len() < self.cap {
            let i = self.nodes.len();
            self.nodes.push(Node {
                key: key.clone(),
                value,
                prev: None,
                next: None,
            });
            self.lookup_table.insert(key, i);
            self.touch(i);
            return;
        }

        // Case 3: at capacity → reuse the LRU slot.
        // `tail` is guaranteed to be `Some` here because `cap >= 1` and the
        // arena is full, but we still handle `None` gracefully.
        if let Some(i) = self.tail {
            let old_key = std::mem::replace(&mut self.nodes[i].key, key);
            self.nodes[i].value = value;
            self.lookup_table.remove(&old_key);
            self.lookup_table
                .insert(self.nodes[i].key.clone(), i);
            self.touch(i);
        }
    }
}

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

    #[test]
    fn basic_eviction() {
        let mut c = LruCache::new(2);
        c.put("A", 1);
        c.put("B", 2);

        assert_eq!(c.get(&"A"), Some(&1)); // A is now MRU
        c.put("C", 3); // evicts B

        assert_eq!(c.get(&"B"), None);
        assert_eq!(c.get(&"A"), Some(&1));
        assert_eq!(c.get(&"C"), Some(&3));
    }

    #[test]
    fn updating_existing_key_keeps_it() {
        let mut c = LruCache::new(2);
        c.put("A", 1);
        c.put("B", 2);

        c.put("A", 100); // update A, A becomes MRU
        c.put("C", 3); // evicts B

        assert_eq!(c.get(&"A"), Some(&100));
        assert_eq!(c.get(&"B"), None);
        assert_eq!(c.get(&"C"), Some(&3));
    }

    #[test]
    fn get_refreshes_recency() {
        let mut c = LruCache::new(2);
        c.put("A", 1);
        c.put("B", 2);

        assert_eq!(c.get(&"A"), Some(&1)); // A refreshed
        c.put("C", 3); // evicts B

        assert_eq!(c.get(&"B"), None);
        assert_eq!(c.get(&"A"), Some(&1));
    }

    #[test]
    fn capacity_one() {
        let mut c = LruCache::new(1);
        c.put("A", 1);
        c.put("B", 2); // evicts A

        assert_eq!(c.get(&"A"), None);
        assert_eq!(c.get(&"B"), Some(&2));
    }

    #[test]
    fn missing_key_returns_none() {
        let mut c: LruCache<&str, i32> = LruCache::new(2);
        assert_eq!(c.get(&"nope"), None);
    }

    #[test]
    #[should_panic(expected = "capacity must be > 0")]
    fn zero_capacity_panics() {
        let _: LruCache<&str, i32> = LruCache::new(0);
    }
}

The tests include a capacity of 1, where the single node is the head and the tail at once. Another test checks that a capacity of 0 panics.

Listing 13.19 Version 3, one operation per method. src/bin/lru_cache_modular.rs

//! A fixed-capacity LRU (Least Recently Used) cache.
//!
//! ## Design
//!
//! Two structures cooperate to give O(1) `get` and `put`:
//!
//! * `lookup_table: HashMap<i32, usize>` — key → index into the arena.
//! * `nodes: Vec<Node>` — an **arena** of nodes; indices play the role
//!   of pointers, sidestepping `Rc<RefCell<…>>` and its borrow-checker pain.
//!
//! The arena is stitched into a doubly linked list through `head`/`tail`:
//!
//! ```text
//!   MRU  →  head → … → tail  →  LRU
//! ```
//!
//! On eviction we **reuse the tail slot** instead of removing it, so no node
//! is ever deallocated mid-life. That keeps the arena dense and index-stable.

use std::collections::HashMap;

/// A single cache entry, linked into the recency list by index.
struct Node {
    /// Retained so we can delete the corresponding map entry when evicting.
    key: i32,
    value: i32,
    /// Neighbour closer to the MRU end (or `None` if this is `head`).
    prev: Option<usize>,
    /// Neighbour closer to the LRU end (or `None` if this is `tail`).
    next: Option<usize>,
}

/// Fixed-capacity LRU cache.
pub struct LruCache {
    /// Maximum number of entries; `>= 1` (enforced by `new`).
    cap: usize,
    /// Key → arena index. The single source of truth for "is this key cached?".
    lookup_table: HashMap<i32, usize>,
    /// Arena of nodes; indices are the "pointers" of the linked list.
    nodes: Vec<Node>,
    /// Arena index of the most recently used entry.
    head: Option<usize>,
    /// Arena index of the least recently used entry (next to be evicted).
    tail: Option<usize>,
}

impl LruCache {
    /// Create a cache holding at most `cap` entries.
    ///
    /// # Panics
    /// Panics if `cap == 0`, since a zero-capacity cache cannot store anything.
    pub fn new(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be > 0");
        Self {
            cap,
            lookup_table: HashMap::new(),
            nodes: Vec::new(),
            head: None,
            tail: None,
        }
    }

    /// Unlink node `i` from the list. `i` must currently be linked.
    fn detach(&mut self, i: usize) {
        let (prev, next) = (self.nodes[i].prev, self.nodes[i].next);
        match prev {
            Some(p) => self.nodes[p].next = next,
            None => self.head = next,
        }
        match next {
            Some(n) => self.nodes[n].prev = prev,
            None => self.tail = prev,
        }
    }

    /// Link node `i` in at the MRU end. `i` must currently be unlinked.
    fn push_front(&mut self, i: usize) {
        self.nodes[i].prev = None;
        self.nodes[i].next = self.head;
        match self.head {
            Some(h) => self.nodes[h].prev = Some(i),
            None => self.tail = Some(i), // list was empty
        }
        self.head = Some(i);
    }

    /// Promote an already-linked node to MRU.
    fn promote_to_front(&mut self, i: usize) {
        if self.head == Some(i) {
            return; // already MRU
        }
        self.detach(i);
        self.push_front(i);
    }

    /// Look up `key`, promoting it to MRU on a hit.
    ///
    /// Returns `None` if the key is not cached.
    pub fn get(&mut self, key: i32) -> Option<i32> {
        let i = *self.lookup_table.get(&key)?;
        self.promote_to_front(i);
        Some(self.nodes[i].value)
    }

    /// Insert or update `key`. Promotes it to MRU. Evicts the LRU entry if
    /// the cache is full.
    pub fn put(&mut self, key: i32, value: i32) {
        // Case 1: key already present → update value, promote.
        if let Some(&i) = self.lookup_table.get(&key) {
            self.nodes[i].value = value;
            self.promote_to_front(i);
            return;
        }

        // Case 2: room to grow → append a fresh (unlinked) node.
        if self.nodes.len() < self.cap {
            let i = self.nodes.len();
            self.nodes.push(Node {
                key,
                value,
                prev: None,
                next: None,
            });
            self.lookup_table.insert(key, i);
            self.push_front(i);
            return;
        }

        // Case 3: at capacity → reuse the LRU slot.
        // `tail` is guaranteed to be `Some` here because `cap >= 1` and the
        // arena is full, but we still handle `None` gracefully.
        if let Some(i) = self.tail {
            // Swap the new key into the node and hand back the old one it held.
            let old_key = std::mem::replace(&mut self.nodes[i].key, key);
            self.nodes[i].value = value;
            self.lookup_table.remove(&old_key);
            self.lookup_table.insert(key, i);
            self.promote_to_front(i);
        }
    }
}

fn main() {
    let mut cache = LruCache::new(2);

    cache.put(1, 10);
    cache.put(2, 20);
    println!("get 1 = {:?}", cache.get(1)); // Some(10), 1 now MRU

    cache.put(3, 30); // evicts 2 (LRU)

    println!("get 2 = {:?}", cache.get(2)); // None
    println!("get 1 = {:?}", cache.get(1)); // Some(10)
    println!("get 3 = {:?}", cache.get(3)); // Some(30)

    cache.put(1, 99);
    println!("get 1 = {:?}", cache.get(1)); // Some(99)
}

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

    #[test]
    fn basic_eviction() {
        let mut c = LruCache::new(2);
        c.put(1, 10);
        c.put(2, 20);

        assert_eq!(c.get(1), Some(10)); // 1 is now MRU
        c.put(3, 30); // evicts 2

        assert_eq!(c.get(2), None);
        assert_eq!(c.get(1), Some(10));
        assert_eq!(c.get(3), Some(30));
    }

    #[test]
    fn updating_existing_key_keeps_it() {
        let mut c = LruCache::new(2);
        c.put(1, 10);
        c.put(2, 20);

        c.put(1, 100); // update 1, 1 becomes MRU
        c.put(3, 30); // evicts 2

        assert_eq!(c.get(1), Some(100));
        assert_eq!(c.get(2), None);
        assert_eq!(c.get(3), Some(30));
    }

    #[test]
    fn get_refreshes_recency() {
        let mut c = LruCache::new(2);
        c.put(1, 10);
        c.put(2, 20);

        assert_eq!(c.get(1), Some(10)); // 1 refreshed
        c.put(3, 30); // evicts 2

        assert_eq!(c.get(2), None);
        assert_eq!(c.get(1), Some(10));
    }

    #[test]
    fn capacity_one() {
        let mut c = LruCache::new(1);
        c.put(1, 10);
        c.put(2, 20); // evicts 1

        assert_eq!(c.get(1), None);
        assert_eq!(c.get(2), Some(20));
    }

    #[test]
    fn missing_key_returns_none() {
        let mut c = LruCache::new(2);
        assert_eq!(c.get(42), None);
    }

    #[test]
    #[should_panic(expected = "capacity must be > 0")]
    fn zero_capacity_panics() {
        let _ = LruCache::new(0);
    }
}

Listing 13.20 The arena LRU cache. src/bin/lru_cache_arena.rs

//! A fixed-capacity LRU (Least Recently Used) cache.
//!
//! ## Design
//!
//! Two structures cooperate to give O(1) `get` and `put`:
//!
//! * `map: HashMap<K, usize>` — key → index into the arena.
//! * `nodes: Vec<Node<K, V>>` — an **arena** of nodes; indices play the role
//!   of pointers, sidestepping `Rc<RefCell<…>>` and its borrow-checker pain.
//!
//! The arena is stitched into a doubly linked list through `head`/`tail`:
//!
//! ```text
//!   MRU  →  head → … → tail  →  LRU
//! ```
//!
//! On eviction we **reuse the tail slot** instead of removing it, so no node
//! is ever deallocated mid-life. That keeps the arena dense and index-stable.

use std::{collections::HashMap, hash::Hash};

/// A single cache entry, linked into the recency list by index.
struct Node<K, V> {
    /// Retained so we can delete the corresponding map entry when evicting.
    key: K,
    value: V,
    /// Neighbour closer to the MRU end (or `None` if this is `head`).
    prev: Option<usize>,
    /// Neighbour closer to the LRU end (or `None` if this is `tail`).
    next: Option<usize>,
}

/// Fixed-capacity LRU cache.
pub struct LruCache<K, V> {
    /// Maximum number of entries; `>= 1` (enforced by `new`).
    cap: usize,
    /// Key → arena index. The single source of truth for "is this key cached?".
    lookup_table: HashMap<K, usize>,
    /// Arena of nodes; indices are the "pointers" of the linked list.
    nodes: Vec<Node<K, V>>,
    /// Arena index of the most recently used entry.
    head: Option<usize>,
    /// Arena index of the least recently used entry (next to be evicted).
    tail: Option<usize>,
}

impl<K, V> LruCache<K, V>
where
    K: Hash + Eq + Clone,
{
    /// Create a cache holding at most `cap` entries.
    ///
    /// # Panics
    /// Panics if `cap == 0`, since a zero-capacity cache cannot store anything.
    pub fn new(cap: usize) -> Self {
        assert!(cap > 0, "capacity must be > 0");
        Self {
            cap,
            lookup_table: HashMap::new(),
            nodes: Vec::new(),
            head: None,
            tail: None,
        }
    }

    /// Promote node `i` to `head` (MRU).
    ///
    /// Handles both cases in one pass:
    /// * **Already linked** — detach from its current neighbours first.
    /// * **Brand new** — the node has `prev = next = None` and is not yet
    ///   referenced by `head`/`tail`, so the detach step is skipped.
    fn touch(&mut self, i: usize) {
        let (prev, next) = (self.nodes[i].prev, self.nodes[i].next);

        // A node is "linked" if any of its four references exist.
        let linked =
            prev.is_some() || next.is_some() || self.head == Some(i) || self.tail == Some(i);

        if linked {
            // Splice `i` out of the list.
            match prev {
                Some(p) => self.nodes[p].next = next,
                None => self.head = next,
            }
            match next {
                Some(n) => self.nodes[n].prev = prev,
                None => self.tail = prev,
            }
        }

        // Splice `i` in at the front.
        self.nodes[i].prev = None;
        self.nodes[i].next = self.head;
        if let Some(h) = self.head {
            self.nodes[h].prev = Some(i);
        }
        self.head = Some(i);
        if self.tail.is_none() {
            self.tail = Some(i);
        }
    }

    /// Look up `key`, promoting it to MRU on a hit.
    ///
    /// Returns `None` if the key is not cached.
    pub fn get(&mut self, key: &K) -> Option<&V> {
        let i = *self.lookup_table.get(key)?;
        self.touch(i);
        Some(&self.nodes[i].value)
    }

    /// Insert or update `key`. Promotes it to MRU. Evicts the LRU entry if
    /// the cache is full.
    pub fn put(&mut self, key: K, value: V) {
        // Case 1: key already present → update value, promote.
        if let Some(&i) = self.lookup_table.get(&key) {
            self.nodes[i].value = value;
            self.touch(i);
            return;
        }

        // Case 2: room to grow → append a fresh node.
        if self.nodes.len() < self.cap {
            let i = self.nodes.len();
            self.nodes.push(Node {
                key: key.clone(),
                value,
                prev: None,
                next: None,
            });
            self.lookup_table.insert(key, i);
            self.touch(i);
            return;
        }

        // Case 3: at capacity → reuse the LRU slot.
        // `tail` is guaranteed to be `Some` here because `cap >= 1` and the
        // arena is full, but we still handle `None` gracefully.
        if let Some(i) = self.tail {
            let old_key = std::mem::replace(&mut self.nodes[i].key, key);
            self.nodes[i].value = value;
            self.lookup_table.remove(&old_key);
            self.lookup_table
                .insert(self.nodes[i].key.clone(), i);
            self.touch(i);
        }
    }
}

fn main() {
    let mut cache = LruCache::new(2);

    cache.put("A", 10);
    cache.put("B", 20);
    println!("get A = {:?}", cache.get(&"A")); // Some(10), A now MRU

    cache.put("C", 30); // evicts B (LRU)

    println!("get B = {:?}", cache.get(&"B")); // None
    println!("get A = {:?}", cache.get(&"A")); // Some(10)
    println!("get C = {:?}", cache.get(&"C")); // Some(30)

    cache.put("A", 99);
    println!("get A = {:?}", cache.get(&"A")); // Some(99)
}

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

    #[test]
    fn basic_eviction() {
        let mut c = LruCache::new(2);
        c.put("A", 1);
        c.put("B", 2);

        assert_eq!(c.get(&"A"), Some(&1)); // A is now MRU
        c.put("C", 3); // evicts B

        assert_eq!(c.get(&"B"), None);
        assert_eq!(c.get(&"A"), Some(&1));
        assert_eq!(c.get(&"C"), Some(&3));
    }

    #[test]
    fn updating_existing_key_keeps_it() {
        let mut c = LruCache::new(2);
        c.put("A", 1);
        c.put("B", 2);

        c.put("A", 100); // update A, A becomes MRU
        c.put("C", 3); // evicts B

        assert_eq!(c.get(&"A"), Some(&100));
        assert_eq!(c.get(&"B"), None);
        assert_eq!(c.get(&"C"), Some(&3));
    }

    #[test]
    fn get_refreshes_recency() {
        let mut c = LruCache::new(2);
        c.put("A", 1);
        c.put("B", 2);

        assert_eq!(c.get(&"A"), Some(&1)); // A refreshed
        c.put("C", 3); // evicts B

        assert_eq!(c.get(&"B"), None);
        assert_eq!(c.get(&"A"), Some(&1));
    }

    #[test]
    fn capacity_one() {
        let mut c = LruCache::new(1);
        c.put("A", 1);
        c.put("B", 2); // evicts A

        assert_eq!(c.get(&"A"), None);
        assert_eq!(c.get(&"B"), Some(&2));
    }

    #[test]
    fn missing_key_returns_none() {
        let mut c: LruCache<&str, i32> = LruCache::new(2);
        assert_eq!(c.get(&"nope"), None);
    }

    #[test]
    #[should_panic(expected = "capacity must be > 0")]
    fn zero_capacity_panics() {
        let _: LruCache<&str, i32> = LruCache::new(0);
    }
}

Listing 13.21 The Rc<RefCell<_>> LRU cache used by the benchmark. benchmarking_examples/cache/rc_list.rs

//! LRU cache built from an `Rc<RefCell<_>>` doubly linked list.
//!
//! The textbook version: `Rc` forward, `Weak` back, and a `HashMap` from key to
//! node. Every node is its own heap allocation, and every move to the front
//! clones an `Rc`, upgrades a `Weak`, and borrows the `RefCell`.
//!
//! The default drop would free a node, which frees its `next`, one stack frame
//! per element, so `Drop` is written to unlink iteratively.

use std::{
    cell::RefCell,
    collections::HashMap,
    hash::Hash,
    rc::{Rc, Weak},
};

use super::Cache;

type Link<K, V> = Option<Rc<RefCell<Node<K, V>>>>;

struct Node<K, V> {
    key: K,
    value: V,
    prev: Weak<RefCell<Node<K, V>>>,
    next: Link<K, V>,
}

pub struct LruCache<K, V> {
    cap: usize,
    map: HashMap<K, Rc<RefCell<Node<K, V>>>>,
    head: Link<K, V>,
    tail: Link<K, V>,
}

impl<K, V> LruCache<K, V>
where
    K: Hash + Eq + Clone,
    V: Copy,
{
    fn detach(&mut self, node: &Rc<RefCell<Node<K, V>>>) {
        let (prev, next) = {
            let entry = node.borrow();
            (entry.prev.clone(), entry.next.clone())
        };

        match prev.upgrade() {
            Some(previous) => previous.borrow_mut().next = next.clone(),
            None => self.head = next.clone(),
        }
        match &next {
            Some(following) => following.borrow_mut().prev = prev,
            None => self.tail = prev.upgrade(),
        }
    }

    fn push_front(&mut self, node: Rc<RefCell<Node<K, V>>>) {
        let head = self.head.clone();
        {
            let mut entry = node.borrow_mut();
            entry.prev = Weak::new();
            entry.next = head.clone();
        }
        match &head {
            Some(previous) => previous.borrow_mut().prev = Rc::downgrade(&node),
            None => self.tail = Some(node.clone()),
        }
        self.head = Some(node);
    }
}

impl<K, V> Cache<K, V> for LruCache<K, V>
where
    K: Hash + Eq + Clone,
    V: Copy,
{
    fn new(capacity: usize) -> Self {
        assert!(capacity > 0, "capacity must be > 0");
        Self {
            cap: capacity,
            map: HashMap::new(),
            head: None,
            tail: None,
        }
    }

    fn get(&mut self, key: &K) -> Option<V> {
        let node = self.map.get(key)?.clone();
        self.detach(&node);
        self.push_front(node.clone());
        Some(node.borrow().value)
    }

    fn put(&mut self, key: K, value: V) {
        if let Some(node) = self.map.get(&key).cloned() {
            node.borrow_mut().value = value;
            self.detach(&node);
            self.push_front(node);
            return;
        }

        if self.map.len() >= self.cap
            && let Some(victim) = self.tail.clone()
        {
            let old_key = victim.borrow().key.clone();
            self.map.remove(&old_key);
            self.detach(&victim);
        }

        let node = Rc::new(RefCell::new(Node {
            key: key.clone(),
            value,
            prev: Weak::new(),
            next: None,
        }));
        self.map.insert(key, node.clone());
        self.push_front(node);
    }

    fn len(&self) -> usize {
        self.map.len()
    }

    fn variant() -> &'static str {
        "Rc<RefCell> list"
    }
}

impl<K, V> Drop for LruCache<K, V> {
    fn drop(&mut self) {
        // Unlink iteratively: dropping a million-node chain recursively overflows
        // the stack.
        let mut current = self.head.take();
        while let Some(node) = current {
            let next = node.borrow_mut().next.take();
            node.borrow_mut().prev = Weak::new();
            current = next;
        }
    }
}

Chapter 14 spreads a cache across several machines, and asks how to decide which machine holds which key.

Exercises

1. Bound the queue in version 1. When recency grows longer than twice the capacity, rebuild it with only the current events. Check that the cost stays amortized O(1).
2. Add peek(&self, key: &K) -> Option<&V> to version 2, which returns a value without changing the order.
3. Add remove(&mut self, key: &K) -> Option<V> to version 3. The removed slot must be reused by a later put. Keep a list of free slots.
4. Change the benchmark’s CACHE_CAPACITY to the full key space, so no request evicts anything. Compare the ratio with the one above, and explain what the change tells you about the cost of allocation.

Shards and consistent hashing

The caches of chapter 13 serve one thread at a time. This chapter asks what happens when many threads, or many machines, share one set of keys.

Both halves of the chapter use the same idea. You split the keys into groups by their hash, and each group is handled separately. A group of keys handled separately is called a shard.

Section 14.1 splits a map inside one program, so threads that use different keys do not wait for each other. Section 14.2 splits keys across machines, so that adding or removing a machine moves as few keys as possible.

14.1 A map split into shards

Section 8.6 showed how to share a value between threads: wrap it in a Mutex, and share the Mutex with an Arc. A thread calls lock() before it touches the value. While one thread holds the lock, every other thread that calls lock() waits.

A single Mutex<HashMap<K, V>> is safe, but it has a cost. If four threads use the map at once, three of them wait, even when each thread wants a different key. Waiting for a lock that another thread holds is called lock contention.

The fix is to give the map several locks. Split it into, say, eight smaller maps, each with its own Mutex (figure 14.1). A key always goes to the same small map. Two threads then wait for each other only when their keys land in the same shard.

Animation 14.1 sends one key and value from each thread into the map. Under the single lock the pairs go in one at a time and stay. Under eight shards they go in together, each into the shard that owns its key.

14.1.1 The type

The cache holds a list of shards, each a HashMap behind its own Mutex. It also holds the hasher that decides which shard a key belongs to.

Listing 14.1 The type and the constructor (lines 16 to 42). src/problems/sharded_cache.rs

use std::{
    collections::{HashMap, hash_map::RandomState},
    hash::{BuildHasher, Hash},
    sync::Mutex,
};

/// A fixed-size map split across independently locked shards.
///
/// The shard count is rounded up to a power of two so the index is a mask instead
/// of a modulo.
pub struct ShardedCache<K, V> {
    shards: Vec<Mutex<HashMap<K, V>>>,
    hasher: RandomState,
    mask: usize,
}

impl<K, V> ShardedCache<K, V>
where
    K: Hash + Eq,
{
    /// Create a cache with at least `shard_count` shards (rounded to a power of two).
    pub fn new(shard_count: usize) -> Self {
        let shard_count = shard_count.max(1).next_power_of_two();

        let shards = (0..shard_count)
            .map(|_| Mutex::new(HashMap::new()))
            .collect();
        Self {
            shards,
            hasher: RandomState::new(),
            mask: shard_count - 1,
        }
    }
    // ...
}

ShardedCache has three fields:

• shards is a Vec of maps, each inside its own Mutex.
• hasher produces the hash that picks a shard for a key.
• mask turns a hash into a shard number, as the next section explains.

new builds the Vec with an iterator. (0..shard_count).map(|_| Mutex::new(HashMap::new())) makes one empty, locked map per shard, and collect() gathers them. The _ in the closure ignores the shard number, which is not needed.

The first line of new adjusts the requested count. shard_count.max(1) turns a request for 0 shards into 1. .next_power_of_two() rounds up to the next power of two, so a request for 6 shards gives 8.

14.1.2 Picking a shard with a mask

A shard count that is a power of two lets the code pick a shard cheaply. For 8 shards, the mask is 8 − 1 = 7, which is 0b111 in binary. The operation hash & mask keeps the lowest three bits of the hash and clears the rest. The result is a number from 0 to 7 (figure 14.2).

hash % 8 would give the same answer. The & is one simple CPU instruction, while % is a division, which takes more time. The difference is small, but this code runs on every call.

Listing 14.2 Picking a shard (lines 45 to 48).

impl<K, V> ShardedCache<K, V>
where
    K: Hash + Eq,
{
    // ...
    fn shard(&self, key: &K) -> &Mutex<HashMap<K, V>> {
        let index = (self.hasher.hash_one(key) as usize) & self.mask;
        &self.shards[index]
    }
    // ...
}

hash_one hashes the key with the cache’s RandomState and returns a u64. The mask keeps its low bits as the shard index. It returns a reference to the chosen shard’s Mutex.

The cache keeps one RandomState for its whole life. RandomState::new() picks random secret keys for the hash function when the cache is created. Every lookup in the same cache uses the same keys, so a key always maps to the same shard. A different cache, or the same program run again, would place the keys differently.

HashMap uses RandomState for the same reason. Random keys stop an attacker from choosing inputs that all hash to the same place and slow the map down.

// 1. The bytes added up. Every order of the same bytes gives one number.
fn hash_sum(bytes: &[u8]) -> u64 {
    bytes.iter().map(|b| u64::from(*b)).sum()
}

// 2. The first byte only. Every key with the same first letter collides.
fn hash_first(bytes: &[u8]) -> u64 {
    u64::from(bytes.first().copied().unwrap_or(0))
}

// 3. The key itself, for a numeric key. The low bits repeat every eight.
fn hash_identity(key: u64) -> u64 {
    key
}

14.1.3 Each method locks one shard

A single-key operation touches one shard only. It hashes the key, locks that shard, and leaves every other shard free for other threads.

Listing 14.3 insert, get, and with (lines 50 to 80).

impl<K, V> ShardedCache<K, V>
where
    K: Hash + Eq,
{
    // ...
    /// Insert a value, returning the previous one if the key was present.
    pub fn insert(&self, key: K, value: V) -> Option<V> {
        self.shard(&key)
            .lock()
            .expect("shard mutex poisoned")
            .insert(key, value)
    }

    /// Read a value by cloning it out of the shard.
    pub fn get(&self, key: &K) -> Option<V>
    where
        V: Clone,
    {
        self.shard(key)
            .lock()
            .expect("shard mutex poisoned")
            .get(key)
            .cloned()
    }

    /// Run `inspect` against the value under the shard lock, without cloning.
    ///
    /// Use this for read-modify-write on a single key; the closure holds the lock
    /// for its duration, so keep it short and do not call back into the cache.
    pub fn with<R>(&self, key: &K, inspect: impl FnOnce(Option<&V>) -> R) -> R {
        let guard = self
            .shard(key)
            .lock()
            .expect("shard mutex poisoned");
        inspect(guard.get(key))
    }
    // ...
}

Each method follows the same three steps: pick the shard, lock it, and call the matching HashMap method. The methods take &self, not &mut self. The Mutex provides the permission to change the map, so a shared reference to the cache is enough. Several threads can then share one cache through an Arc.

lock() returns a Result. It is an error only if another thread panicked while it held the same lock. Such a lock is called poisoned, and chapter 16 covers it. Here .expect(...) turns that error into a panic with a clear message.

The lock stays held until the guard returned by lock() is dropped. In insert, the guard is a temporary value in one expression, so it is dropped at the end of the statement.

get must return a clone of the value, which is why it asks for V: Clone. A reference to the value would point into the map, and the map is only reachable through the guard. When get returns, the guard is dropped and the lock released. A reference could then be read while another thread changes the map, so the compiler does not allow it to escape.

14.1.4 Reading under the lock with a closure

Cloning a large value only to read one field of it wastes work. with avoids the clone. You pass it a closure, and with runs the closure while it holds the lock:

pub fn with<R>(&self, key: &K, inspect: impl FnOnce(Option<&V>) -> R) -> R

• inspect: impl FnOnce(Option<&V>) -> R accepts any closure that takes an Option<&V> and returns some type R. FnOnce means with calls it at most once.
• The closure receives a reference into the map, valid while the lock is held.
• Only the closure’s result, of type R, leaves the function. R cannot borrow from the map.

The test with_exposes_the_value_without_cloning uses it to read the length of a String:

let observed = cache.with(&"node", |value| value.map(|v| v.len()));

The doc comment of with gives two rules. Keep the closure short, because every other thread that needs the same shard waits while it runs. And do not call the cache from inside the closure. A call that lands on the same shard would try to lock a Mutex that this thread already holds. The standard Mutex does not allow that: the thread blocks forever or panics. A thread waiting forever for a lock is called a deadlock.

14.1.5 Operations on every shard

Some operations need every shard: the total size, and clearing the cache. They visit the shards one at a time.

Listing 14.4 len and clear (lines 96 to 119).

impl<K, V> ShardedCache<K, V>
where
    K: Hash + Eq,
{
    // ...
    pub fn len(&self) -> usize {
        self.shards
            .iter()
            .map(|shard| {
                shard
                    .lock()
                    .expect("shard mutex poisoned")
                    .len()
            })
            .sum()
    }

    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    pub fn clear(&self) {
        for shard in &self.shards {
            shard
                .lock()
                .expect("shard mutex poisoned")
                .clear();
        }
    }
    // ...
}

len locks each shard in turn, reads its size, releases the lock, and adds up the sizes. clear also visits the shards one at a time.

This is the price of sharding, and the comment at the top of the file states it. No moment exists when all shards are locked together. While len runs, other threads can insert into shards it has already counted. The total is correct if no other thread is writing, and approximate if one is.

14.1.6 The complete file

Listing 14.5 The complete file, with tests. src/problems/sharded_cache.rs

//! Sharded concurrent map to reduce lock contention.
//!
//! A single `Mutex<HashMap>` serializes every access. Splitting the map into N
//! shards, each with its own lock, lets independent keys proceed in parallel. The
//! cost is that `len` and `clear` must visit every shard, and there is no global
//! atomic snapshot.
//!
//! Typical uses: per-account token caches, metadata caches, and request
//! de-duplication tables.

use std::{
    collections::{HashMap, hash_map::RandomState},
    hash::{BuildHasher, Hash},
    sync::Mutex,
};

/// A fixed-size map split across independently locked shards.
///
/// The shard count is rounded up to a power of two so the index is a mask instead
/// of a modulo.
pub struct ShardedCache<K, V> {
    shards: Vec<Mutex<HashMap<K, V>>>,
    hasher: RandomState,
    mask: usize,
}

impl<K, V> ShardedCache<K, V>
where
    K: Hash + Eq,
{
    /// Create a cache with at least `shard_count` shards (rounded to a power of two).
    pub fn new(shard_count: usize) -> Self {
        let shard_count = shard_count.max(1).next_power_of_two();

        let shards = (0..shard_count)
            .map(|_| Mutex::new(HashMap::new()))
            .collect();
        Self {
            shards,
            hasher: RandomState::new(),
            mask: shard_count - 1,
        }
    }

    fn shard(&self, key: &K) -> &Mutex<HashMap<K, V>> {
        let index = (self.hasher.hash_one(key) as usize) & self.mask;
        &self.shards[index]
    }

    /// Insert a value, returning the previous one if the key was present.
    pub fn insert(&self, key: K, value: V) -> Option<V> {
        self.shard(&key)
            .lock()
            .expect("shard mutex poisoned")
            .insert(key, value)
    }

    /// Read a value by cloning it out of the shard.
    pub fn get(&self, key: &K) -> Option<V>
    where
        V: Clone,
    {
        self.shard(key)
            .lock()
            .expect("shard mutex poisoned")
            .get(key)
            .cloned()
    }

    /// Run `inspect` against the value under the shard lock, without cloning.
    ///
    /// Use this for read-modify-write on a single key; the closure holds the lock
    /// for its duration, so keep it short and do not call back into the cache.
    pub fn with<R>(&self, key: &K, inspect: impl FnOnce(Option<&V>) -> R) -> R {
        let guard = self
            .shard(key)
            .lock()
            .expect("shard mutex poisoned");
        inspect(guard.get(key))
    }

    pub fn remove(&self, key: &K) -> Option<V> {
        self.shard(key)
            .lock()
            .expect("shard mutex poisoned")
            .remove(key)
    }

    pub fn contains_key(&self, key: &K) -> bool {
        self.shard(key)
            .lock()
            .expect("shard mutex poisoned")
            .contains_key(key)
    }

    pub fn len(&self) -> usize {
        self.shards
            .iter()
            .map(|shard| {
                shard
                    .lock()
                    .expect("shard mutex poisoned")
                    .len()
            })
            .sum()
    }

    pub fn is_empty(&self) -> bool {
        self.len() == 0
    }

    pub fn clear(&self) {
        for shard in &self.shards {
            shard
                .lock()
                .expect("shard mutex poisoned")
                .clear();
        }
    }

    pub fn shard_count(&self) -> usize {
        self.shards.len()
    }
}

#[cfg(test)]
mod tests {
    use std::{sync::Arc, thread};

    use super::*;

    #[test]
    fn insert_get_remove() {
        let cache: ShardedCache<String, u32> = ShardedCache::new(4);
        assert_eq!(cache.insert("server-1".into(), 8), None);
        assert_eq!(cache.get(&"server-1".into()), Some(8));
        assert_eq!(cache.insert("server-1".into(), 16), Some(8));
        assert_eq!(cache.get(&"server-1".into()), Some(16));
        assert_eq!(cache.remove(&"server-1".into()), Some(16));
        assert!(!cache.contains_key(&"server-1".into()));
        assert!(cache.is_empty());
    }

    #[test]
    fn with_exposes_the_value_without_cloning() {
        let cache: ShardedCache<&str, String> = ShardedCache::new(2);
        cache.insert("node", "ABCD".to_string());
        let observed = cache.with(&"node", |value| value.map(|v| v.len()));
        assert_eq!(observed, Some(4));
    }

    #[test]
    fn concurrent_writers_all_land() {
        let cache = Arc::new(ShardedCache::new(16));
        let mut handles = Vec::new();

        for writer in 0..8 {
            let cache = Arc::clone(&cache);
            handles.push(thread::spawn(move || {
                for key in 0..500 {
                    cache.insert(format!("{writer}-{key}"), key);
                }
            }));
        }
        for handle in handles {
            handle.join().expect("writer panicked");
        }

        assert_eq!(cache.len(), 8 * 500);
    }

    #[test]
    fn keys_spread_across_shards() {
        let cache: ShardedCache<u32, u32> = ShardedCache::new(8);
        for key in 0..4_096 {
            cache.insert(key, key);
        }
        // Every shard should hold roughly 1/8 of the keys; assert none is starved.
        let smallest = cache
            .shards
            .iter()
            .map(|shard| {
                shard
                    .lock()
                    .expect("shard mutex poisoned")
                    .len()
            })
            .min()
            .expect("at least one shard");
        assert!(smallest > 0, "at least one shard was empty");
    }
}

The test concurrent_writers_all_land is the one that uses threads. It wraps the cache in an Arc, and starts eight threads with thread::spawn. Each thread gets its own clone of the Arc and inserts 500 keys. join() waits for each thread to finish. The final len must be 8 × 500 = 4,000, which shows that no insert was lost.

The test keys_spread_across_shards inserts 4,096 keys into 8 shards and checks that no shard is empty. It reaches the private shards field directly. A test module inside the file can see private items of its parent module.

$ cargo test --lib problems::sharded_cache
running 4 tests
test problems::sharded_cache::tests::with_exposes_the_value_without_cloning ... ok
test problems::sharded_cache::tests::insert_get_remove ... ok
test problems::sharded_cache::tests::concurrent_writers_all_land ... ok
test problems::sharded_cache::tests::keys_spread_across_shards ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 133 filtered out

14.2 Spreading keys across machines

Now move from threads to machines. Suppose a cache is spread over several servers, and each key must live on exactly one of them. Every client must compute the same server for the same key, with no central directory to ask.

14.2.1 The problem with hash % N

The obvious rule is hash(key) % N, where N is the number of servers. It spreads keys evenly and needs no storage. It breaks down when N changes.

Figure 14.3 shows keys with hashes 0 to 11 when a fourth server joins three others. A key stays in place only if hash % 3 equals hash % 4.

The pattern repeats every 12 hashes, so 75% of all keys change servers. For a cache, a moved key is a miss: the new server does not have it. Adding one server would empty most of the cache at once.

14.2.2 The ring

Consistent hashing places both servers and keys on a circle of hash values, called the ring. The ring covers every u64 value. After the largest value, it wraps around to 0.

Each server is hashed to a point on the ring. A key is hashed too, and it belongs to the first server point clockwise from it. In practice, “clockwise” means “the next larger hash”.

When a server joins, it takes over only the keys between its point and the point before it. Every other key keeps its server. When a server leaves, only its own keys move, to the next point clockwise.

With one point per server, the arcs between points are uneven, so some servers get much more of the ring than others. The fix is to place each server at many points, called virtual nodes. With many small arcs per server, the shares even out (figure 14.4).

Figure 14.5 shows the ring cut open and laid flat, before and after a third node joins.

Animation 14.2 follows the join through the whole system. It shows the ring, the keys each node holds, the key that moves, and the clients that learn about it.

Each node keeps the keys it owns. A join moves the keys in the new arc from the old owner to the new one. Every client also keeps a ConsistentHash of its own and computes the owner locally, so no lookup needs a central directory. When a node joins or leaves, each client has to learn the new ring. Until it does, it sends keys to the old owner. A client that still points k30 at node b asks a node that has given that key up.

With n servers, a new server takes over about 1/(n + 1) of the keys. Going from 3 servers to 4 moves about 25% of the keys, where hash % N moved 75%.

14.2.3 The ring as a sorted Vec

The ring of figure 14.4 can be stored as a vector of points, kept sorted by hash. Each point records its position on the ring and the server it belongs to.

Listing 14.6 The type and add_node (lines 17 to 55). src/problems/consistent_hash.rs

use std::{
    collections::{HashSet, hash_map::DefaultHasher},
    hash::{Hash, Hasher},
    sync::Arc,
};

/// A hash ring mapping keys to node names.
pub struct ConsistentHash {
    replicas: usize,
    /// Sorted `(hash, node)` pairs. The node name is an `Arc<str>` so that the
    /// many virtual nodes for one physical node share a single allocation.
    ring: Vec<(u64, Arc<str>)>,
}

impl ConsistentHash {
    /// Create an empty ring with `replicas` virtual nodes per physical node.
    /// Panics if `replicas` is zero.
    pub fn new(replicas: usize) -> Self {
        assert!(replicas > 0, "replicas must be > 0");
        Self {
            replicas,
            ring: Vec::new(),
        }
    }

    /// Add a node and its virtual nodes. Adding a node that already exists is a
    /// no-op.
    pub fn add_node(&mut self, node: &str) {
        if self
            .ring
            .iter()
            .any(|(_, name)| name.as_ref() == node)
        {
            return;
        }

        // One allocation for the name, then a refcount bump per virtual node.
        let name: Arc<str> = Arc::from(node);
        for replica in 0..self.replicas {
            let hash = virtual_node_hash(node, replica);
            self.ring
                .push((hash, Arc::clone(&name)));
        }
        self.ring.sort_by_key(|(hash, _)| *hash);
    }

    /// Remove a node and all of its virtual nodes.
    pub fn remove_node(&mut self, node: &str) {
        self.ring
            .retain(|(_, name)| name.as_ref() != node);
    }
    // ...
}

The ring is a Vec<(u64, Arc<str>)>, kept sorted by hash. Each entry is one virtual node: its position on the ring, and the name of the server it belongs to.

With 128 virtual nodes per server, each name would be stored 128 times as a String. The code stores it as Arc<str> instead. Arc::from(node) copies the name into one heap block once. Each Arc::clone(&name) then adds a pointer to that same block and increases its reference count. No text is copied.

add_node does three things:

1. It checks whether the server is already on the ring, by scanning the entries. If so, it returns.
2. It pushes one entry per virtual node, with the hash from virtual_node_hash.
3. It sorts the ring by hash again.

remove_node keeps every entry that belongs to another server, with retain. Removing entries does not change the order of the rest, so the ring stays sorted.

Listing 14.7 The hash functions (lines 94 to 109).

fn hash_of(input: &str) -> u64 {
    let mut hasher = DefaultHasher::new();
    input.hash(&mut hasher);
    hasher.finish()
}

/// Hash of the `replica`-th virtual node for `node`.
///
/// Hashing the two fields separately avoids allocating a `"{node}#{replica}"`
/// string for every virtual node on the ring.
fn virtual_node_hash(node: &str, replica: usize) -> u64 {
    let mut hasher = DefaultHasher::new();
    node.hash(&mut hasher);
    replica.hash(&mut hasher);
    hasher.finish()
}

virtual_node_hash feeds both the server name and the replica number into one hasher. Each replica number gives a different point for the same server. Feeding the two values separately avoids building a string such as "node-a#17" for every virtual node.

14.2.4 Finding a key’s server

To find a key’s server, hash the key and find the first point on the ring after that hash. If there is none, wrap around to the first point.

Listing 14.8 get (lines 64 to 77).

impl ConsistentHash {
    // ...
    /// Return the node responsible for `key`, or `None` when the ring is empty.
    pub fn get(&self, key: &str) -> Option<&str> {
        if self.ring.is_empty() {
            return None;
        }

        let hash = hash_of(key);
        // First virtual node strictly clockwise from the key.
        let index = self
            .ring
            .partition_point(|(point, _)| *point <= hash);
        let index = if index == self.ring.len() { 0 } else { index };
        Some(self.ring[index].1.as_ref())
    }
    // ...
}

get must find the first ring entry with a hash larger than the key’s hash. The ring is sorted, so a binary search can find it in O(log n) steps, as in section 3.10.

partition_point performs that binary search. It takes a condition that is true for a first part of the slice and false for the rest. It returns the index where the condition turns false (figure 14.6). Here the condition is point <= hash, so the result is the index of the first point larger than the key’s hash.

If the key’s hash is larger than every point, partition_point returns the length of the ring. The ring wraps around there, so the code uses index 0 instead.

get returns Option<&str>, a reference into the ring. .as_ref() turns the Arc<str> into a &str. An empty ring has no servers, so the function returns None for it.

14.2.5 The complete file

Listing 14.9 The complete file, with tests. src/problems/consistent_hash.rs

//! Consistent hashing ring.
//!
//! When a distributed gateway shards work across N backends, a plain
//! `hash(key) % N` remaps nearly every key the moment N changes. Consistent
//! hashing places each node at several points on a hash ring, so adding or
//! removing one node only moves the keys that node owns. That property is the
//! reason it shows up in caches, sharded queues, and load balancers.
//!
//! Each physical node is placed at `replicas` points (virtual nodes) to smooth the
//! key distribution; more replicas means a less lumpy ring.

use std::{
    collections::{HashSet, hash_map::DefaultHasher},
    hash::{Hash, Hasher},
    sync::Arc,
};

/// A hash ring mapping keys to node names.
pub struct ConsistentHash {
    replicas: usize,
    /// Sorted `(hash, node)` pairs. The node name is an `Arc<str>` so that the
    /// many virtual nodes for one physical node share a single allocation.
    ring: Vec<(u64, Arc<str>)>,
}

impl ConsistentHash {
    /// Create an empty ring with `replicas` virtual nodes per physical node.
    /// Panics if `replicas` is zero.
    pub fn new(replicas: usize) -> Self {
        assert!(replicas > 0, "replicas must be > 0");
        Self {
            replicas,
            ring: Vec::new(),
        }
    }

    /// Add a node and its virtual nodes. Adding a node that already exists is a
    /// no-op.
    pub fn add_node(&mut self, node: &str) {
        if self
            .ring
            .iter()
            .any(|(_, name)| name.as_ref() == node)
        {
            return;
        }

        // One allocation for the name, then a refcount bump per virtual node.
        let name: Arc<str> = Arc::from(node);
        for replica in 0..self.replicas {
            let hash = virtual_node_hash(node, replica);
            self.ring
                .push((hash, Arc::clone(&name)));
        }
        self.ring.sort_by_key(|(hash, _)| *hash);
    }

    /// Remove a node and all of its virtual nodes.
    pub fn remove_node(&mut self, node: &str) {
        self.ring
            .retain(|(_, name)| name.as_ref() != node);
    }

    /// Return the node responsible for `key`, or `None` when the ring is empty.
    pub fn get(&self, key: &str) -> Option<&str> {
        if self.ring.is_empty() {
            return None;
        }

        let hash = hash_of(key);
        // First virtual node strictly clockwise from the key.
        let index = self
            .ring
            .partition_point(|(point, _)| *point <= hash);
        let index = if index == self.ring.len() { 0 } else { index };
        Some(self.ring[index].1.as_ref())
    }

    /// Number of distinct physical nodes.
    pub fn node_count(&self) -> usize {
        self.ring
            .iter()
            .map(|(_, name)| name.as_ref())
            .collect::<HashSet<_>>()
            .len()
    }

    /// Number of virtual nodes on the ring.
    pub fn ring_len(&self) -> usize {
        self.ring.len()
    }
}

fn hash_of(input: &str) -> u64 {
    let mut hasher = DefaultHasher::new();
    input.hash(&mut hasher);
    hasher.finish()
}

/// Hash of the `replica`-th virtual node for `node`.
///
/// Hashing the two fields separately avoids allocating a `"{node}#{replica}"`
/// string for every virtual node on the ring.
fn virtual_node_hash(node: &str, replica: usize) -> u64 {
    let mut hasher = DefaultHasher::new();
    node.hash(&mut hasher);
    replica.hash(&mut hasher);
    hasher.finish()
}

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

    #[test]
    fn empty_ring_has_no_owner() {
        let ring = ConsistentHash::new(64);
        assert_eq!(ring.get("workload-1"), None);
        assert_eq!(ring.node_count(), 0);
    }

    #[test]
    fn lookup_is_stable_for_a_fixed_ring() {
        let mut ring = ConsistentHash::new(64);
        ring.add_node("node-a");
        ring.add_node("node-b");

        let first = ring.get("job-42").map(str::to_string);
        for _ in 0..100 {
            assert_eq!(ring.get("job-42").map(str::to_string), first);
        }
        assert!(first.is_some());
    }

    #[test]
    fn keys_spread_across_nodes() {
        let mut ring = ConsistentHash::new(128);
        for node in ["node-a", "node-b", "node-c"] {
            ring.add_node(node);
        }

        let mut counts = std::collections::HashMap::new();
        for key in 0..3_000 {
            let owner = ring
                .get(&format!("key-{key}"))
                .expect("ring is populated");
            *counts
                .entry(owner.to_string())
                .or_insert(0) += 1;
        }

        assert_eq!(counts.len(), 3, "every node should own some keys");
        let smallest = *counts
            .values()
            .min()
            .expect("non-empty");
        assert!(smallest > 300, "distribution is too lumpy: {counts:?}");
    }

    #[test]
    fn adding_a_node_only_moves_keys_to_the_new_node() {
        let keys: Vec<String> = (0..2_000)
            .map(|i| format!("workload-{i}"))
            .collect();

        let mut ring = ConsistentHash::new(128);
        ring.add_node("node-a");
        ring.add_node("node-b");
        let before: Vec<String> = keys
            .iter()
            .map(|key| {
                ring.get(key)
                    .expect("ring is populated")
                    .to_string()
            })
            .collect();

        ring.add_node("node-c");
        let after: Vec<String> = keys
            .iter()
            .map(|key| {
                ring.get(key)
                    .expect("ring is populated")
                    .to_string()
            })
            .collect();

        for (old, new) in before.iter().zip(after.iter()) {
            assert!(
                old == new || new == "node-c",
                "adding a node moved a key from {old} to {new}"
            );
        }
    }

    #[test]
    fn removing_a_node_drops_it_from_the_ring() {
        let mut ring = ConsistentHash::new(32);
        ring.add_node("node-a");
        ring.add_node("node-b");
        assert_eq!(ring.node_count(), 2);
        assert_eq!(ring.ring_len(), 64);

        ring.remove_node("node-a");
        assert_eq!(ring.node_count(), 1);
        for _ in 0..500 {
            assert!(matches!(ring.get("any-key"), Some("node-b")));
        }
    }
}

node_count counts distinct servers by collecting the names into a HashSet, which keeps one copy of each.

The tests check the properties this section described:

• keys_spread_across_nodes places 3,000 keys on three servers with 128 virtual nodes each. Each server must own more than 300 keys. An even split would give each one 1,000.
• adding_a_node_only_moves_keys_to_the_new_node records the owner of 2,000 keys, adds a third server, and looks again. Every key must either keep its owner or move to the new server.
• removing_a_node_drops_it_from_the_ring checks that 2 servers with 32 virtual nodes give 64 ring entries, and that removing one leaves every key with the other.

$ cargo test --lib problems::consistent_hash
running 5 tests
test problems::consistent_hash::tests::empty_ring_has_no_owner ... ok
test problems::consistent_hash::tests::lookup_is_stable_for_a_fixed_ring ... ok
test problems::consistent_hash::tests::removing_a_node_drops_it_from_the_ring ... ok
test problems::consistent_hash::tests::adding_a_node_only_moves_keys_to_the_new_node ... ok
test problems::consistent_hash::tests::keys_spread_across_nodes ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 132 filtered out

Chapter 15 looks below the data structures, at how the CPU caches memory and how the operating system hands it out.

Exercises

1. Add update(&self, key: &K, change: impl FnOnce(&mut V)) to ShardedCache, which changes a value in place under the lock.
2. Write a test that counts how many keys change owner when a fourth server joins a ring of three. Compare the result with 25%.
3. Measure how even the ring is. For 10, 50, and 200 virtual nodes per server, place 100,000 keys and report the largest and smallest share.
4. add_node sorts the whole ring after every call. Rewrite it to insert each new entry at its sorted position with partition_point and Vec::insert, and compare the two for 100 servers.

Memory, CPU caches, and the operating system

The earlier chapters counted steps: O(1), O(log n), O(n). Step counts predict how a program grows, but not how long one step takes. On a real machine, one memory read can take 2 ns or 150 ns, depending on where the data is. Chapter 13 already saw a factor of three between two caches with the same step count.

This chapter looks at the machine under the data structures. Section 15.1 measures the memory system. Sections 15.2 to 15.4 show three programs whose speed depends on how they lay out and touch memory. Sections 15.5 to 15.7 look at three services of the operating system: virtual memory, scheduling, and system calls.

Most programs in this chapter print times. Run them with --release, and expect your numbers to differ from mine. All the numbers here come from one laptop with an Intel Core i5-1038NG7 CPU, running macOS.

15.1 How far away is memory?

Main memory, the RAM, is large and slow compared with the CPU. To hide the difference, the CPU keeps copies of recently used memory in small, fast memories called caches. There are usually three levels:

• L1 is the smallest and fastest, and each core has its own. On this CPU it holds 48 KiB of data per core.
• L2 is larger and slower, also per core: 512 KiB here.
• L3 is shared by all cores: 6 MiB here.

Caches do not copy single bytes. They copy blocks of 64 bytes, called cache lines. Reading one u64 brings in the line around it, so the next seven u64 values in memory arrive at no extra cost.

To see the cost of each level, I measured a pointer chase. The program fills an array with the indexes of a random cycle, so each element holds the index of the next one to read. The loop then runs i = next[i] many times. Each read needs the result of the previous one, so the reads cannot overlap. The time per step is the time of one read. Figure 15.1 shows the result for five array sizes.

A read from L1 took 2.2 ns. A read that had to go to main memory took 120 to 146 ns. In 120 ns, this CPU can run several hundred simple instructions. The larger sizes also include the cost of translating addresses, which section 15.5 explains.

Those five numbers describe one hierarchy, not five separate machines. Data in L1 answers a dependent read in 2.2 ns. The same read against 256 KiB costs 5.6 ns. That array no longer fits in a 48 KiB L1, so the line comes from L2. At 2 MiB the cost is 42.3 ns, having left L2 as well. From 32 MiB upward it is 120 ns or more, which is main memory. A larger level holds several times more than the one above it, and answers several times more slowly. The trade is forced. A store that answers in 2 ns has to be small, because reaching a location costs more as the store grows.

A cache line is 64 bytes, and it arrives as one unit. A program that reads one u64 and then the next seven pays for a single line and uses all of it. A program that jumps to a new random line on every read pays the same 120 ns. It uses one eighth of what it fetched.

Animation 15.1 follows single reads through the hierarchy, then a line read in order and lines read scattered.

The rest of the chapter comes back to one fact. Data that is close together in memory, and read in order, is much cheaper than data scattered around. Keeping related data close together is called locality.

15.2 A bump allocator

Programs get heap memory from an allocator. Every Box::new and every growing Vec asks the allocator for a block, and every drop gives one back. A general-purpose allocator must handle blocks of any size, freed in any order, from any thread. That takes bookkeeping.

A bump allocator is the simplest allocator. It owns one large buffer and an offset, the position of the first free byte. To allocate, it hands out the bytes at the offset and moves the offset forward. It never frees a single block. Instead, reset frees everything at once by setting the offset back to 0.

This fits work that allocates many small pieces and throws them all away together. A parser can allocate its syntax tree in an arena and drop it after compiling. A server can allocate per request and reset after sending the response.

15.2.1 Alignment

Most types must start at an address that is a multiple of some number, called their alignment. A u64 has alignment 8, so it must start at an address divisible by 8. The CPU reads aligned values in one step, and some instructions refuse unaligned ones.

So an allocator must sometimes skip bytes before a block, to reach an address with the right alignment. The skipped bytes are called padding. Figure 15.2 shows two allocations and the padding between them.

15.2.2 The code

Listing 15.1 alloc (lines 27 to 42) and align_up (lines 65 to 70). src/problems/bump_allocator.rs

impl BumpArena {
    // ...
    /// Allocate `size` bytes aligned to `align`.
    ///
    /// Returns `None` when the request does not fit. `align` must be a power of
    /// two.
    pub fn alloc(&mut self, size: usize, align: usize) -> Option<&mut [u8]> {
        assert!(align.is_power_of_two(), "align must be a power of two");

        let start = align_up(self.offset, align)?;
        let end = start.checked_add(size)?;
        if end > self.buffer.len() {
            return None;
        }

        self.offset = end;
        Some(&mut self.buffer[start..end])
    }
    // ...
}

fn align_up(offset: usize, align: usize) -> Option<usize> {
    let mask = align - 1;
    offset
        .checked_add(mask)
        .map(|value| value & !mask)
}

align_up rounds the offset up to the next multiple of align. The alignment must be a power of two, which the assert! in alloc checks. A power of two has exactly one bit set, so align - 1 is a mask with all the bits below it set. For align = 16, the mask is 0b1111.

The rounding happens in two steps. Adding the mask pushes the offset past the next multiple, unless it is already on one. Then & !mask clears the low bits, which rounds down to a multiple. Work through the second allocation of figure 15.2 by hand:

1. The offset is 1, and the alignment is 16, so the mask is 15.
2. 1 + 15 = 16.
3. 16 with the low four bits cleared is 16. The block starts at 16.

An offset of 16 would give 16 + 15 = 31, which rounds down to 16 again. An offset already aligned stays where it is.

alloc uses checked_add twice, and the ? operator returns None if either addition overflows. It also returns None if the block would end past the buffer. Only after every check passes does it move the offset. So a failed allocation leaves the arena unchanged, which the test exhaustion_returns_none_and_keeps_state checks.

The block is returned as &mut [u8], a slice of the buffer. That reference borrows the arena mutably, so you cannot call alloc again while you hold it. A production arena allocator hands out many live references at once, and needs unsafe code or interior mutability to do so.

Listing 15.2 The complete file, with tests. src/problems/bump_allocator.rs

//! A bump (arena) allocator over a fixed byte buffer.
//!
//! Bump allocation is the simplest allocator: hand out bytes from a cursor and
//! never free an individual block. It is O(1) per allocation, has no fragmentation
//! bookkeeping, and is freed all at once with [`BumpArena::reset`]. Parsers,
//! request handlers, and per-frame buffers in games use exactly this shape.
//!
//! This version does not try to beat the system allocator. It shows alignment,
//! the memory layout you hand to hardware, and why "free everything at once" is
//! both the strength and the limitation.

/// A fixed-capacity bump allocator.
pub struct BumpArena {
    buffer: Vec<u8>,
    offset: usize,
}

impl BumpArena {
    /// Create an arena backed by `capacity` zeroed bytes.
    pub fn with_capacity(capacity: usize) -> Self {
        Self {
            buffer: vec![0; capacity],
            offset: 0,
        }
    }

    /// Allocate `size` bytes aligned to `align`.
    ///
    /// Returns `None` when the request does not fit. `align` must be a power of
    /// two.
    pub fn alloc(&mut self, size: usize, align: usize) -> Option<&mut [u8]> {
        assert!(align.is_power_of_two(), "align must be a power of two");

        let start = align_up(self.offset, align)?;
        let end = start.checked_add(size)?;
        if end > self.buffer.len() {
            return None;
        }

        self.offset = end;
        Some(&mut self.buffer[start..end])
    }

    /// Bytes handed out so far, including alignment padding.
    pub fn used(&self) -> usize {
        self.offset
    }

    /// Bytes still available before the next allocation.
    pub fn remaining(&self) -> usize {
        self.buffer.len() - self.offset
    }

    /// Total capacity.
    pub fn capacity(&self) -> usize {
        self.buffer.len()
    }

    /// Free everything at once, as an arena does.
    pub fn reset(&mut self) {
        self.offset = 0;
    }
}

fn align_up(offset: usize, align: usize) -> Option<usize> {
    let mask = align - 1;
    offset
        .checked_add(mask)
        .map(|value| value & !mask)
}

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

    #[test]
    fn allocations_are_aligned() {
        let mut arena = BumpArena::with_capacity(64);

        let first = arena.alloc(1, 8).expect("fits");
        assert_eq!(first.as_ptr() as usize % 8, 0);
        assert_eq!(first.len(), 1);

        let second = arena.alloc(4, 16).expect("fits");
        assert_eq!(second.as_ptr() as usize % 16, 0);

        // The first block occupies 1 byte. Aligning the next block to 16 adds 15
        // bytes of padding, so the arena has consumed 16 + 4 = 20 bytes.
        assert_eq!(arena.used(), 20);
        assert_eq!(arena.remaining(), 44);
    }

    #[test]
    fn exhaustion_returns_none_and_keeps_state() {
        let mut arena = BumpArena::with_capacity(16);
        assert!(arena.alloc(16, 1).is_some());

        let used_before = arena.used();
        assert!(arena.alloc(1, 1).is_none());
        assert_eq!(arena.used(), used_before, "a failed alloc must not advance");
    }

    #[test]
    fn reset_reclaims_everything() {
        let mut arena = BumpArena::with_capacity(32);
        assert!(arena.alloc(20, 4).is_some());
        assert_eq!(arena.remaining(), 12);

        arena.reset();
        assert_eq!(arena.used(), 0);
        assert_eq!(arena.remaining(), arena.capacity());
        assert!(arena.alloc(32, 1).is_some());
    }

    #[test]
    fn zero_sized_allocation_is_allowed() {
        let mut arena = BumpArena::with_capacity(8);
        let empty = arena.alloc(0, 8).expect("fits");
        assert!(empty.is_empty());
        assert_eq!(arena.used(), 0);
    }

    #[test]
    fn writes_are_isolated_between_allocations() {
        let mut arena = BumpArena::with_capacity(16);
        arena
            .alloc(4, 4)
            .expect("fits")
            .copy_from_slice(&[1, 2, 3, 4]);
        let second = arena.alloc(4, 4).expect("fits");
        assert!(second.iter().all(|&byte| byte == 0));
        second.copy_from_slice(&[9, 9, 9, 9]);

        let view = arena.buffer.as_slice();
        assert_eq!(&view[0..4], &[1, 2, 3, 4]);
        assert_eq!(&view[4..8], &[9, 9, 9, 9]);
    }
}

$ cargo test --lib problems::bump_allocator
running 5 tests
test problems::bump_allocator::tests::allocations_are_aligned ... ok
test problems::bump_allocator::tests::exhaustion_returns_none_and_keeps_state ... ok
test problems::bump_allocator::tests::reset_reclaims_everything ... ok
test problems::bump_allocator::tests::zero_sized_allocation_is_allowed ... ok
test problems::bump_allocator::tests::writes_are_isolated_between_allocations ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 132 filtered out

15.3 Reading in order, and reading scattered

Figure 15.3 shows how the order of reads changes the work. Reading a u64 array in order uses every value of each cache line it loads. The CPU also notices the pattern and fetches the next lines before they are needed, which is called prefetching. Reading scattered values loads a whole line for each value and uses one eighth of it.

15.3.1 The program

Listing 15.3 The two loops (lines 9 to 30). src/bin/cs_locality.rs

use std::time::{Duration, Instant};

/// A power of two, so a stride must be odd to visit every index.
const ELEMENTS: usize = 4 * 1024 * 1024;

/// Odd, and therefore coprime with `ELEMENTS`: the walk visits every slot once.
const STRIDE: usize = 1_000_003;

fn sequential_sum(data: &[u64]) -> (u64, Duration) {
    let start = Instant::now();
    let sum = data.iter().sum();
    (sum, start.elapsed())
}

fn strided_sum(data: &[u64]) -> (u64, Duration) {
    let start = Instant::now();
    let mut index = 0usize;
    let mut sum = 0u64;
    for _ in 0..data.len() {
        index = (index + STRIDE) % data.len();
        sum = sum.wrapping_add(data[index]);
    }
    (sum, start.elapsed())
}

Both functions add up every element of the same 32 MiB array, which is too large for any cache. sequential_sum reads it in order with data.iter().sum(). strided_sum jumps 1,000,003 elements forward at each step, wrapping around with %.

The jump must eventually visit every element exactly once. The array has 4,194,304 elements, which is 2 to the power 22. The stride is odd, so it shares no factor with a power of two. A walk whose step shares no factor with the length visits every position once before it returns to the start.

Listing 15.4 The complete program. src/bin/cs_locality.rs

//! Cache locality: the same data is much faster to walk in order than to jump
//! around, because memory moves in cache lines and the prefetcher helps only the
//! sequential case.
//!
//! Run with: cargo run --bin cs_locality

use std::time::{Duration, Instant};

/// A power of two, so a stride must be odd to visit every index.
const ELEMENTS: usize = 4 * 1024 * 1024;

/// Odd, and therefore coprime with `ELEMENTS`: the walk visits every slot once.
const STRIDE: usize = 1_000_003;

fn sequential_sum(data: &[u64]) -> (u64, Duration) {
    let start = Instant::now();
    let sum = data.iter().sum();
    (sum, start.elapsed())
}

fn strided_sum(data: &[u64]) -> (u64, Duration) {
    let start = Instant::now();
    let mut index = 0usize;
    let mut sum = 0u64;
    for _ in 0..data.len() {
        index = (index + STRIDE) % data.len();
        sum = sum.wrapping_add(data[index]);
    }
    (sum, start.elapsed())
}

fn main() {
    let data: Vec<u64> = (0..ELEMENTS as u64).collect();
    println!(
        "{} elements, {} MiB",
        data.len(),
        data.len() * 8 / (1024 * 1024)
    );

    let (sequential, sequential_time) = sequential_sum(&data);
    let (strided, strided_time) = strided_sum(&data);

    println!("\n  sequential: {sequential} in {sequential_time:?}");
    println!("  strided:    {strided} in {strided_time:?}");

    // Both touch every element exactly once, so the sums must match; only the
    // access pattern differs.
    assert_eq!(sequential, strided);
    assert_eq!(sequential, ELEMENTS as u64 * (ELEMENTS as u64 - 1) / 2);

    println!("\nequal work, different pattern; timings vary by machine");
}

main checks that both sums are equal, and that they match the formula for 0 + 1 + … + (n − 1). The two loops did the same additions. Only the order of reading differs.

$ cargo run --release --bin cs_locality
4194304 elements, 32 MiB

  sequential: 8796090925056 in 3.127311ms
  strided:    8796090925056 in 37.375274ms

equal work, different pattern; timings vary by machine

15.3.2 What the strided loop measured

The strided loop took twelve times as long. It is tempting to credit all of that to the cache, but the two loops differ in more than their reading order.

strided_sum computes (index + STRIDE) % data.len() at every step. data.len() is not known at compile time, so % is compiled as a real division instruction, one of the slowest integer instructions. Each step’s index depends on the previous one, so the divisions run one after another.

To separate the two costs, I ran four variants of the loop:

Table 15.1 Variants of the 32 MiB sum, release build

The third row settles it. With stride 1, the loop reads memory in perfect order, and it still takes 36 ms. The division sets the pace of strided_sum, not the memory.

The last three rows remove the division and show the real cost of scattered reads. Reading through a list of indexes in random order took about seven times as long as reading through the same list in order. The reads are independent of each other, so the CPU keeps several of them in flight at once. In the pointer chase of section 15.1, each read must wait for the previous one. There, the same 4 million reads take 478 ms, about 114 ns each.

Two lessons come out of this. Scattered memory access is expensive, from a few times slower to a hundred times, depending on whether reads can overlap. And a benchmark measures everything in its loop. Before you explain a number, change one thing at a time and check that the number moves.

15.4 False sharing

Chapter 16 covers threads in depth. This section needs only two facts about them:

• thread::scope(|scope| { ... }) creates a scope. Threads started inside it with scope.spawn may borrow local variables, because the scope waits for all of them to finish before it returns.
• An atomic integer such as AtomicUsize can be changed by several threads at once without a lock. fetch_add(1, Ordering::Relaxed) adds 1 in one indivisible step. The Ordering argument is explained in chapter 16. Relaxed is enough for a counter that nothing else depends on.

Now the problem. Each core has its own L1 cache. Before a core writes to a cache line, it must have the only copy of that line. Every other core’s copy is thrown away. If two cores write to the same line in turn, the line moves back and forth between them on almost every write.

That is expected when two threads write the same variable. False sharing is the same slowdown when the two threads write different variables that happen to sit in the same cache line (figure 15.4). The threads share no data, but the hardware moves memory in whole lines, so they share a line.

Animation 15.2 shows the line moving between the cores, then the same writes with one line per counter.

The fix is to place each counter in its own cache line. #[repr(align(64))] on a struct makes its alignment 64, so every value of the type starts on a new line. The size rounds up to a multiple of the alignment, so the value fills the line.

15.4.1 Four counters

Listing 15.5 Two counter types (lines 16 to 41). src/bin/concurrency_false_sharing.rs

use std::{
    mem::size_of,
    sync::atomic::{AtomicUsize, Ordering},
    thread,
    time::{Duration, Instant},
};

/// Packed by default: consecutive counters share a cache line.
struct Unpadded(AtomicUsize);

impl Unpadded {
    fn new() -> Self {
        Self(AtomicUsize::new(0))
    }

    fn increment(&self) {
        self.0.fetch_add(1, Ordering::Relaxed);
    }
}

/// Padded to a cache line, so no two counters share one.
#[repr(align(64))]
struct Padded(AtomicUsize);

impl Padded {
    fn new() -> Self {
        Self(AtomicUsize::new(0))
    }

    fn increment(&self) {
        self.0.fetch_add(1, Ordering::Relaxed);
    }
}

Unpadded is 8 bytes, so a Vec of four of them fits in 32 bytes, inside one or two cache lines. Padded is 64 bytes, and each one gets a line.

Listing 15.6 The timed run (lines 43 to 59).

/// Scoped threads borrow the vector directly, so there is no `Arc` and no clone.
fn run_unpadded() -> Duration {
    let counters: Vec<Unpadded> = (0..THREADS)
        .map(|_| Unpadded::new())
        .collect();
    let start = Instant::now();
    thread::scope(|scope| {
        for counter in &counters {
            scope.spawn(move || {
                for _ in 0..ITERATIONS {
                    counter.increment();
                }
            });
        }
    });
    start.elapsed()
}

The loop for counter in &counters gives each thread a reference to its own counter. move || moves that reference into the thread’s closure. Each thread increments only its own counter, two million times.

Listing 15.7 The complete program. src/bin/concurrency_false_sharing.rs

//! False sharing: two independent counters that land on the same cache line make
//! each other slow, because every write moves the line between cores.
//!
//! Run with: cargo run --bin concurrency_false_sharing

use std::{
    mem::size_of,
    sync::atomic::{AtomicUsize, Ordering},
    thread,
    time::{Duration, Instant},
};

const THREADS: usize = 4;
const ITERATIONS: usize = 2_000_000;

/// Packed by default: consecutive counters share a cache line.
struct Unpadded(AtomicUsize);

impl Unpadded {
    fn new() -> Self {
        Self(AtomicUsize::new(0))
    }

    fn increment(&self) {
        self.0.fetch_add(1, Ordering::Relaxed);
    }
}

/// Padded to a cache line, so no two counters share one.
#[repr(align(64))]
struct Padded(AtomicUsize);

impl Padded {
    fn new() -> Self {
        Self(AtomicUsize::new(0))
    }

    fn increment(&self) {
        self.0.fetch_add(1, Ordering::Relaxed);
    }
}

/// Scoped threads borrow the vector directly, so there is no `Arc` and no clone.
fn run_unpadded() -> Duration {
    let counters: Vec<Unpadded> = (0..THREADS)
        .map(|_| Unpadded::new())
        .collect();
    let start = Instant::now();
    thread::scope(|scope| {
        for counter in &counters {
            scope.spawn(move || {
                for _ in 0..ITERATIONS {
                    counter.increment();
                }
            });
        }
    });
    start.elapsed()
}

fn run_padded() -> Duration {
    let counters: Vec<Padded> = (0..THREADS)
        .map(|_| Padded::new())
        .collect();
    let start = Instant::now();
    thread::scope(|scope| {
        for counter in &counters {
            scope.spawn(move || {
                for _ in 0..ITERATIONS {
                    counter.increment();
                }
            });
        }
    });
    start.elapsed()
}

fn main() {
    println!("atomic:   {} bytes", size_of::<AtomicUsize>());
    println!(
        "unpadded: {} bytes (several counters per 64 byte line)",
        size_of::<Unpadded>()
    );
    println!(
        "padded:   {} bytes (one counter per 64 byte line)",
        size_of::<Padded>()
    );

    let unpadded = run_unpadded();
    let padded = run_padded();

    println!("\n{THREADS} threads x {ITERATIONS} increments, each on its own counter");
    println!("  unpadded (shared lines): {unpadded:?}");
    println!("  padded   (own line):     {padded:?}");

    assert!(size_of::<Padded>() >= 64, "padding must fill a cache line");
    assert!(unpadded.as_nanos() > 0 && padded.as_nanos() > 0);

    println!("\ntimings vary by machine; the padded run is normally the faster one");
}

$ cargo run --release --bin concurrency_false_sharing
atomic:   8 bytes
unpadded: 8 bytes (several counters per 64 byte line)
padded:   64 bytes (one counter per 64 byte line)

4 threads x 2000000 increments, each on its own counter
  unpadded (shared lines): 205.466825ms
  padded   (own line):     20.667095ms

timings vary by machine; the padded run is normally the faster one

Adding 56 bytes of padding to each counter made the same work ten times faster.

15.4.2 Two counters

The second program makes the sharing certain instead of likely. SameLine holds both counters and is aligned to 64, so both are guaranteed to be in one line.

#[repr(align(64))] makes every value of the type start at an address that is a multiple of 64. That is the size of a cache line. SameLine puts two counters in one line on purpose. Padded gives one counter a whole line:

/// Both counters are guaranteed to live inside one 64-byte cache line.
#[repr(align(64))]
struct SameLine {
    a: AtomicU64,
    b: AtomicU64,
}

/// Each of these occupies its own 64-byte block.
#[repr(align(64))]
struct Padded(AtomicU64);

Listing 15.8 The complete program. src/bin/false_sharing.rs

use std::{
    sync::atomic::{AtomicU64, Ordering},
    thread,
    time::{Duration, Instant},
};

const ITERS: u64 = 20_000_000;

/// Both counters are guaranteed to live inside one 64-byte cache line.
#[repr(align(64))]
struct SameLine {
    a: AtomicU64,
    b: AtomicU64,
}

/// Each of these occupies its own 64-byte block.
#[repr(align(64))]
struct Padded(AtomicU64);

fn time<F: FnOnce()>(f: F) -> Duration {
    let t = Instant::now();
    f();
    t.elapsed()
}

fn main() {
    // ---- 1. False sharing: two counters on the same cache line ----
    let same = SameLine {
        a: AtomicU64::new(0),
        b: AtomicU64::new(0),
    };

    let d1 = time(|| {
        thread::scope(|s| {
            s.spawn(|| {
                for _ in 0..ITERS {
                    same.a.fetch_add(1, Ordering::Relaxed);
                }
            });
            s.spawn(|| {
                for _ in 0..ITERS {
                    same.b.fetch_add(1, Ordering::Relaxed);
                }
            });
        });
    });

    // ---- 2. Padded: same work, but counters are on separate cache lines ----
    let p0 = Padded(AtomicU64::new(0));
    let p1 = Padded(AtomicU64::new(0));

    let d2 = time(|| {
        thread::scope(|s| {
            s.spawn(|| {
                for _ in 0..ITERS {
                    p0.0.fetch_add(1, Ordering::Relaxed);
                }
            });
            s.spawn(|| {
                for _ in 0..ITERS {
                    p1.0.fetch_add(1, Ordering::Relaxed);
                }
            });
        });
    });

    println!("same cache line (false sharing): {:?}", d1);
    println!("padded (separate lines):         {:?}", d2);
}

time is a small generic helper. It takes any closure that can be called once, F: FnOnce(), runs it, and returns how long it took.

The spawned closures have no move. They borrow same, p0, and p1 directly, which thread::scope allows.

$ cargo run --release --bin false_sharing
same cache line (false sharing): 838.152232ms
padded (separate lines):         170.243616ms

Here the difference is about five times.

15.5 Pages and page faults

Every address your program uses is a virtual address. The operating system gives each process its own private range of addresses. The CPU translates each virtual address into a physical address, a location in the actual RAM.

Translation works on fixed-size blocks called pages. On this machine a page is 4,096 bytes. Apple’s ARM Macs use 16 KiB pages. The operating system keeps a page table for each process, which maps each virtual page to a physical block of RAM, called a frame.

An address splits into two parts (figure 15.5). The high part is the page number, which the page table translates. The low part is the offset inside the page, which stays the same. With 4,096-byte pages, the offset is the low 12 bits, because 2 to the power 12 is 4,096.

Looking up the page table on every access would be slow. The CPU keeps recent translations in a small cache called the TLB (translation lookaside buffer). Scattered reads over a large array need many different pages, miss the TLB, and pay for a table lookup. That cost is part of the larger numbers in figure 15.1.

When the translation cannot complete, the CPU stops the program and hands control to the kernel. This is a page fault. The kernel decides what kind it is:

• Invalid: the address is not mapped at all. The program is stopped, usually with a segmentation fault.
• Protection: the page is mapped, but the access is not allowed, such as a write to a read-only page.
• Major: the page is valid, but its contents are on disk. The kernel reads it in and restarts the access. This takes milliseconds.
• Minor: the kernel can fix the mapping without reading the disk. Examples are the first write to a freshly allocated page, or a write to a page shared after fork (copy-on-write). This takes microseconds.

Listing 15.9 The address arithmetic and the fault model (lines 6 to 35). src/bin/os_paging.rs

const PAGE_SIZE: u64 = 4096;

fn split_page(address: u64) -> (u64, u64) {
    (address / PAGE_SIZE, address % PAGE_SIZE)
}

fn pages_needed(bytes: u64) -> u64 {
    bytes.div_ceil(PAGE_SIZE)
}

#[derive(Debug, PartialEq, Eq)]
enum Fault {
    /// The page is resident; a copy-on-write write or permission upgrade.
    Minor,
    /// The mapping is valid but the page must be read from backing store.
    Major,
    /// The mapping is valid and resident, but the access permission is wrong.
    Protection,
    /// No valid mapping at this address.
    Invalid,
}

fn classify_fault(mapped: bool, present: bool, writable: bool) -> Fault {
    match (mapped, present, writable) {
        (false, _, _) => Fault::Invalid,
        (true, false, _) => Fault::Major,
        (true, true, false) => Fault::Protection,
        (true, true, true) => Fault::Minor,
    }
}

split_page divides by the page size for the page number, and takes the remainder for the offset. pages_needed rounds up with div_ceil, because 4,097 bytes need two pages, not one.

classify_fault matches on three facts at once, written as a tuple. They are: is the address mapped, is the page present in memory, and does the mapping allow the access. The arms are tried in order, so the first arm that fits wins. (false, _, _) catches every unmapped address, whatever the other two values are.

The model is a simplification. It treats every page that is not in memory as a major fault. A real kernel also counts some of those as minor, because no disk read is needed. Examples are a first touch of new memory, and a file page already in the kernel’s file cache.

Listing 15.10 The complete program. src/bin/os_paging.rs

//! Virtual memory arithmetic: address to page and offset, page counts, and how a
//! page fault is classified.
//!
//! Run with: cargo run --bin os_paging

const PAGE_SIZE: u64 = 4096;

fn split_page(address: u64) -> (u64, u64) {
    (address / PAGE_SIZE, address % PAGE_SIZE)
}

fn pages_needed(bytes: u64) -> u64 {
    bytes.div_ceil(PAGE_SIZE)
}

#[derive(Debug, PartialEq, Eq)]
enum Fault {
    /// The page is resident; a copy-on-write write or permission upgrade.
    Minor,
    /// The mapping is valid but the page must be read from backing store.
    Major,
    /// The mapping is valid and resident, but the access permission is wrong.
    Protection,
    /// No valid mapping at this address.
    Invalid,
}

fn classify_fault(mapped: bool, present: bool, writable: bool) -> Fault {
    match (mapped, present, writable) {
        (false, _, _) => Fault::Invalid,
        (true, false, _) => Fault::Major,
        (true, true, false) => Fault::Protection,
        (true, true, true) => Fault::Minor,
    }
}

fn main() {
    println!("page size: {PAGE_SIZE} bytes");

    println!("\naddress -> page, offset");
    for address in [0u64, 0x1234, 0x1fff, 0x2000] {
        let (page, offset) = split_page(address);
        println!("  0x{address:04x} -> page {page:>2}, offset 0x{offset:03x}");
    }

    println!("\npages needed");
    for bytes in [0u64, 1, PAGE_SIZE, PAGE_SIZE + 1] {
        println!("  {bytes:>5} bytes -> {}", pages_needed(bytes));
    }

    println!("\nfault classification");
    println!(
        "  unmapped           -> {:?}",
        classify_fault(false, false, false)
    );
    println!(
        "  mapped, not in ram -> {:?}",
        classify_fault(true, false, true)
    );
    println!(
        "  resident, read-only-> {:?}",
        classify_fault(true, true, false)
    );
    println!(
        "  resident, writable -> {:?}",
        classify_fault(true, true, true)
    );

    assert_eq!(split_page(0x1234), (1, 0x234));
    assert_eq!(pages_needed(0), 0);
    assert_eq!(pages_needed(PAGE_SIZE + 1), 2);
    assert_eq!(classify_fault(true, false, true), Fault::Major);
    assert_eq!(classify_fault(true, true, false), Fault::Protection);
    assert_eq!(classify_fault(false, true, true), Fault::Invalid);

    println!("\nall checks passed");
}

$ cargo run --bin os_paging
page size: 4096 bytes

address -> page, offset
  0x0000 -> page  0, offset 0x000
  0x1234 -> page  1, offset 0x234
  0x1fff -> page  1, offset 0xfff
  0x2000 -> page  2, offset 0x000

pages needed
      0 bytes -> 0
      1 bytes -> 1
   4096 bytes -> 1
   4097 bytes -> 2

fault classification
  unmapped           -> Invalid
  mapped, not in ram -> Major
  resident, read-only-> Protection
  resident, writable -> Minor

all checks passed

0x1fff is the last byte of page 1, and 0x2000 is the first byte of page 2.

15.6 Taking turns on the CPU

A machine runs more threads than it has cores. The operating system’s scheduler decides which thread runs on each core, and switches between them many times per second. A context switch saves one thread’s registers and loads another’s.

Round robin is the simplest fair policy. The runnable tasks wait in a line. The first runs for a fixed time, called the quantum or time slice, and then goes to the back of the line (figure 15.6). No task can hold a core forever, so none starves.

Listing 15.11 The complete program. src/bin/os_scheduler.rs

//! Round-robin scheduling: each runnable task gets one fixed time slice in turn,
//! so no task starves. This is the simplest fair policy a scheduler can use.
//!
//! Run with: cargo run --bin os_scheduler

const QUANTUM_MS: u64 = 5;

/// The task chosen on each of `ticks` time slices.
fn schedule<'a>(tasks: &[&'a str], ticks: usize) -> Vec<&'a str> {
    if tasks.is_empty() {
        return Vec::new();
    }
    (0..ticks)
        .map(|tick| tasks[tick % tasks.len()])
        .collect()
}

fn main() {
    let tasks = ["encoder", "decoder", "gc"];

    println!("{} runnable tasks, {QUANTUM_MS} ms quantum", tasks.len());
    for (tick, task) in schedule(&tasks, 7).iter().enumerate() {
        let start = tick as u64 * QUANTUM_MS;
        println!(
            "  slice {tick}: {start:>2}-{:>2} ms  {task}",
            start + QUANTUM_MS
        );
    }

    let order = schedule(&tasks, 7);
    assert_eq!(
        order,
        [
            "encoder", "decoder", "gc", "encoder", "decoder", "gc", "encoder"
        ]
    );
    assert!(schedule(&[], 3).is_empty());

    // A long task is preempted, not run to completion, which is what bounds its
    // worst-case latency to one quantum times the number of tasks.
    println!(
        "\nworst-case wait for one slice: {} ms",
        QUANTUM_MS * tasks.len() as u64
    );
    println!("all checks passed");
}

schedule returns the task for each slice: slice tick goes to task tick % tasks.len(). The early return avoids a division by zero when there are no tasks.

The signature fn schedule<'a>(tasks: &[&'a str], ticks: usize) -> Vec<&'a str> has one named lifetime. It says that the returned names borrow from the same strings as the names in tasks, not from the slice that holds them. The caller can drop the slice and keep the result.

$ cargo run --bin os_scheduler
3 runnable tasks, 5 ms quantum
  slice 0:  0- 5 ms  encoder
  slice 1:  5-10 ms  decoder
  slice 2: 10-15 ms  gc
  slice 3: 15-20 ms  encoder
  slice 4: 20-25 ms  decoder
  slice 5: 25-30 ms  gc
  slice 6: 30-35 ms  encoder

worst-case wait for one slice: 15 ms
all checks passed

Between two of its own slices, a task waits 10 ms, while the other two tasks run. From an arbitrary moment, it waits at most one full round of 15 ms, which is the number the program prints. A shorter quantum makes tasks wait less, but switches more often, and each switch costs time.

15.7 The cost of a system call

A program cannot touch hardware or other processes directly. It asks the kernel, with a system call: opening a file, reading a socket, starting a thread. The CPU switches from user mode into kernel mode, the kernel does the work, and the CPU switches back (figure 15.7). The switch itself costs time, even when the work is tiny.

15.7.1 Calling C from Rust

The program calls getpid, which returns the process ID. getpid is a C function from the system’s C library. The libc crate declares it for Rust.

Calling a function written in another language is called a foreign function interface (FFI) call. Rust cannot check what C code does, so every call to it must be inside an unsafe block. Each block here carries a SAFETY comment explaining why the call is sound. getpid takes no pointers and changes no memory.

Listing 15.12 The timed loop (lines 27 to 47). src/bin/syscall_overhead.rs

use std::time::Instant;

/// Calls `getpid()` `iterations` times and returns the average cost in
/// nanoseconds per call.
fn measure_getpid_ns_per_call(iterations: u64) -> f64 {
    let start = Instant::now();

    for _ in 0..iterations {
        // SAFETY: `libc::getpid` is a pure read-only system call with no
        // pointer arguments and no memory side effects. The FFI declaration in
        // the `libc` crate matches the Linux kernel ABI.
        //
        // `black_box` prevents the optimizer from assuming the loop has no
        // observable effect, which matters because the syscall result is
        // otherwise unused.
        unsafe {
            libc::getpid();
        }
    }

    let elapsed = start.elapsed();
    elapsed.as_nanos() as f64 / iterations as f64
}

The comment inside the loop mentions black_box, but the loop does not use it, and does not need it. The compiler cannot see inside an external C function, so it must assume each call has an effect, and it cannot remove the loop.

Listing 15.13 The complete program. src/bin/syscall_overhead.rs

// ============================================================================
// Syscall overhead measurement
//
// Ported from the Rust playground repo (`mkdir_syscall.rs`).
//
// What this measures:
//   - Every syscall crosses the user/kernel boundary: argument validation,
//     kernel work, scheduling checks, and return to user space.
//   - This program calls `getpid()` in a tight loop and estimates the average
//     per-call cost. `getpid()` is a tiny syscall, so the measured cost is
//     close to the irreducible syscall overhead on this kernel/hardware.
//
// Where this appears in practice:
//   - High-performance data planes care about per-packet or per-I/O syscall
//     cost. The difference between one syscall per event and batching via
//     io_uring/recvmmsg can be enormous.
//   - It also demonstrates unsafe FFI, safety comments, warm-up loops, and
//     benchmark methodology: warm the code path, run enough iterations, and
//     report average cost rather than one lucky sample.
//
// Run:
//   cargo run --bin syscall_overhead
// ============================================================================

use std::time::Instant;

/// Calls `getpid()` `iterations` times and returns the average cost in
/// nanoseconds per call.
fn measure_getpid_ns_per_call(iterations: u64) -> f64 {
    let start = Instant::now();

    for _ in 0..iterations {
        // SAFETY: `libc::getpid` is a pure read-only system call with no
        // pointer arguments and no memory side effects. The FFI declaration in
        // the `libc` crate matches the Linux kernel ABI.
        //
        // `black_box` prevents the optimizer from assuming the loop has no
        // observable effect, which matters because the syscall result is
        // otherwise unused.
        unsafe {
            libc::getpid();
        }
    }

    let elapsed = start.elapsed();
    elapsed.as_nanos() as f64 / iterations as f64
}

fn main() {
    const ITERATIONS: u64 = 10_000_000;

    // Warm up the code path before timing. The first calls may fault in the
    // libc/PLT, cache lines, or CPU frequency may still be ramping.
    for _ in 0..100_000 {
        // SAFETY: same reasoning as above; read-only syscall.
        unsafe { libc::getpid() };
    }

    let ns_per_call = measure_getpid_ns_per_call(ITERATIONS);

    println!("Iterations:      {}", ITERATIONS);
    println!(
        "Total time:      {:.3}s",
        ns_per_call * ITERATIONS as f64 / 1e9
    );
    println!("Per syscall:     {:.1} ns", ns_per_call);

    // Example framing: if a service processed 10M packets/s and used one
    // getpid-style syscall per packet, this fraction of each second would be
    // spent crossing into the kernel just for the syscall overhead.
    let cpu_seconds_per_second = ns_per_call * 10_000_000.0 / 1_000_000_000.0;
    println!(
        "At 10M calls/s, syscall overhead would consume: {:.2} CPU-seconds per second",
        cpu_seconds_per_second
    );
}

// ============================================================================
// Tests (cargo test --bin syscall_overhead)
// ============================================================================
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn measurement_returns_a_positive_finite_number() {
        let ns = measure_getpid_ns_per_call(10_000);
        assert!(ns.is_finite(), "nanoseconds per call must be finite");
        assert!(ns > 0.0, "a syscall cannot cost zero time");
        // On any real kernel this is microseconds or tens/hundreds of ns, not
        // seconds per call.
        assert!(
            ns < 1_000_000.0,
            "suspiciously slow syscall measurement: {ns} ns"
        );
    }

    #[test]
    fn getpid_returns_nonzero_pid() {
        // SAFETY: read-only syscall, no pointers, no side effects.
        let pid = unsafe { libc::getpid() };
        assert!(pid > 0);
    }
}

main warms up with 100,000 untimed calls, then times ten million. Warming up lets the first-call costs, such as loading the function’s code into the cache, happen outside the measurement.

$ cargo run --release --bin syscall_overhead
Iterations:      10000000
Total time:      0.031s
Per syscall:     3.1 ns
At 10M calls/s, syscall overhead would consume: 0.03 CPU-seconds per second

15.7.2 What the 3.1 ns measured

3.1 ns is far too fast for a trip into the kernel. It is about the time of two L1 reads. The program measured something other than its title says.

The C library on macOS stores the process ID the first time it is asked, and answers later getpid calls from that stored value. None of the ten million calls entered the kernel.

To measure a real round trip, the call must be one the library cannot answer by itself. On the same machine, I timed getppid, which returns the parent’s process ID, and a raw syscall(SYS_getpid). Both took about 594 ns per call, nearly 200 times the cached getpid.

On Linux, the answer is different again. The GNU C library stopped caching getpid in version 2.25, so there the same program does measure a real system call.

The lesson matches section 15.3. Before you trust a number, check that the code did the work you meant to time. The comment block at the top of the file names the practical point. A program that handles millions of events per second cannot afford one system call per event. Interfaces such as Linux’s recvmmsg and io_uring exist to handle many events per system call.

Chapter 16 starts the concurrency part of the book: threads, atomics, and locks, and the rules that keep them correct.

Exercises

1. Change strided_sum to use & (data.len() - 1) instead of % data.len(), and compare its time with stride 1 and stride 1,000,003.
2. Write the pointer chase of section 15.1, and measure it on your machine for sizes from 4 KiB to 512 MiB. Find where the time jumps, and compare with your CPU’s cache sizes.
3. Fix the warning in section 15.2. Make BumpArena allocate its buffer with std::alloc::alloc and a Layout aligned to 64. Add a test that requests alignment 64.
4. Change concurrency_false_sharing.rs to use #[repr(align(128))], and check whether the time changes on your machine.
5. Time getppid in a loop on your system, and compare it with getpid.

Threads, atomics, and locks

Chapter 15 showed that a laptop CPU has several cores. A program that runs on one thread uses one of them. To use the others, the program must split its work across several threads: independent sequences of instructions that the operating system schedules onto cores.

Threads share the process’s memory, so they can all read the same data. That sharing also makes them dangerous. When two threads change the same memory at the same time, the result can be wrong in ways that are hard to reproduce.

Rust’s promise here is narrow and specific. Safe Rust code cannot contain a data race. In a data race, two threads access the same memory at the same time, and at least one of them writes. Nothing orders the two accesses. The compiler checks this with two traits, Send and Sync. The chapter starts there.

16.1 Starting threads

16.1.1 What a thread is

A process owns memory: the program’s code, its static data, and its heap. A thread is one path of execution through that code. Each thread has its own stack, which holds the local variables of the functions it is running. Each also has its own copy of the CPU registers, including the instruction pointer that says which instruction runs next. Everything else is shared. Every thread reads the same code and can reach the same heap (figure 16.1).

The kernel’s scheduler decides which threads run. A core runs one thread at a time. When there are more runnable threads than cores, the scheduler gives each a short slice of time. Between slices it saves one thread’s registers and loads another’s. That swap is a context switch, and it costs a few microseconds.

A thread that waits for I/O or for a lock is not runnable. It uses no CPU time while it waits, only the memory of its stack.

Because the heap is shared, two threads can reach the same value at the same moment. Section 16.2 shows what goes wrong then, and the rest of the chapter builds the tools that prevent it.

16.1.2 spawn and join