Skip to content

Commit

Permalink
Rollup merge of rust-lang#52508 - joshtriplett:dangling-not-sentinel,…
Browse files Browse the repository at this point in the history
… r=Mark-Simulacrum

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.
  • Loading branch information
kennytm committed Jul 21, 2018
2 parents 51f50ad + ce75632 commit 3c66e8b
Showing 1 changed file with 10 additions and 0 deletions.
10 changes: 10 additions & 0 deletions src/libcore/ptr.rs
Original file line number Diff line number Diff line change
Expand Up @@ -2716,6 +2716,11 @@ impl<T: Sized> Unique<T> {
///
/// 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 {
Expand Down Expand Up @@ -2847,6 +2852,11 @@ impl<T: Sized> NonNull<T> {
///
/// 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 {
Expand Down

0 comments on commit 3c66e8b

Please sign in to comment.