rephrase UnsafeCell doc

[NovemberZulu]

As shown by discussions on users.rust-lang.org [1], [2], UnsafeCell doc is not totally clear. I tried to made the doc univocal regarding what is allowed and what is not. The edits are based on my understanding following [1].

[rust-highfive]

Thanks for the pull request, and welcome! The Rust team is excited to review your changes, and you should hear from @TimNN (or someone else) soon.

If any changes to this PR are deemed necessary, please add them as extra commits. This ensures that the reviewer can see what has changed since they last reviewed the code. Due to the way GitHub handles out-of-date commits, this should also make it reasonably obvious what issues have or haven't been addressed. Large or tricky changes may require several passes of review and changes.

Please see the contribution instructions for more information.

[TimNN]

Re-assigning to docs team.

r? @steveklabnik

[pietroalbini]

Thanks for the PR @NovemberZulu!

@steveklabnik, or someone else from @rust-lang/docs, can we get a review on this PR?

[GuillaumeGomez]

I'm not sure that putting italic in here brings anything.

[NovemberZulu]

removed italic

[GuillaumeGomez]

Except for my little concern, it seems good to me.

[steveklabnik]

I would really like someone from @rust-lang/libs or @rust-lang/lang to sign off here; changing an unsafe lang item's docs is something i'm super wary of doing without their input.

[cramertj]

Can you reformat this as a list? Several of the entries are long, and the sentence becomes hard to follow.

[cramertj]

These rules are kind of confusingly stated. I think it should be something like the following:
(1) While a mutable reference exists, no second reference or of any kind may exist.
(2) While a reference of any kind exists, all mutations must go through that reference. This means that mutations cannot occur while an immutable reference exists.

[NovemberZulu]

I'll try to merge three rules into one, so it will be easier to follow.

[NovemberZulu]

As far as I understand -- and I quite possible I am wrong -- simply storing a "bad" reference is not a crime, it is just some bytes in memory, but actually using it is UB, so I talk about active references in the doc. What exactly is "using" as opposed to stored is another story, and should be defined in memory model, I believe.

[nikomatsakis]

I tried to offer some feedback but found it harder than expected. I will say that I continue to be strongly opposed to the term "immutable reference" -- I know we use it a lot, but particularly in the context of UnsafeCell, it strikes me as quite confusing. I'd prefer that we either say "shared reference" or just &-reference (perhaps clearer).

I personally found the current form of "English-y paragraph" sort of confusing, to be honest. I think I'd prefer something that says like:

UnsafeCell is the only way that data reached via a &-reference can be correctly mutated: any data that is not stored within an UnsafeCell must be immutable when reachable via & reference. The UnsafeCell API itself is very simple: it gives you a raw pointer (*mut T) to its contents. It is up to you to use that raw pointer correctly.

The precise Rust aliasing rules are somewhat in flux, but the main points are not contentious:

• If you create a safe reference with lifetime 'a (either a & or &mut reference) that is accessible by safe code (for example, because you returned it), then you must not access the data in any way that contradicts that reference for the remainder of 'a.
  • For example, that means that if you take the *mut T from an UnsafeCell<T> and case it to an &T, then until that reference's lifetime expires, the data in T must remain immutable (modulo any UnsafeCell data found within T, of course). Similarly, if you create an &mut T reference that is released to safe code, then you must not access the data within the UnsafeCell until that reference expires.
• At all times, you must avoid data races, meaning that if multiple threads have access to the same UnsafeCell, then any writes must have a proper happens-before relation to all other accesses (or use C++11 atomics).

[NovemberZulu]

I totally agree that proper wording here is a challenge -- the text must be univocal, concise, yet as simple as possible. I think that "shared reference" might be a bit confusing, because of "shared with what?" question. &-reference is a bit jargon term, but &-reference contrasts &mut-reference very nicely.

I think the best way is to state explicitly allowed code flows, at least for single-thread access -- multi-thread access is way more complicated (does Rust strictly define happens-before relation?) -- something like this:

UnsafeCell is the only way in core Rust that data reached via a &-reference can be correctly mutated: any data that is not stored within an UnsafeCell must be immutable when reachable via &-reference. All other types that allow internal mutability, such as Cell<T> and RefCell<T> use UnsafeCell to wrap their internal data. The UnsafeCell API itself is very simple: it gives you a raw pointer (*mut T) to its contents. It is up to you as the abstraction designer to use that raw pointer correctly.

The precise Rust aliasing rules are somewhat in flux, but the main points are not contentious:

• If you create a safe reference with lifetime 'a (either a & or &mut reference) that is accessible by safe code (for example, because you returned it), then you must not access the data in any way that contradicts that reference for the remainder of 'a. For example, that means that if you take the *mut T from an UnsafeCell<T> and case it to an &T, then until that reference's lifetime expires, the data in T must remain immutable (modulo any UnsafeCell data found within T, of course). Similarly, if you create an &mut T reference that is released to safe code, then you must not access the data within the UnsafeCell until that reference expires. The following two scenarios are explicitly legal:

  1. a &-reference can be released to safe code and there it can co-exit with other &-references, but not with a &mut-reference

  2. a &mut-reference may be released to safe code, provided neither other &mut-references nor even &-references co-exist with it. A &mut-reference must always be unique.

• At all times, you must avoid data races, meaning that if multiple threads have access to the same UnsafeCell, then any writes must have a proper happens-before relation to all other accesses (or use atomics).

[nikomatsakis]

does Rust strictly define happens-before relation

We inherit the C++11 model, basically.

[NovemberZulu]

We inherit the C++11 model, basically.

(sigh) I was so hoping to get away from it...

[emberian]

@NovemberZulu why? because of how complex it is?

[NovemberZulu]

Because, as with numerous other C++ features, you never know when it is going to bite you in the ass

[emberian]

I'm confused. The C++11 memory model is extremely well understood. http://www.cl.cam.ac.uk/~pes20/weakmemory/#CPP

[NovemberZulu]

C++ is hardly an esoteric or obscure language, and the documentation is both readily available and extensive, that is certainly true. Still, to my mind, it is too easy to end up with a code that looks OK, seems to work the way you expect it to work, but is, in fact, UB.

P.S. I think we are digressing.

[steveklabnik]

@nikomatsakis we use "reference" and "mutable reference", officially. Or at least, that's what I've been keeping consistent in every bit of docs I come across, it's hard, of course.

I agree "immutable reference" is a bit misleading, which is part of why we chose this this way so long ago.

[NovemberZulu]

we use "reference" and "mutable reference", officially.

I am afraid I have been using "reference" as an umbrella term for both &T and &mut T adding to the confusion :( Following Liskov, &mut T IS-A &T, isn't? BTW, what is misleading about "immutable reference"?

Anyway, may be we can just use &T and &mut T in UnsafeCell<T> doc?

[Kimundi]

@NovemberZulu: A &T might allow some mutation inside the T if T uses internal mutability like Cell, so its not always immutable.

[NovemberZulu]

A &T might allow some mutation inside the T if T uses internal mutability like Cell, so its not always immutable.

Yes, true, and this is exactly the case we have. I still have a mental picture of T * const when thinking of UnsafeCell<T> :(

[nikomatsakis]

@steveklabnik

we use "reference" and "mutable reference", officially. Or at least, that's what I've been keeping consistent in every bit of docs I come across, it's hard, of course.

That make sense, but it seems like sometimes we will want to clarify that we mean an &T and that we are excluding &mut T. In those cases, what do you do?

[steveklabnik]

If "reference" isn't clear enough, I often write &T, like @Kimundi did above:

A &T might allow some mutation inside the T if T uses internal mutability like Cell, so its not always immutable.

[NovemberZulu]

Another attempt at rewording:

If you have a reference &SomeStruct, then normally in Rust all fields of SomeStruct are immutable. UnsafeCel<T> is the only core language feature to work around this restriction. All other types that allow internal mutability, such as Cell<T> and RefCell<T> use UnsafeCell to wrap their internal data. The UnsafeCell API itself is technically very simple: it gives you a raw pointer *mut T to its contents. It is up to you as the abstraction designer to use that raw pointer correctly.

The precise Rust aliasing rules are somewhat in flux, but the main points are not contentious:

• If you create a safe reference with lifetime 'a (either a &T or &mut T reference) that is accessible by safe code (for example, because you returned it), then you must not access the data in any way that contradicts that reference for the remainder of 'a. For example, that means that if you take the *mut T from an UnsafeCell<T> and case it to an &T, then until that reference's lifetime expires, the data in T must remain immutable (modulo any UnsafeCell data found within T, of course). Similarly, if you create an &mut T reference that is released to safe code, then you must not access the data within the UnsafeCell until that reference expires.

• At all times, you must avoid data races, meaning that if multiple threads have access to the same UnsafeCell, then any writes must have a proper happens-before relation to all other accesses (or use atomics).

To assist with proper design, the following scenarios are explicitly declared legal for single-thread code:

1. A &T reference can be released to safe code and there it can co-exit with other &T references, but not with a &mut T

2. A &mut T reference may be released to safe code, provided neither other &mut T nor &T co-exist with it. A &mut T must always be unique.

[nikomatsakis]

@NovemberZulu I like it quite a lot

[NovemberZulu]

Updated the pull request. I feel the transition between old and new text is bit rough. Comments are welcome!

[pietroalbini]

Ping from triage @steveklabnik! The author pushed new commits, could you review them?

[steveklabnik]

I think it reads great, thanks!

@bors: r+ rollup

[bors]

📌 Commit 55be283 has been approved by steveklabnik

[NovemberZulu]

Everyone, thank you very much for your support!