From f52505204d1e442b302a3f428937c6d46473fbff Mon Sep 17 00:00:00 2001 From: LemonJ <1632798336@qq.com> Date: Tue, 25 Mar 2025 10:52:43 +0800 Subject: [PATCH 1/2] fix missing safety in as_mut --- library/core/src/ptr/mut_ptr.rs | 16 ++++++++++------ library/core/src/ptr/non_null.rs | 16 +++++++++++----- 2 files changed, 21 insertions(+), 11 deletions(-) diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index b960a3d86bef0..b839cf70c48f9 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -593,19 +593,21 @@ impl *mut T { } /// Returns `None` if the pointer is null, or else returns a unique reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_mut`] - /// must be used instead. + /// the value wrapped in `Some`. /// /// For the shared counterpart see [`as_ref`]. /// - /// [`as_uninit_mut`]: #method.as_uninit_mut /// [`as_ref`]: pointer#method.as_ref-1 /// /// # Safety /// - /// When calling this method, you have to ensure that *either* - /// the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * *Either* the pointer is null *or* the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_mut`] must be used instead. + /// + /// * Note that multiple calls to this API may create multiple mutable references simultaneously, violating the exclusive mutable reference principle. /// /// # Panics during const evaluation /// @@ -614,6 +616,8 @@ impl *mut T { /// /// [`is_null`]: #method.is_null-1 /// + /// [`as_uninit_mut`]: #method.as_uninit_mut + /// /// # Examples /// /// ``` diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs index c769ba673c61e..cef664409a7aa 100644 --- a/library/core/src/ptr/non_null.rs +++ b/library/core/src/ptr/non_null.rs @@ -428,18 +428,24 @@ impl NonNull { unsafe { &*self.as_ptr().cast_const() } } - /// Returns a unique reference to the value. If the value may be uninitialized, [`as_uninit_mut`] - /// must be used instead. + /// Returns a unique reference to the value. /// /// For the shared counterpart see [`as_ref`]. /// - /// [`as_uninit_mut`]: NonNull::as_uninit_mut /// [`as_ref`]: NonNull::as_ref /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_mut`] must be used instead. + /// + /// * Note that multiple calls to this API may create multiple mutable references simultaneously, violating the exclusive mutable reference principle. + /// + /// [`as_uninit_mut`]: NonNull::as_uninit_mut + /// /// # Examples /// /// ``` From 74c9c3b8c91da91c4314d612401b5f62bb36d875 Mon Sep 17 00:00:00 2001 From: LemonJ <1632798336@qq.com> Date: Tue, 25 Mar 2025 14:16:00 +0800 Subject: [PATCH 2/2] fix missing doc in as_ref --- library/core/src/ptr/mut_ptr.rs | 67 +++++++++++++++++++++----------- library/core/src/ptr/non_null.rs | 37 +++++++++++------- 2 files changed, 67 insertions(+), 37 deletions(-) diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs index b839cf70c48f9..4b86190d450fe 100644 --- a/library/core/src/ptr/mut_ptr.rs +++ b/library/core/src/ptr/mut_ptr.rs @@ -233,18 +233,22 @@ impl *mut T { } /// Returns `None` if the pointer is null, or else returns a shared reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. + /// the value wrapped in `Some`. /// /// For the mutable counterpart see [`as_mut`]. /// - /// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1 /// [`as_mut`]: #method.as_mut /// /// # Safety /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * *Either* the pointer is null *or* the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_ref`] must be used instead. + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). /// /// # Panics during const evaluation /// @@ -252,6 +256,7 @@ impl *mut T { /// determined to be null or not. See [`is_null`] for more information. /// /// [`is_null`]: #method.is_null-1 + /// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1 /// /// # Examples /// @@ -289,18 +294,25 @@ impl *mut T { } /// Returns a shared reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. /// /// For the mutable counterpart see [`as_mut_unchecked`]. /// - /// [`as_ref`]: #method.as_ref - /// [`as_uninit_ref`]: #method.as_uninit_ref /// [`as_mut_unchecked`]: #method.as_mut_unchecked /// /// # Safety /// - /// When calling this method, you have to ensure that the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. + /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). + /// + /// [`as_ref`]: #method.as_ref + /// [`as_uninit_ref`]: #method.as_uninit_ref /// /// # Examples /// @@ -332,10 +344,10 @@ impl *mut T { /// /// # Safety /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). - /// Note that because the created reference is to `MaybeUninit`, the - /// source pointer can point to uninitialized memory. + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). /// /// # Panics during const evaluation /// @@ -607,7 +619,8 @@ impl *mut T { /// /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_mut`] must be used instead. /// - /// * Note that multiple calls to this API may create multiple mutable references simultaneously, violating the exclusive mutable reference principle. + /// * Note that after obtaining the mutable reference, the original pointer + /// must not be used to access the data until the reference's lifetime ends. /// /// # Panics during const evaluation /// @@ -653,19 +666,25 @@ impl *mut T { } /// Returns a unique reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_mut`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_mut`] must be used instead. /// /// For the shared counterpart see [`as_ref_unchecked`]. /// - /// [`as_mut`]: #method.as_mut - /// [`as_uninit_mut`]: #method.as_uninit_mut /// [`as_ref_unchecked`]: #method.as_mut_unchecked /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * If the pointer may be null or the value may be uninitialized, [`as_uninit_mut`] must be used instead. + /// If the pointer may be null, but the value is known to have been initialized, [`as_mut`] must be used instead. + /// + /// * Note that after obtaining the mutable reference, the original pointer + /// must not be used to access the data until the reference's lifetime ends. + /// + /// [`as_mut`]: #method.as_mut + /// [`as_uninit_mut`]: #method.as_uninit_mut /// /// # Examples /// @@ -698,8 +717,10 @@ impl *mut T { /// /// # Safety /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the mutable reference, the original pointer must not + /// be used to access the data until the reference's lifetime ends. /// /// # Panics during const evaluation /// diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs index cef664409a7aa..a1c66a65e45ac 100644 --- a/library/core/src/ptr/non_null.rs +++ b/library/core/src/ptr/non_null.rs @@ -152,10 +152,11 @@ impl NonNull { /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). - /// Note that because the created reference is to `MaybeUninit`, the - /// source pointer can point to uninitialized memory. + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). + /// #[inline] #[must_use] #[unstable(feature = "ptr_as_uninit", issue = "75402")] @@ -175,10 +176,11 @@ impl NonNull { /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). - /// Note that because the created reference is to `MaybeUninit`, the - /// source pointer can point to uninitialized memory. + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * Note that after obtaining the mutable reference, the original pointer must not + /// be used to access the data until the reference's lifetime ends. + /// #[inline] #[must_use] #[unstable(feature = "ptr_as_uninit", issue = "75402")] @@ -391,18 +393,24 @@ impl NonNull { unsafe { mem::transmute::(self) } } - /// Returns a shared reference to the value. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. + /// Returns a shared reference to the value. /// /// For the mutable counterpart see [`as_mut`]. /// - /// [`as_uninit_ref`]: NonNull::as_uninit_ref /// [`as_mut`]: NonNull::as_mut /// /// # Safety /// - /// When calling this method, you have to ensure that - /// the pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// When calling this method, you have to ensure that: + /// + /// * The pointer is [convertible to a reference](crate::ptr#pointer-to-reference-conversion). + /// + /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_ref`] must be used instead. + /// + /// * Note that after obtaining the mutable reference, the original pointer must not + /// be mutated until the reference's lifetime ends (except inside `UnsafeCell`). + /// + /// [`as_uninit_ref`]: NonNull::as_uninit_ref /// /// # Examples /// @@ -442,7 +450,8 @@ impl NonNull { /// /// * The value of memory pointed by the ptr must be initialized. If not, [`as_uninit_mut`] must be used instead. /// - /// * Note that multiple calls to this API may create multiple mutable references simultaneously, violating the exclusive mutable reference principle. + /// * Note that after obtaining the mutable reference, the original pointer + /// must not be used to access the data until the reference's lifetime ends. /// /// [`as_uninit_mut`]: NonNull::as_uninit_mut ///