X-Git-Url: https://git.ralfj.de/rust-101.git/blobdiff_plain/20c3754739514b710a2e6744c9fd43bcb83c4706..02337846140cac7ff30e3cc64fd3c9a024bee17c:/src/part04.rs diff --git a/src/part04.rs b/src/part04.rs index f2a6b6c..fb3604e 100644 --- a/src/part04.rs +++ b/src/part04.rs @@ -37,9 +37,9 @@ fn ownership_demo() { //@ //@ If you give a book to your friend, you cannot just come to his place next day and get the book! //@ It's no longer yours. Rust makes sure you don't break this rule. Try enabling the commented -//@ line in `ownership_demo`. Rust will tell you that `v` has been *moved*, which is to say that ownership -//@ has been transferred somewhere else. In this particular case, the buffer storing the data -//@ does not even exist anymore, so we are lucky that Rust caught this problem! +//@ line in `ownership_demo`. Rust will tell you that `v` has been *moved*, which is to say that +//@ ownership has been transferred somewhere else. In this particular case, the buffer storing the +//@ data does not even exist anymore, so we are lucky that Rust caught this problem! //@ Essentially, ownership rules out aliasing, hence making the kind of problem discussed above //@ impossible. @@ -49,17 +49,17 @@ fn ownership_demo() { //@ vector. Hence, when `vec_min` finishes, the entire vector is deleted. That's of course not what //@ we wanted! Can't we somehow give `vec_min` access to the vector, while retaining ownership of it? //@ -//@ Rust calls this *a reference* the vector, and it considers references as *borrowing* ownership. This -//@ works a bit like borrowing does in the real world: If you borrow a book to your friend, your friend -//@ can have it and work on it (and you can't!) as long as the book is still borrowed. Your friend could -//@ even borrow the book to someone else. Eventually however, your friend has to give the book back to you, -//@ at which point you again have full control. +//@ Rust calls this *a reference* to the vector, and it considers references as *borrowing* +//@ ownership. This works a bit like borrowing does in the real world: If your friend borrows a +//@ book from you, your friend can have it and work on it (and you can't!) as long as the book is +//@ still borrowed. Your friend could even lend the book to someone else. Eventually however, your +//@ friend has to give the book back to you, at which point you again have full control. //@ //@ Rust distinguishes between two kinds of references. First of all, there's the *shared* reference. //@ This is where the book metaphor kind of breaks down... you can give a shared reference to //@ *the same data* to lots of different people, who can all access the data. This of course -//@ introduces aliasing, so in order to live up to its promise of safety, Rust generally does not allow -//@ mutation through a shared reference. +//@ introduces aliasing, so in order to live up to its promise of safety, Rust generally does not +//@ allow mutation through a shared reference. //@ So, let's re-write `vec_min` to work on a shared reference to a vector, written `&Vec`. //@ I also took the liberty to convert the function from `SomethingOrNothing` to the standard @@ -68,8 +68,8 @@ fn vec_min(v: &Vec) -> Option { use std::cmp; let mut min = None; - // This time, we explicitly request an iterator for the vector `v`. The method `iter` just borrows the vector - // it works on, and provides shared references to the elements. + // This time, we explicitly request an iterator for the vector `v`. The method `iter` just + // borrows the vector it works on, and provides shared references to the elements. for e in v.iter() { // In the loop, `e` now has type `&i32`, so we have to dereference it to obtain an `i32`. min = Some(match min { @@ -88,9 +88,9 @@ fn shared_ref_demo() { vec_min(&v); println!("The first element is: {}", *first); } -//@ What's going on here? First, `&` is how you borrow ownership to someone - this operator creates a shared reference. -//@ `shared_ref_demo` creates three shared references to `v`: -//@ The reference `first` begins in the 2nd line of the function and lasts all the way to the end. The other two +//@ What's going on here? First, `&` is how you lend ownership to someone - this operator creates a +//@ shared reference. `shared_ref_demo` creates three shared references to `v`: The reference +//@ `first` begins in the 2nd line of the function and lasts all the way to the end. The other two //@ references, created for calling `vec_min`, only last for the duration of that respective call. //@ //@ Technically, of course, references are pointers. Notice that since `vec_min` only gets a shared @@ -98,13 +98,16 @@ fn shared_ref_demo() { //@ that was created before calling `vec_min` remains valid. // ## Unique, mutable references -//@ There is a second way to borrow something, a second kind of reference: The *mutable reference*. This is a reference that comes with the promise -//@ that nobody else has *any kind of access* to the referee - in contrast to shared references, there is no aliasing with mutable references. It is thus always safe to perform mutation through such a reference. + +//@ There is a second way to borrow something, a second kind of reference: The *mutable reference*. +//@ This is a reference that comes with the promise that nobody else has *any kind of access* to +//@ the referee - in contrast to shared references, there is no aliasing with mutable references. +//@ It is thus always safe to perform mutation through such a reference. //@ Because there cannot be another reference to the same data, we could also call it a *unique* reference, but that is not their official name. //@ As an example, consider a function which increments every element of a vector by 1. -//@ The type `&mut Vec` is the type of mutable references to `vec`. Because the reference is -//@ mutable, we can use a mutable iterator, providing mutable references to the elements. +//@ The type `&mut Vec` is the type of mutable references to `vec`. Because the reference +//@ is mutable, we can use a mutable iterator, providing mutable references to the elements. fn vec_inc(v: &mut Vec) { for e in v.iter_mut() { *e += 1; @@ -118,29 +121,37 @@ fn mutable_ref_demo() { vec_inc(&mut v); /* println!("The first element is: {}", *first); */ /* BAD! */ } -//@ `&mut` is the operator to create a mutable reference. We have to mark `v` as mutable in order to create such a -//@ reference: Even though we completely own `v`, Rust tries to protect us from accidentally mutating things. + +//@ `&mut` is the operator to create a mutable reference. We have to mark `v` as mutable in order +//@ to create such a reference: Even though we completely own `v`, Rust tries to protect us from +//@ accidentally mutating things. //@ Hence owned variables that you intend to mutate have to be annotated with `mut`. -//@ Because the reference passed to `vec_inc` only lasts as long as the function call, we can still call -//@ `vec_inc` on the same vector twice: The durations of the two references do not overlap, so we never have more -//@ than one mutable reference - we only ever borrow `v` once at a time. However, we can *not* create a shared reference that spans a call to `vec_inc`. Just try +//@ Because the reference passed to `vec_inc` only lasts as long as the function call, we can still +//@ call `vec_inc` on the same vector twice: The durations of the two references do not overlap, so +//@ we never have more than one mutable reference - we only ever borrow `v` once at a time. +//@ However, we can *not* create a shared reference that spans a call to `vec_inc`. Just try //@ enabling the commented-out lines, and watch Rust complain. This is because `vec_inc` could mutate //@ the vector structurally (i.e., it could add or remove elements), and hence the reference `first` -//@ could become invalid. In other words, Rust keeps us safe from bugs like the one in the C++ snipped above. +//@ could become invalid. In other words, Rust keeps us safe from bugs like the one in the C++ +//@ snippet above. //@ -//@ Above, I said that having a mutable reference excludes aliasing. But if you look at the code above carefully, -//@ you may say: "Wait! Don't the `v` in `mutable_ref_demo` and the `v` in `vec_inc` alias?" And you are right, -//@ they do. However, the `v` in `mutable_ref_demo` is not actually usable, it is not *active*: As long as `v` is -//@ borrowed, Rust will not allow you to do anything with it. +//@ Above, I said that having a mutable reference excludes aliasing. But if you look at the code +//@ above carefully, you may say: "Wait! Don't the `v` in `mutable_ref_demo` and the `v` in +//@ `vec_inc` alias?" And you are right, they do. However, the `v` in `mutable_ref_demo` is not +//@ actually usable, it is not *active*: As long as `v` is borrowed, Rust will not allow you to do +//@ anything with it. // ## Summary // The ownership and borrowing system of Rust enforces the following three rules: // // * There is always exactly one owner of a piece of data // * If there is an active mutable reference, then nobody else can have active access to the data -// * If there is an active shared reference, then every other active access to the data is also a shared reference +// * If there is an active shared reference, then every other active access to the data is also a +// shared reference // -// As it turns out, combined with the abstraction facilities of Rust, this is a very powerful mechanism -// to tackle many problems beyond basic memory safety. You will see some examples for this soon. +// As it turns out, combined with the abstraction facilities of Rust, this is a very powerful +// mechanism to tackle many problems beyond basic memory safety. You will see some examples for +// this soon. -//@ [index](main.html) | [previous](part03.html) | [raw source](https://www.ralfj.de/git/rust-101.git/blob_plain/HEAD:/workspace/src/part04.rs) | [next](part05.html) +//@ [index](main.html) | [previous](part03.html) | [raw source](workspace/src/part04.rs) | +//@ [next](part05.html)