Box<T>: values on the heap

What is a smart pointer?

A pointer holds an address. A smart pointer is a struct that acts like a pointer but also has extra abilities and rules, such as owning the data and cleaning it up. String and Vec are smart pointers too: they own heap memory and free it on drop. Box<T> is the simplest one.

fn main() {
    let b = Box::new(5000);     // the number 5000 lives on the heap
    println!("{}", b + 1);       // 5001: Box behaves like the value
}                                // b is dropped: heap memory freed

  STACK            HEAP
  b: ptr ------->  5000

Deref and Drop: what makes it "smart"

Two traits make a Box feel natural. Deref lets you use a Box<T> where a &T is expected and lets * reach the value inside; that is why b + 1 works. Drop runs cleanup code when the value goes out of scope; for Box, it frees the heap memory. You can implement Drop for your own types, for example to log when a connection closes.

struct Connection { id: u32 }

impl Drop for Connection {
    fn drop(&mut self) {
        println!("closing connection {}", self.id);
    }
}

fn main() {
    let _a = Connection { id: 1 };
    let _b = Connection { id: 2 };
    println!("working");
}   // prints: working, closing connection 2, closing connection 1

Use 1: recursive types

A recursive type contains a value of its own type, like a linked list or a tree. The compiler must know the size of every type. A type that contains itself directly would be infinitely big. A Box has a fixed size (one pointer), so putting the inner value in a Box makes the size known.

// error[E0072]: recursive type `List` has infinite size
// enum List { Cons(i32, List), Nil }

enum List {
    Cons(i32, Box<List>),
    Nil,
}

use List::{Cons, Nil};

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

fn main() {
    let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil))))));
    println!("{}", sum(&list));   // 6
}

list:  Cons(1, ptr) --> Cons(2, ptr) --> Cons(3, ptr) --> Nil
         stack            heap             heap             heap

Use 2: trait objects

You met Box<dyn Trait> in module 7: a pointer to some value of unknown size that implements a trait. This is the most common use of Box in everyday code: lists of handlers, plugins and widgets, or a function that returns one of several types.

Use 3: large values

Moving a big struct (say, a 1 MB array) copies all its bytes. Moving a Box<BigStruct> copies one pointer. This matters rarely; measure before optimising.

When NOT to use Box

• For ordinary small values: just use the value. The stack is faster.
• For lists: use Vec, which already stores its items on the heap.
• For shared ownership: Box has exactly one owner. Use Rc (next topic) or Arc (module 9).

Common mistakes

• Defining a recursive struct or enum without Box: E0072 "recursive type has infinite size". Wrap the recursive field in Box (or Vec, or Option<Box<...>>).
• Boxing everything because other languages put objects on the heap. In Rust, default to plain values.
• Trying to clone a Box<dyn Trait> without the trait supporting it. Cloning trait objects needs extra work.