From ce756321ba888c7701cb81febd1de2bd98f87724 Mon Sep 17 00:00:00 2001 From: Josh Triplett Date: Wed, 18 Jul 2018 12:50:13 -0700 Subject: [PATCH] Document that Unique::empty() and NonNull::dangling() aren't sentinel values The documentation of Unique::empty() and NonNull::dangling() could potentially suggest that they work as sentinel values indicating a not-yet-initialized pointer. However, they both declare a non-null pointer equal to the alignment of the type, which could potentially reference a valid value of that type (specifically, the first such valid value in memory). Explicitly document that the return value of these functions does not work as a sentinel value. --- src/libcore/ptr.rs | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/src/libcore/ptr.rs b/src/libcore/ptr.rs index 0af642258c2..d8e061496d9 100644 --- a/src/libcore/ptr.rs +++ b/src/libcore/ptr.rs @@ -2703,6 +2703,11 @@ impl Unique { /// /// This is useful for initializing types which lazily allocate, like /// `Vec::new` does. + /// + /// Note that the pointer value may potentially represent a valid pointer to + /// a `T`, which means this must not be used as a "not yet initialized" + /// sentinel value. Types that lazily allocate must track initialization by + /// some other means. // FIXME: rename to dangling() to match NonNull? pub const fn empty() -> Self { unsafe { @@ -2834,6 +2839,11 @@ impl NonNull { /// /// This is useful for initializing types which lazily allocate, like /// `Vec::new` does. + /// + /// Note that the pointer value may potentially represent a valid pointer to + /// a `T`, which means this must not be used as a "not yet initialized" + /// sentinel value. Types that lazily allocate must track initialization by + /// some other means. #[stable(feature = "nonnull", since = "1.25.0")] pub fn dangling() -> Self { unsafe {