loopcell 1.0.0

//! [qcell]: https://docs.rs/qcell/latest/qcell/
//! [ghost_cell]: https://docs.rs/ghost-cell/latest/ghost_cell/
//!
//! 
//! [LoopCell]: `LoopCell`
//! [LoopSyncCell]: `LoopSyncCell`
#![doc = include_str!("../README.md")]
#![cfg_attr(not(test), no_std)]

use core::{
    cell::Cell,
    fmt::Debug,
    mem,
    ops::{Deref, DerefMut},
};

use option_lock::OptionLock;

/// Specialized cell for building iterators that handle a value (such as a shared buffer), make it
/// available for processing, modification, etc., and then it needs to be available for the next
/// iteration. Access is performed by [`LoopCell::access`].
///
/// Because [`Cell`] is not [`Sync`], the [`LoopCellAccess`] for [`LoopCell`]s are not [`Send`].
/// This is particularly important when writing [`core::future::Future`]s and asynchronous code,
/// which is often a place where you'd want this (e.g. handling streams of events). In that case,
/// you want [`LoopSyncCell`].
///
/// Unlike the internal cell data (which uses an [`Option`]), this cell type only implements [`Default`]
/// if the type parameter implements [`Default`], and contains the relevant default value.
///
/// If you access the [`LoopCell`] while something else is holding on to the [`LoopCell`] value,
/// then you will not be able to obtain a value. You can also
/// [create an empty `LoopCell` that cannot provide any access][LoopCell::new_empty]
#[repr(transparent)]
pub struct LoopCell<T>(Cell<Option<T>>);

impl<T> LoopCell<T> {
    /// Create a new [`LoopCell`] with the given value
    #[inline]
    pub const fn new(initial_value: T) -> Self {
        Self(Cell::new(Some(initial_value)))
    }

    /// Create a new [`LoopCell`] using the default value of the type it holds
    #[inline]
    pub fn new_default() -> Self
    where
        T: Default,
    {
        Self::default()
    }

    /// Create a new, empty [`LoopCell`] that can never provide a value.
    #[inline]
    pub const fn new_empty() -> Self {
        Self(Cell::new(None))
    }

    /// Attempt to access the loop cell, producing an accessor that will write back any changes to
    /// the cell once it is dropped (unless it's manually disarmed).
    ///
    /// Only produces [`Some`] if no other accessors are using this [`LoopCell`]
    #[inline]
    pub fn access(&self) -> Option<LoopCellAccess<'_, T>> {
        let maybe_available = self.0.replace(None);
        maybe_available.map(|value| LoopCellAccess::new(self, value))
    }
}

impl<T: Copy + Debug> Debug for LoopCell<T> {
    #[inline]
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_tuple("LoopCell").field(&self.0).finish()
    }
}

impl<T> From<T> for LoopCell<T> {
    #[inline]
    fn from(value: T) -> Self {
        Self(Cell::new(Some(value)))
    }
}

impl<T: Default> Default for LoopCell<T> {
    #[inline]
    fn default() -> Self {
        Self::new(Default::default())
    }
}

/// Accessor for a [`LoopCell`], that will automatically write back any modifications to `T`
/// when dropped (or manually committed), unless you deliberately disarm it with
/// [`LoopCellAccess::consume`] to make it so the [`LoopCell`] is "used up".
///
/// The [`Send`]-equivalent form is [`LoopSyncCellAccess`]
#[clippy::has_significant_drop]
pub struct LoopCellAccess<'cell, T> {
    /// The actual loop cell. When creating this structure, this should now have [`None`] in it, as
    /// the loop accessor (self) holds the `T`.
    loop_cell: &'cell LoopCell<T>,
    /// The value of the cell, directly.
    ///
    /// This is **always [`Some`] except during drop or discard/consume**.
    value: Option<T>,
}

impl<'cell, T> LoopCellAccess<'cell, T> {
    /// Build a new [`LoopCellAccess`] from the cell, and the value that was extracted from it.
    ///
    /// This is an internal function.
    #[inline]
    const fn new(cell: &'cell LoopCell<T>, value: T) -> Self {
        Self {
            loop_cell: cell,
            value: Some(value),
        }
    }

    /// Consume the accessor and commit the changes made to the [`LoopCell`]'s value, making the
    /// value available once again to anyone trying to get it via [`LoopCell::access`]. Equivalent
    /// to [`mem::drop`]
    #[inline]
    pub fn commit(self) {
        mem::drop(self)
    }

    /// Consume the accessor, but do not write the value to the [`LoopCell`]. This will leave the
    /// [`LoopCell`] in such a state that it can no longer ever provide values.
    ///
    /// This returns the value itself as-per it's modifications.
    #[inline]
    pub fn consume(mut self) -> T {
        self.value
            .take()
            .expect("value inside loop cell accessor should always be Some")
    }

    /// Get a version of this capable of being mapped.
    #[inline]
    pub fn into_mapped_access(self) -> LoopCellMappedAccess<'cell, T, ()> {
        self.into()
    }

    /// Directly map this bare [`LoopCellAccess`] into one that is "mapped" to another value.
    #[inline]
    pub fn map_loopcell_access<O>(
        mut self,
        f: impl FnOnce(&mut T) -> O,
    ) -> LoopCellMappedAccess<'cell, T, O> {
        let o = f(&mut self);
        LoopCellMappedAccess {
            bare_access: self,
            value: o,
        }
    }

    /// Get the value of the loopcell from the access
    #[inline]
    pub fn as_loopcell_value(&self) -> &T {
        self
    }

    /// Get the value of the loopcell from the access, mutably.
    #[inline]
    pub fn as_loopcell_value_mut(&mut self) -> &mut T {
        self
    }
}

impl<'cell, T: Debug> Debug for LoopCellAccess<'cell, T> {
    #[inline]
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("LoopCellAccess")
            .field("loop_cell", &"<opaque>")
            .field("value", &self.value)
            .finish()
    }
}

impl<'cell, T> Deref for LoopCellAccess<'cell, T> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &T {
        self.value
            .as_ref()
            .expect("value should always be Some inside loopcell accessor")
    }
}

impl<'cell, T> DerefMut for LoopCellAccess<'cell, T> {
    #[inline]
    fn deref_mut(&mut self) -> &mut T {
        self.value
            .as_mut()
            .expect("value should always be Some inside loopcell accessor")
    }
}

impl<'cell, T> AsRef<T> for LoopCellAccess<'cell, T> {
    #[inline]
    fn as_ref(&self) -> &T {
        self
    }
}

impl<'cell, T> AsMut<T> for LoopCellAccess<'cell, T> {
    #[inline]
    fn as_mut(&mut self) -> &mut T {
        self
    }
}

impl<'cell, T> Drop for LoopCellAccess<'cell, T> {
    fn drop(&mut self) {
        // If we've not been disarmed, then set the value
        if let Some(v) = self.value.take() {
            self.loop_cell.0.set(Some(v))
        }
    }
}

/// Accessor for a [`LoopCell`], that will automatically write back any modifications to the value
/// on drop (unless disarmed with [`LoopCellMappedAccess::consume`]) so the [`LoopCell`] is "used
/// up".
///
/// Unlike [`LoopCellAccess`], this contains an extra value, and lets you perform modifications to
/// it with the "context" of the loop cell accessor (which is mutable).
///
/// This provides a clean way to bundle an accessor and also bundle a data value, which should be
/// processed with the accessor.
#[clippy::has_significant_drop]
pub struct LoopCellMappedAccess<'cell, T, V = ()> {
    /// Bare accessor. This handles all the relevant drop code.
    bare_access: LoopCellAccess<'cell, T>,
    /// Value "paired" with the loop cell access.
    value: V,
}

impl<'cell, T, V> LoopCellMappedAccess<'cell, T, V> {
    /// Apply a function to the mapped value, to produce a new mapped value - but it also makes the
    /// inner loop cell value that we have access to available.
    #[inline]
    pub fn map_loopcell_access<O>(
        self,
        f: impl FnOnce(&mut T, V) -> O,
    ) -> LoopCellMappedAccess<'cell, T, O> {
        let Self {
            mut bare_access,
            value,
        } = self;
        let o = f(&mut bare_access, value);
        LoopCellMappedAccess {
            bare_access,
            value: o,
        }
    }

    /// Commit the changes made to the [`LoopCell`] through this accessor, making the [`LoopCell`]
    /// available to everyone once again with the new cell data, while also emitting the bundled value.
    #[inline]
    pub fn commit(self) -> V {
        self.bare_access.commit();
        self.value
    }

    /// Consume the changes made to the [`LoopCell`] through this accessor, making the [`LoopCell`]
    /// never have any more values. This returns the last value of the [`LoopCell`] as modified by
    /// this accessor, as well as the bundled value.
    #[inline]
    pub fn consume(self) -> (T, V) {
        let cell_v = self.bare_access.consume();
        (cell_v, self.value)
    }

    /// Get the value of the loopcell from the access
    #[inline]
    pub fn get_loopcell_value(&self) -> &T {
        &self.bare_access
    }

    /// Get the value of the loopcell from the access, mutably.
    #[inline]
    pub fn get_loopcell_value_mut(&mut self) -> &mut T {
        &mut self.bare_access
    }

    /// Get the bundled value from the access
    #[inline]
    pub fn get_value(&self) -> &V {
        &self.value
    }

    /// Get the bundled value from the access, mutably.
    #[inline]
    pub fn get_value_mut(&mut self) -> &mut V {
        &mut self.value
    }

    #[inline]
    /// Unpack the bundled value from the normal [`LoopCellAccess`]
    pub fn unmap_access(self) -> (LoopCellAccess<'cell, T>, V) {
        (self.bare_access, self.value)
    }
}

impl<'cell, T, V: Default> From<LoopCellAccess<'cell, T>> for LoopCellMappedAccess<'cell, T, V> {
    #[inline]
    fn from(bare_access: LoopCellAccess<'cell, T>) -> Self {
        Self {
            bare_access,
            value: Default::default(),
        }
    }
}

impl<'cell, T, V> Deref for LoopCellMappedAccess<'cell, T, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.get_value()
    }
}

impl<'cell, T, V> DerefMut for LoopCellMappedAccess<'cell, T, V> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.get_value_mut()
    }
}

impl<'cell, T, V> AsRef<V> for LoopCellMappedAccess<'cell, T, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        self
    }
}

impl<'cell, T, V> AsMut<V> for LoopCellMappedAccess<'cell, T, V> {
    #[inline]
    fn as_mut(&mut self) -> &mut V {
        self
    }
}

/// Specialized cell for when you want to build an iterator that produces a value, to then be
/// modified and used, but then finally made available for the next iteration. The value of this
/// cell can be restored from an accessor on a different thread to the one where it was taken (i.e.
/// it is [`Sync`]).
///
/// This form is particularly useful when writing asynchronous event processors with shared data,
/// where you might need to hold an access across an await point. It is an alternative to
/// [`LoopCell`], and is likely to be used often.
///
/// Unlike the underlying [`option_lock::OptionLock`], this only implements [`Default`] if the type
/// parameter `T` implements [`Default`], and it is created with the default value of `T` in that
/// case. Also note that [`option_lock::OptionLock`] is implemented entirely with atomics - it's
/// very lightweight and doesn't carry the overhead of allocation or normal mutex. This is
/// essentially close to the most minimal equivalent to how we use `Cell<Option<T>>` in [`LoopCell`].
///
/// If you access the [`LoopSyncCell`] while something else is holding on to an accessor, then you
/// won't be able to get any access. If something else deliberately consumes it's accessor, then
/// you will not be able to get any values out of this any more. You can also
/// [create a `LoopSyncCell` which cannot have anything retrieved][LoopSyncCell::new_empty]
// The internal lock here is only held for very short periods of time (for taking and then
// restoring). This is why we tolerate spinlocking, as it's an extremely ephemeral lock. This type
// only ever permits exactly one accessor to actually exist at a time with `Some` in it.
#[repr(transparent)]
pub struct LoopSyncCell<T>(OptionLock<T>);

impl<T> LoopSyncCell<T> {
    /// Create a new [`LoopSyncCell`] with the given value
    #[inline]
    pub const fn new(initial_value: T) -> Self {
        Self(OptionLock::new(initial_value))
    }

    /// Create a new [`LoopSyncCell`] using the default value of the type it holds
    #[inline]
    pub fn new_default() -> Self
    where
        T: Default,
    {
        Self::default()
    }

    /// Create a new, empty [`LoopSyncCell`] that can never provide a value.
    #[inline]
    pub const fn new_empty() -> Self {
        Self(OptionLock::empty())
    }

    /// Attempt to access the loop cell, producing an accessor that will write back any changes to
    /// the cell once it is dropped (unless it's manually disarmed).
    ///
    /// Only produces [`Some`] if no other accessors are using this [`LoopSyncCell`]
    #[inline]
    pub fn access(&self) -> Option<LoopSyncCellAccess<'_, T>> {
        // Spinlock is ok because the lock is only ever held very ephemerally.
        let maybe_available = self.0.spin_lock().take();
        maybe_available.map(|value| LoopSyncCellAccess::new(self, value))
    }
}

impl<T: Copy + Debug> Debug for LoopSyncCell<T> {
    #[inline]
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_tuple("LoopSyncCell").field(&self.0).finish()
    }
}

impl<T> From<T> for LoopSyncCell<T> {
    #[inline]
    fn from(value: T) -> Self {
        Self::new(value)
    }
}

impl<T: Default> Default for LoopSyncCell<T> {
    #[inline]
    fn default() -> Self {
        Self::new(T::default())
    }
}

/// Accessor for a [`LoopSyncCell`], that will automatically write back any modifications to `T`
/// when dropped (or manually committed), unless you deliberately disarm it with
/// [`LoopSyncCellAccess::consume`] to make it so the [`LoopSyncCell`] is "used up".
#[clippy::has_significant_drop]
pub struct LoopSyncCellAccess<'cell, T> {
    /// The actual loop cell. When creating this structure, this should now have [`None`] in it, as
    /// the loop accessor (self) holds the `T`.
    loop_cell: &'cell LoopSyncCell<T>,
    /// The value of the cell, directly.
    ///
    /// This is **always [`Some`] except during drop or discard/consume**.
    value: Option<T>,
}

impl<'cell, T> LoopSyncCellAccess<'cell, T> {
    /// Build a new [`LoopSyncCellAccess`] from the cell, and the value that was extracted from it.
    ///
    /// This is an internal function.
    #[inline]
    const fn new(cell: &'cell LoopSyncCell<T>, value: T) -> Self {
        Self {
            loop_cell: cell,
            value: Some(value),
        }
    }

    /// Consume the accessor and commit the changes made to the [`LoopSyncCell`]'s value, making the
    /// value available once again to anyone trying to get it via [`LoopSyncCell::access`]. Equivalent
    /// to [`mem::drop`]
    #[inline]
    pub fn commit(self) {
        mem::drop(self)
    }

    /// Consume the accessor, but do not write the value to the [`LoopSyncCell`]. This will leave the
    /// [`LoopSyncCell`] in such a state that it can no longer ever provide values.
    ///
    /// This returns the value itself as-per it's modifications.
    #[inline]
    pub fn consume(mut self) -> T {
        self.value
            .take()
            .expect("value inside loop cell accessor should always be Some")
    }

    /// Get a version of this capable of being mapped.
    #[inline]
    pub fn into_mapped_access(self) -> LoopSyncCellMappedAccess<'cell, T, ()> {
        self.into()
    }

    /// Directly map this bare [`LoopSyncCellAccess`] into one that is "mapped" to another value.
    #[inline]
    pub fn map_loopcell_access<O>(
        mut self,
        f: impl FnOnce(&mut T) -> O,
    ) -> LoopSyncCellMappedAccess<'cell, T, O> {
        let o = f(&mut self);
        LoopSyncCellMappedAccess {
            bare_access: self,
            value: o,
        }
    }

    /// Get the value of the loopcell from the access
    #[inline]
    pub fn as_loopcell_value(&self) -> &T {
        self
    }

    /// Get the value of the loopcell from the access, mutably.
    #[inline]
    pub fn as_loopcell_value_mut(&mut self) -> &mut T {
        self
    }
}

impl<'cell, T: Debug> Debug for LoopSyncCellAccess<'cell, T> {
    #[inline]
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("LoopSyncCellAccess")
            .field("loop_cell", &"<opaque>")
            .field("value", &self.value)
            .finish()
    }
}

impl<'cell, T> Deref for LoopSyncCellAccess<'cell, T> {
    type Target = T;

    #[inline]
    fn deref(&self) -> &T {
        self.value
            .as_ref()
            .expect("value should always be Some inside loopcell accessor")
    }
}

impl<'cell, T> DerefMut for LoopSyncCellAccess<'cell, T> {
    #[inline]
    fn deref_mut(&mut self) -> &mut T {
        self.value
            .as_mut()
            .expect("value should always be Some inside loopcell accessor")
    }
}

impl<'cell, T> AsRef<T> for LoopSyncCellAccess<'cell, T> {
    #[inline]
    fn as_ref(&self) -> &T {
        self
    }
}

impl<'cell, T> AsMut<T> for LoopSyncCellAccess<'cell, T> {
    #[inline]
    fn as_mut(&mut self) -> &mut T {
        self
    }
}

impl<'cell, T> Drop for LoopSyncCellAccess<'cell, T> {
    fn drop(&mut self) {
        // While `self.value` is almost always `Some`, if we've been disarmed then it will be `None`. No point in spinlocking if there is nothing there.
        if let Some(v) = self.value.take() {
            // spinlock is ok because this is very ephemeral - note that the value returned "should" be `None` as only one thing can take out of the loop sync cell at once.
            self.loop_cell.0.spin_lock().replace(v);
        }
    }
}

/// Accessor for a [`LoopSyncCell`], that will automatically write back any modifications to the value
/// on drop (unless disarmed with [`LoopSyncCellMappedAccess::consume`]) so the [`LoopSyncCell`] is "used
/// up".
///
/// Unlike [`LoopSyncCellAccess`], this contains an extra value, and lets you perform modifications to
/// it with the "context" of the loop cell accessor (which is mutable).
///
/// This provides a clean way to bundle an accessor and also bundle a data value, which should be
/// processed with the accessor.
#[clippy::has_significant_drop]
pub struct LoopSyncCellMappedAccess<'cell, T, V = ()> {
    /// Bare accessor. This handles all the relevant drop code.
    bare_access: LoopSyncCellAccess<'cell, T>,
    /// Value "paired" with the loop cell access.
    value: V,
}

impl<'cell, T, V> LoopSyncCellMappedAccess<'cell, T, V> {
    /// Apply a function to the mapped value, to produce a new mapped value - but it also makes the
    /// inner loop cell value that we have access to available.
    #[inline]
    pub fn map_loopcell_access<O>(
        self,
        f: impl FnOnce(&mut T, V) -> O,
    ) -> LoopSyncCellMappedAccess<'cell, T, O> {
        let Self {
            mut bare_access,
            value,
        } = self;
        let o = f(&mut bare_access, value);
        LoopSyncCellMappedAccess {
            bare_access,
            value: o,
        }
    }

    /// Commit the changes made to the [`LoopSyncCell`] through this accessor, making the [`LoopSyncCell`]
    /// available to everyone once again with the new cell data, while also emitting the bundled value.
    #[inline]
    pub fn commit(self) -> V {
        self.bare_access.commit();
        self.value
    }

    /// Consume the changes made to the [`LoopSyncCell`] through this accessor, making the [`LoopSyncCell`]
    /// never have any more values. This returns the last value of the [`LoopSyncCell`] as modified by
    /// this accessor, as well as the bundled value.
    #[inline]
    pub fn consume(self) -> (T, V) {
        let cell_v = self.bare_access.consume();
        (cell_v, self.value)
    }

    /// Get the value of the loopcell from the access
    #[inline]
    pub fn get_loopcell_value(&self) -> &T {
        &self.bare_access
    }

    /// Get the value of the loopcell from the access, mutably.
    #[inline]
    pub fn get_loopcell_value_mut(&mut self) -> &mut T {
        &mut self.bare_access
    }

    /// Get the bundled value from the access
    #[inline]
    pub fn get_value(&self) -> &V {
        &self.value
    }

    /// Get the bundled value from the access, mutably.
    #[inline]
    pub fn get_value_mut(&mut self) -> &mut V {
        &mut self.value
    }

    #[inline]
    /// Unpack the bundled value from the normal [`LoopSyncCellAccess`]
    pub fn unmap_access(self) -> (LoopSyncCellAccess<'cell, T>, V) {
        (self.bare_access, self.value)
    }
}

impl<'cell, T, V: Default> From<LoopSyncCellAccess<'cell, T>>
    for LoopSyncCellMappedAccess<'cell, T, V>
{
    #[inline]
    fn from(bare_access: LoopSyncCellAccess<'cell, T>) -> Self {
        Self {
            bare_access,
            value: Default::default(),
        }
    }
}

impl<'cell, T, V> Deref for LoopSyncCellMappedAccess<'cell, T, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self.get_value()
    }
}

impl<'cell, T, V> DerefMut for LoopSyncCellMappedAccess<'cell, T, V> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        self.get_value_mut()
    }
}

impl<'cell, T, V> AsRef<V> for LoopSyncCellMappedAccess<'cell, T, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        self
    }
}

impl<'cell, T, V> AsMut<V> for LoopSyncCellMappedAccess<'cell, T, V> {
    #[inline]
    fn as_mut(&mut self) -> &mut V {
        self
    }
}

// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.