instance_copy_on_write/

cow_mutex.rs

/*-
 * instance-copy-on-write - a synchronization primitive based on copy-on-write.
 * 
 * Copyright (C) 2025 Aleksandr Morozov alex@
 * 
 * The scram-rs crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. the Mozilla Public License Version 2.0 (the “MPL”) OR
 *                     
 *   2. EUROPEAN UNION PUBLIC LICENCE v. 1.2 EUPL © the European Union 2007, 2016
 */

#[cfg(test)]
use std::sync::Weak;
use std::{fmt, ops::{Deref, DerefMut}, sync::{atomic::{AtomicBool, AtomicI32, Ordering}, Arc, RwLock, RwLockWriteGuard, TryLockError}};

use crossbeam_utils::Backoff;

use crate::{ICoWError, ICoWLockTypes};


/// A read only guard. Implements [Deref] only. The guarded value is valid
/// all the time, even if the inner value was updated. The updated value
/// will not be visible in the current instance until `re-read` is
/// performed.
#[derive(Debug)]
pub struct ICoWRead<'read, ITEM: fmt::Debug + Send>
{
    /// Guarded value.
    pub(crate) item: Arc<ITEM>,

    /// A bind to base.
    bind: &'read ICoW<ITEM>
}

#[cfg(test)]
impl<'read, ITEM: fmt::Debug + Send> ICoWRead<'read, ITEM>
{
    pub(crate) 
    fn weak(&self) -> Weak<ITEM>
    {
        return Arc::downgrade(&self.item);
    }
}

impl<'read, ITEM: fmt::Debug + Send> Deref for ICoWRead<'read, ITEM>
{
    type Target = ITEM;

    fn deref(&self) -> &Self::Target
    {
        return &self.item;
    }
}

impl<'read, ITEM: fmt::Debug + Send> ICoWRead<'read, ITEM>
{
    pub 
    fn into_inner(self) -> Arc<ITEM>
    {
        return self.item;
    }
}

/// A write-guard which holds new value to which the new values are written. And
/// previous value too. This type of guard is not exclusive, so it does not prevent
/// multiple CoW operations. Normally, if some object which may be written 
/// simultaniously i.e lost connection to remote server and reconnect is required,
/// the `exclusive` lock would be more desirable.
#[derive(Debug)]
pub struct ICoWCopy<'copy, ITEM: fmt::Debug + Send>
{
    /// A reference to previous value
    prev_item: ICoWRead<'copy, ITEM>,
    
    /// A freshly createc/copied/clonned item
    new_item: ITEM,

    /// A reference to base to avoid Send.
    inst: &'copy ICoW<ITEM>
}

impl<'copy, ITEM: fmt::Debug + Send> Deref for ICoWCopy<'copy, ITEM>
{
    type Target = ITEM;

    fn deref(&self) -> &Self::Target
    {
        return &self.new_item;
    }
}

impl<'copy, ITEM: fmt::Debug + Send> DerefMut for ICoWCopy<'copy, ITEM>
{
    fn deref_mut(&mut self) -> &mut Self::Target
    {
        return &mut self.new_item
    }
}

impl<'copy, ITEM: fmt::Debug + Send> ICoWCopy<'copy, ITEM>
{
    /// Returns a reference to previous value. To access modified version use
    /// [Deref] or [DerefMut].
    pub 
    fn prev_val(&self) -> &ITEM
    {
        return &self.prev_item;
    }

    /// Commits the changes made in the guarded variable. A non-blocking
    /// function. It will not block the thread completly and returns the
    /// [ICoWError::WouldBlock] if attempt to grab the pointer atomically 
    /// fails.
    /// 
    /// # Returns
    /// 
    /// The [Result::Err] is returned with:
    /// 
    /// * `0` - [ICoWError] with the error type.
    /// 
    /// * `1` - [ICoWCopy] instance itself.
    /// 
    /// Error types [ICoWError]:
    /// 
    /// * [ICoWError::ExclusiveLockPending] - if exclusivly locked from another thread.
    /// 
    /// * [ICoWError::WouldBlock] - `atomic only!` if "exponential backoff has completed and blocking the thread is advised".
    pub 
    fn commit(self) -> Result<(), (ICoWError, Self)>
    {
        let write_lock = 
            self
                .inst
                .inner
                .try_write();
                //.unwrap_or_else(|e| e.into_inner());

        let mut lock = 
            match write_lock
            {
                Ok(lock) => 
                    lock,
                Err(TryLockError::Poisoned(lock_err)) => 
                    lock_err.into_inner(),
                Err(TryLockError::WouldBlock) => 
                {
                    if self.inst.exclusivly_locked.load(Ordering::Relaxed) == 1
                    {
                        return Err((ICoWError::ExclusiveLockPending, self));
                    }
                    else
                    {
                        return Err((ICoWError::WouldBlock, self));
                    }
                }
            };

        *lock = Arc::new(self.new_item);

        return Ok(());
    }

    /// Commits the changes to the mainstream instance of [ICoW]. A partially 
    /// non-blocking function. It would wait for an exclusive access ignoring 
    /// the [ICoWError::WouldBlock]  only if the instance is not locked 
    /// exclusivly.
    /// 
    /// If [Result::Err] is returned, the instance is locked exclusivly.
    ///  
    /// # Returns
    /// 
    /// The [Result::Err] is returned with:
    /// 
    /// [ICoWCopy] commited instance itself.
    pub 
    fn commit_blocking(self) -> Result<(), Self>
    {
        if self.inst.exclusivly_locked.load(Ordering::Relaxed) == 1
        {
            return Err(self);
        }

        let mut write_lock = 
            self
                .inst
                .inner
                .write()
                .unwrap_or_else(|e| e.into_inner());

        *write_lock = Arc::new(self.new_item);

        return Ok(());
    }   

    /// Drops the instance without commiting changes returning 
    /// a copy, clone, default, or new i.e what was in the `new` field
    /// of the instance.
    pub 
    fn into_inner(self) -> ITEM
    {
        return self.new_item;
    }
}

/// A write-guard which holds new value to which the new values are written. And
/// previous value too. This type of guard is exclusive, so multiple
/// CoW operations **CANNOT** be performed in parallel which is good for instance 
/// update without racing. The readers are also waiting until the changes are 
/// commited.
#[derive(Debug)]
pub struct ICoWLock<'lock, ITEM: fmt::Debug + Send>
{
    /// An exclusive lock in the previous value.
    prev_item: RwLockWriteGuard<'lock, Arc<ITEM>>,

    /// A freshly createc/copied/clonned item
    pub(crate) item: ITEM,

    /// A reference to base to avoid Send.
    inst: &'lock ICoW<ITEM>
}

impl<'lock, ITEM: fmt::Debug + Send> ICoWLock<'lock, ITEM>
{
    /// Returns a reference to previous value. To access modified version use
    /// [Deref] or [DerefMut].
    pub 
    fn prev_val(&self) -> &ITEM
    {
        return self.prev_item.as_ref();
    }

    /// Commits the changes made in the guarded variable.
    /// 
    /// # Returns
    /// 
    /// Always returns [Result::Ok], but the `atomic` realization
    /// would return [Result::Err] if:
    /// 
    /// > The [Result::Err] is retruned if race condition happens i.e when 
    /// > updating the inner atomic ptr fails because someone have already 
    /// > changed the value.
    #[inline]
    pub 
    fn commit(mut self)
    {
        *self.prev_item = Arc::new(self.item);

        return;
    }

    /// Commits the changes made in the guarded variable and 
    /// returning the atomic reference [Arc] to previous.
    #[inline]
    pub 
    fn commit_wiht_into_inner(mut self) -> Arc<ITEM>
    {
        let prev = self.prev_item.clone();

        *self.prev_item = Arc::new(self.item);

        return prev;
    }
}

impl<'lock, ITEM: fmt::Debug + Send> Deref for ICoWLock<'lock, ITEM>
{
    type Target = ITEM;

    fn deref(&self) -> &Self::Target
    {
        return &self.item;
    }
}

impl<'lock, ITEM: fmt::Debug + Send> DerefMut for ICoWLock<'lock, ITEM>
{
    fn deref_mut(&mut self) -> &mut Self::Target
    {
        return &mut self.item
    }
}

/// A main structure which implements CoW approach based on [RwLock] for the
/// multithreading syncing.  The object stored inside can be read directly, but 
/// modifying the `inner` value is performed using `CoW` copy-on-write approach. 
/// 
/// The inner value must either [Copy], [Clone], [Default], or provide 
/// new value manually. The copied value is modified and stored back either
/// shared or exclusive method. The exclusive lock prevents other CoW operations
/// guaranteeing the uniq write access.
/// 
/// ```ignore
/// #[derive(Debug, Clone)]
/// struct TestStruct { s: u32 }
/// 
/// let cow_val = ICoW::new(TestStruct{ s: 2 });
/// 
/// // read
/// let read0 = cow_val.read().unwrap();
/// // ...
/// drop(read0);
/// 
/// // write new non-exclusivly
/// let mut write0 = cow_val.try_clone().unwrap();
/// write0.s = 3;
/// 
/// write0.commit().unwrap();
/// 
/// // write new exclusivly
/// let mut write0 = cow_val.try_clone_exclusivly().unwrap();
/// write0.s = 3;
/// 
/// write0.commit().unwrap(); 
/// 
/// ```
#[derive(Debug)]
pub struct ICoW<ITEM: fmt::Debug + Send>
{
    /// A rwlock protected CoW.
    inner: RwLock<Arc<ITEM>>,

    /// Helps to detect if instance locked exclusivly or normal
    /// write operation. This is needed to be in sync with atomics-based
    /// version which is able to detect this. It is needed if one
    /// thread copied the instance and attempts to commit changes while
    /// being locked exclusivly after the normal copy was performed.
    exclusivly_locked: AtomicI32,
}

impl<ITEM: fmt::Debug + Send> ICoW<ITEM>
{
    /// Initalizes a new instance.
    pub 
    fn new(item: ITEM) -> Self
    {
        return 
            Self
            { 
                inner: 
                    RwLock::new(Arc::new(item)),
                exclusivly_locked:
                    AtomicI32::new(0),
            }
    }

    /// Returns the syncing meachanism.
    pub 
    fn get_lock_type() -> ICoWLockTypes
    {
        return ICoWLockTypes::RwLock;
    }
}

impl<ITEM: fmt::Debug + Send> ICoW<ITEM>
{
    /// Attempts to read the inner value returning the guard. This function 
    /// blocks the current thread until the value becomes available. This
    /// can happen if exclusive copy-on-write is in progress.
    /// 
    /// # Returns 
    /// 
    /// An instance with clonned reference is returned.
    pub 
    fn read(&self) -> ICoWRead<'_, ITEM>
    {
        let lock = 
            self
                .inner
                .read()
                .unwrap_or_else(|e| e.into_inner());

        return ICoWRead{ item: lock.clone(), bind: self };
    }

    /// Attempts to read the inner value, returning the read guard in case of success. 
    /// This function does not block the current thread until the value becomes available. 
    /// This function fails if exclusive copy-on-write is in progress.
    /// 
    /// But, this fucntion would block the thread until the [Backoff] reports
    /// that it is recomended to park the thread.
    /// 
    /// # Returns 
    /// 
    /// A [Option] is retrurned. The [Option::None] is returned if operation
    /// would block for a long time. 
    pub 
    fn try_read(&self) -> Option<ICoWRead<'_, ITEM>>
    {
        let lock_res = 
            self
                .inner
                .try_read();

        match lock_res 
        {
            Ok(lock) => 
            {
                return Some(ICoWRead{ item: lock.clone(), bind: self });
            },
            Err(TryLockError::WouldBlock)=>
            {
                return None;
            },
            Err(TryLockError::Poisoned(lock)) =>
            {
                return Some(ICoWRead{ item: lock.into_inner().clone(), bind: self });
            }
        }
    }

    /// Forces the **exclusive** Copy-on-Write to prevent duplicate
    /// writing. It means that if any other thread is holding an exclusive CoW
    /// this function will block until other thread releases or commits the 
    /// changes.
    /// 
    /// # Returns
    /// 
    /// Always returns [ICoWLock].
    pub 
    fn new_exclusivly(&self, new_item: ITEM) -> ICoWLock<'_, ITEM>
    {
        let write_lock =  
            self
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);
        
        return 
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self };
    }

    /// Attempts to grab the **exclusive** Copy-on-Write to prevent duplicate
    /// writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Result] is returned where the [Option::None] is returned if
    /// an exclusive CoW lock have already been issued.
    pub 
    fn try_new_exclusivly(&self, new_item: ITEM) -> Result<ICoWLock<'_, ITEM>, ITEM>
    {
        let write_lock =  
            match self.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return Err(new_item),
            };
        
        return Ok(
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self }
        );
    }

    /// Attempts to update old value to new value for the inner.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline. And does not block if the write access
    /// is not available now due to the exclusive lock pending.
    /// 
    /// Does not return guard. Updates the value in-place.
    /// 
    /// # Returns
    /// 
    /// A [Result] is returned where the [Result::Err] is returned with:
    /// 
    /// * [ICoWError::ExclusiveLockPending] - if exclsive write already pending.
    /// 
    /// * errors which are returned by [ICoWCopy::commit()].
    pub 
    fn try_new_inplace(&self, new_item: ITEM) -> Result<(), (ICoWError, ITEM)>
    {
        if let Some(read) = self.try_read()
        {
            let ret = 
                ICoWCopy
                { 
                    prev_item: read, 
                    new_item: new_item, 
                    inst: self 
                };

            return ret.commit().map_err(|e| (e.0, e.1.new_item));
        }
        else
        {
            return Err((ICoWError::WouldBlock, new_item));
        }
    }

    /// Attempts to update old value to new value for the inner
    /// **exclusively**.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline.
    /// 
    /// Does not return guard. Updates the value in-place.
    /// 
    /// # Returns
    /// 
    /// A [Result] is returned where the [Result::Err] is returned with:
    /// 
    /// * [ICoWError::ExclusiveLockPending] - if exclsive write already pending.
    /// 
    /// * [ICoWError::AlreadyUpdated] - if duplicate write operation attempt.
    /// 
    /// * [ICoWError::RaceCondition] - a race condition detected during update.
    /// 
    /// * errors which are returned by [ICoWCopy::commit()].
    pub 
    fn try_new_exclusivly_inplace(&self, new_item: ITEM) -> Result<(), (ICoWError, ITEM)>
    {
        
        let write_lock =  
            match self.inner.try_write()
            {
                Ok(lock) => 
                    lock,
                Err(TryLockError::Poisoned(e)) => 
                    e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return Err((ICoWError::ExclusiveLockPending, new_item))
            };
        
        let ret =
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self };
        
        ret.commit();

        return Ok(());
    }
}

impl<ITEM: fmt::Debug + Send + Copy> ICoW<ITEM>
{
    /// Performs the copy of the inner value for writing.
    /// 
    /// Blocking function i.e always retruns the result.
    /// 
    /// # Returns
    /// 
    /// An [ICoWCopy] is returned.
    pub 
    fn copy(&self) -> ICoWCopy<'_, ITEM>
    {
        let read = self.read();

        let new_item = *read.item.as_ref();

        let ret = 
            ICoWCopy
            { 
                prev_item: read, 
                new_item: new_item, 
                inst: self 
            };

        return ret;
    }

    /// Attempts to perform the copy of the inner value for writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// copy before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// it failed.
    pub 
    fn try_copy(&self) -> Option<ICoWCopy<'_, ITEM>>
    {
        let read = self.try_read()?;

        let new_item = *read.item.as_ref();

        let ret = 
            ICoWCopy
            { 
                prev_item: read, 
                new_item: new_item, 
                inst: self 
            };

        return Some(ret);
    }

    /// Forces the exclusive locking the CoW instance and copying the content
    /// after lock is aquired. The lock is holded in the inner of the returned
    /// instance.
    /// 
    /// If other thread is holding the exclusive CoW lock, the current thread
    /// will be blocked until lock is released.
    /// 
    /// # Returns
    /// 
    /// Always returns [ICoWLock].
    pub 
    fn copy_exclusivly(&self) -> ICoWLock<'_, ITEM>
    {
        let write_lock =  
            self
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);
        
        let new_item = *write_lock.as_ref(); 

        return 
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self };
    }

    /// Attempts to perform the copy of the inner value for 
    /// **exclusive** writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// copy before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// an exclusive CoW lock have already been issued.
    pub 
    fn try_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
    {

       let write_lock =  
            match self.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return None
            };
        
        let new_item = *write_lock.as_ref(); 
        
        return Some(
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self }
        );
    }
}

impl<ITEM: fmt::Debug + Send + Clone> ICoW<ITEM>
{
    /// Attempts to perform the clone of the inner value for writing.
    /// 
    /// Blocking function i.e always retruns the result.
    /// 
    /// # Returns
    /// 
    /// An [ICoWCopy] is returned.
    pub 
    fn clone(&self) -> ICoWCopy<'_, ITEM>
    {
        let read = self.read();

        let new_item = read.item.as_ref().clone();

        let ret = 
            ICoWCopy
            { 
                prev_item: read, 
                new_item: new_item, 
                inst: self 
            };

        return ret;
    }

    /// Attempts to perform the clone of the inner value for writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// it failed.
    pub 
    fn try_clone(&self) -> Option<ICoWCopy<'_, ITEM>>
    {
        let read = self.try_read()?;

        let new_item = read.item.as_ref().clone();

        let ret = 
            ICoWCopy
            { 
                prev_item: read, 
                new_item: new_item, 
                inst: self 
            };

        return Some(ret);
    }

    /// Forces the exclusive locking the CoW instance and cloning the content
    /// after lock is aquired. The lock is holded in the inner of the returned
    /// instance.
    /// 
    /// If other thread is holding the exclusive CoW lock, the current thread
    /// will be blocked until lock is released.
    /// 
    /// # Returns
    /// 
    /// Always returns [ICoWLock].
    pub 
    fn clone_exclusivly(&self) -> ICoWLock<'_, ITEM>
    {
        let write_lock =  
            self
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);
        
        let new_item = write_lock.as_ref().clone();

        return 
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self };
    }

    /// Attempts to perform the clone of the inner value for 
    /// **exclusive** writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// an exclusive CoW lock have already been issued.
    pub 
    fn try_clone_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
    {
        
        let write_lock =  
            match self.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return None
            };
        
        let new_item = write_lock.as_ref().clone();
        
        return Some(
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self }
        );
    }
}

impl<ITEM: fmt::Debug + Send + Default> ICoW<ITEM>
{
    /// Construct the guard from the [Default] of the inner value for writing.
    /// 
    /// Blocking function i.e always retruns the result.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// it failed.
    pub 
    fn from_default(&self) -> ICoWCopy<'_, ITEM>
    {
        let read = self.read();

        let new_item = ITEM::default();

        let ret = 
            ICoWCopy
            { 
                prev_item: read, 
                new_item: new_item, 
                inst: self 
            };

        return ret;
    }

    /// Attempts to init default of the inner value for writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// it failed.
    pub 
    fn try_default(&self) -> Option<ICoWCopy<'_, ITEM>>
    {
        let read = self.try_read()?;

        let new_item = ITEM::default();

        let ret = 
            ICoWCopy
            { 
                prev_item: read, 
                new_item: new_item, 
                inst: self 
            };

        return Some(ret);
    }

    /// Forces the exclusive locking the CoW instance and create a default instance
    /// after lock is aquired. The lock is holded in the inner of the returned
    /// instance.
    /// 
    /// If other thread is holding the exclusive CoW lock, the current thread
    /// will be blocked until lock is released.
    /// 
    /// # Returns
    /// 
    /// Always returns [ICoWLock].
    pub 
    fn default_exclusivly(&self) -> ICoWLock<'_, ITEM>
    {
        let write_lock =  
            self
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);
        
        let new_item = ITEM::default();

        return 
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self };
    }
      

    /// Attempts to init default of the inner value for 
    /// **exclusive** writing.
    /// 
    /// Non-blocking function i.e returns if it fails to acquire the
    /// clone before some deadline.
    /// 
    /// # Returns
    /// 
    /// An [Option] is returned where the [Option::None] is returned if
    /// an exclusive CoW lock have already been issued.
    pub 
    fn try_default_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
    {
        let write_lock =  
            match self.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return None
            };
        
        let new_item = ITEM::default();
        
        return Some(
            ICoWLock{ prev_item: write_lock, item: new_item, inst: self }
        );
    }
}


#[cfg(test)]
mod test
{
    // mutex based specific tests goes there
}