Saturday, February 29, 2020

Rust Ownership Rules

If you have been following this blog, then it would have been obvious that at the beginning of this year, I started learning Rust. This blogpost is a breakaway from the journal style of capturing the main points I encountered while reading the Rust book. It instead captures my understanding thus far of Rust ownership rules.

One of Rust's main differentiator is that it provides memory safety. This it does by providing compile-time guarantees that flag code that potentially could lead to memory bugs as a compile-time error. The compile-time guarantees enforce what is normally referred to as ownership rules. In this post, I took the opportunity to re-summarise what I consider to be the essence of this ownership rules in Rust. The key points can be outlined as follows:
  • Values are owned by variables. 
  • When the owning variables go out of scope, the memory the value is occupying will be deallocated.
  • The values can be used by other variables, they just need to adhere to certain rules that are enforced by the compiler.
The ways that other variables make use of value can be grouped into 4 categories and these ways of usage will dictate the rules to be adhered to:
  • Clone: Here the value is copied to the other variable. The other variable gets its own ownership of the copied value, while the original variable keeps the ownership of its value.
  • Move. Here the ownership is handed over to the other variable that wants to make use of the value. The original variable no longer has ownership.
  • Immutable Borrow. Here no ownership transfer occurs but the value can be accessed for reading by another variable. The memory is not de-allocated if the borrowing variable goes out of scope, since the borrowing variable does not have ownership.
  • Mutable Borrow. Here the value can be accessed for both reading and writing by the other variable. The memory is also not de-allocated if this borrowing variable goes out of scope since the borrowing variable does not have ownership.


To ensure that all of the above usages do not lead to memory bugs,  Rust then enforces it's ownership rules at compile time. The rules can be outlined as follows:

Ownership rules for Cloning

There is little special about values getting cloned. It is almost the same mechanics you are used to if you have been programming for a while and know how to pass variables like numbers and strings around. Hence there are really not many Rust specific rules to highlight here. Only that most of the time, you won't be cloning values, as this happens to be expensive. The other usage of variables comes with Rust specific rules, and hence we look at them in more detail.

Ownership rules for ownership move

With ownership move, the original variable holding the value would no longer be available for use. The value would now be only accessible via the new variable now holding the value, and has ownership. Attempt to use the variable that has moved it's ownership would lead to compile error:

fn main() {
    let mut original_owner = format!("Hello world");
    
    // move occurs to new owner    
    let new_owner = original_owner;
    
    // attempt to use original_owner will 
    // lead to compile time error    
    println!("{}", original_owner)
}
error[E0382]: borrow of moved value: `original_owner`

Ownership rules for Immutable borrow

With Immutable borrow, the variable borrowing can read the value but cannot mutate (even if the original value is mutable) With immutable borrow, the borrowing variable is guaranteed that the value would not change. Any code that tries to violates these conditions would lead to a compile-time error.

Compile error due to immutable borrow trying to mutate 

fn main() {

  let mut original_owner = format!("Hello world");
  // immutable borrow occurred
  let borrow_owner = &original_owner; 

  // multiple reads possibe via owner
  println!("{}", original_owner);
  println!("{}", original_owner);
  
  // multiple reads possible via borrower
  println!("{}", borrow_owner);
  println!("{}", borrow_owner);
  //error: mutating not possible via borrower
  borrow_owner.push('.')
}
error[E0596]: cannot borrow `*borrow_owner` as mutable, as it is behind a `&` reference
  --> src/main.rs:14:5

Compile error due to owner mutation changing value while still borrowed

If there is code that breaks the guarantee that the borrowing variable would not change, the Rust compiler flags this with a compile-time error.

fn main() {

  let mut original_owner = format!("Hello world");
  // immutable borrow occurred
  let borrow_owner = &original_owner;

  // multiple reads possible via owner
  println!("{}", original_owner);
  println!("{}", original_owner);

  // multiple reads possible via borrower
  println!("{}", borrow_owner);

  // original owner trying to mutate
  original_owner.push('.');

  println!("{}", borrow_owner);
}

error[E0502]: cannot borrow `original_owner` as mutable because it is also borrowed as immutable
If the mutation is moved to a place where the borrow already went out of scope, then the mutation won't lead to a compile-time error. This is because there is no risk of breaking the guarantee to the borrowing variable that value would not change. Eg the following compiles:

fn main() {

  let mut original_owner = format!("Hello world");
  // immutable borrow occurred
  let borrow_owner = &original_owner;
  
  // multiple reads possible via owner
  println!("{}", original_owner);
  println!("{}", original_owner);
  
  // multiple reads possible via borrower
  println!("{}", borrow_owner);
  println!("{}", borrow_owner);
  
  // original owner trying to mutate
  original_owner.push('.');
}

Ownership rules for Mutable borrow

With Mutable borrow, the variable borrowing gets an exclusive right to the variable. This means reading and writing would now have to go through the mutable borrowing variable. The original variable that has ownership won't also be able to read or write until the mutable borrow goes out of scope. The restriction enforces memory consistencies. It prevents things like data races from occurring since it effectively disallows any other writing or reading of the variable via other means, apart from the variable who has a mutable borrow. The rule with mutable borrow also ensures there is always only one active mutable borrow. Doing this makes sense because once you have multiple abilities to borrow and mutate you can no longer enforce consistency. These rules are checked at compile time.

Compile error due to multiple mutable borrows

fn main() {

  let mut original_owner = format!("Hello world");
  
  // mutable borrow occurred
  let borrow_mutable_owner = &mut original_owner;
  // compile error due to second mutable borrow
  let illegal_borrow = &mut original_owner; 
  println!("{}", borrow_mutable_owner);

}


error[E0499]: cannot borrow `original_owner` as mutable more than once at a time

Compile error due to violation of exclusive access via mutable borrow

fn main() {
    let mut original_owner = format!("Hello world");
    
    // mutable borrow occurred
    let borrow_mutable_owner = &mut original_owner;

    // compile error due to: 
    //original owner can no longer read while
    // while borrow_mutale_owner is in scope     
    println!("{}", original_owner);
// borrowing owner can also mutate borrow_mutable_owner.push('!');
    // compile error due to:
    // original owner also cannot write
    original_owner.push('.');
    println!("{}", original_owner);
    println!("{}", borrow_mutable_owner);
}
error[E0502]: cannot borrow `original_owner` as immutable because it is also borrowed as mutable

We have no compilation error if the mutation and reading by the owning variable are moved to a place after the mutable borrow is out of scope. This is fine since there is no longer a need to enforce the mutual exclusivity required by the mutable borrow.

fn main() {
   
  let mut original_owner = format!("Hello world");
  // mutable borrow occurred
  let borrow_mutable_owner = &mut original_owner;

  // borrowing owner can also mutate
  // below is the last usage
  borrow_mutable_owner.push('!');
  
  println!("{}", borrow_mutable_owner);
  // borrow_mutable_owner is now out of scope
  // original owner can now read
  println!("{}", original_owner);
 
  // original owner can now write
  original_owner.push('.');
  println!("{}", original_owner);
}

No error will occur when the above code snippet is compiled.

Summary


To put things in a more succinct form:
  • with cloning:
    • No special rules to guide against memory bugs
    • Generally expensive for non trivial data structures
  • with moving:
    • Once ownership is moved from a variable, that variable no longer has access to the value it originally holds.
  • with immutable borrow: 
    • you can create unlimited immutable borrows
    • all immutable borrows can only read
    • The original owning variable is now restricted regarding how it mutates the value it owned. It can only mutate as long as no immutable borrow is in scope. This ensures that Rust promise to immutable borrow that the variable they borrow won't change is kept.
    • basically: Many readers, no writers (as long as there are readers around. If not, then writing becomes possible) 
  • with mutable borrow:
    • you can only have one mutable borrow.
    • all reading and writing can be done only via the active mutable borrow.
    • The original owning variable also can no longer read nor write as long as there is an active mutable borrow.
    • basically: One write and reader: the mutable borrow 
  • hence the borrow checker ensures:
    • while you can have multiple &T, you cannot also have a &mut T to the same object in scope, as long as any of the &T is still in scope.
    • While having a &mut T, you cannot also have any reference to the same object in scope.

7 comments:

Jahooma said...

Thanks, this was a great intro.

Bala said...

Nice summary of Rust ownership.

A correction (highlighted) -

The restriction enforces memory inconsistencies.

Anonymous said...

I would love an article about ownership and borrowing structs, and how we should employ lifetimes within references inside structs.

shank21101985 said...

Very good summary !

sivakon said...

https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=4c3d69eb180d4827330e7be31aa26683

// compile error due to:
//original owner can no longer read

This compiles and gives me the output, what's wrong here?

John Hopkins said...

15 | println!("{}", original_owner);
| ^^^^^^^^^^^^^^ immutable borrow occurs here

The original_owner is just doing an immutable borrow here.
borrow_mutable_owner became the owner and allows that.
Their ownership roles reversed.

dade said...

@sivakon I fixed the code snippet. It should now work. It should have been like this: https://play.rust-lang.org/?version=stable&mode=debug&edition=2021&gist=c8ed9f3e3425d15c64f405813fbb1b7e basically the immutable read by the original owner should have bee attempted before mutation by the variable that borrows mutable. In that scenario, the compilation fails