unsafe_binders/

unsafe.rs

#![allow(unsafe_code)]
use ::core::{
    marker::PhantomData as PD,
    pin::Pin,
    ptr,
};
use ::maybe_dangling::{
    ManuallyDrop as MD,
};
use ::higher_kinded_types::{
    ForLt,
};
use crate::{
    DropMarker::{self, DropMarkerKind},
    ForLifetime,
};

pub trait Is {
    type ItSelf : ?Sized;
}

impl<T : ?Sized> Is for T {
    type ItSelf = Self;
}

trait NoAutoTraits {}

/// Stable rust polyfill of [`unsafe<'lt> …` binders](https://hackmd.io/@compiler-errors/HkXwoBPaR),
/// with a fixed arity of 1.
///
/// **Important note**: only use this _type_ name when wanting to access the associated functions.
/// Most notably, the [`Unsafe::wrap_binder…()`][`Unsafe::wrap_binder_manually_drop()`]
/// constructors.
///
/// Otherwise, the eponymous [`Unsafe![]`][`Unsafe!`] macro is to be used.
///
/// # Memory layout
///
/// This is a SemVer-guaranteed `#[repr(transparent)]` around its inner `T::Of<'_>` value.
///
/// ## Guarantees `unsafe` code may rely on
///
/// Given this, if you know that for some wrapper type `Coll`, `Coll<&'a str>` is sound to transmute
/// into `Coll<&'b str>`, for instance **because the `Coll` wrapper type makes guarantees about its
/// own layout and API based on that of the `<T>` generic type**, then it will be sound to transmute
/// an `&'a str`-stemming `Coll<Unsafe<_, T>>` into a `Coll<T::Of<'b>>`. And so on for other
/// `T::Of<'_>` lifetime-generic wrappee types.
///
///   - You should generally not need this, thanks to the various
///     [`Self::unwrap_binder…()`][`Self::unwrap_binder()`] APIs already exposed by this type.
///
///   - In any "sane wrapper type" case, the property required herein is met.
///
///     But a counter-example would be the following:
///
///     <details class="custom"><summary><span class="summary-box"><span>Click to show</span></span></summary>
///
///     ```rust ,no_run
///     # use ::unsafe_binders::prelude::*;
///     #
///     struct Helix<T: Shenanigans>(
///         <T as Shenanigans>::Assoc,
///     );
///
///     trait Shenanigans {
///         type Assoc;
///     }
///
///     impl Shenanigans for &str {
///         type Assoc = bool;
///     }
///
///     impl<D: DropMarkerKind> Shenanigans for Unsafe![D, &str] {
///         type Assoc = u8;
///     }
///
///     let helix: Helix<Unsafe![DropMarker::NoDropGlue, &str]> = Helix(2_u8);
///     let Helix::<&str>(bool) = unsafe {
///         ::core::mem::transmute::<
///             Helix<Unsafe![<'any> &'any str]>,
///             Helix<                 &'_ str >,
///         >(helix)
///     }; // UB! `bool: bool`'s bitpattern is `2_u8`!
///     ```
///
///     </details>
#[repr(transparent)]
pub
struct Unsafe<D : DropMarkerKind, T : ForLifetime> {
    _p: PD<(fn() -> D, dyn NoAutoTraits)>,
    value: MD<T::Of<'static>>,
}

impl<D : DropMarkerKind, T : ForLifetime> Drop for Unsafe<D, T> {
    fn drop(&mut self) {
        match <D as DropMarker::Sealed>::REIFIED {
            DropMarker::Reified::MayDrop => {
                unsafe {
                    self.do_drop_in_place();
                }
            },
            DropMarker::Reified::NoDropGlue => {},
        }
    }
}

unsafe
impl<D : DropMarkerKind, T : ForLifetime> Send for Unsafe<D, T>
where
    for<'any> T::Of<'any> : Send,
{}

unsafe
impl<D : DropMarkerKind, T : ForLifetime> Sync for Unsafe<D, T>
where
    for<'any> T::Of<'any> : Sync,
{}

/// Pinning projection (see [`Self::unwrap_binder_pin_mut()`]).
impl<T : ForLifetime> Unpin for Unsafe<DropMarker::MayDrop, T>
where
    for<'any> T::Of<'any> : Unpin,
{}

/// **No** pinning projection whatsoever (unconditionally `Unpin`).
impl<T : ForLifetime> Unpin for Unsafe<DropMarker::NoDropGlue, T> {}

unsafe
fn transmute_lt<'src, 'dst, T : ForLifetime>(src: T::Of<'src>) -> T::Of<'dst> {
    unsafe {
        ::core::mem::transmute(src)
    }
}

/* Nobody cares about you, `{Ref,}UnwindSafe`. */

impl<D : DropMarkerKind, T : ForLifetime> Unsafe<D, T> {
    unsafe
    fn new(value: T::Of<'_>) -> Self {
        Self {
            _p: PD,
            value: MD::new(unsafe {
                transmute_lt::<T>(value)
            }),
        }
    }

    /// Constructs an [`Unsafe<_, T>`][`Self`] with [`DropMarker::NoDropGlue`], _i.e._, with no drop
    /// glue attached.
    ///
    /// <div class="warning">
    ///
    /// This means that a memory leak may ensue when
    /// [`::core::mem::needs_drop::<T::Of<'_>>()`][1]
    ///
    /// </div>
    ///
    /// [1]: `::core::mem::needs_drop()`
    ///
    ///   - If so, you will need to call [`Self::manually_drop_in_place()`] eventually to avoid
    ///     that.
    ///
    ///   - When <code>T::Of\<\'_\> : [Copy]</code>, consider using [`Self::wrap_binder_copy()`]
    ///     instead.
    #[doc(alias = "new")]
    pub
    fn wrap_binder_manually_drop(value: T::Of<'_>) -> Self
    where
        DropMarker::NoDropGlue : Is<ItSelf = D>,
    {
        unsafe { Self::new(value) }
    }

    /// Constructs an [`Unsafe<_, T>`][`Self`] with a [`DropMarker`] which does not matter. This is
    /// fine since this requires <code>T::Of\<\'input\> : [Copy]</code> to hold, so there cannot be
    /// actual drop glue.
    #[doc(alias = "new")]
    pub
    fn wrap_binder_copy<'input>(value: T::Of<'input>) -> Self
    where
        DropMarker::NoDropGlue : Is<ItSelf = D>,
        T::Of<'input> : Copy,
    {
        unsafe { Self::new(value) }
    }

    /// Constructs an [`Unsafe<_, T>`][`Self`] with [`DropMarker::MayDrop`], _i.e._, with drop
    /// glue attached to it.
    ///
    /// <div class="warning">
    ///
    /// The very point of using this wrapper is to erase a lifetime, so this API can result in
    /// access to dangling data (UAF) when misused!
    ///
    /// </div>
    ///
    /// # Safety
    ///
    /// It must be sound to call [`Self::manually_drop_in_place()`] when this instance is dropped /
    /// goes out of scope. This soundness property is usually the result of immediately wrapping
    /// this instance in an aptly-lifetime infected or properly self-referential struct.
    ///
    /// Moreover, it must be sound to access the inner value as long as this value lives. This
    /// is indeed the case due to the existence of the scoped/existential-lifetime
    /// [`Self::with_unwrapped_binder…()`][`Self::with_unwrapped_binder()`] APIs.
    ///
    ///   - A subtle corollary is that you can only relinquish owned access of this instance to
    ///     an arbitrary API if you are fine with the `value` becoming `T::Of<'static>`.
    ///
    ///     Or phrased differently: you can only soundly call this constructor as an **owner** (who
    ///     wraps the whole thing in a sound API). This is a very non-local `SAFETY` property much
    ///     alike that of `Pin::new_unchecked()`.
    #[doc(alias = "new")]
    pub
    unsafe
    fn wrap_binder_with_drop_glue(value: T::Of<'_>) -> Self
    where
        DropMarker::MayDrop : Is<ItSelf = D>,
    {
        unsafe { Self::new(value) }
    }

    /// **By value,** imbue back the binder with a concrete `'lt` of your choice.
    ///
    /// # Safety
    ///
    /// Pick `'lt` wisely: it ought to match the original input lifetime used when doing
    /// `Self::wrap_binder…()`, or something semantically equivalent.
    ///
    /// Using `'input` upon `Self::wrap_binder…()` construction and `'lt` here is tantamount
    /// to having transmuted the `'input` lifetime to `'lt`.
    pub
    unsafe
    fn unwrap_binder<'lt>(self) -> T::Of<'lt>
    where
        'lt : /* early-bound, turbofishable */,
    {
        let value = unsafe { MD::take(&mut (*MD::new(self)).value) };
        unsafe {
            transmute_lt::<T>(value)
        }
    }

    /// **By `&`-reference,** imbue back the binder with a concrete `'lt` of your choice.
    ///
    /// # Safety
    ///
    /// Pick `'lt` wisely: it ought to match the original input lifetime used when doing
    /// `Self::wrap_binder…()`, or something semantically equivalent.
    ///
    /// Using `'input` upon `Self::wrap_binder…()` construction and `'lt` here is tantamount
    /// to having transmuted the `'input` lifetime to `'lt`.
    pub
    unsafe
    fn unwrap_binder_ref<'r, 'lt>(&'r self) -> &'r T::Of<'lt>
    where
        'lt : /* early-bound, turbofishable */,
        'r : /* needs to be early-bound for `'lt` to be turbofishable */,
    {
        let value = &self.value;
        unsafe {
            transmute_lt::<ForLt!(&'r T::Of<'_>)>(value)
        }
    }


    /// **By `&mut`-reference,** imbue back the binder with a concrete `'lt` of your choice.
    ///
    /// # Safety
    ///
    /// Pick `'lt` wisely: it ought to match the original input lifetime used when doing
    /// `Self::wrap_binder…()`, or something semantically equivalent.
    ///
    /// Using `'input` upon `Self::wrap_binder…()` construction and `'lt` here is tantamount
    /// to having transmuted the `'input` lifetime to `'lt`.
    pub
    unsafe
    fn unwrap_binder_mut<'r, 'lt>(&'r mut self) -> &'r mut T::Of<'lt>
    where
        'lt : /* early-bound, turbofishable */,
        'r : /* needs to be early-bound for `'lt` to be turbofishable */,
    {
        let value = &mut self.value;
        unsafe {
            transmute_lt::<ForLt!(&'r mut T::Of<'_>)>(value)
        }
    }


    /// **By `&pin mut`-reference,** imbue back the binder with a concrete `'lt` of your choice.
    ///
    /// This is effectively a pinning projection (on top of lifetime transmutation).
    ///
    /// # Safety
    ///
    /// Pick `'lt` wisely: it ought to match the original input lifetime used when doing
    /// `Self::wrap_binder…()`, or something semantically equivalent.
    ///
    /// Using `'input` upon `Self::wrap_binder…()` construction and `'lt` here is tantamount
    /// to having transmuted the `'input` lifetime to `'lt`.
    pub
    unsafe
    fn unwrap_binder_pin_mut<'r, 'lt>(
        self: Pin<&'r mut Self>,
    ) -> Pin<&'r mut T::Of<'lt>>
    where
        'lt : /* early-bound, turbofishable */,
        'r : /* needs to be early-bound for `'lt` to be turbofishable */,
        DropMarker::MayDrop : Is<ItSelf = D>,
    {
        let value = unsafe {
            self.map_unchecked_mut(|Self { value , ..}| -> &mut T::Of<'_> { value })
        };
        unsafe {
            transmute_lt::<ForLt!(Pin<&'r mut T::Of<'_>>)>(value)
        }
    }

    unsafe
    fn do_drop_in_place(&mut self) {
        unsafe {
            ptr::drop_in_place::<T::Of<'_>>(self.unwrap_binder_mut());
        }
    }

    /// Manually drop in place the `value` provided to [`Self::wrap_binder_manually_drop()`] (since
    /// it would otherwise not be dropped).
    ///
    /// Note: this API is only available in the [`DropMarker::NoDropGlue`] case. If you nonetheless
    /// wish to do this in the [`DropMarker::MayDrop`] case despite the resulting humongous risk of
    /// double dropping, then do so the usual way, _i.e._, using [`::core::ptr::drop_in_place()`]
    /// or your own [`::core::mem::ManuallyDrop::drop()`].
    pub
    unsafe
    fn manually_drop_in_place(&mut self)
    where
        DropMarker::NoDropGlue : Is<ItSelf = D>,
    {
        unsafe {
            self.do_drop_in_place();
        }
    }
}

/// Convenience non-`unsafe` APIs, courtesy of the `unsafe` promise provided by
/// [`Unsafe::wrap_binder_with_drop_glue()`].
///
/// Uses a scoped API to emulate an existential lifetime.
///
/// # Example
///
/// ```rust
/// use ::unsafe_binders::prelude::*;
///
/// let static_: &'static str = "Hello, World!";
/// let erased: Unsafe![DropMarker::MayDrop, &str] = unsafe {
///     // Safety: `&str` is covariant, and we have a `&'static str`, so we may
///     // as well have a `&'any str`.
///     Unsafe::wrap_binder_with_drop_glue(static_)
/// };
///
/// // Safely access the value!
/// erased.with_unwrapped_binder_ref(|&s| {
///     assert_eq!(s, "Hello, World!");
/// })
/// ```
impl<T : ForLifetime> Unsafe<DropMarker::MayDrop, T> {
    pub
    fn with_unwrapped_binder<R>(
        self,
        scope: impl FnOnce(T::Of<'_>) -> R,
    ) -> R
    {
        scope(unsafe {
            self.unwrap_binder::<'_>()
        })
    }

    pub
    fn with_unwrapped_binder_ref<'r, R>(
        &'r self,
        scope: impl FnOnce(&'r T::Of<'_>) -> R,
    ) -> R
    {
        scope(unsafe {
            self.unwrap_binder_ref::<'r, '_>()
        })
    }

    pub
    fn with_unwrapped_binder_mut<'r, R>(
        &'r mut self,
        scope: impl FnOnce(&'r mut T::Of<'_>) -> R,
    ) -> R
    {
        scope(unsafe {
            self.unwrap_binder_mut::<'r, '_>()
        })
    }
}

/// Convenience macro to _name_/express an `unsafe<'lt> …` type:
///
/// ```rust
/// # {} /*
/// Unsafe![<'lt> = …] // morally, `unsafe<'lt> …`
/// // e.g.
/// Unsafe![<'lt> = &'lt str] // morally, `unsafe<'lt> &'lt str`.
/// # */
/// ```
///
/// # Syntax
///
/// ```rust
/// # {} /*
/// Unsafe![
///     $($DropMarker:ty, )? // if elided, it is left to be `_`-inferred.
///
///     // then, either:
///     <$lt:lifetime> = $T:ty $(,)?
///
///     // or (lifetime-elision shorthand syntax):
///     $T:ty // <- every `'_` or unnamed `&`-lifetime is deemed parametric.
/// ]
/// # */
/// ```
///
///   - ### Lifetime-elision shorthand syntax
///
///     Similar to lifetime-elision in `fn` signatures (to be more precise, the elision of the
///     return type of an `fn` pointer, item, or `Fn…` trait), the [`Unsafe!`] macro also allows for
///     "inferring" which lifetime parameters are parametric simply by virtue of eliding them,
///     be it explicitly (_via_ `'_`), or implicitly (unnamed-`&[mut]`).
///
///     <div class="warning">
///
///     Do note that this macro is not able to see through `elided_lifetimes_in_paths`.
///
///     </div>
///
/// # Example
///
/// ```rust
/// use ::unsafe_binders::{DropMarker, Unsafe};
///
/// pub struct SelfReferential {
///     full_name: String,
///     first_name: Unsafe![DropMarker::NoDropGlue, <'this> &'this str],
///                                                // using lifetime-elision shorthand syntax:
///     last_name: Unsafe![DropMarker::NoDropGlue, &str],
/// }
///
/// impl SelfReferential {
///     pub fn new(full_name: String) -> Option<Self> {
///         let (first_name, last_name) = full_name.split_once(" ")?;
///         // erase the `&'full_name` lifetime:
///         let first_name: Unsafe![_, &str] = Unsafe::wrap_binder_copy(first_name);
///                                // shorthand syntax
///         let last_name: Unsafe![&str] = Unsafe::wrap_binder_copy(last_name);
///         Some(Self {
///             full_name,
///             first_name,
///             last_name,
///         })
///     }
///
///     pub fn first_name<'r>(&'r self) -> &'r str {
///         unsafe {
///             self.first_name.unwrap_binder_ref::<'_, 'r>()
///         }
///     }
///
///     pub fn last_name<'r>(&'r self) -> &'r str {
///         unsafe {
///             self.last_name.unwrap_binder_ref::<'_, 'r>()
///         }
///     }
/// }
/// ```
///
/// <!-- rust-analyzer nudge
/// ```rust ,ignore
/// ඞUnsafe![];
/// ```
/// -->
#[doc(hidden)] #[macro_export]
macro_rules! ඞUnsafe {
    (
        <$lt:lifetime> $($T:tt)+
    ) => (
        $crate::Unsafe<_, $crate::ඞ::ForLt!(<$lt> = $($T)+)>
    );

    (
        $DropMarker:ty,
        <$lt:lifetime> $($T:tt)+
    ) => (
        $crate::Unsafe<$DropMarker, $crate::ඞ::ForLt!(<$lt> = $($T)+)>
    );

    (
        $DropMarker:ty,
        $($T:tt)+
    ) => (
        $crate::Unsafe<$DropMarker, $crate::ඞ::ForLt!($($T)+)>
    );

    (
        $($T:tt)+
    ) => (
        $crate::Unsafe<_, $crate::ඞ::ForLt!($($T)+)>
    );
}
#[doc(inline)]
pub use ඞUnsafe as Unsafe;