potential-well 3.0.0

//! [`Well`] and [`WellMut`] traits.
#[cfg(any(test, feature = "alloc"))]
use alloc::{
    boxed::Box,
    sync::{self as arc, Arc},
};
use core::{
    mem,
    ops::{Deref, DerefMut},
    pin::Pin,
    ptr::NonNull,
};

#[cfg(feature = "alloc")]
use {
    crate::atomic::{PotentialAtomic, PotentialAtomicOption},
    alloc::rc::{self, Rc},
};

/// Smart pointer.
///
/// # Safety
///
/// Types that implement this trait assert that the [`insert`] and [`remove`] methods are true
/// inverses of each other with no side effects.
///
/// [`insert`]: Well::insert
/// [`remove`]: Well::remove
pub unsafe trait Well {
    /// Data stored in the pointer.
    type Target;

    /// Put the data back into the well.
    ///
    /// # Safety
    ///
    /// The pointer passed to [`insert`] must previously have been received from [`remove`].
    ///
    /// [`insert`]: Well::insert
    /// [`remove`]: Well::remove
    unsafe fn insert(ptr: NonNull<Self::Target>) -> Self;

    /// Take the data out of the well.
    fn remove(self) -> NonNull<Self::Target>;
}

/// Gets the target for a [`Well`].
pub type Target<W> = <W as Well>::Target;

/// Implementation of trait alias that uses trait aliases.
#[cfg(feature = "nightly")]
macro_rules! trait_alias {
    (
        $(#[$attr:meta])*
        $vis:vis trait $t:ident = ($($bound:tt)*);
    ) => {
        $(#[$attr])*
        ///
        /// Implemented as a trait alias with the `nightly` feature,
        /// and an automatically-implemented trait otherwise.
        $vis trait $t = $($bound)*;
    }
}

/// Implementation of trait alias that uses traits.
#[cfg(not(feature = "nightly"))]
macro_rules! trait_alias {
    (
        $(#[$attr:meta])*
        $vis:vis trait $t:ident = ($($bound:tt)*);
    ) => {
        $(#[$attr])*
        ///
        /// Implemented as a trait alias with the `nightly` feature,
        /// and an automatically-implemented trait otherwise.
        $vis trait $t: $($bound)* {}
        impl<T: $($bound)*> $t for T {}
    }
}

/// Smart pointer without direct access to its data.
///
/// # Safety
///
/// Implementors of this trait assert that [`insert`] and [`remove`] calls of themselves and their
/// [`Strong`] variant can be interchanged as long as the number of "weak" and "strong" versions
/// remain the same.
///
/// [`Strong`]: WeakWell::Strong
/// [`insert`]: Well::insert
/// [`remove`]: Well::remove
pub unsafe trait WeakWell: Well {
    /// Smart pointer that can directly access data.
    type Strong: StrongWell + Deref<Target = Self::Target>;

    /// Attempts to access data inside the well.
    fn access(&self) -> Option<Self::Strong>;

    /// Converts strong well back into weak version.
    fn weaken(access: &Self::Strong) -> Self;
}

/// Smart pointer with direct access to its data.
///
/// # Safety
///
/// Types that implement this trait assert, in addition to the requirements of [`Well`], that the
/// pointers returned/received by [`insert`] and [`remove`] are also valid to deref directly
/// whenever a valid reference to the pointer is obtained, *and* that if they implement
/// [`DerefMut`], the same applies to mutable dereferences.
///
/// Additionally, implementations guarantee that their contents are implicitly pinned, and thus
/// [`Pin::new_unchecked`] and [`Pin::into_inner_unchecked`] have the correct semantics for the
/// generic [`Pin`]ned implementation.
///
/// [`insert`]: Well::insert
/// [`remove`]: Well::remove
pub unsafe trait StrongWell:
    Deref<Target: Sized> + Well<Target = <Self as Deref>::Target>
{
}

// SAFETY: Ensured by contract for `StrongWell`.
unsafe impl<W: StrongWell> Well for Pin<W> {
    type Target = Target<W>;

    #[inline]
    unsafe fn insert(ptr: NonNull<Target<W>>) -> Pin<W> {
        // SAFETY: Ensured by contract for `StrongWell`.
        unsafe { Pin::new_unchecked(W::insert(ptr)) }
    }

    #[inline]
    fn remove(self) -> NonNull<Target<W>> {
        // SAFETY: Ensured by contract for `StrongWell`.
        unsafe { Pin::into_inner_unchecked(self).remove() }
    }
}
// SAFETY: Ensured by contract for `StrongWell`.
unsafe impl<W: StrongWell> StrongWell for Pin<W> {}

trait_alias! {
    /// Alias for <code>[StrongWell] + [DerefMut]</code>.
    ///
    /// Since [`StrongWell`] is unsafe to implement, it can assert that its guarantees apply to
    /// [`DerefMut`] implementations as well.
    pub trait StrongWellMut = (StrongWell + DerefMut);
}

// SAFETY: `NonNull::from` and `NonNull::as_ref` are direct inverses.
unsafe impl<'w, T> Well for &'w T {
    type Target = T;

    #[inline]
    unsafe fn insert(ptr: NonNull<T>) -> &'w T {
        // SAFETY: Ensured by caller.
        unsafe { ptr.as_ref() }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        NonNull::from(self)
    }
}
// SAFETY: `Deref for &T` is stable.
unsafe impl<T> StrongWell for &T {}

// SAFETY: `NonNull::from` and `NonNull::as_mut` are direct inverses.
unsafe impl<T> Well for &mut T {
    type Target = T;

    #[inline]
    unsafe fn insert(mut ptr: NonNull<T>) -> Self {
        // SAFETY: Ensured by caller.
        unsafe { ptr.as_mut() }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        NonNull::from(self)
    }
}
// SAFETY: `Deref for &mut T` is stable.
unsafe impl<T> StrongWell for &mut T {}

#[cfg(any(test, feature = "alloc"))]
// SAFETY: `Box::from_raw` and `Box::into_raw` are direct inverses.
unsafe impl<T> Well for Box<T> {
    type Target = T;

    #[inline]
    unsafe fn insert(ptr: NonNull<T>) -> Self {
        // SAFETY: Ensured by caller.
        unsafe { Box::from_raw(ptr.as_ptr()) }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        // SAFETY: Box's pointer is always non-null.
        unsafe { NonNull::new_unchecked(Box::into_raw(self)) }
    }
}
#[cfg(any(test, feature = "alloc"))]
// SAFETY: `Deref for Box<T>` is stable.
unsafe impl<T> StrongWell for Box<T> {}

#[cfg(feature = "alloc")]
// SAFETY: `Rc::from_raw` and `Rc::into_raw` are direct inverses.
unsafe impl<T> Well for Rc<T> {
    type Target = T;

    #[inline]
    unsafe fn insert(ptr: NonNull<T>) -> Self {
        // SAFETY: Ensured by caller.
        unsafe { Rc::from_raw(ptr.as_ptr()) }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        // SAFETY: Rc's pointer is always non-null.
        unsafe { NonNull::new_unchecked(Rc::into_raw(self).cast_mut()) }
    }
}
#[cfg(feature = "alloc")]
// SAFETY: `Deref for Rc<T>` is stable.
unsafe impl<T> StrongWell for Rc<T> {}

#[cfg(feature = "alloc")]
// SAFETY: `Weak::from_raw` and `Weak::into_raw` are direct inverses.
unsafe impl<T> Well for rc::Weak<T> {
    type Target = T;

    #[inline]
    unsafe fn insert(ptr: NonNull<T>) -> Self {
        // SAFETY: Ensured by caller.
        unsafe { rc::Weak::from_raw(ptr.as_ptr()) }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        // SAFETY: WeakArc's pointer is always non-null.
        unsafe { NonNull::new_unchecked(rc::Weak::into_raw(self).cast_mut()) }
    }
}
#[cfg(feature = "alloc")]
// SAFETY: `Rc` and `Weak` share the same pointers.
unsafe impl<T> WeakWell for rc::Weak<T> {
    type Strong = Rc<T>;

    #[inline]
    fn access(&self) -> Option<Rc<T>> {
        self.upgrade()
    }

    #[inline]
    fn weaken(access: &Rc<T>) -> rc::Weak<T> {
        Rc::downgrade(access)
    }
}

#[cfg(any(test, feature = "alloc"))]
// SAFETY: `Arc::from_raw` and `Arc::into_raw` are direct inverses.
unsafe impl<T> Well for Arc<T> {
    type Target = T;

    #[inline]
    unsafe fn insert(ptr: NonNull<T>) -> Self {
        // SAFETY: Ensured by caller.
        unsafe { Arc::from_raw(ptr.as_ptr()) }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        // SAFETY: Arc's pointer is always non-null.
        unsafe { NonNull::new_unchecked(Arc::into_raw(self).cast_mut()) }
    }
}
#[cfg(any(test, feature = "alloc"))]
// SAFETY: `Deref for Arc<T>` is stable.
unsafe impl<T> StrongWell for Arc<T> {}

#[cfg(any(test, feature = "alloc"))]
// SAFETY: `Weak::from_raw` and `Weak::into_raw` are direct inverses.
unsafe impl<T> Well for arc::Weak<T> {
    type Target = T;

    #[inline]
    unsafe fn insert(ptr: NonNull<T>) -> Self {
        // SAFETY: Ensured by caller.
        unsafe { arc::Weak::from_raw(ptr.as_ptr()) }
    }

    #[inline]
    fn remove(self) -> NonNull<T> {
        // SAFETY: WeakArc's pointer is always non-null.
        unsafe { NonNull::new_unchecked(arc::Weak::into_raw(self).cast_mut()) }
    }
}
#[cfg(any(test, feature = "alloc"))]
// SAFETY: `Arc` and `Weak` share the same pointers.
unsafe impl<T> WeakWell for arc::Weak<T> {
    type Strong = Arc<T>;

    #[inline]
    fn access(&self) -> Option<Arc<T>> {
        self.upgrade()
    }

    #[inline]
    fn weaken(access: &Arc<T>) -> arc::Weak<T> {
        Arc::downgrade(access)
    }
}

/// Potential well, representing a generic container.
///
/// Useful for recursive data structures, since it avoids recursive types.
///
/// # Examples
///
/// Atomic linked list via [`PotentialWell`]:
///
/// ```
/// use potential_well::{PotentialWell, PotentialAtomicOption};
///
/// struct Link<T, W: PotentialWell = Box<()>> {
///     data: T,
///     next: PotentialAtomicOption<Link<T, W>, W>
/// }
/// struct List<T, W: PotentialWell = Box<()>> {
///     root: PotentialAtomicOption<Link<T, W>, W>,
/// }
///
/// let list: List<u32> = List {
///     root: PotentialAtomicOption::some(Box::new(Link {
///         data: 1,
///         next: PotentialAtomicOption::some(Box::new(Link {
///             data: 2,
///             next: PotentialAtomicOption::some(Box::new(Link {
///                 data: 3,
///                 next: PotentialAtomicOption::none(),
///             }))
///         })),
///     })),
/// };
///
/// // no Drop implementation needed!
/// drop(list);
/// ```
///
/// Without [`PotentialWell`], you immediately run into trouble:
///
/// ```compile_fail
/// use potential_well::{Well, AtomicOption};
///
/// // recursive type: Link<T, Box<Link<T, Box<Link<T, ...>>>>>
/// struct Link<T, W: Well<Target = Link<T, Self>>> {
///     data: T,
///     next: AtomicOption<W>,
/// }
/// struct List<T, W: Well<Target = Link<T, Self>>> {
///     root: AtomicOption<W>,
/// }
///
/// let list: List<u32, Box<_>> = List {
///     root: AtomicOption::some(Box::new(Link {
///         data: 1,
///         next: AtomicOption::some(Box::new(Link {
///             data: 2,
///             next: AtomicOption::some(Box::new(Link {
///                 data: 3,
///                 next: AtomicOption::none(),
///             }))
///         })),
///     })),
/// };
/// ```
pub trait PotentialWell {
    /// Makes a well of a particular type.
    type Well<T>: KineticWell<Target = T>;

    /// Makes that well.
    fn new<T>(data: T) -> Self::Well<T>;
}

/// [`PotentialWell`] that always yields [`StrongWell`]s.
///
/// Unfortunately, without higher-kinded trait bounds (HKTBs) for generic associated types (GATs),
/// we can't make this into a proper trait alias, and it must be implemented manually.
pub trait StrongPotentialWell: PotentialWell {
    /// Makes a well of a particular type.
    ///
    /// This only acts to verify the trait, and is never used directly.
    type StrongWell<T>: StrongWell
        + Deref<Target = T>
        + KineticWell<Potential: PotentialWell<Well<T> = Self::StrongWell<T>>>
        + KineticWell<Potential = Self>;
}
impl<W: StrongPotentialWell> StrongPotentialWell for Pin<W> {
    type StrongWell<T> = Pin<W::StrongWell<T>>;
}
impl<W: StrongPotentialWell> PotentialWell for Pin<W> {
    type Well<T> = Pin<W::StrongWell<T>>;

    fn new<T>(data: T) -> Self::Well<T> {
        let well = mem::ManuallyDrop::new(W::new(data));

        // SAFETY: `W::Well = W::StrongWell`.
        let well = unsafe { mem::transmute_copy(&well) };

        // SAFETY: Ensured by contract for `StrongWell`.
        unsafe { Pin::new_unchecked(well) }
    }
}
impl<W: StrongWell + KineticWell<Potential: StrongPotentialWell<StrongWell<Target<W>> = W>>>
    KineticWell for Pin<W>
{
    type Potential = Pin<W::Potential>;
}

/// [`PotentialWell`] that always yields [`WeakWell`]s.
///
/// Unfortunately, without higher-kinded trait bounds (HKTBs) for generic associated types (GATs),
/// we can't make this into a proper trait alias, and it must be implemented manually.
pub trait WeakPotentialWell: PotentialWell {
    /// Potential well that corresponds to the [`Strong`] wells for each weak well.
    ///
    /// [`Strong`]: WeakWell::Strong
    type Strong: StrongPotentialWell;

    /// Makes a well of a partiuclar type.
    ///
    /// This only acts to verify the trait, and is never used directly.
    type WeakWell<T>: WeakWell<Target = T, Strong: KineticWell<Potential = Self::Strong>>
        + KineticWell<Potential: PotentialWell<Well<T> = Self::WeakWell<T>>>;
}

/// Inverse trait for [`PotentialWell`].
pub trait KineticWell: Well {
    /// Potential version.
    type Potential: PotentialWell<Well<Target<Self>> = Self>;
}

#[cfg(any(test, feature = "alloc"))]
impl PotentialWell for Box<()> {
    type Well<T> = Box<T>;

    #[inline]
    fn new<T>(data: T) -> Box<T> {
        Box::new(data)
    }
}
#[cfg(any(test, feature = "alloc"))]
impl StrongPotentialWell for Box<()> {
    type StrongWell<T> = Box<T>;
}
#[cfg(any(test, feature = "alloc"))]
impl<T> KineticWell for Box<T> {
    type Potential = Box<()>;
}

#[cfg(feature = "alloc")]
impl PotentialWell for Rc<()> {
    type Well<T> = Rc<T>;

    #[inline]
    fn new<T>(data: T) -> Rc<T> {
        Rc::new(data)
    }
}
#[cfg(feature = "alloc")]
impl StrongPotentialWell for Rc<()> {
    type StrongWell<T> = Rc<T>;
}
#[cfg(feature = "alloc")]
impl<T> KineticWell for Rc<T> {
    type Potential = Rc<()>;
}

#[cfg(feature = "alloc")]
impl PotentialWell for rc::Weak<()> {
    type Well<T> = rc::Weak<T>;

    #[inline]
    fn new<T>(_: T) -> rc::Weak<T> {
        rc::Weak::default()
    }
}
#[cfg(feature = "alloc")]
impl WeakPotentialWell for rc::Weak<()> {
    type Strong = Rc<()>;
    type WeakWell<T> = rc::Weak<T>;
}
#[cfg(feature = "alloc")]
impl<T> KineticWell for rc::Weak<T> {
    type Potential = rc::Weak<()>;
}

#[cfg(any(test, feature = "alloc"))]
impl PotentialWell for Arc<()> {
    type Well<T> = Arc<T>;

    #[inline]
    fn new<T>(data: T) -> Arc<T> {
        Arc::new(data)
    }
}
#[cfg(any(test, feature = "alloc"))]
impl StrongPotentialWell for Arc<()> {
    type StrongWell<T> = Arc<T>;
}
#[cfg(any(test, feature = "alloc"))]
impl<T> KineticWell for Arc<T> {
    type Potential = Arc<()>;
}

#[cfg(any(test, feature = "alloc"))]
impl PotentialWell for arc::Weak<()> {
    type Well<T> = arc::Weak<T>;

    #[inline]
    fn new<T>(_: T) -> arc::Weak<T> {
        arc::Weak::default()
    }
}
#[cfg(any(test, feature = "alloc"))]
impl WeakPotentialWell for arc::Weak<()> {
    type Strong = Arc<()>;
    type WeakWell<T> = arc::Weak<T>;
}
#[cfg(any(test, feature = "alloc"))]
impl<T> KineticWell for arc::Weak<T> {
    type Potential = arc::Weak<()>;
}

/// Alias for <code>[PotentialAtomic]&lt;T, [Box]&lt;()&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicBox<T> = PotentialAtomic<T, Box<()>>;

/// Alias for <code>[PotentialAtomic]&lt;T, [Pin]&lt;[Box]&lt;()&gt;&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicPinBox<T> = PotentialAtomic<T, Pin<Box<()>>>;

/// Alias for <code>[PotentialAtomic]&lt;T, [Rc]&lt;()&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicRc<T> = PotentialAtomic<T, Rc<()>>;

/// Alias for <code>[PotentialAtomic]&lt;T, [Pin]&lt;[Rc]&lt;()&gt;&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicPinRc<T> = PotentialAtomic<T, Pin<Rc<()>>>;

/// Alias for <code>[PotentialAtomic]&lt;T, [Arc]&lt;()&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicArc<T> = PotentialAtomic<T, Arc<()>>;

/// Alias for <code>[PotentialAtomic]&lt;T, [Pin]&lt;[Arc]&lt;()&gt;&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicPinArc<T> = PotentialAtomic<T, Pin<Arc<()>>>;

/// Alias for <code>[PotentialAtomicOption]&lt;T, [Box]&lt;()&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicOptionBox<T> = PotentialAtomicOption<T, Box<()>>;

/// Alias for <code>[PotentialAtomicOption]&lt;T, [Pin]&lt;[Box]&lt;()&gt;&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicOptionPinBox<T> = PotentialAtomicOption<T, Pin<Box<()>>>;

/// Alias for <code>[PotentialAtomicOption]&lt;T, [Rc]&lt;()&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicOptionRc<T> = PotentialAtomicOption<T, Rc<()>>;

/// Alias for <code>[PotentialAtomicOption]&lt;T, [Pin]&lt;[Rc]&lt;()&gt;&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicOptionPinRc<T> = PotentialAtomicOption<T, Pin<Rc<()>>>;

/// Alias for <code>[PotentialAtomicOption]&lt;T, [Arc]&lt;()&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicOptionArc<T> = PotentialAtomicOption<T, Arc<()>>;

/// Alias for <code>[PotentialAtomicOption]&lt;T, [Pin]&lt;[Arc]&lt;()&gt;&gt;&gt;</code>
#[cfg(feature = "alloc")]
pub type AtomicOptionPinArc<T> = PotentialAtomicOption<T, Pin<Arc<()>>>;