maybe_dangling.rs - source
Description: Source of the Rust file `library/core/src/mem/maybe_dangling.rs`.

#
core/mem/
maybe_dangling.rs

    1#![unstable(feature = "maybe_dangling", issue = "118166")]
    2
    3use crate::{mem, ptr};
    4
    5/// Allows wrapped [references] and [boxes] to dangle.
    6///
    7/// <section class="warning">
    8/// This type is not properly implemented yet, and the documentation below is thus not accurate.
    9/// </section>
    10///
    11/// That is, if a reference (or a `Box`) is wrapped in `MaybeDangling` (including when in a
    12/// (nested) field of a compound type wrapped in `MaybeDangling`), it does not have to follow
    13/// pointer aliasing rules or be dereferenceable.
    14///
    15/// This can be useful when the value can become dangling while the function holding it is still
    16/// executing (particularly in concurrent code). As a somewhat absurd example, consider this code:
    17///
    18/// ```rust,no_run
    19/// #![feature(box_as_ptr)]
    20/// # use std::alloc::{dealloc, Layout};
    21/// # use std::mem;
    22///
    23/// let mut boxed = Box::new(0_u32);
    24/// let ptr = Box::as_mut_ptr(&mut boxed);
    25///
    26/// // Safety: the pointer comes from a box and thus was allocated before; `box` is not used afterwards
    27/// unsafe { dealloc(ptr.cast(), Layout::new::<u32>()) };
    28///
    29/// mem::forget(boxed); // <-- this is UB!
    30/// ```
    31///
    32/// Even though the `Box`e's destructor is not run (and thus we don't have a double free bug), this
    33/// code is still UB. This is because when moving `boxed` into `forget`, its validity invariants
    34/// are asserted, causing UB since the `Box` is dangling. The safety comment is as such wrong, as
    35/// moving the `boxed` variable as part of the `forget` call *is* a use.
    36///
    37/// To fix this we could use `MaybeDangling`:
    38///
    39// FIXME: remove `no_run` once the semantics are actually implemented
    40/// ```rust,no_run
    41/// #![feature(maybe_dangling, box_as_ptr)]
    42/// # use std::alloc::{dealloc, Layout};
    43/// # use std::mem::{self, MaybeDangling};
    44///
    45/// let mut boxed = MaybeDangling::new(Box::new(0_u32));
    46/// let ptr = Box::as_mut_ptr(boxed.as_mut());
    47///
    48/// // Safety: the pointer comes from a box and thus was allocated before; `box` is not used afterwards
    49/// unsafe { dealloc(ptr.cast(), Layout::new::<u32>()) };
    50///
    51/// mem::forget(boxed); // <-- this is OK!
    52/// ```
    53///
    54/// Note that the bit pattern must still be valid for the wrapped type. That is, [references]
    55/// (and [boxes]) still must be aligned and non-null.
    56///
    57/// Additionally note that safe code can still assume that the inner value in a `MaybeDangling` is
    58/// **not** dangling -- functions like [`as_ref`] and [`into_inner`] are safe. It is not sound to
    59/// return a dangling reference in a `MaybeDangling` to safe code. However, it *is* sound
    60/// to hold such values internally inside your code -- and there's no way to do that without
    61/// this type. Note that other types can use this type and thus get the same effect; in particular,
    62/// [`ManuallyDrop`] will use `MaybeDangling`.
    63///
    64/// Note that `MaybeDangling` doesn't prevent drops from being run, which can lead to UB if the
    65/// drop observes a dangling value. If you need to prevent drops from being run use [`ManuallyDrop`]
    66/// instead.
    67///
    68/// [references]: prim@reference
    69/// [boxes]: ../../std/boxed/struct.Box.html
    70/// [`into_inner`]: MaybeDangling::into_inner
    71/// [`as_ref`]: MaybeDangling::as_ref
    72/// [`ManuallyDrop`]: crate::mem::ManuallyDrop
    73#[repr(transparent)]
    74#[rustc_pub_transparent]
    75#[derive(Debug, Copy, Clone, Default)]
    76pub struct MaybeDangling<P: ?Sized>(P);
    77
    78impl<P: ?Sized> MaybeDangling<P> {
    79    /// Wraps a value in a `MaybeDangling`, allowing it to dangle.
    80    pub const fn new(x: P) -> Self
    81    where
    82        P: Sized,
    83    {
    84        MaybeDangling(x)
    85    }
    86
    87    /// Returns a reference to the inner value.
    88    ///
    89    /// Note that this is UB if the inner value is currently dangling.
    90    pub const fn as_ref(&self) -> &P {
    91        &self.0
    92    }
    93
    94    /// Returns a mutable reference to the inner value.
    95    ///
    96    /// Note that this is UB if the inner value is currently dangling.
    97    pub const fn as_mut(&mut self) -> &mut P {
    98        &mut self.0
    99    }
    100
    101    /// Extracts the value from the `MaybeDangling` container.
    102    ///
    103    /// Note that this is UB if the inner value is currently dangling.
    104    pub const fn into_inner(self) -> P
    105    where
    106        P: Sized,
    107    {
    108        // FIXME: replace this with `self.0` when const checker can figure out that `self` isn't actually dropped
    109        // SAFETY: this is equivalent to `self.0`
    110        let x = unsafe { ptr::read(&self.0) };
    111        mem::forget(self);
    112        x
    113    }
    114}