rust-lang / rust-lang/rust

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

Open
#157,544 12 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-docs T-libs T-opsem
Dominant language
Rust
Stars
119k
Forks
16.1k
PR merge metrics
PR metrics pending

Description

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

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the UnsafeCell documentation at the linked std/cell/struct.UnsafeCell.html page, then compare its guidance with Cell::as_slice_of_cells() and the referenced unsafe-code-guidelines issue 455. Clarify which immutable-reference and slice casts are sound, and document the relevant safety caveats; the work is done when the page explicitly addresses the listed questions.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.