« Back to Index

Rust: Ownership, Borrowing, Lifetimes

View original Gist on GitHub

Tags: #rust #rustlang #ownership #memory

Rust Ownership, Borrowing, Lifetimes.md

Ownership

NOTE: all information learned from https://doc.rust-lang.org/stable/book/ch04-00-understanding-ownership.html

Understanding ownership requires understanding ‘stack’ vs ‘heap’ memory.

• Stack data is released once it goes out of scope (e.g. once a function ends the arguments passed are dropped).
• Stack is quick because the values are literal and can be hardcoded into the compiled binary.
• This means stack values are immutable.
• Heap is for memory that grows or has unknown size and needs to be explicitly dropped.
• Heap is slower as it is allocated at runtime and you have to follow a ‘pointer’ to find the data in heap memory.
• Rust primitive/scalar types (int, bool, float, char, string literal etc) are stored in stack memory.
• Most other complex types (String, Box etc.) are stored into heap memory.

Rules

• Each value in Rust has a variable that’s called its owner.
• There can only be one owner at a time.
• When the owner goes out of scope, the value will be dropped.
  • Primitive types are popped from the stack memory automatically when out of scope.
  • Complex types must implement a drop function which Rust will call when out of scope (to explicitly deallocate heap memory).

Gotchas

• Primitive types are ‘copied’ (a = 1; b = a) because they exist in stack memory and are known size (i.e. cheap to copy).
  • Primitive types have a Copy trait that enable this.
• Complex types ‘move’ ownership (a = String::from("hello"); b = a).
  • Complex types do not have a Copy trait (which is a common error).
• One an owner changes, the previous owner cannot be reused (e.g. you can’t reference the previous owner variable in a print statement after ownership has changed).
• To allow an owner to stay an owner, you’d need to ‘clone’ the complex type (e.g a = String::from("hello"); b = a.clone()) which will actually duplicate the heap memory (so it’s not cheap!).
• Passing a variable (i.e. owner) to a function will move or copy, just as assignment does.
• Returning values can also transfer ownership.
  • Returning a complex type will move ownership to the caller (and the variable the result is assigned to becomes the new owner).
  • In this scenario drop is not called, even if the owner was created within the function, as would normally be the case if a variable went out of scope at the end of the function.

Borrowing

NOTE: all information learned from https://doc.rust-lang.org/stable/book/ch04-02-references-and-borrowing.html

Taking ownership and then returning ownership with every function is a bit tedious. To prevent this you can pass a ‘reference’ to a complex type (e.g. function foo(s: &String) and caller foo(&a)).

In the above example the s variable will (depending on function implementation) go out of scope, and yet nothing will happen (i.e. it won’t be dropped) because the function doesn’t own what s refers to.

In order to mutate something borrowed, the caller and the receiver need to define the type as a ‘mutable’ type:

fn main() {
    let mut s = String::from("hello");

    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

Gotchas

• You can have only one mutable reference (i.e. this prevents data races).
• You can have multiple mutable references only if the scope allows for it.
  • e.g. {let a = &mut s;} let b = &mut s; (as a will go out of scope before b is reached).
• Multiple immutable references is safe.
• We cannot have a mutable reference while we have an immutable one (as this otherwise could change the value of the immutable reference).
• A reference’s scope is from when it’s defined to where it’s last used.
  • This means you can define multiple immutable references and a mutable reference as long as the immutable references go out of scope before the mutable reference.
• Returning a variable created within function (while it being returned as a reference) isn’t allowed because the variable will be dropped once out of scope (this avoids a ‘dangling pointer’).
  • You must instead return the variable itself rather than a reference, and this will cause the ownership to be moved instead.

Lifetimes

NOTE: all information learned from https://doc.rust-lang.org/stable/book/ch10-03-lifetime-syntax.html

Lifetimes ultimately are coupled to references, hence the compiler uses what’s called a “borrow checker” to validate lifetimes (as a ‘reference’ is a term related to the concept of “borrowing”).

Rust prevents variables from trying to hold references to data that has since gone out of scope (i.e. dangling pointer).

The ‘lifetime’ of a reference begins when the reference is created and ends when it’s last used.

If a function returns a reference that changes depending on some logic (e.g. if X return A else return B, where A/B are two different references) then the borrow checker can’t statically analyse if your code is safe as it doesn’t know which reference will be returned at runtime.

In those cases we need to add lifetime annotations…

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

The longest function definition states all references in the signature must have the same lifetime 'a.

We’re specifying that the borrow checker should reject any values that don’t adhere to these constraints.

The lifetime named ‘static’ is a special lifetime. It signals that something has the lifetime of the entire program.

String literals can be assigned the type &'static lifetime annotation as a way to indicate the reference is always alive, i.e. they are baked into the data segment of the final binary.