MaybeDangling in core::mem - Rust
Description: Allows wrapped references and boxes to dangle.

## MaybeDangling

# Struct MaybeDangling

Source

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

🔬This is a nightly-only experimental API. (`maybe_dangling` #118166)
Expand description

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)]

    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`e’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§

Source§

### impl<P: ?Sized> MaybeDangling<P>

Source

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

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

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

Source

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

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

Returns a reference to the inner value.

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

Source

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

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

Returns a mutable reference to the inner value.

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

Source

#### pub const fn into_inner(self) -> P
where P: Sized,

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

Extracts the value from the `MaybeDangling` container.

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

## Trait Implementations§

Source§

### impl<P: Clone + ?Sized> Clone for MaybeDangling<P>

Source§

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

Returns a duplicate of the value. Read more
1.0.0 · Source§

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

Performs copy-assignment from `source`. Read more
Source§

### impl<P: Debug + ?Sized> Debug for MaybeDangling<P>

Source§

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

Formats the value using the given formatter. Read more
Source§

### impl<P: Default + ?Sized> Default for MaybeDangling<P>

Source§

#### fn default() -> MaybeDangling<P>

Returns the “default value” for a type. Read more
Source§

### impl<P: Copy + ?Sized> Copy for MaybeDangling<P>

## Auto Trait Implementations§

§

### impl<P> Freeze for MaybeDangling<P>
where P: Freeze + ?Sized,

§

### impl<P> RefUnwindSafe for MaybeDangling<P>
where P: RefUnwindSafe + ?Sized,

§

### impl<P> Send for MaybeDangling<P>
where P: Send + ?Sized,

§

### impl<P> Sync for MaybeDangling<P>
where P: Sync + ?Sized,

§

### impl<P> Unpin for MaybeDangling<P>
where P: Unpin + ?Sized,

§

### impl<P> UnwindSafe for MaybeDangling<P>
where P: UnwindSafe + ?Sized,

## Blanket Implementations§

Source§

### impl<T> Any for T
where T: 'static + ?Sized,

Source§

#### fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`. Read more
Source§

### impl<T> Borrow<T> for T
where T: ?Sized,

Source§

#### fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

### impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

#### fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

### impl<T> CloneToUninit for T
where T: Clone,

Source§

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

🔬This is a nightly-only experimental API. (`clone_to_uninit` #126799)
Performs copy-assignment from `self` to `dest`. Read more
Source§

### impl<T> From<T> for T

Source§

#### fn from(t: T) -> T

Returns the argument unchanged.

Source§

### impl<T, U> Into<U> for T
where U: From<T>,

Source§

#### fn into(self) -> U

Calls `U::from(self)`.

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

Source§

### impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

#### type Error = Infallible

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.
Source§

### impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

#### type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

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

Performs the conversion.