diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index a11f9e8c14579..0f1af8be850ae 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -1619,10 +1619,8 @@ impl Weak { /// Returns a raw pointer to the object `T` pointed to by this `Weak`. /// - /// It is up to the caller to ensure that the object is still alive when accessing it through - /// the pointer. - /// - /// The pointer may be [`null`] or be dangling in case the object has already been destroyed. + /// The pointer is valid only if there are some strong references. The pointer may be dangling + /// or even [`null`] otherwise. /// /// # Examples /// @@ -1702,14 +1700,18 @@ impl Weak { /// This can be used to safely get a strong reference (by calling [`upgrade`] /// later) or to deallocate the weak count by dropping the `Weak`. /// - /// It takes ownership of one weak count. In case a [`null`] is passed, a dangling [`Weak`] is - /// returned. + /// It takes ownership of one weak count (with the exception of pointers created by [`new`], + /// as these don't have any corresponding weak count). /// /// # Safety /// - /// The pointer must represent one valid weak count. In other words, it must point to `T` which - /// is or *was* managed by an [`Rc`] and the weak count of that [`Rc`] must not have reached - /// 0. It is allowed for the strong count to be 0. + /// The pointer must have originated from the [`into_raw`] (or [`as_raw`], provided there was + /// a corresponding [`forget`] on the `Weak`) and must still own its potential weak reference + /// count. + /// + /// It is allowed for the strong count to be 0 at the time of calling this, but the weak count + /// must be non-zero or the pointer must have originated from a dangling `Weak` (one created + /// by [`new`]). /// /// # Examples /// @@ -1734,11 +1736,13 @@ impl Weak { /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); /// ``` /// - /// [`null`]: ../../std/ptr/fn.null.html /// [`into_raw`]: struct.Weak.html#method.into_raw /// [`upgrade`]: struct.Weak.html#method.upgrade /// [`Rc`]: struct.Rc.html /// [`Weak`]: struct.Weak.html + /// [`as_raw`]: struct.Weak.html#method.as_raw + /// [`new`]: struct.Weak.html#method.new + /// [`forget`]: ../../std/mem/fn.forget.html #[unstable(feature = "weak_into_raw", issue = "60728")] pub unsafe fn from_raw(ptr: *const T) -> Self { if ptr.is_null() { diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs index 4b10f089c2950..be2d127b133d0 100644 --- a/src/liballoc/sync.rs +++ b/src/liballoc/sync.rs @@ -1295,10 +1295,8 @@ impl Weak { /// Returns a raw pointer to the object `T` pointed to by this `Weak`. /// - /// It is up to the caller to ensure that the object is still alive when accessing it through - /// the pointer. - /// - /// The pointer may be [`null`] or be dangling in case the object has already been destroyed. + /// The pointer is valid only if there are some strong references. The pointer may be dangling + /// or even [`null`] otherwise. /// /// # Examples /// @@ -1379,14 +1377,18 @@ impl Weak { /// This can be used to safely get a strong reference (by calling [`upgrade`] /// later) or to deallocate the weak count by dropping the `Weak`. /// - /// It takes ownership of one weak count. In case a [`null`] is passed, a dangling [`Weak`] is - /// returned. + /// It takes ownership of one weak count (with the exception of pointers created by [`new`], + /// as these don't have any corresponding weak count). /// /// # Safety /// - /// The pointer must represent one valid weak count. In other words, it must point to `T` which - /// is or *was* managed by an [`Arc`] and the weak count of that [`Arc`] must not have reached - /// 0. It is allowed for the strong count to be 0. + /// The pointer must have originated from the [`into_raw`] (or [`as_raw'], provided there was + /// a corresponding [`forget`] on the `Weak`) and must still own its potential weak reference + /// count. + /// + /// It is allowed for the strong count to be 0 at the time of calling this, but the weak count + /// must be non-zero or the pointer must have originated from a dangling `Weak` (one created + /// by [`new`]). /// /// # Examples /// @@ -1411,11 +1413,13 @@ impl Weak { /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); /// ``` /// - /// [`null`]: ../../std/ptr/fn.null.html + /// [`as_raw`]: struct.Weak.html#method.as_raw + /// [`new`]: struct.Weak.html#method.new /// [`into_raw`]: struct.Weak.html#method.into_raw /// [`upgrade`]: struct.Weak.html#method.upgrade /// [`Weak`]: struct.Weak.html /// [`Arc`]: struct.Arc.html + /// [`forget`]: ../../std/mem/fn.forget.html #[unstable(feature = "weak_into_raw", issue = "60728")] pub unsafe fn from_raw(ptr: *const T) -> Self { if ptr.is_null() {