From b4c96a9199f13c5c1c2afa6258d2b9206c151d9f Mon Sep 17 00:00:00 2001 From: Lukas Lueg Date: Tue, 28 Jan 2020 22:28:13 +0100 Subject: [PATCH] Refine [Arc/Rc]::from_raw() docs --- src/liballoc/rc.rs | 18 +++++++++++++----- src/liballoc/sync.rs | 18 +++++++++++++----- 2 files changed, 26 insertions(+), 10 deletions(-) diff --git a/src/liballoc/rc.rs b/src/liballoc/rc.rs index 60a8e1714b6..1d2222adb9d 100644 --- a/src/liballoc/rc.rs +++ b/src/liballoc/rc.rs @@ -570,16 +570,24 @@ pub fn into_raw(this: Self) -> *const T { ptr } - /// Constructs an `Rc` from a raw pointer. + /// Constructs an `Rc` from a raw pointer. /// - /// The raw pointer must have been previously returned by a call to a - /// [`Rc::into_raw`][into_raw] using the same `T`. + /// The raw pointer must have been previously returned by a call to + /// [`Rc::into_raw`][into_raw] where `U` must have the same size + /// and alignment as `T`. This is trivially true if `U` is `T`. + /// Note that if `U` is not `T` but has the same size and alignment, this is + /// basically like transmuting references of different types. See + /// [`mem::transmute`][transmute] for more information on what + /// restrictions apply in this case. + /// + /// The user of `from_raw` has to make sure a specific value of `T` is only + /// dropped once. /// /// This function is unsafe because improper use may lead to memory unsafety, - /// even if `T` is never accessed. For example, a double-free may occur if the function is - /// called twice on the same raw pointer. + /// even if the returned `Rc` is never accessed. /// /// [into_raw]: struct.Rc.html#method.into_raw + /// [transmute]: ../../std/mem/fn.transmute.html /// /// # Examples /// diff --git a/src/liballoc/sync.rs b/src/liballoc/sync.rs index 024f9407604..f9c8da58c75 100644 --- a/src/liballoc/sync.rs +++ b/src/liballoc/sync.rs @@ -550,16 +550,24 @@ pub fn into_raw(this: Self) -> *const T { ptr } - /// Constructs an `Arc` from a raw pointer. + /// Constructs an `Arc` from a raw pointer. /// - /// The raw pointer must have been previously returned by a call to a - /// [`Arc::into_raw`][into_raw], using the same `T`. + /// The raw pointer must have been previously returned by a call to + /// [`Arc::into_raw`][into_raw] where `U` must have the same size and + /// alignment as `T`. This is trivially true if `U` is `T`. + /// Note that if `U` is not `T` but has the same size and alignment, this is + /// basically like transmuting references of different types. See + /// [`mem::transmute`][transmute] for more information on what + /// restrictions apply in this case. + /// + /// The user of `from_raw` has to make sure a specific value of `T` is only + /// dropped once. /// /// This function is unsafe because improper use may lead to memory unsafety, - /// even if `T` is never accessed. For example, a double-free may occur if the function is - /// called twice on the same raw pointer. + /// even if the returned `Arc` is never accessed. /// /// [into_raw]: struct.Arc.html#method.into_raw + /// [transmute]: ../../std/mem/fn.transmute.html /// /// # Examples /// -- 2.44.0