Struct MaybeDangling

struct MaybeDangling<P: ?Sized>(_)

Allows wrapped references and boxes to dangle.

This type is not properly implemented yet, and the documentation below is thus not accurate.

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)]
# use std::alloc::{dealloc, Layout};
# use std::mem;

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)]
# use std::alloc::{dealloc, Layout};
# use std::mem::{self, MaybeDangling};

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: ?Sized> MaybeDangling<P>

const fn new(x: P) -> Self
where
    P: Sized

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

const fn as_ref(self: &Self) -> &P

Returns a reference to the inner value.

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

const fn as_mut(self: &mut Self) -> &mut P

Returns a mutable reference to the inner value.

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

const fn into_inner(self: Self) -> P
where
    P: Sized

Extracts the value from the MaybeDangling container.

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

impl<P> Freeze for MaybeDangling<P>

impl<P> RefUnwindSafe for MaybeDangling<P>

impl<P> Send for MaybeDangling<P>

impl<P> Sync for MaybeDangling<P>

impl<P> Unpin for MaybeDangling<P>

impl<P> UnsafeUnpin for MaybeDangling<P>

impl<P> UnwindSafe for MaybeDangling<P>

impl<P: $crate::clone::Clone + ?Sized> Clone for MaybeDangling<P>

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

impl<P: $crate::default::Default + ?Sized> Default for MaybeDangling<P>

fn default() -> MaybeDangling<P>

impl<P: $crate::fmt::Debug + ?Sized> Debug for MaybeDangling<P>

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

impl<P: $crate::marker::Copy + ?Sized> Copy for MaybeDangling<P>

impl<T> Any for MaybeDangling<P>

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for MaybeDangling<P>

fn borrow(self: &Self) -> &T

impl<T> BorrowMut for MaybeDangling<P>

fn borrow_mut(self: &mut Self) -> &mut T

impl<T> CloneToUninit for MaybeDangling<P>

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

impl<T> From for MaybeDangling<P>

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for MaybeDangling<P>

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

impl<T, U> TryFrom for MaybeDangling<P>

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

impl<T, U> TryInto for MaybeDangling<P>

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>