Add documentation about the memory layout of UnsafeCell<T>

[Pointerbender]

The documentation for UnsafeCell<T> currently does not make any promises about its memory layout. This PR adds this documentation, namely that the memory layout of UnsafeCell<T> is the same as the memory layout of its inner T.

Use case

Without this layout promise, the following cast would not be legally possible:

fn example<T>(ptr: *mut T) -> *const UnsafeCell<T> {
  ptr as *const UnsafeCell<T>
}

A use case where this can come up involves FFI. If Rust receives a pointer over a FFI boundary which provides shared read-write access (with some form of custom synchronization), and this pointer is managed by some Rust struct with lifetime 'a, then it would greatly simplify its (internal) API and safety contract if a &'a UnsafeCell<T> can be created from a raw FFI pointer *mut T. A lot of safety checks can be done when receiving the pointer for the first time through FFI (non-nullness, alignment, initialize uninit bytes, etc.) and these properties can then be encoded into the &UnsafeCell<T> type. Without this documentation guarantee, this is not legal today outside of the standard library.

Caveats

Casting in the opposite direction is still not valid, even with this documentation change:

fn example2<T>(ptr: &UnsafeCell<T>) -> &mut T {
  let t = ptr as *const UnsafeCell<T> as *mut T;
  unsafe { &mut *t }
}

This is because the only legal way to obtain a mutable pointer to the contents of the shared reference is through UnsafeCell::get and UnsafeCell::raw_get. Although there might be a desire to also make this legal at some point in the future, that part is outside the scope of this PR. Also see this relevant Zulip thread.

Alternatives

Instead of adding a new documentation promise, it's also possible to add a new method to UnsafeCell<T> with signature pub fn from_ptr_bikeshed(ptr: *mut T) -> *const UnsafeCell<T> which indirectly only allows one-way casting to *const UnsafeCell<T>.

[rustbot]

Hey! It looks like you've submitted a new PR for the library teams!

If this PR contains changes to any rust-lang/rust public library APIs then please comment with @rustbot label +T-libs-api -T-libs to tag it appropriately. If this PR contains changes to any unstable APIs please edit the PR description to add a link to the relevant API Change Proposal or create one if you haven't already. If you're unsure where your change falls no worries, just leave it as is and the reviewer will take a look and make a decision to forward on if necessary.

Examples of T-libs-api changes:

• Stabilizing library features
• Introducing insta-stable changes such as new implementations of existing stable traits on existing stable types
• Introducing new or changing existing unstable library APIs (excluding permanently unstable features / features without a tracking issue)
• Changing public documentation in ways that create new stability guarantees
• Changing observable runtime behavior of library APIs

[rust-highfive]

r? @Mark-Simulacrum

(rust-highfive has picked a reviewer for you, use r? to override)

[m-ou-se]

@rfcbot merge

[rfcbot]

Team member @m-ou-se has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se
• @yaahc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[Pointerbender]

Just a gentle little nudge: this (small) documentation PR needs only 1 more approval from either @Amanieu, @joshtriplett or @yaahc to start the FCP :) If there is any further feedback I could address in the mean time, please let me know! ❤️

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[Amanieu]

LGTM.

On a somewhat unrelated note, should the documentation also mention the fact that UnsafeCell disables enum niche optimizations? For example Option<UnsafeCell<NonNull<u8>> is 16 bytes instead of 8. This is intentional for safety reasons (#68491, #87341).

[Pointerbender]

@Amanieu @RalfJung Thanks for the feedback! I will update the PR by tomorrow to incorporate both your suggestions 👍

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[Amanieu]

@bors r+ rollup

[bors]

📌 Commit ddd119b has been approved by Amanieu

It is now in the queue for this repository.

[RalfJung]

I still find the last two sentences very confusing. They have nothing to do with the rest of the paragraph, do they? And the examples have nothing to do with the 90% of the paragraph that talk about the by-value representation of UnsafeCell<T>.

There are two rather unrelated things mixed up between this paragraph and the examples:

• the by-value layout of UnsafeCell<T>
• some aspect of the interior mutability rules and how to get a mutable ptr to a shared reference to an UnsafeCell

We should have a paragraph and examples only about the first point.

And then maybe another paragraph and examples only about the 2nd point (which is not a new point, it just was not fully explicit so far).

[RalfJung]

@bors r-
the writing is still confusing and needs improving IMO (as I had said 10 days ago already)

[RalfJung]

Ah this will probably land because it is rolled up.

@Pointerbender please make a follow-up PR that fixes the writing issues here.