From 64e7337be596cb12aa8c7f593a1fe5d17ab089ca Mon Sep 17 00:00:00 2001 From: Ralf Jung Date: Tue, 4 Jun 2024 07:37:24 +0200 Subject: [PATCH] more explicitly state the basic rules of working with the obtained raw pointers --- library/core/src/ptr/mod.rs | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs index f1a1b1a41493..c6af6617bab7 100644 --- a/library/core/src/ptr/mod.rs +++ b/library/core/src/ptr/mod.rs @@ -779,6 +779,15 @@ where /// /// For `r: &T`, `from_ref(r)` is equivalent to `r as *const T`, but is a bit safer since it will /// never silently change type or mutability, in particular if the code is refactored. +/// +/// The caller must ensure that the pointee outlives the pointer this function returns, or else it +/// will end up pointing to garbage. +/// +/// The caller must also ensure that the memory the pointer (non-transitively) points to is never +/// written to (except inside an `UnsafeCell`) using this pointer or any pointer derived from it. If +/// you need to mutate the pointee, use [`from_mut`]`. Specifically, to turn a mutable reference `m: +/// &mut T` into `*const T`, prefer `from_mut(m).cast_const()` to obtain a pointer that can later be +/// used for mutation. #[inline(always)] #[must_use] #[stable(feature = "ptr_from_ref", since = "1.76.0")] @@ -791,6 +800,9 @@ pub const fn from_ref(r: &T) -> *const T { /// Convert a mutable reference to a raw pointer. /// +/// The caller must ensure that the pointee outlives the pointer this function returns, or else it +/// will end up pointing to garbage. +/// /// For `r: &mut T`, `from_mut(r)` is equivalent to `r as *mut T`, but is a bit safer since it will /// never silently change type or mutability, in particular if the code is refactored. #[inline(always)]