Struct MaybeDangling 

pub struct MaybeDangling<P>(/* private fields */)
where
    P: ?Sized;

🔬This is a nightly-only experimental API. (maybe_dangling)

Available on crate features crypto and std only.

Allows wrapped references and boxes to dangle.

That is, if a reference (or a Box) is wrapped in MaybeDangling (including when in a (nested) field of a compound type wrapped in MaybeDangling), it does not have to follow pointer aliasing rules or be dereferenceable.

This can be useful when the value can become dangling while the function holding it is still executing (particularly in concurrent code). As a somewhat absurd example, consider this code:

#![feature(box_as_ptr)]

let mut boxed = Box::new(0_u32);
let ptr = Box::as_mut_ptr(&mut boxed);

// Safety: the pointer comes from a box and thus was allocated before; `box` is not used afterwards
unsafe { dealloc(ptr.cast(), Layout::new::<u32>()) };

mem::forget(boxed); // <-- this is UB!

Even though the Box’s destructor is not run (and thus we don’t have a double free bug), this code is still UB. This is because when moving boxed into forget, its validity invariants are asserted, causing UB since the Box is dangling. The safety comment is as such wrong, as moving the boxed variable as part of the forget call is a use.

To fix this we could use MaybeDangling:

#![feature(maybe_dangling, box_as_ptr)]

let mut boxed = MaybeDangling::new(Box::new(0_u32));
let ptr = Box::as_mut_ptr(boxed.as_mut());

// Safety: the pointer comes from a box and thus was allocated before; `box` is not used afterwards
unsafe { dealloc(ptr.cast(), Layout::new::<u32>()) };

mem::forget(boxed); // <-- this is OK!

Note that the bit pattern must still be valid for the wrapped type. That is, references (and boxes) still must be aligned and non-null.

Additionally note that safe code can still assume that the inner value in a MaybeDangling is not dangling – functions like as_ref and into_inner are safe. It is not sound to return a dangling reference in a MaybeDangling to safe code. However, it is sound to hold such values internally inside your code – and there’s no way to do that without this type. Note that other types can use this type and thus get the same effect; in particular, ManuallyDrop will use MaybeDangling.

Note that MaybeDangling doesn’t prevent drops from being run, which can lead to UB if the drop observes a dangling value. If you need to prevent drops from being run use ManuallyDrop instead.

Implementations

impl<P> MaybeDangling<P>

where P: ?Sized,

pub const fn new(x: P) -> MaybeDangling<P>

🔬This is a nightly-only experimental API. (maybe_dangling)

Available on crate feature rustls only.

Wraps a value in a MaybeDangling, allowing it to dangle.

pub const fn as_ref(&self) -> &P

🔬This is a nightly-only experimental API. (maybe_dangling)

Available on crate feature rustls only.

Returns a reference to the inner value.

Note that this is UB if the inner value is currently dangling.

pub const fn as_mut(&mut self) -> &mut P

🔬This is a nightly-only experimental API. (maybe_dangling)

Available on crate feature rustls only.

Returns a mutable reference to the inner value.

Note that this is UB if the inner value is currently dangling.

pub const fn into_inner(self) -> P

🔬This is a nightly-only experimental API. (maybe_dangling)

Available on crate feature rustls only.

Extracts the value from the MaybeDangling container.

Note that this is UB if the inner value is currently dangling.

Trait Implementations

impl<P> Clone for MaybeDangling<P>

where P: Clone + ?Sized,

fn clone(&self) -> MaybeDangling<P>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<P> Debug for MaybeDangling<P>

where P: Debug + ?Sized,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<P> Default for MaybeDangling<P>

where P: Default + ?Sized,

fn default() -> MaybeDangling<P>

Returns the “default value” for a type.

impl<P> Copy for MaybeDangling<P>

where P: Copy + ?Sized,

impl<T> StructuralPartialEq for MaybeDangling<T>

where T: ?Sized,