potential_well/

atomic.rs

//! Atomic primitives.
use core::{
    fmt,
    marker::PhantomData,
    mem::ManuallyDrop,
    ops::{Deref, DerefMut},
    pin::Pin,
    sync::atomic::{AtomicPtr, Ordering},
};

use crate::{
    inner,
    traits::{Bucket, KineticWell, PotentialWell, StrongWell, StrongWellMut, WeakWell, Well},
};

/// Potentially empty atomic potential well.
///
/// Internally, this just wraps a pointer to `Bucket<T>` and uses atomic pointer
/// operations to access it. However, the number of operations on the pointer is limited to
/// ensure correctness in safe code.
#[repr(transparent)]
pub struct AtomicOption<W: Well> {
    /// Inner pointer.
    ptr: inner::AtomicOption<Bucket<W>>,

    /// Data marker.
    marker: PhantomData<Option<W>>,
}

/// By default, nothing is stored in the atomic.
impl<W: Well> Default for AtomicOption<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn default() -> Self {
        AtomicOption::none()
    }
}
impl<W: Well> AtomicOption<W> {
    /// Creates atomic without anything inside.
    #[inline]
    pub fn none() -> AtomicOption<W> {
        AtomicOption::new(None)
    }

    /// Creates atomic with something inside.
    #[inline]
    pub fn some(well: W) -> AtomicOption<W> {
        AtomicOption::new(Some(well))
    }

    /// Creates atomic.
    #[inline]
    pub fn new(well: Option<W>) -> AtomicOption<W> {
        AtomicOption {
            ptr: inner::AtomicOption::new(well.map(Well::remove)),
            marker: PhantomData,
        }
    }

    /// Gives access to the underlying [`AtomicPtr`].
    ///
    /// # Safety
    ///
    /// The pointer inside the atomic must always be null, or a valid pointer from [`Well::remove`].
    /// Additionally, keep in mind that this atomic *owns* the pointer, and if you want to move it
    /// out, you must put a different pointer in its place first.
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    pub unsafe fn as_raw_unchecked(&self) -> &AtomicPtr<Bucket<W>> {
        self.ptr.as_raw()
    }

    /// Atomically swaps the data inside the well.
    ///
    /// This is equivalent to an atomic [`swap`].
    ///
    /// [`swap`]: AtomicPtr::swap
    #[inline]
    pub fn swap(&self, well: W, ordering: Ordering) -> Option<W> {
        let ptr = self.ptr.swap(Some(well.remove()), ordering)?;

        // SAFETY: We only insert pointers that were `remove`d from wells.
        Some(unsafe { Well::insert(ptr) })
    }

    /// Takes the data out of the well.
    ///
    /// This is equivalent to an atomic [`swap`] with a null pointer.
    ///
    /// [`swap`]: AtomicPtr::swap
    #[inline]
    pub fn take(&self, ordering: Ordering) -> Option<W> {
        let ptr = self.ptr.swap(None, ordering)?;

        // SAFETY: We only insert pointers that were `remove`d from wells.
        Some(unsafe { Well::insert(ptr) })
    }

    /// Inserts data into the well.
    ///
    /// This uses [`compare_exchange`] to avoid inserting into the well if it's already full. If you
    /// want to use [`compare_exchange_weak`] instead, use [`insert_weak`].
    ///
    /// [`insert_weak`]: AtomicOption::insert_weak
    /// [`compare_exchange`]: AtomicPtr::compare_exchange
    /// [`compare_exchange_weak`]: AtomicPtr::compare_exchange_weak
    #[inline]
    pub fn insert(&self, well: W, success: Ordering, failure: Ordering) -> Result<(), W> {
        let ptr = well.remove();
        if self
            .ptr
            .compare_exchange(None, Some(ptr), success, failure)
            .is_ok()
        {
            Ok(())
        } else {
            // SAFETY: We just `remove`d this from a well, and since it wasn't stored,
            //   we can re`insert` it.
            Err(unsafe { Well::insert(ptr) })
        }
    }

    /// Inserts data into the well, sometimes failing spuriously.
    ///
    /// This uses [`compare_exchange_weak`] to avoid inserting into the well if it's already full,
    /// which may spuriously fail. If you want to use [`compare_exchange`] instead, use [`insert`].
    ///
    /// [`insert`]: AtomicOption::insert
    /// [`compare_exchange`]: AtomicPtr::compare_exchange
    /// [`compare_exchange_weak`]: AtomicPtr::compare_exchange_weak
    #[inline]
    pub fn insert_weak(&self, well: W, success: Ordering, failure: Ordering) -> Result<(), W> {
        let ptr = well.remove();
        if self
            .ptr
            .compare_exchange_weak(None, Some(ptr), success, failure)
            .is_ok()
        {
            Ok(())
        } else {
            // SAFETY: We just `remove`d this from a well, and since it wasn't stored,
            //   we can re`insert` it.
            Err(unsafe { Well::insert(ptr) })
        }
    }
}
impl<W: WeakWell> AtomicOption<W> {
    /// Tries to load the inner data.
    ///
    /// This is equivalent to an atomic [`load`], but it may fail due to the weak reference. If
    /// the reference fails to upgrade, it will still remain inside the well.
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn try_load(&self, ordering: Ordering) -> Option<<W as WeakWell>::Access> {
        let ptr = self.ptr.load(ordering)?;

        // SAFETY: This was `remove`d from a well.
        let ptr = unsafe { ManuallyDrop::new(W::insert(ptr)) };

        WeakWell::access(&*ptr)
    }
}
impl<W: StrongWell> AtomicOption<W> {
    /// Loads the inner data as an immutable reference.
    ///
    /// This is equivalent to an atomic [`load`].
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load(&self, ordering: Ordering) -> Option<&Bucket<W>> {
        let ptr = self.ptr.load(ordering)?;

        // SAFETY: The pointer is stable.
        Some(unsafe { ptr.as_ref() })
    }

    /// Atomically swaps the data inside the well and returns a reference to the new data.
    ///
    /// This is [`swap`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`swap`]: AtomicOption::swap
    #[inline]
    pub fn swap_get(&self, well: W, ordering: Ordering) -> (Option<W>, &Bucket<W>) {
        let new = well.remove();
        let old = self.ptr.swap(Some(new), ordering);

        // SAFETY: The pointer is stable.
        let new = unsafe { new.as_ref() };

        (
            // SAFETY: This was `remove`d from a well.
            old.map(|old| unsafe { Well::insert(old) }),
            new,
        )
    }

    /// Inserts data into the well and returns a reference to the new data.
    ///
    /// This is [`insert`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`insert`]: AtomicOption::insert
    #[inline]
    pub fn insert_get(
        &self,
        well: W,
        success: Ordering,
        failure: Ordering,
    ) -> Result<&Bucket<W>, W> {
        let new = well.remove();
        if self
            .ptr
            .compare_exchange(None, Some(new), success, failure)
            .is_ok()
        {
            // SAFETY: The pointer is stable.
            Ok(unsafe { new.as_ref() })
        } else {
            // SAFETY: We just `remove`d this from a well, and since it wasn't stored,
            //   we can re`insert` it.
            Err(unsafe { Well::insert(new) })
        }
    }

    /// Inserts data into the well, returns reference to the new data, sometimes failing spuriously.
    ///
    /// This is [`insert_weak`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`insert_weak`]: AtomicOption::insert_weak
    #[inline]
    pub fn insert_weak_get(
        &self,
        well: W,
        success: Ordering,
        failure: Ordering,
    ) -> Result<&Bucket<W>, W> {
        let new = well.remove();
        if self
            .ptr
            .compare_exchange_weak(None, Some(new), success, failure)
            .is_ok()
        {
            // SAFETY: The pointer is stable.
            Ok(unsafe { new.as_ref() })
        } else {
            // SAFETY: We just `remove`d this from a well, and since it wasn't stored,
            //   we can re`insert` it.
            Err(unsafe { Well::insert(new) })
        }
    }
}
impl<W: StrongWellMut + DerefMut<Target: Unpin>> AtomicOption<W> {
    /// Loads the inner data as a mutable reference.
    ///
    /// This performs a non-atomic access since the atomic is mutably borrowed.
    #[inline]
    pub fn load_mut(&mut self) -> Option<&mut Bucket<W>> {
        // SAFETY: The pointer is stable.
        Some(unsafe { self.ptr.get_mut()?.as_mut() })
    }
}
impl<W: StrongWellMut> AtomicOption<Pin<W>> {
    /// Loads the inner data as a pinned mutable reference.
    ///
    /// This is a version of [`load_mut`] that works with pinned values.
    ///
    /// [`load_mut`]: AtomicOption::load_mut
    #[inline]
    pub fn load_mut_pinned(&mut self) -> Option<Pin<&mut <Pin<W> as Well>::Target>> {
        // SAFETY: The pointer is stable, and we don't disrupt the pin.
        Some(unsafe { Pin::new_unchecked(self.ptr.get_mut()?.as_mut()) })
    }
}
impl<W: Well> From<W> for AtomicOption<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn from(well: W) -> Self {
        AtomicOption::some(well)
    }
}
impl<W: Well> From<Option<W>> for AtomicOption<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn from(well: Option<W>) -> Self {
        AtomicOption::new(well)
    }
}
impl<W: Well + Clone> AtomicOption<W> {
    /// Loads a clone of the inner data.
    ///
    /// This still performs an atomic [`load`], but instead of offering a reference, the smart
    /// pointer is cloned instead.
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load_clone(&self, ordering: Ordering) -> Option<W> {
        let ptr = self.ptr.load(ordering)?;

        // SAFETY: This was `remove`d from a well.
        let ptr = unsafe { ManuallyDrop::new(W::insert(ptr)) };

        Some((*ptr).clone())
    }
}
impl<W: Well> Drop for AtomicOption<W> {
    #[inline]
    fn drop(&mut self) {
        if let Some(ptr) = self.ptr.load_drop() {
            // SAFETY: This was `remove`d from a well.
            unsafe {
                drop(W::insert(ptr));
            }
        }
    }
}
impl<W: Well + fmt::Debug> fmt::Debug for AtomicOption<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let mut tuple = f.debug_tuple("AtomicOption");
        let Some(ptr) = self.ptr.load_debug() else {
            return tuple.field(&None::<W>).finish();
        };

        // SAFETY: This was `remove`d from a well.
        let ptr = unsafe { ManuallyDrop::new(W::insert(ptr)) };

        tuple.field(&Some(&*ptr)).finish()
    }
}

/// Atomic potential well.
///
/// Internally, this just wraps a pointer to `Bucket<T>` and uses atomic pointer
/// operations to access it. However, the number of operations on the pointer is limited to
/// ensure correctness in safe code.
#[repr(transparent)]
pub struct Atomic<W: Well>(inner::Atomic<Bucket<W>>);
impl<W: Well + Default> Default for Atomic<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn default() -> Self {
        Atomic::new(Default::default())
    }
}
impl<W: Well> Atomic<W> {
    /// Creates atomic with a value.
    #[inline]
    pub fn new(well: W) -> Atomic<W> {
        Atomic(inner::Atomic::new(well.remove()))
    }

    /// Gives access to the underlying [`AtomicPtr`].
    ///
    /// # Safety
    ///
    /// The pointer inside the atomic must always a valid pointer from [`Well::remove`] and
    /// therefore must not be null. Additionally, keep in mind that this atomic *owns* the
    /// pointer, and if you want to move it out, you must put a different pointer in its place
    /// first.
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    pub unsafe fn as_raw_unchecked(&self) -> &AtomicPtr<Bucket<W>> {
        self.0.as_raw()
    }

    /// Atomically swaps the data inside the well.
    ///
    /// This is equivalent to an atomic [`swap`].
    ///
    /// [`swap`]: AtomicPtr::swap
    #[inline]
    pub fn swap(&self, well: W, ordering: Ordering) -> W {
        let ptr = self.0.swap(well.remove(), ordering);

        // SAFETY: This was `remove`d from a well.
        unsafe { Well::insert(ptr) }
    }
}
impl<W: WeakWell> Atomic<W> {
    /// Tries to load the inner data.
    ///
    /// This is equivalent to an atomic [`load`], but it may fail due to the weak reference.
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn try_load(&self, ordering: Ordering) -> Option<<W as WeakWell>::Access> {
        let ptr = self.0.load(ordering);

        // SAFETY: This was `remove`d from a well.
        let ptr = unsafe { ManuallyDrop::new(W::insert(ptr)) };

        WeakWell::access(&*ptr)
    }
}
impl<W: StrongWell + Deref<Target: Sized>> Atomic<W> {
    /// Loads the inner data as an immutable reference.
    ///
    /// This is equivalent to an atomic [`load`].
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load(&self, ordering: Ordering) -> &Bucket<W> {
        let ptr = self.0.load(ordering);

        // SAFETY: The pointer is stable.
        unsafe { ptr.as_ref() }
    }

    /// Atomically swaps the data inside the well and returns a reference to the new data.
    ///
    /// This is [`swap`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`swap`]: AtomicOption::swap
    #[inline]
    pub fn swap_get(&self, well: W, ordering: Ordering) -> (W, &Bucket<W>) {
        let new = well.remove();
        let old = self.0.swap(new, ordering);

        // SAFETY: The pointer is stable.
        let new = unsafe { new.as_ref() };

        (
            // SAFETY: This was `remove`d from a well.
            unsafe { Well::insert(old) },
            new,
        )
    }
}
impl<W: StrongWellMut + DerefMut<Target: Unpin>> Atomic<W> {
    /// Loads the inner data as a mutable reference.
    ///
    /// This performs a non-atomic access since the atomic is mutably borrowed.
    #[inline]
    pub fn load_mut(&mut self) -> &mut Bucket<W> {
        let mut ptr = self.0.get_mut();

        // SAFETY: The pointer is stable.
        unsafe { ptr.as_mut() }
    }
}
impl<W: StrongWellMut> Atomic<Pin<W>> {
    /// Loads the inner data as a mutable reference.
    ///
    /// This is a version of [`load_mut`] that works with pinned values.
    ///
    /// [`load_mut`]: AtomicOption::load_mut
    #[inline]
    pub fn load_mut_pinned(&mut self) -> Pin<&mut <Pin<W> as Well>::Target> {
        let mut ptr = self.0.get_mut();

        // SAFETY: The pointer is stable, and we don't disrupt the pin.
        unsafe { Pin::new_unchecked(ptr.as_mut()) }
    }
}
impl<W: Well> From<W> for Atomic<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn from(well: W) -> Self {
        Atomic::new(well)
    }
}
impl<W: Well + Clone> Atomic<W> {
    /// Loads a clone of the inner data.
    ///
    /// This still performs an atomic [`load`], but instead of offering a reference, the smart
    /// pointer is cloned instead.
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load_clone(&self, ordering: Ordering) -> W {
        let ptr = self.0.load(ordering);

        // SAFETY: This was `remove`d from a well.
        let ptr = unsafe { ManuallyDrop::new(W::insert(ptr)) };

        (*ptr).clone()
    }
}
impl<W: Well> Drop for Atomic<W> {
    #[inline]
    fn drop(&mut self) {
        let ptr = self.0.load_drop();

        // SAFETY: This was `remove`d from a well.
        unsafe {
            drop(W::insert(ptr));
        }
    }
}
impl<W: Well + fmt::Debug> fmt::Debug for Atomic<W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        let ptr = self.0.load_debug();

        // SAFETY: This was `remove`d from a well.
        let ptr = unsafe { ManuallyDrop::new(W::insert(ptr)) };

        f.debug_tuple("Atomic").field(&*ptr).finish()
    }
}

/// Type-hoisted [`AtomicOption`].
///
/// Uses [`PotentialWell`] to allow for recursive structures at the cost of some usability.
/// See the documentation for [`PotentialWell`] for more information.
#[repr(transparent)]
pub struct PotentialAtomicOption<T, W: PotentialWell>(AtomicOption<KineticWell<T, W>>);

/// By default, nothing is stored in the atomic.
impl<T, W: PotentialWell> Default for PotentialAtomicOption<T, W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn default() -> Self {
        PotentialAtomicOption::none()
    }
}
impl<T, W: PotentialWell> PotentialAtomicOption<T, W> {
    /// Creates atomic without anything inside.
    #[inline]
    pub fn none() -> PotentialAtomicOption<T, W> {
        PotentialAtomicOption::new(None)
    }

    /// Creates atomic with something inside.
    #[inline]
    pub fn some(well: KineticWell<T, W>) -> PotentialAtomicOption<T, W> {
        PotentialAtomicOption::new(Some(well))
    }

    /// Creates atomic.
    pub fn new(well: Option<KineticWell<T, W>>) -> PotentialAtomicOption<T, W> {
        PotentialAtomicOption(AtomicOption::new(well))
    }

    /// Gives access to the underlying [`AtomicPtr`].
    ///
    /// # Safety
    ///
    /// The pointer inside the atomic must always be null, or a valid pointer from [`Well::remove`].
    /// Additionally, keep in mind that this atomic *owns* the pointer, and if you want to move it
    /// out, you must put a different pointer in its place first.
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    pub unsafe fn as_raw_unchecked(&self) -> &AtomicPtr<T> {
        // SAFETY: Ensured by caller.
        unsafe { self.0.as_raw_unchecked() }
    }

    /// Atomically swaps the data inside the well.
    ///
    /// This is equivalent to an atomic [`swap`].
    ///
    /// [`swap`]: AtomicPtr::swap
    #[inline]
    pub fn swap(&self, well: KineticWell<T, W>, ordering: Ordering) -> Option<KineticWell<T, W>> {
        self.0.swap(well, ordering)
    }

    /// Takes the data out of the well.
    ///
    /// This is equivalent to an atomic [`swap`] with a null pointer.
    ///
    /// [`swap`]: AtomicPtr::swap
    #[inline]
    pub fn take(&self, ordering: Ordering) -> Option<KineticWell<T, W>> {
        self.0.take(ordering)
    }

    /// Inserts data into the well.
    ///
    /// This uses [`compare_exchange`] to avoid inserting into the well if it's already full. If you
    /// want to use [`compare_exchange_weak`] instead, use [`insert_weak`].
    ///
    /// [`insert_weak`]: PotentialAtomicOption::insert_weak
    /// [`compare_exchange`]: AtomicPtr::compare_exchange
    /// [`compare_exchange_weak`]: AtomicPtr::compare_exchange_weak
    #[inline]
    pub fn insert(
        &self,
        well: KineticWell<T, W>,
        success: Ordering,
        failure: Ordering,
    ) -> Result<(), KineticWell<T, W>> {
        self.0.insert(well, success, failure)
    }

    /// Inserts data into the well, sometimes failing spuriously.
    ///
    /// This uses [`compare_exchange_weak`] to avoid inserting into the well if it's already full,
    /// which may spuriously fail. If you want to use [`compare_exchange`] instead, use [`insert`].
    ///
    /// [`insert`]: PotentialAtomicOption::insert
    /// [`compare_exchange`]: AtomicPtr::compare_exchange
    /// [`compare_exchange_weak`]: AtomicPtr::compare_exchange_weak
    #[inline]
    pub fn insert_weak(
        &self,
        well: KineticWell<T, W>,
        success: Ordering,
        failure: Ordering,
    ) -> Result<(), KineticWell<T, W>> {
        self.0.insert_weak(well, success, failure)
    }
}
impl<T, W: PotentialWell> PotentialAtomicOption<T, W>
where
    KineticWell<T, W>: StrongWell + Deref<Target = T>,
{
    /// Loads the inner data as an immutable reference.
    ///
    /// This is equivalent to an atomic [`load`].
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load(&self, ordering: Ordering) -> Option<&T> {
        self.0.load(ordering)
    }

    /// Atomically swaps the data inside the well and returns a reference to the new data.
    ///
    /// This is [`swap`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`swap`]: AtomicOption::swap
    #[inline]
    pub fn swap_get(
        &self,
        well: KineticWell<T, W>,
        ordering: Ordering,
    ) -> (Option<KineticWell<T, W>>, &T) {
        self.0.swap_get(well, ordering)
    }

    /// Inserts data into the well and returns a reference to the new data.
    ///
    /// This is [`insert`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`insert`]: AtomicOption::insert
    #[inline]
    pub fn insert_get(
        &self,
        well: KineticWell<T, W>,
        success: Ordering,
        failure: Ordering,
    ) -> Result<&T, KineticWell<T, W>> {
        self.0.insert_get(well, success, failure)
    }

    /// Inserts data into the well, returns reference to the new data, sometimes failing spuriously.
    ///
    /// This is [`insert_weak`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`insert_weak`]: AtomicOption::insert_weak
    #[inline]
    pub fn insert_weak_get(
        &self,
        well: KineticWell<T, W>,
        success: Ordering,
        failure: Ordering,
    ) -> Result<&T, KineticWell<T, W>> {
        self.0.insert_weak_get(well, success, failure)
    }
}
impl<T: Unpin, W: PotentialWell> PotentialAtomicOption<T, W>
where
    KineticWell<T, W>: StrongWellMut + Deref<Target = T>,
{
    /// Loads the inner data as a mutable reference.
    ///
    /// This performs a non-atomic access since the atomic is mutably borrowed.
    #[inline]
    pub fn load_mut(&mut self) -> Option<&mut T> {
        self.0.load_mut()
    }
}
impl<T, W: PotentialWell> PotentialAtomicOption<T, Pin<W>>
where
    KineticWell<T, W>: StrongWellMut + Deref<Target = T>,
    Pin<W>: PotentialWell<Well<T> = Pin<KineticWell<T, W>>>,
{
    /// Loads the inner data as a pinned mutable reference.
    ///
    /// This is a version of [`load_mut`] that works with pinned values.
    ///
    /// [`load_mut`]: PotentialAtomicOption::load_mut
    #[inline]
    pub fn load_mut_pinned(&mut self) -> Option<Pin<&mut T>> {
        self.0.load_mut_pinned()
    }
}
impl<T, W: PotentialWell> From<Option<KineticWell<T, W>>> for PotentialAtomicOption<T, W> {
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn from(well: Option<KineticWell<T, W>>) -> Self {
        match well {
            Some(well) => PotentialAtomicOption::some(well),
            None => PotentialAtomicOption::none(),
        }
    }
}
impl<T, W: PotentialWell> PotentialAtomicOption<T, W>
where
    KineticWell<T, W>: Clone,
{
    /// Loads a clone of the inner data.
    ///
    /// This still performs an atomic [`load`], but instead of offering a reference, the smart
    /// pointer is cloned instead.
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load_clone(&self, ordering: Ordering) -> Option<KineticWell<T, W>> {
        self.0.load_clone(ordering)
    }
}
impl<T, W: PotentialWell> fmt::Debug for PotentialAtomicOption<T, W>
where
    KineticWell<T, W>: fmt::Debug,
{
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&self.0, f)
    }
}

/// Type-hoisted [`Atomic`].
///
/// Uses [`PotentialWell`] to allow for recursive structures at the cost of some usability.
/// See the documentation for [`PotentialWell`] for more information.
#[repr(transparent)]
pub struct PotentialAtomic<T, W: PotentialWell>(Atomic<KineticWell<T, W>>);
impl<T: Default, W: PotentialWell> Default for PotentialAtomic<T, W>
where
    KineticWell<T, W>: Default,
{
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn default() -> Self {
        PotentialAtomic::new(Default::default())
    }
}
impl<T, W: PotentialWell> PotentialAtomic<T, W> {
    /// Creates atomic with a value.
    #[inline]
    pub fn new(well: KineticWell<T, W>) -> PotentialAtomic<T, W> {
        PotentialAtomic(Atomic::new(well))
    }

    /// Gives access to the underlying [`AtomicPtr`].
    ///
    /// # Safety
    ///
    /// The pointer inside the atomic must always a valid pointer from [`Well::remove`] and
    /// therefore must not be null. Additionally, keep in mind that this atomic *owns* the
    /// pointer, and if you want to move it out, you must put a different pointer in its place
    /// first.
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    pub unsafe fn as_raw_unchecked(&self) -> &AtomicPtr<T> {
        // SAFETY: Ensured by caller.
        unsafe { self.0.as_raw_unchecked() }
    }

    /// Atomically swaps the data inside the well.
    ///
    /// This is equivalent to an atomic [`swap`].
    ///
    /// [`swap`]: AtomicPtr::swap
    #[inline]
    pub fn swap(&self, well: KineticWell<T, W>, ordering: Ordering) -> KineticWell<T, W> {
        self.0.swap(well, ordering)
    }
}
impl<T, W: PotentialWell> PotentialAtomic<T, W>
where
    KineticWell<T, W>: StrongWell + Deref<Target = T>,
{
    /// Loads the inner data as an immutable reference.
    ///
    /// This is equivalent to an atomic [`load`].
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load(&self, ordering: Ordering) -> &T {
        self.0.load(ordering)
    }

    /// Atomically swaps the data inside the well and returns a reference to the new data.
    ///
    /// This is [`swap`], but with the unsafe deref hidden behind a safe API.
    ///
    /// [`swap`]: AtomicOption::swap
    #[inline]
    pub fn swap_get(&self, well: KineticWell<T, W>, ordering: Ordering) -> (KineticWell<T, W>, &T) {
        self.0.swap_get(well, ordering)
    }
}
impl<T: Unpin, W: PotentialWell> PotentialAtomic<T, W>
where
    KineticWell<T, W>: StrongWellMut + Deref<Target = T>,
{
    /// Loads the inner data as a mutable reference.
    ///
    /// This performs a non-atomic access since the atomic is mutably borrowed.
    #[inline]
    pub fn load_mut(&mut self) -> &mut T {
        self.0.load_mut()
    }
}
impl<T, W: PotentialWell> PotentialAtomic<T, Pin<W>>
where
    KineticWell<T, W>: StrongWellMut + Deref<Target = T>,
    Pin<W>: PotentialWell<Well<T> = Pin<KineticWell<T, W>>>,
{
    /// Loads the inner data as a mutable reference.
    ///
    /// This is a version of [`load_mut`] that works with pinned values.
    ///
    /// [`load_mut`]: PotentialAtomicOption::load_mut
    #[inline]
    pub fn load_mut_pinned(&mut self) -> Pin<&mut T> {
        self.0.load_mut_pinned()
    }
}
impl<T, W: PotentialWell> PotentialAtomic<T, W>
where
    KineticWell<T, W>: Clone,
{
    /// Loads a clone of the inner data.
    ///
    /// This still performs an atomic [`load`], but instead of offering a reference, the smart
    /// pointer is cloned instead.
    ///
    /// [`load`]: AtomicPtr::load
    #[inline]
    pub fn load_clone(&self, ordering: Ordering) -> KineticWell<T, W> {
        self.0.load_clone(ordering)
    }
}
impl<T, W: PotentialWell> fmt::Debug for PotentialAtomic<T, W>
where
    KineticWell<T, W>: fmt::Debug,
{
    #[inline]
    #[cfg_attr(any(coverage_nightly, feature = "nightly"), coverage(off))]
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        fmt::Debug::fmt(&self.0, f)
    }
}