Rollup merge of #59130 - RalfJung:non-null, r=rkruppe

Note that NonNull does not launder shared references for mutation

See https://users.rust-lang.org/t/relative-pointer-an-abstraction-to-build-movable-self-referential-types/26186/6

1 files changed, 10 insertions, 0 deletions

diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs
index d288ca449df..a9a029d606d 100644
--- a/src/libcore/ptr.rs
+++ b/src/libcore/ptr.rs
@@ -2874,6 +2874,16 @@ impl<'a, T: ?Sized> From<NonNull<T>> for Unique<T> {
 /// Usually this won't be necessary; covariance is correct for most safe abstractions,
 /// such as Box, Rc, Arc, Vec, and LinkedList. This is the case because they
 /// provide a public API that follows the normal shared XOR mutable rules of Rust.
+///
+/// Notice that `NonNull<T>` has a `From` instance for `&T`. However, this does
+/// not change the fact that mutating through a (pointer derived from a) shared
+/// reference is undefined behavior unless the mutation happens inside an
+/// [`UnsafeCell<T>`]. The same goes for creating a mutable reference from a shared
+/// reference. When using this `From` instance without an `UnsafeCell<T>`,
+/// it is your responsibility to ensure that `as_mut` is never called, and `as_ptr`
+/// is never used for mutation.
+///
+/// [`UnsafeCell<T>`]: ../cell/struct.UnsafeCell.html
 #[stable(feature = "nonnull", since = "1.25.0")]
 #[repr(transparent)]
 #[rustc_layout_scalar_valid_range_start(1)]