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@4neko.org
 * 
 * The instance-copy-on-write crate can be redistributed and/or modified
 * under the terms of either of the following licenses:
 *
 *   1. The MIT License (MIT)
 */

/// RwLock based copy-on-write realization.

use std::
{
    cell::{OnceCell, RefCell}, fmt, marker::PhantomData, ops::{Deref, DerefMut}, sync::
    {
        Arc, RwLock, RwLockWriteGuard, TryLockError, Weak, 
        atomic::{AtomicBool, Ordering}
    }
};

use crate::{ICoWError, ICoWLockTypes, ICowType};

/// An instance emmited by the [ICoWWeak::aquire] which allows to read the item for
/// a `'weak` period of time.
/// 
/// # Fields
/// 
/// * `0` - the reference to the stored inner value (read only).
/// 
/// * `1` - the flag which indicates that the `0` was reloaded or not.
/// 
/// * `2` - phantom to prevent `Send`.
#[derive(Debug)]
pub struct ICoWWeakRead<'weak, ITEM: Sized>(Arc<ITEM>, bool, PhantomData<&'weak ()>);

impl<'weak, ITEM: Sized> Deref for ICoWWeakRead<'weak, ITEM>
{
    type Target = ITEM;

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

impl<'weak, ITEM: Sized + fmt::Debug> ICoWWeakRead<'weak, ITEM>
{
    /// Tells if `item` was reloaded. If `true` is returned, the
    /// `item` was loaded from `base` and not from the cache.
    pub 
    fn item_updated(&self) -> bool
    {
        return self.1;
    }
}

/// A independent from the [ICoW] instance, which is not binded to the lifetime
/// of the main instance. The value contains a read-only weak reference to `ITEM`.
/// If the weak reference become invalid, then a new copy will be obtained.
/// 
/// It should not be accessed from multiple threads simultaniously!
#[derive(Debug)]
pub struct ICoWWeak<ITEM: Sized>
{
    /// A [Weak] reference to the `ITEM`. If reference no longer exists, then
    /// an attempt to fetch new will be made.
    item: RefCell<Weak<ITEM>>,

    /// A [Weak] reference to the [ICoWInternal] which will be used to update 
    /// the 
    base: Weak<ICoWInternal<ITEM>>,
}

unsafe impl<ITEM: Sized> Send for ICoWWeak<ITEM> {}

impl<ITEM: Sized> ICoWWeak<ITEM> 
{
    pub 
    fn aquire<'weak>(&self) -> Option<ICoWWeakRead<'weak, ITEM>>
    {
        let Some(val) = self.item.borrow().upgrade()
            else
            {
                // try to aquire new instance
                let Some(cur_base) = self.base.upgrade()
                    else
                    {
                        // ops, the base has gone
                        return None;
                    };

                let rd_only = cur_base.read();

                *self.item.borrow_mut() = Arc::downgrade(&rd_only);

                return Some(ICoWWeakRead(rd_only, true, PhantomData));
            };

        return Some(ICoWWeakRead(val, false, PhantomData));
    }
}

/// 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: Sized>
{
    /// Guarded value.
    pub(crate) item: Arc<ITEM>,

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

impl<'read, ITEM: Sized> Deref for ICoWRead<'read, ITEM>
{
    type Target = ITEM;

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

impl<'read, ITEM: Sized + fmt::Debug + Clone> ICoWRead<'read, ITEM>
{
    /// Consumes the itance and returns the clonned `ITEM` value.
    pub 
    fn clone_copy_into_inner(self) -> ITEM
    {
        return self.item.as_ref().clone();
    }
}

impl<'read, ITEM: Sized + fmt::Debug + Copy> ICoWRead<'read, ITEM>
{
    /// Consumes the itance and returns the copied `ITEM` value.
    pub 
    fn copy_into_inner(self) -> ITEM
    {
        return *self.item.as_ref();
    }
}

impl<'read, ITEM: Sized> ICoWRead<'read, ITEM>
{
    /// Returns the weak reference.
    pub 
    fn weak(&self) -> Weak<ITEM>
    {
        return Arc::downgrade(&self.item);
    }
}

impl<'read, ITEM: Sized + fmt::Debug + Copy> ICoWRead<'read, ITEM>
{
    /// Upgrades from [ICoWRead] `the self` to copy [ICoWCopy] which can 
    /// be commited to mainstream by using [Copy].
    pub 
    fn upgrade_copy(self) -> ICoWCopy<'read, ITEM> 
    {
        let new_item = *self.item;
        let bind = self.bind;

        return 
            ICoWCopy
            {
                prev_item: self, 
                new_item: new_item,
                inst: bind
            };
    }
}

impl<'read, ITEM: Sized + fmt::Debug + Clone> ICoWRead<'read, ITEM>
{
    /// Upgrades from [ICoWRead] `the self` to copy [ICoWCopy] which can 
    /// be commited to mainstream by using [Clone].
    pub 
    fn upgrade_clone_copy(self) -> ICoWCopy<'read, ITEM> 
    {
        let new_item = self.item.as_ref().clone();
        let bind = self.bind;

         return 
            ICoWCopy
            {
                prev_item: self, 
                new_item: new_item,
                inst: bind
            };
    }
}

impl<'read, ITEM: Sized + fmt::Debug + Default> ICoWRead<'read, ITEM>
{
    /// Upgrades from [ICoWRead] `the self` to copy [ICoWCopy] which can 
    /// be commited to mainstream by using [Default].
    pub 
    fn upgrade_default(self) -> ICoWCopy<'read, ITEM> 
    {
        let new_item = ITEM::default();
        let bind = self.bind;

         return 
            ICoWCopy
            {
                prev_item: self, 
                new_item: new_item,
                inst: bind
            };
    }
}

/// A write-guard which holds new value to which the new data is written. And
/// previous value too. This type of guard is not exclusive, so multiple
/// CoW operations may be performed in parallel which is not normally needed.
/// 
/// The changes made in the current instance becomes visible for the rest
/// of the threads only after commit.
#[derive(Debug)]
pub struct ICoWCopy<'copy, ITEM: Sized>
{
    /// 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: Sized> Deref for ICoWCopy<'copy, ITEM>
{
    type Target = ITEM;

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

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

impl<'copy, ITEM: Sized> 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 in reasonable time. for blocking `commit` use 
    /// [Self::commit_blocking].
    /// 
    /// # Returns
    /// 
    /// If operation was successfull, a [Result::Ok] is returned.
    /// 
    /// The [Result::Err] is retruned as tuple
    /// 
    /// * `0` - [ICoWError] with the error type.
    /// 
    /// * `1` - [ICoWCopy] instance itself.
    /// 
    /// Error types:
    /// 
    /// * [ICoWError::ExclusiveLockPending] - if exclusivly locked from another thread.
    /// 
    /// * [ICoWError::WouldBlock] - if "exponential backoff has completed and blocking the thread is advised"
    pub 
    fn commit(self) -> Result<(), (ICoWError, Self)>
    {
        let write_lock = 
            self
                .inst
                .0
                .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.0.exclusivly_locked.load(Ordering::Relaxed) == true
                    {
                        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 argument `ignore_excl` is set to true, the instance will not return
    /// [ICoWError::ExclusiveLockPending] error and wait until the lock release.
    /// 
    /// If [Result::Err] is returned, the instance is locked exclusivly. 
    /// (only if `ignore_excl` argument is set to `true`)
    ///  
    /// # Returns
    /// 
    /// The [Result::Err] is returned with:
    /// 
    /// [ICoWCopy] commited instance itself.
    pub 
    fn commit_blocking(self, ignore_excl: bool) -> Result<(), Self>
    {
        if self.inst.0.exclusivly_locked.load(Ordering::Relaxed) == true && ignore_excl == false
        {
            return Err(self);
        }

        let mut write_lock = 
            self
                .inst
                .0
                .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.
/// 
/// If dropped, no changes will be made.
#[derive(Debug)]
pub struct ICoWLock<'lock, ITEM: Sized>
{
    /// An exclusive lock in the previous value.
    prev_item: RwLockWriteGuard<'lock, Arc<ITEM>>,

    /// A freshly create/copied/clonned item
    pub(crate) item: OnceCell<ITEM>,

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

impl<'lock, ITEM: Sized> Drop for ICoWLock<'lock, ITEM>
{
    fn drop(&mut self) 
    {
        if let Some(_item) = self.item.take()
        {
            
        }

        self.inst.0.exclusivly_locked.store(false, Ordering::Relaxed);

        return;
    }
}

impl<'lock, ITEM: Sized> 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 current guarded instance guarantees
    /// that the future readers will read new value and no other writes
    /// will be perfomed at the same time.
    /// 
    /// # Returns
    /// 
    /// Returns nothing
    #[inline]
    pub 
    fn commit(mut self)
    {
        *self.prev_item = Arc::new(self.item.take().unwrap());

        // don't unlock exclusivly_locked, it will be unlocked when dropped

        return;
    }
}

impl<'lock, ITEM: Sized> Deref for ICoWLock<'lock, ITEM>
{
    type Target = ITEM;

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

impl<'lock, ITEM: Sized> DerefMut for ICoWLock<'lock, ITEM>
{
    fn deref_mut(&mut self) -> &mut Self::Target
    {
        return self.item.get_mut().unwrap()
    }
}

#[derive(Debug)]
pub struct ICoWInternal<ITEM: Sized>
{
    /// 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: AtomicBool,
}

impl<ITEM: Sized> ICoWInternal<ITEM>
{
    /// Initalizes a new instance.
    pub 
    fn new(item: ITEM) -> Self
    {
        return 
            Self
            { 
                inner: 
                    RwLock::new(Arc::new(item)),
                exclusivly_locked:
                    AtomicBool::new(false),
            };
    }

    pub 
    fn read(&self) -> Arc<ITEM>
    {
        let lock = 
            self
                .inner
                .read()
                .unwrap_or_else(|e| e.into_inner());

        return lock.clone();
    }

    fn try_read(&self) -> Option<Arc<ITEM>>
    {
        let lock_res = 
            self
                .inner
                .try_read();

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

/// A main structure which implements CoW approach based on [RwLock]. The object 
/// stored inside can be read directly, but  modifying the `inner` value is 
/// performed using `CoW` copy-on-write approach. 
/// 
/// The `read` operations are faster than `write`, because in order to `write` a
/// more operations needs to be performed.
/// 
/// This is for Mutlithreading environment only. It will be usedless when using
/// in single-thread programs. For the single thread, use a `SICoW` which would
/// improve the performance.
/// 
/// The inner value must be 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_copy().unwrap();
/// write0.s = 3;
/// 
/// write0.commit().unwrap();
/// 
/// // write new exclusivly
/// let mut write0 = cow_val.try_clone_copy_exclusivly().unwrap();
/// write0.s = 3;
/// 
/// write0.commit().unwrap(); 
/// 
/// ```
#[derive(Debug)]
pub struct ICoW<ITEM: Sized>(Arc<ICoWInternal<ITEM>>);

unsafe impl<ITEM: Sized + Send> Send for ICoW<ITEM> {}
unsafe impl<ITEM: Sized + Send> Sync for ICoW<ITEM> {}

impl<ITEM> ICowType for ICoW<ITEM>
{
    fn get_lock_type() -> ICoWLockTypes 
    {
        return ICoWLockTypes::RwLock;
    }
}

impl<ITEM> ICoW<ITEM>
{
    /// Initalizes a new instance.
    pub 
    fn new(item: ITEM) -> Self
    {
        return Self( Arc::new( ICoWInternal::<ITEM>::new(item)) );
    }

    /// Reads the inner value returning the `weak reader` which allows
    /// to keep it somewhere else i.e in the `thread_local`. The returned
    /// item is not [Sync] but can be sent to other thread [Send].
    /// 
    /// If the base [ICoW] will be dropped, the instance should instantly 
    /// become no longer valid which means that it won't be possible to 
    /// aquire `read`.
    /// 
    /// # Returns 
    /// 
    /// An instance with [Weak] references to `ITEM` and `ICoW`.
    pub 
    fn reader(&self) -> ICoWWeak<ITEM>
    {
        let readed = self.read();

        return 
            ICoWWeak
            {
                item: 
                    RefCell::new(readed.weak()),
                base: 
                    Arc::downgrade(&self.0),
            };
    }

    /// 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.
    #[inline]
    pub 
    fn read(&self) -> ICoWRead<'_, ITEM>
    {
        let read_item = 
            self
                .0
                .read();

        return ICoWRead{ item: read_item, bind: self };
    }

    /// Attempts to read the inner value returning the guard. This function 
    /// does not block the current thread until the value becomes available. This
    /// function fails if exclusive copy-on-write is in progress.
    /// 
    /// # Returns 
    /// 
    /// A [Option] is retrurned. The [Option::None] is returned if operation
    /// would block for a long time. 
    #[inline]
    pub 
    fn try_read(&self) -> Option<ICoWRead<'_, ITEM>>
    {
        return 
            self
                .0
                .try_read()
                .map(|r| 
                    ICoWRead{ item: r, 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
                .0
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);

        self.0.exclusivly_locked.store(true, Ordering::Relaxed);
        
        return 
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(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.0.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return Err(new_item),
            };

        self.0.exclusivly_locked.store(true, Ordering::Relaxed);
        
        return Ok(
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(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 is in progress.
    /// 
    /// * [ICoWError::WouldBlock] - if failed to acquire lock in reasonable time.
    /// 
    /// * 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.0.inner.try_write()
            {
                Ok(lock) => 
                    lock,
                Err(TryLockError::Poisoned(e)) => 
                    e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                {
                    if self.0.exclusivly_locked.load(Ordering::Relaxed) == true
                    {
                        return Err((ICoWError::ExclusiveLockPending, new_item));
                    }
                    else
                    {
                        return Err((ICoWError::WouldBlock, new_item));
                    }
                }
                    
            };

        self.0.exclusivly_locked.store(true, Ordering::Relaxed);
        
        let ret =
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(new_item), inst: self };
        
        // this sets exclusivly_locked to false
        ret.commit();

        return Ok(());
    }
}

impl<ITEM: fmt::Debug + 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
                .0
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);

        self.0.exclusivly_locked.store(true, Ordering::SeqCst);
        
        let new_item = *write_lock.as_ref(); 

        return 
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(new_item), inst: self };
    }

    fn internal_copy_excl(&self) -> Result<ICoWLock<'_, ITEM>, ICoWError>
    {
        let write_lock =  
            match self.0.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                {
                    if self.0.exclusivly_locked.load(Ordering::Relaxed) == true
                    {
                        return Err(ICoWError::ExclusiveLockPending);
                    }
                    else
                    {
                        return Err(ICoWError::WouldBlock);
                    }
                }
            };

        self.0.exclusivly_locked.store(true, Ordering::SeqCst);
        
        let new_item = *write_lock.as_ref(); 
        
        return Ok(
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(new_item), inst: self }
        );
    }

    /// Attempts to [Copy] the instance exclusively, but if failes due to the 
    /// have been already exclusivly locked, returns [ICoWRead] after lock release.
    /// In case of `WouldBlock` error, the operation is repeated.
    /// 
    /// This function is blocking.
    pub 
    fn copy_exclusive_or_read(&self) -> Result<ICoWLock<'_, ITEM>, ICoWRead<'_, ITEM>>
    {
        loop
        {
            let res = self.internal_copy_excl();

            if let Err(err) = res
            {
                if err == ICoWError::WouldBlock
                {
                    continue;
                }

                return Err(self.read());
            }
            
            return Ok(res.unwrap());
        }
    }

    /// 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>>
    {
        return self.internal_copy_excl().ok();
    }
}

impl<ITEM: fmt::Debug + Clone> ICoW<ITEM>
{
    /// > [!IMPORTANT]
    /// > Previously `clone()`. renamed to `clone_copy()` due to the 
    /// > conflict with [Clone].
    /// 
    /// 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_copy(&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;
    }

    /// > [!IMPORTANT]
    /// > Previously `try_clone()`. renamed to `try_clone_copy()` due to the 
    /// > conflict with [Clone].
    /// 
    /// 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_copy(&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);
    }

    fn internal_clone_copy_excl(&self) -> Result<ICoWLock<'_, ITEM>, ICoWError>
    {
       let write_lock =  
            match self.0.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                {
                    if self.0.exclusivly_locked.load(Ordering::Relaxed) == true
                    {
                        return Err(ICoWError::ExclusiveLockPending);
                    }
                    else
                    {
                        return Err(ICoWError::WouldBlock);
                    }
                }
            };

        self.0.exclusivly_locked.store(true, Ordering::Relaxed);
        
        let new_item = write_lock.as_ref().clone();
        
        return Ok(
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(new_item), inst: self }
        );
    }

    /// Attempts to [Clone] the instance exclusively, but if failes due to the 
    /// have been already exclusivly locked, returns [ICoWRead] after lock release.
    /// In case of `WouldBlock` error, the operation is repeated.
    /// 
    /// This function is blocking.
    pub 
    fn clone_copy_exclus_or_read(&self) -> Result<ICoWLock<'_, ITEM>, ICoWRead<'_, ITEM>>
    {
        loop
        {
            let res = self.internal_clone_copy_excl();

            if let Err(err) = res
            {
                if err == ICoWError::WouldBlock
                {
                    continue;
                }

                return Err(self.read());
            }
            
            return Ok(res.unwrap());
        }
    }

    /// > [!IMPORTANT]
    /// > Previously `clone_exclusivly()`. renamed to `clone_copy_exclusivly()` due to the 
    /// > conflict with [Clone].
    /// 
    /// 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_copy_exclusivly(&self) -> ICoWLock<'_, ITEM>
    {
        let write_lock =  
            self
                .0
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);

        self.0.exclusivly_locked.store(true, Ordering::Relaxed);
        
        let new_item = write_lock.as_ref().clone();

        return 
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(new_item), inst: self };
    }

    /// > [!IMPORTANT]
    /// > Previously `try_clone_exclusivly()`. renamed to `try_clone_copy_exclusivly()` due to the 
    /// > conflict with [Clone].
    /// 
    /// 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.
    #[inline]
    pub 
    fn try_clone_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
    {
        return self.internal_clone_copy_excl().ok();
    }
}

impl<ITEM: fmt::Debug + 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
                .0
                .inner
                .write()
                .map_or_else(|e| e.into_inner(), |v| v);
        
        self.0.exclusivly_locked.store(true, Ordering::Relaxed);

        let new_item = ITEM::default();

        return 
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(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.0.inner.try_write()
            {
                Ok(r) => r,
                Err(TryLockError::Poisoned(e)) => e.into_inner(),
                Err(TryLockError::WouldBlock) =>
                    return None
            };

        self.0.exclusivly_locked.store(true, Ordering::Relaxed);
        
        let new_item = ITEM::default();
        
        return Some(
            ICoWLock{ prev_item: write_lock, item: OnceCell::from(new_item), inst: self }
        );
    }
}


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