Why is the Brown Book still recommended?

[JayanAXHF]

URL to the section(s) of the book with this problem:
https://doc.rust-lang.org/book/

Description of the problem:

The cover of the rust book suggests using the "Brown Book" (a version of the rust book from Brown University. However, this book has many known flaws, including but not limited to poor chapter structure, and misleading quizzes that do disservice to the underlying concept at hand.

1. https://rust-book.cs.brown.edu/ch04-02-references-and-borrowing.html#permissions-are-returned-at-the-end-of-a-references-lifetime
   This part of the book mentions terms like "Flow Permission", which are not standard or colloquial terms in the Rust Community, and as such make it harder for many to ask for help from other sources.
2. The Brown Book talks about fixing Vec borrow errors (4.3) before it even introduces those errors (8.1)
3. Question three of the second quiz in https://rust-book.cs.brown.edu/ch04-03-fixing-ownership-errors.html has an incorrect answer. The book states that this is program does not have any UB, however, it does. (The UB would be from overlapping exclusive borrows).

These are just some examples that I happen to have found quickly, and the Book is littered with mistakes and confusion all throughout.

I am also quoting a few messages from the Rust Programming Language Community Discord, to present the opinion others in the community.

Thank u very much <@499019818893049866> and <@518196659394445337>, I took your advice and read the original book... And indeed, it's much clearer! the RWOs in the brown book confused me more than anything else. For example, this rule was very helpfull for me :
- At any given time, you can have either one mutable reference or any number of immutable references.

Link

FYI, many people find the brown experimental book version to be confusing.

Link

That chapter and the "which of these would not be ub if compiler allowed them" are probably the most notorious parts of the Brown book

Link

Suggested fix:

1. Either the disclaimer about the Brown book should be completely removed, or
2. The disclaimer should explicitly mention that the Brown Book is not suited well for beginners, and has some certain issues and quirks to note.

[JayanAXHF]

Bump

[carols10cents]

@willcrichton Are you still gathering research through the Brown book? Are you planning on addressing feedback like the issues listed here?

[willcrichton]

Hi @carols10cents, at present, we are not running any active experiments on the Brown book, although that is mostly for lack of time / labor, since I just started my professorship this past semester. I have been regularly updating the book every ~3 months, both to sync with upstream, and to fix things I consider outstanding issues.

My general response to the concerns in the OP: it's absolutely true that different explanations of ownership will work for different people. However, I stand behind the ownership chapter in the Brown book, both because I think it's a good way to explain ownership, and because our research has demonstrated its efficacy on large populations of Rust learners. As such, I think the main book ought to retain its link to the Brown book.

More concretely, after deploying our ownership chapter, it did not harm any general indicators (retention rates, accuracy on questions unrelated to ownership), while it did meaningfully improve indicators related to ownership (accuracy on ownership questions). This data is gathered from over 100,000 readers. I can also offer quotes from several people who have emailed me to praise how the Brown book helped them understand ownership better than existing resources. For the interested, I gave a presentation at RustConf 2023 on this research: https://www.youtube.com/watch?v=x5EbGrgmXKw

That said, I don't want to minimize individuals' concerns, and if something is truly unclear or misleading, I am happy to revise the text.

To the specific points raised here:

This part of the book mentions terms like "Flow Permission", which are not standard or colloquial terms in the Rust Community, and as such make it harder for many to ask for help from other sources.

This is very true. The premise of our pedagogy is that we needed to introduce new terms to talk about the internal state of the borrow checker, for which there are no standard or colloquial terms. However, this makes our book the single source of truth. We do hope that our online permissions REPL can help learners along with the book: https://cel.cs.brown.edu/aquascope/

The Brown Book talks about fixing Vec borrow errors (4.3) before it even introduces those errors (8.1)

Vec borrow errors are introduced in Section 4.2. It was a conscious decision to introduce vectors and strings a bit earlier, because they are extremely useful vehicles for talking about ownership.

Question three of the second quiz in [...] has an incorrect answer

I'm not sure what this is referring to. I had run these answers by Miri to vet the presence / absence of UB, although it's possible the standard has been updated since the quiz question was developed. I would be happy to address an issue filed on the repository.

Book is littered with mistakes and confusion all throughout.

This is frankly a little insulting, but I would argue the book is not littered with mistakes and confusion. Every change has been carefully measured in terms of its effects on quiz questions, and most changes are relatively small. Besides the ownership chapter, the most substantial changes throughout the book are additions of quizzes, and additions of runtime diagrams to depict program behavior.

[JayanAXHF]

This is frankly a little insulting, but I would argue the book is not littered with mistakes and confusion. Every change has been carefully measured in terms of its effects on quiz questions, and most changes are relatively small. Besides the ownership chapter, the most substantial changes throughout the book are additions of quizzes, and additions of runtime diagrams to depict program behavior.

Im sorry for writing that. The poor and degrading wording is a fault on my part. I understand that the changes have been measured effectively, and do have purpose and intent behind them. The concern that I wanted to express (which I did rather disrespectfully, for which I again apologise), was not that it is fully bad per se, but that some explainations and pedagogical methods were a bit confusing and not suited to beginners. This is why I suggest not removing the link to it entirely, but adding a small text that warns the user that it takes an innovative and new method of teaching.

[JayanAXHF]

My general response to the concerns in the OP: it's absolutely true that different explanations of ownership will work for different people. However, I stand behind the ownership chapter in the Brown book, both because I think it's a good way to explain ownership, and because our research has demonstrated its efficacy on large populations of Rust learners. As such, I think the main book ought to retain its link to the Brown book.

More concretely, after deploying our ownership chapter, it did not harm any general indicators (retention rates, accuracy on questions unrelated to ownership), while it did meaningfully improve indicators related to ownership (accuracy on ownership questions). This data is gathered from over 100,000 readers. I can also offer quotes from several people who have emailed me to praise how the Brown book helped them understand ownership better than existing resources. For the interested, I gave a presentation at RustConf 2023 on this research: https://www.youtube.com/watch?v=x5EbGrgmXKw

Thank you for being so understanding. It is true that your method of teaching works, as shown by the data. The point I wanted to raise what that the use of nominal terms like flow permissions makes it harder for people to ask questions on forums. After some more though, removing the Brown Book link entirely would not be prudent; instead, I'd suggest adding text like in my previous message.

[willcrichton]

It's all good. I can also make it clearer in the book that the ownership chapter specifically has been substantively changed vs. the original book, so readers are aware that they can return to the original book if they find the explanation unhelpful.

[JayanAXHF]

I can also make it clearer in the book that the ownership chapter specifically has been substantively changed vs. the original book, so readers are aware that they can return to the original book if they find the explanation unhelpful.

That would be sweet!

[kpreid]

Question three of the second quiz in [...] has an incorrect answer

I'm not sure what this is referring to. I had run these answers by Miri to vet the presence / absence of UB, although it's possible the standard has been updated since the quiz question was developed. I would be happy to address an issue filed on the repository.

@willcrichton I will explain how this question is (somewhat arguably) incorrect. The question currently consists of the following text:

Question 3
The following program does not compile:

fn copy_to_prev(v: &mut Vec<i32>, i: usize) {
  let n = &mut v[i];
  *n = v[i - 1];
}
fn main() {
  let mut v = vec![1, 2, 3];
  copy_to_prev(&mut v, 1);
}

Which of the following best describes the undefined behavior that could occur if this program were allowed to execute?

The four answers available are:

• The assignment *n is a use of freed memory
• The read of v[i - 1] is a use of freed memory
• There is no undefined behavior in this program
• The borrow &mut v[i] creates a pointer to freed memory

None of these four answers is correct. The program has undefined behavior not because of freed memory, but because on the second line, the Vec<i32> v is dereferenced, creating an &mut [i32] which overlaps with the already-existing &mut i32. To demonstrate this, we can modify the program to defeat the borrow checker without changing anything else:

/// Returns the input reference with a changed lifetime.
fn cheat_lifetime<'a, 'b, T: ?Sized>(input: &'a mut T) -> &'b mut T {
    unsafe { &mut *std::ptr::from_mut(input) }
}

fn copy_to_prev(v: &mut Vec<i32>, i: usize) {
  let n = cheat_lifetime(&mut v[i]); // allows compilation, but still UB
  *n = v[i - 1];
}

Miri then reports the following UB:

error: Undefined Behavior: attempting a write access using <606> at alloc290[0x4], but that tag does not exist in the borrow stack for this location
 --> src/main.rs:7:3
  |
7 |   *n = v[i - 1];
  |   ^^^^^^^^^^^^^ this error occurs as part of an access at alloc290[0x4..0x8]
  |
  = help: this indicates a potential bug in the program: it performed an invalid operation, but the Stacked Borrows rules it violated are still experimental
  = help: see https://github.com/rust-lang/unsafe-code-guidelines/blob/master/wip/stacked-borrows.md for further information
help: <606> was created by a Unique retag at offsets [0x4..0x8]
 --> src/main.rs:6:11
  |
6 |   let n = cheat_lifetime(&mut v[i]);
  |           ^^^^^^^^^^^^^^^^^^^^^^^^^
help: <606> was later invalidated at offsets [0x0..0xc] by a SharedReadOnly retag
 --> src/main.rs:7:9
  |
7 |   *n = v[i - 1];
  |         ^^^^^^^

(As noted, Stacked Borrows is still an experimental set of rules and the future of Rust semantics might look different, but we shouldn’t be teaching people that SB violations are fine until SB is definitely rejected. Furthermore, this is also UB under Tree Borrows if you move the second line into its own function. All this is nuance which people being introduced to UB should be steered away from.)

My recollection, which I have not verified, is that other “if this program were allowed to execute” quiz questions are similarly incorrect: they answer “there is no undefined behavior” according to a model of the program semantics which contradicts Rust’s semantics, and which will lead to incorrect conclusions about what is valid to do using unsafe code. (For example of how it applies to this case: unsafe code can be used to write programs that access memory in patterns the borrow checker does not accept but are otherwise valid, but you may not use unsafe code to create overlapping &mut — that is UB regardless of what the borrow checker thinks, and programs which wish to work with overlapping slices must use raw pointers to those slices rather than &mut to those slices.)

This problem — teaching an incorrect model of UB — is, in my personal opinion (I am not a Rust team member), the reason why the Brown edition of the book should either be revised to correct these errors, or not recommended as it stands. If you are interested in making corrections, I would be willing to help out by critiquing the other questions similarly.

[willcrichton]

Let me offer my reasoning for this particular question. The answer is marked as "There is no undefined behavior in this program" because v[i] and v[i - 1] do not alias. The intuition here is that if you used raw pointers instead of safe references, then the resulting program would pass Miri under either Stacked or Tree Borrows:

fn copy_to_prev(v: &mut Vec<i32>, i: usize) {
  let n = &raw mut v[i];
  unsafe { *n = v[i - 1]; }
}

fn main() {
  let mut v = vec![1, 2, 3];
  copy_to_prev(&mut v, 1);
}

I believe this program is more in the spirit of the question than one with a transmute, because the question in the context of the chapter is asking: if Rust didn't have the borrow checker, what would happen?

The goal of this question is to reinforce to learners that they should think about whether two references actually alias, in order to distinguish a soundness vs. completeness issue in the borrow checker. A key finding in our research is that this skill, reasoning about soundness vs. completeness, is essential to dealing with the borrow checker in the daily practice of Rust. For example, in this program, a Rust user should see the compiler error and think "I need to reach for a helper function which encapsulates this access pattern implemented in unsafe code", a process I make very explicit in Section 4.3: https://rust-book.cs.brown.edu/ch04-03-fixing-ownership-errors.html

More generally, I have discussed this concern at length in several threads, such as cognitive-engineering-lab#186 and cognitive-engineering-lab#265. In short, our ownership chapter discusses an extremely abbreviated model of UB for the sole purpose of helping learners reason about ownership errors. I would argue this model is not incorrect, but it is certainly not exhaustive. The goal is not to help Rust learners write unsafe code, for which they need formal training in the entire scope of UB as e.g. provided by the Rustonomicon. This anti-goal is made explicit at several points in the book, and I have seen no evidence that the ownership chapter leads learners to incorrect conclusions about unsafe code. However, I have seen evidence that this chapter leads learners to better understand ownership in the aggregate.

[kpreid]

if you used raw pointers instead of safe references, then the resulting program would pass Miri under either Stacked or Tree Borrows:

Yes, that is true. But “remove the borrow checker” is not the same action as “change the program to use raw pointers”. (The cheat_lifetimes function I wrote is a very good approximation of “remove the borrow checker” — I specifically wrote it to be that.) That’s the entire problem, I believe — the quiz answers are written for “change the program to use raw pointers”, but the questions are written for “remove the borrow checker”; they say “if this program compiled…”, not “if you changed the types to raw pointers so that the program compiled…”. I don’t particularly care which of those two perspectives you use, but you should pick one of them and stick with it, not use half of one and half of the other.

[willcrichton]

Perhaps this is a disagreement then in perspective? I think of "transmute your types so as to satisfy the borrow checker" not as removing the borrow checker as much as working around it. For me, removing the borrow checker is considering if Rust had unchecked pointer operations as in C, best represented by raw pointers. So I see the book as using a consistent perspective throughout the chapter.

[kpreid]

"transmute your types so as to satisfy the borrow checker" not as removing the borrow checker as much as working around it.

The borrow checker is a portion of the compiler which, strictly, either accepts or rejects a program, and never affects its semantics. Therefore, cheating lifetimes, by any means, also does not change the semantics of the program. Switching between raw pointers and references does change the semantics of the program.

Therefore, changing lifetimes with casts/transmutes (or actually deleting the borrow checker) is a way to obtain completely accurate answers to questions of the form “what if this program compiled?”, in cases where it succeeds. On the other hand, expecting an answer as if the types were changed to raw pointers is teaching a language that is not Rust, but has a misleadingly similar syntax.