References and the borrowing rules

let first = &queue[0]; followed by queue.push(50); is two lines that Rust refuses with error E0502. The push needs a fifth place in a Vec that has room for four, so it may move all four items to a new block of memory, as a run below shows, and first would then point into the old block, which has just been freed; in C++, which accepts the same lines, the standard calls such a reference invalidated.

This lesson shows how references let code use a value without owning it, the two borrowing rules that every reference follows (any number of readers or one writer, and no reference to a value that is gone), and why the order of your lines decides what compiles. The Rust programs here ran on Rust 1.99.0.

A reference lets code use a value without owning it

A referencereference: A value that refers to another value without owning it: &T lets code read the value and &mut T lets it change it. The compiler checks that no reference outlives the value it refers to. is an address that comes with a promise: &marks refers to marks without taking it, and the compiler guarantees that it refers to a valid value for as long as it is used. Passing &marks to a function lends the value, and when the function returns the loan is over. A shared referenceshared reference: A reference written &T. Any number of them may refer to a value at the same time, and none of them can change it., &T, lets the borrower read; a mutable referencemutable reference: A reference written &mut T, through which code can change the value it refers to. While it is in use, no other reference to that value may be used., &mut T, lets it change the value in place, and only an owner declared with mut can lend one:

// A shared borrow to read, a mutable borrow to change: main owns the marks throughout.
fn total(marks: &[u32]) -> u32 {
    marks.iter().sum()
}

fn add_bonus(marks: &mut Vec<u32>, bonus: u32) {
    for mark in marks.iter_mut() {
        *mark += bonus;
    }
    marks.push(bonus);
}

fn main() {
    let mut marks = vec![72, 45, 88];
    println!("total {}", total(&marks));
    add_bonus(&mut marks, 5);
    println!("total {}", total(&marks));
    let first = &marks[0];
    let second = &marks[1];
    println!("first {first}, second {second}, both read at once");
    let last = marks.last_mut().unwrap();
    *last = 10;
    println!("marks {marks:?}, total {}", total(&marks));
}

total 205
total 225
first 77, second 50, both read at once
marks [77, 50, 93, 10], total 230

Step through the loans in order:

main owned the marks the whole time. total read them through &[u32], a borrowed view of the items, and add_bonus changed them through &mut Vec<u32>, which can also push. Method calls see through a reference, so marks.iter() reads a Vec and a reference to one alike, while *mark += bonus writes through a reference with an explicit *.

The borrowing rules: any number of readers, or one writer

Every borrowborrow: To take a reference to a value, so that other code can use the value while its owner keeps it. A borrow lasts from where the reference is made to the last place it is used. follows two borrowing rules. The Rust book states the first one this way:

At any given time, you can have either one mutable reference or any number of immutable references.

The second is that references must always be valid. The borrow checkerborrow checker: The part of the Rust compiler that checks every reference against the ownership and borrowing rules, and refuses to build a program in which a reference could outlive its value or break those rules. applies both borrowing rules before the program is built, so the program from the opening never runs:

// A reference into a Vec, held across a push that needs more room than the Vec has.
fn main() {
    let mut queue: Vec<u64> = Vec::with_capacity(4);
    queue.extend([10, 20, 30, 40]);
    let first = &queue[0];
    queue.push(50);
    println!("first is {first}");
}

error[E0502]: cannot borrow `queue` as mutable because it is also borrowed as immutable
 --> push_conflict.rs:6:5
  |
5 |     let first = &queue[0];
  |                  ----- immutable borrow occurs here
6 |     queue.push(50);
  |     ^^^^^^^^^^^^^^ mutable borrow occurs here
7 |     println!("first is {first}");
  |                         ----- immutable borrow later used here

error: aborting due to 1 previous error

For more information about this error, try `rustc --explain E0502`.

E0502 names the two borrows that overlap: first, made on line 5 and used on line 7, and the mutable borrow that push needs on line 6. The reason for the rule shows when the same push runs with no reference held:

// Where the Vec keeps its items before and after a push that needs more room.
fn main() {
    let mut queue: Vec<u64> = Vec::with_capacity(4);
    queue.extend([10, 20, 30, 40]);
    let neighbour: Vec<u64> = vec![0; 4];
    let before = queue.as_ptr();
    println!("length {}, capacity {}", queue.len(), queue.capacity());
    queue.push(50);
    let after = queue.as_ptr();
    println!("length {}, capacity {}", queue.len(), queue.capacity());
    println!("items moved to a new block: {}", before != after);
    println!("{} items beside it", neighbour.len());
}

length 4, capacity 4
length 5, capacity 8
items moved to a new block: true
4 items beside it

The capacity went from 4 to 8, and the items moved to a new block; the standard library documents that when a vector’s length exceeds its capacity, its elements have to be reallocated. Step through what first would have pointed at:

Two mutable references to one value, both in use at once, break the same rule from the other side, and rustc reports them as error E0499. A narrow exception, two-phase borrows, lets a method call such as v.push(v.len()) read the vector in its own argument.

A borrow lasts until its last use, not until the end of the block

A borrow lasts from the line that makes the reference to the last line that uses it. So moving one line can fix E0502:

// A borrow lasts until its last use, so the order of the lines decides what compiles.
fn main() {
    let mut queue: Vec<u64> = Vec::with_capacity(4);
    queue.extend([10, 20, 30, 40]);

    let first = &queue[0];
    println!("first is {first}"); // the last use of first: the borrow ends here
    queue.push(50); // so the Vec may change now

    let copied = queue[0]; // a u64 is Copy: copied holds its own value, no borrow
    queue.push(60);
    println!("copied is {copied}, queue is {queue:?}");
}

first is 10
copied is 10, queue is [10, 20, 30, 40, 50, 60]

Printing first before the push ends its borrow, so the push is allowed. Copying a value out of the Vec avoids the borrow altogether: a u64 is Copy, so copied holds its own 10 and points into nothing. Step through which borrow is in use at each line:

This is called non-lexical lifetimes: the length of a borrow follows the flow of the code, not the braces of the block. It arrived with the 2018 edition, and Rust 1.63 removed the older borrow checker from every edition.

Two writers, a missing mut and two-phase borrows, reproduced Pro: opens with a Pro, Premium or Ultimate pass

What the rules prevent: invalidated references and data races Pro: opens with a Pro, Premium or Ultimate pass

Practise: references and the borrowing rules

These questions are about lending with & and &mut, the rule of many readers or one writer, and where a borrow ends. Every choice says why it is right or what it misses.

Interview questions

Warm-up (fresher): what is the difference between &T and &mut T?

&T is a shared reference: it lends a value to read, any number of them can be in use at once, and none of them can change it, so a &T is Copy. &mut T is a mutable reference: it lends the value to be changed in place, needs an owner declared with mut, and while it is in use no other reference to the value may be used, so it is not Copy. Both are borrows: the owner keeps the value, and the compiler checks that no reference outlives it. A good answer adds why: many readers or one writer is what lets the compiler rule out data races and references into moved memory.

Key takeaways

• A reference lends a value without moving it, &T to read and &mut T to change it, and the owner keeps the value throughout.
• At any moment a value may have any number of shared references or one mutable reference, never both, and rustc refuses a program that breaks the rule (E0502).
• A push may move a Vec’s items to a new block, which is why a reference into a Vec and a change to it cannot overlap.
• A borrow lasts until the reference’s last use, so moving a line or copying a value out often fixes a borrow error.