Clarify `&UnsafeCell<T>` → `&T` access

[kpreid]

Location (URL)

https://doc.rust-lang.org/stable/std/cell/struct.UnsafeCell.html

Summary

The documentation has extensive explanation of how to obtain and use an *mut T or &mut T from UnsafeCell<T> and use that pointer to mutate the cell. However, it says nothing explicitly about the means to, and the safety considerations of, obtaining &Ts which derive from and overlap with an &UnsafeCell<T>, or any other situations involving immutable references. For example, if one is working with bulk data, one might have these questions:

• Is it sound to cast &UnsafeCell<[T]> to &[UnsafeCell<T>]?

  The implementation of Cell::as_slice_of_cells() implies that it is, so it would be desirable to have the more general property documented.

• Is it sound to cast &[UnsafeCell<T>] to &UnsafeCell<[T]>?

• Is it sound to cast &[UnsafeCell<T>] to &[T], provided no mutation occurs while the reference is in use?

  UCG says this is not yet definitively OK because SB rejects it but the library documentation should at least explicitly caveat this.

@rustbot label +T-libs +T-opsem

[theemathas]

cc @RalfJung

[RalfJung]

I am quite confused by the questions since your introduction seems to raise an entirely different question than your three bullets later.

Regarding the question raised in the introduction: once you have an &mut T, you can turn it to an &T in the usual safe way.

Regarding the three bullets:

The first two are both safe, you're not "entering" the UnsafeCell. Suggestions for how to best document this are welcome.

The third is in the gray area of undecided aliasing model details. SB says it's UB, TB says it's fine. I think this is a bug in SB; TB is my preferred outcome here.

[kpreid]

@RalfJung I think you misread the introductory paragraph, but I can also see that I was not very clear; I have expanded it to make the intended topic clearer.

The question is not about starting with &mut or *mut, or using &mut or *mut at all; &mut was mentioned only for comparison, because the documentation covers the interactions of &mut and UnsafeCell very thoroughly. The point of the issue is that the documentation does not cover the interactions of &T with UnsafeCell<T>; it does not give any safety conditions, cautions, or recommended patterns.

I’m not primarily looking for getting edge cases nailed down, here, but for having at least some documentation of what considerations one must make when performing shared borrowing of memory that is within the bounds of an UnsafeCell.

[RalfJung]

You have to distinguish the interaction with &mut/& to the outside the UnsafeCell and with &mut/& to the inside the UnsafeCell .

For references to the outside, the docs mention both & and &mut extensively -- the latter mostly to explain that there are no interactions, &mut UnsafeCell<T> is basically the same as &mut T, you can not get out of the uniqueness of mutable references with an UnsafeCell.

For references to the inside, the only legal way to get a pointer to the "inside" is get (and get_raw). And then once you did that you can turn that raw pointer into a mutable reference or shared reference, whatever you need. We don't have special docs for either of these cases as far as I can tell? At this point "normal" raw pointer rules apply, nothing specific to UnsafeCell.

the documentation covers the interactions of &mut and UnsafeCell very thoroughly

So IOW, I don't know which part of the docs you are referring to here. The only long paragraph about &mut is about outside references (and we discuss outside shared references as well, in fact most of the docs talk about that case), but your question seems to be about inside references.

[kpreid]

For references to the inside, the only legal way to get a pointer to the "inside" is get (and get_raw). And then once you did that you can turn that raw pointer into a mutable reference or shared reference, whatever you need.

If the documentation contained the phrase “you can turn that … into a shared reference” that would be an improvement. As it is, when I scan the documentation, I find references to what I can do with an &T reference, but not how to create it:

If you create a safe reference with lifetime 'a (either a &T or &mut T reference), then you must not access the data in any way that contradicts that reference for the remainder of 'a.

and I find references to creating an &mut T reference, but not an &T reference:

Note that the only valid way to obtain a *mut T pointer to the contents of a shared UnsafeCell is through .get() or .raw_get(). A &mut T reference can be obtained by either dereferencing this pointer or by calling .get_mut() on an exclusive UnsafeCell.

but there is nothing that states explicitly that if I want an &T reference, I should be going through the *mut T (well, or calling the unstable .as_ref_unchecked()). It's possible to draw this conclusion by carefully reading the text and acting conservatively, but it's not easy. I think the documentation should make it easy to learn this fact.

This issue is not like a UCG issue where the main point is clarification of what the boundaries of sound code are; it is a request that the documentation be written to better introduce the reader to the space in which those boundaries are drawn, because it is not obvious.

[Morgane55440]

@kpreid

• Is it sound to cast &[UnsafeCell<T>] to &[T], provided no mutation occurs while the reference is in use?
  UCG says this is not yet definitively OK because SB rejects it but the library documentation should at least explicitly caveat this.

@RalfJung

The third is in the gray area of undecided aliasing model details. SB says it's UB, TB says it's fine. I think this is a bug in SB; TB is my preferred outcome here.

you seem to be mixing up concepts here, the issue is not &[UnsafeCell<T>] -> &[T], but &[T] -> &[UnsafeCell<T>].
this is actually not related to slices, simply to the concept of &T -> &UnsafeCell<T>, which SB does not like.
here is an example you can test under miri to see what exactly is happening

use std::cell::UnsafeCell;

fn good_as_long_as_no_mutation<T>(r : &[UnsafeCell<T>]) -> &[T] {
    unsafe {&*(r as *const [UnsafeCell<T>] as  *const [T])}
}

fn not_good_even_if_no_mutation<T>(r : &[T]) -> &[UnsafeCell<T>] {
    unsafe {&*(r as *const [T] as  *const [UnsafeCell<T>])}
}

fn main() {
    let arr = [const { UnsafeCell::new(0u32) } ;32]; 
    dbg!(good_as_long_as_no_mutation(arr.as_slice()).iter().sum::<u32>()); // not UB under any model

    let arr = [0u32 ;32];
    dbg!(not_good_even_if_no_mutation(arr.as_slice()).iter().map(|c| unsafe {*c.get()}).sum::<u32>()); // UB under stacked borrows
}

so your comment that is was not definitely ok is incorrect. both models consider &[UnsafeCell<T>] -> &[T] to be totally fine, it is treated the same as &UnsafeCell<T> -> &T, which is what as_ref_unchecked does.

the issue is with &[T] -> &[UnsafeCell<T>] (or more accurately &T -> &UnsafeCell<T>)under SB, is thatthe orignal pointer is SharedReadOnly (as it is an immutable reference), but it believes the output should unconditionally be SharedReadWrite (as it contains an UnsafeCell), which is it does not consider to be a valid retag.

the other way around is completely fine.

[RalfJung]

but there is nothing that states explicitly that if I want an &T reference

Sure, if you think it is helpful to say "an &T or &mut T reference" instead, we can add that. Do you want to make a PR? Seems like a very small change (though it needs a bit of rewording for that get_mut part).

It is very hard to predict which conclusions people find obvious and which are hard. It would be a bad use of space (and also often cause more confusion than it resolves) to list everything you can do with a mutable reference once you have it. So we have to figure out which of the many things one can do with mutable references are worth repeating here. Do we spell out that you can read and write via that reference? No, I hope we agree that that's obvious. Do we spell out that you can reborrow it? Also seems more confusing than helpful. Do we spell out that you can coerce it to a shared reference? Your feedback is that this would be helpful.

you seem to be mixing up concepts here, the issue is not &[UnsafeCell] -> &[T], but &[T] -> &[UnsafeCell].

Oh right the SB issue was the other way around.

But both directions are in the grey area of underspecified parts of the language.

[Morgane55440]

But both directions are in the grey area of underspecified parts of the language.

you said that &[UnsafeCell<T>] -> &UnsafeCell<[T]> is safe in your first message, and afaik as_ref_unchecked is not a gray area.

since &[UnsafeCell<T>] -> &[T] is simply a combination of both, so it seems to me that it should be as well defined as as_ref_unchecked is, unless the issue is does not go through get ?