UnsafePinned: update get() docs and signature to allow shared mutation #142162
Conversation
|
rustbot has assigned @workingjubilee. Use |
rustbot
added
S-waiting-on-review
| /// This can be cast to a pointer of any kind. | ||
| /// Ensure that the access is unique (no active references, mutable or not) | ||
| /// when casting to `&mut T`, and ensure that there are no mutations | ||
| /// or mutable aliases going on when casting to `&T`. |
There was a problem hiding this comment.
Nit. This would be better, I'd suggest, mechanically wrapped.
There was a problem hiding this comment.
I personally prefer semantic linebreaks, since the primary way this will be read is in the actual compiled documentation form and so the internal format of our docs is best-off organized around tracking history.
I don't usually quibble much over it though.
There was a problem hiding this comment.
We use auto-wrapping almost everywhere, and semantic wrapping doesn't go well with out 100 column limit, so I think I'll re-wrap this.
| /// when casting to `&mut T`, and ensure that there are no mutations | ||
| /// or mutable aliases going on when casting to `&T`. |
There was a problem hiding this comment.
I'd suggest wording here along the lines of "...ensure that there are no ongoing mutations or live mutable references when casting to &T."
There was a problem hiding this comment.
FWIW this paragraph is copied verbatim from UnsafeCell::get. I was hoping we could just reuse it without spending a lot of time on editing.^^
| /// Ensure that the access is unique (no active references, mutable or not) | ||
| /// when casting to `&mut T`, and ensure that there are no mutations |
There was a problem hiding this comment.
Since the second half of this, about casting to &T, makes note about ensuring there are no ongoing foreign writes (i.e. even if no active references exist), perhaps the first half should as well, since I'd expect casting to &mut T to have this same precondition.
| /// when casting to `&mut T`, and ensure that there are no mutations | ||
| /// or mutable aliases going on when casting to `&T`. | ||
| /// | ||
| /// All the usual caveats around mutation shared state apply, see [`UnsafeCell`]. |
There was a problem hiding this comment.
| /// All the usual caveats around mutation shared state apply, see [`UnsafeCell`]. | |
| /// All the usual caveats around mutation of shared state apply, see [`UnsafeCell`]. |
| /// This can be cast to a pointer of any kind. | ||
| /// Ensure that the access is unique (no active references, mutable or not) | ||
| /// when casting to `&mut T`, and ensure that there are no mutations | ||
| /// or mutable aliases going on when casting to `&T`. |
There was a problem hiding this comment.
I wonder if we can apply the deduplicating technique of #141609 or if it's even worth it here? Probably not, it's just a few lines.
|
I've replaced the paragraph in question with a reference to the |
Follow-up to #140638, making
getconsistent with the fact that there's anUnsafeCellinside this type now by returning*mut Tinstead of*const T.Cc @rust-lang/libs-api
Tracking issue: #125735