instance-copy-on-write 0.9.2

/*-
 * 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)
 */

/// Atomics based Copy-on-write realization.

use std::
{
    cell::{OnceCell, RefCell, UnsafeCell}, fmt, marker::PhantomData, ops::{Deref, DerefMut}, sync::{Arc, Weak, atomic::{AtomicI32, Ordering}}, time::Duration
};

use crossbeam_deque::{Injector, Steal};
use crossbeam_utils::{Backoff, sync::{Parker, Unparker}};

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



/// 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 + fmt::Debug>
{
    /// An `current` (actual) value which is still visible for the rest.
    read: ICoWRead<'copy, ITEM>,

    /// A new item which will replace the `current` value.
    new_item: ITEM,

    /// A reference to base.
    bind: &'copy ICoW<ITEM>,
}

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

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

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

impl<'copy, ITEM: Sized + fmt::Debug> 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.read;
    }

    /// 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)>
    {
        if let Err(err) = self.bind.int_lock_excl()
        {
            return Err((err, self));
        }
        
        self.bind.replace(self.new_item);

        self.bind.unlock();

        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>
    {
        let mut inst = self;
        let mut park_cnt = 1;

        loop
        {
            let Err((errn, this)) = inst.commit()
                else
                {
                    return Ok(());
                };

            if errn == ICoWError::ExclusiveLockPending && ignore_excl == false
            {
                return Err(this);
            }

            this.bind.park(park_cnt);

            park_cnt += 1;

            inst = this;
        }
    }  

    /// 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
    {
        self.bind.wakeup();

        return self.new_item;
    }
}

/*
/// A guard which perfroms the copy of the instance sequentially i.e
/// in order. A calling thread #3 performs seq copy, then the rest
/// threads will wait until the thread either commit or drop.
/// 
/// But readers can still read() the instance because this is not exclusive
/// lock.
#[derive(Debug)]
pub struct ICoWSeqCopy<'secopy, ITEM: Sized + fmt::Debug>
{
    copy: ICoWCopy<'secopy, ITEM>,
    seq_read: ,
}

impl<'secopy, ITEM: Sized + fmt::Debug> ICoWLock<'secopy, 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 + fmt::Debug>
{
    /// Previous item.
    prev_item: 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 + fmt::Debug> Drop for ICoWLock<'lock, ITEM>
{
    fn drop(&mut self) 
    {
        if let Some(_item) = self.item.take()
        {
            self.inst.unlock();
        }

        return;
    }
}

impl<'lock, ITEM: Sized + fmt::Debug> 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
    pub 
    fn commit(mut self)
    {
        self.inst.replace(self.item.take().unwrap());

        self.inst.unlock();

        return;
    }
}

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

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

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


/// 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 + fmt::Debug>(Arc<ITEM>, bool, PhantomData<&'weak ()>);

impl<'weak, ITEM: Sized + fmt::Debug> 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 + fmt::Debug>
{
    /// 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 `item`.
    base: Weak<ICoWInternal<ITEM>>,
}

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

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

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

impl<'read, ITEM: Sized + fmt::Debug> 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 + fmt::Debug> 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
            {
                read: self, 
                new_item: new_item,
                bind: 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
            {
                read: self, 
                new_item: new_item,
                bind: 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
            {
                read: self, 
                new_item: new_item,
                bind: bind,
            };
    }
}

#[derive(Debug)]
pub struct ICoWInternal<ITEM: Sized + fmt::Debug>
{
    /// Amount of the pending operation and the state field.
    /// 
    /// When field == 1, read/write allowed, no pending readers.  
    /// When field > 1, pending read operations.  
    /// When fieled == 0, read prohibited, the readers must wait for release.
    /// When field < 0, read prohibited, the pending readers are completing op.
    op_cnt: AtomicI32,
    
    /// The data which is shared and copied on write.
    inner: UnsafeCell<Arc<ITEM>>, 

    /// A dumb theard wakeup system where threads injects theirs
    /// [Unparker]s. Depends on the state of the field `waker_lock`.
    /// 
    /// Used only for exclusive locks and copy commit(temporary).
    waker: Injector<Unparker>,

    /// The `waker` control state.
    /// 
    /// When field == 1, `waker` is available.  
    /// When field >= 1, `waker` is available, pending operations.  
    /// When field == 0, `waker` is not available.  
    /// When field < 0, `waker` is no longer available, pending ops.
    waker_lock: AtomicI32,
}

impl<ITEM: Sized + fmt::Debug> ICoWInternal<ITEM>
{
    /// Initalizes a new instance.
    pub 
    fn new(item: ITEM) -> Self
    {
        return 
            Self
            { 
                op_cnt: AtomicI32::new(1),
                inner: UnsafeCell::new(Arc::new(item)),
                waker: Injector::new(),
                waker_lock: AtomicI32::new(0),
            };
    }

    fn read(&self) -> Arc<ITEM>
    {
        let bkoff = Backoff::new();
        let mut park_cnt = 1;

        loop
        {
            let Some(read) = self.try_read()
                else
                {
                    if bkoff.is_completed() == false
                    {
                        bkoff.snooze();
                    }
                    else
                    {
                        // park thread
                        self.park(park_cnt);

                        park_cnt += 1;
                    }

                    continue;
                };

            // wake up next if necessary
            //self.wakeup();

            return read;
        }
    }

    fn try_read(&self) -> Option<Arc<ITEM>>
    {
        let mut inner = self.op_cnt.load(Ordering::Relaxed);

        loop 
        {
            if inner > 0
            {
                let res = 
                    self
                        .op_cnt
                        .compare_exchange_weak(
                            inner, 
                            inner+1, 
                            Ordering::SeqCst, 
                            Ordering::Acquire
                        );

                match res
                {
                    Ok(_old) =>
                    {
                        let cow_read = unsafe{ self.inner.get().as_ref() }.unwrap().clone();

                        self.op_cnt.fetch_sub(1, Ordering::SeqCst);

                        return Some(cow_read);
                    },
                    Err(new_innwe) =>
                    {
                        inner = new_innwe;

                        continue;
                    }
                }

            }
            else
            {
                return None;
            }
        }
    }

    fn park(&self, repeat: u64)
    {
        let backoff = Backoff::new();

        let mut current = self.waker_lock.load(Ordering::Relaxed);

        loop
        {
            if current <= 0
            {
                if repeat < 100000
                {
                    PARKER
                        .with_borrow(|parker| parker.park_timeout(Duration::from_nanos(repeat * 100)));
                }

                return;
            }

            let res = 
                self
                    .waker_lock
                    .compare_exchange_weak(
                        current, 
                        current+1, 
                        Ordering::SeqCst, 
                        Ordering::Acquire
                    );

            if let Err(e) = res
            {
                current = e;
                backoff.snooze();
                continue;
            }
            
            let unparker = 
                PARKER
                    .with_borrow(|parker| parker.unparker().clone());
            
            self.waker.push(unparker);
                
            self.waker_lock.fetch_sub(1, Ordering::SeqCst);

            PARKER
                .with_borrow(|parker| parker.park());

            return;
        }
    }
}

/// A main structure which implements CoW approach based on atomics. 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(); 
/// 
/// ```
#[repr(transparent)]
#[derive(Debug, Clone)]
pub struct ICoW<ITEM: Sized + fmt::Debug>(Arc<ICoWInternal<ITEM>>);

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

impl<ITEM: Sized + fmt::Debug> Drop for ICoW<ITEM>
{
    fn drop(&mut self) 
    {
        let mut current = 1;
        let backoff = Backoff::new();

        loop
        {
            let res = 
                self
                    .0
                    .op_cnt
                    .compare_exchange_weak(
                        current, 
                        0, 
                        Ordering::SeqCst, 
                        Ordering::Acquire
                    );

            if let Err(other) = res
            {
                if other >= 1
                {
                    current = other; 

                    continue;
                }
                else if other <= 0
                {
                    // this should not happen because the reference to base is
                    // borrowed, but anyway.
                    backoff.snooze();

                    continue;
                }
            }

            break;
        }   

        self.unlock();

        return;
    }
}

impl<ITEM: Sized + fmt::Debug> ICowType for ICoW<ITEM>
{
    fn get_lock_type() -> ICoWLockTypes 
    {
        return ICoWLockTypes::Atomic;
    }
}

thread_local! {
    static PARKER: RefCell<Parker> =  RefCell::new(Parker::new());
}

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

    /// Sets the `waker` state to enabled. No checks are performed becuase
    /// the waker is initilized only after the exclusive lock is occured.
    fn make_waker(&self) 
    {
        self.0.waker_lock.store(1, Ordering::SeqCst);

        return;
    }

    #[inline]
    fn replace(&self, new: ITEM)
    {
        *unsafe { self.0.inner.get().as_mut() }.unwrap() = Arc::new(new);
    }

    #[inline]
    fn unlock(&self)
    {
        self.0.op_cnt.store(1, Ordering::Relaxed);

        self.wakeup();
    }

    /// Wakes up all threads which pushed their [Unparker] to the waker's [Injector].
    fn wakeup(&self)
    {
        let backoff = Backoff::new();
        let mut current = 1;
        
        loop
        {
            // try to lock the `waker`

            let res = 
                self
                    .0
                    .waker_lock
                    .compare_exchange_weak(
                        current, 
                        -1, 
                        Ordering::SeqCst, 
                        Ordering::Acquire
                    );

            if let Err(e) = res 
            {
                if e <= 0
                {
                    // nothing to wakeup
                    return;
                }
                else
                {
                    backoff.snooze();

                    current = e;
                    continue;
                }
            }

            let backoff = Backoff::new();
            if current > 1
            {
                // wait for all wake operations
                current = -current;

                loop
                {
                    if self.0.waker_lock.load(Ordering::Relaxed) != current
                    {
                        backoff.snooze();
                        continue;
                    }

                    break;
                }
            }

            // wake up next if necessary
            if self.0.waker.is_empty() == false
            {
                loop
                {
                    match self.0.waker.steal()
                    {
                        Steal::Empty => 
                            return,
                        Steal::Success(v) => 
                        {
                            v.unpark();
                        },
                        Steal::Retry => 
                            return,
                    }
                }
            }

            return;
        }
        
    }

    /// Parks the current thread if `waker` is available. If not, will park for a
    /// short periods of time starting from 100ns and increasing each iteration
    /// which is controlled by `repeat` argument. The max repeats is 100_000 which
    /// will be 100_000_000ns or 100_000us or 100ms.
    #[inline]
    fn park(&self, repeat: u64)
    {
        self.0.park(repeat);
    }

    /// Internal function which aquires the exclusive lock.
    /// 
    /// Returns error in cases:
    /// 
    /// * [ICoWError::ExclusiveLockPending] - when other exclusive lock 
    ///     is already pending.
    /// 
    /// * [ICoWError::WouldBlock] - when it was not possible to aquire the 
    ///     lock in reasonable time and operation whould be repeated.
    fn int_lock_excl(&self) -> Result<(), ICoWError>
    {
        let mut current = 1;
        let backoff = Backoff::new();

        loop
        {
            // try to lock the access/state counter
            let res = 
                self
                    .0
                    .op_cnt
                    .compare_exchange_weak(
                        current, 
                        0, 
                        Ordering::SeqCst, 
                        Ordering::Acquire
                    );

            if let Err(other) = res
            {
                if other >= 1
                {
                    current = other; //todo

                    continue;
                }
                else if other <= 0
                {
                    // already locked
                    return Err(ICoWError::ExclusiveLockPending);
                }
            }

            // if counter contains more than 1 op, then wait for the rest because
            // someone is in process of reading and replacing the `inner` would 
            // cause SIGSEGV due to racing i.e descructed before copied.
            // This can happen when the reader thread was interrupted by OS in the 
            // half of the `reading` process.
            if current > 1
            {
                // wait for all read operations i.e the reader will fetch_sub the value
                // so if now we have 3 in current variable and 0 in `op_cnt`, 
                // the required current is 1 and -2 in `op_cnt`.
                // Reducing the current by 1 and negating it, so now each reader would
                // substract the negative like:
                // 3 - 1 = 2 | 0 - 1 = -1  | != -2
                // 2 - 1 = 1 | -1 - 1 = -2 | == -2
                current = -(current - 1);

                loop
                {
                    // replace the value in `op_cnt` to 0 when all readers would complete the read
                    // operation. 0 - means locked from reading.
                    let Err(other) = 
                        self
                            .0
                            .op_cnt
                            .compare_exchange_weak(
                                current, 
                                0, 
                                Ordering::SeqCst, 
                                Ordering::Acquire
                            )
                        else
                        {
                            break;
                        };

                    if backoff.is_completed() == false
                    {
                        // don't park the thread. Reading should not take too much time.
                        backoff.snooze();

                        continue;
                    }
                    else
                    {
                        // restore counter
                        self.0.op_cnt.store(-(other + 1), Ordering::Relaxed);

                        return Err(ICoWError::WouldBlock);
                    }
                }
            }

            return Ok(());
        }
    }
}



impl<ITEM: Sized + fmt::Debug> ICoW<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),
            };
    }

    /// Reads 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>
    {
        return 
            ICoWRead
            { 
                item: 
                    self.0.read(),
                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.
    /// 
    /// 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>>
    {
        return 
            self.0.try_read()
                .map(|arc_val|
                    ICoWRead
                    { 
                        item: 
                            arc_val,
                        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 bkoff = Backoff::new();
        let mut new_item_loc = new_item;
        let mut park_cnt = 1;

        loop
        {
            match self.try_new_exclusivly(new_item_loc)
            {
                Ok(res) =>
                    return res,
                Err(ret_new_item) =>
                {
                    if bkoff.is_completed() == true
                    {
                        // park thread
                        self.park(park_cnt);

                        park_cnt += 1;
                    }
                    else
                    {
                        bkoff.snooze();
                    }

                    new_item_loc = ret_new_item;
                }
            }
        }
    }  

    
    /// 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 [Option] 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>
    {
        if let Err(_) = self.int_lock_excl()
        {
            return Err(new_item);
        }


        self.make_waker();

        return Ok(
            ICoWLock
            { 
                prev_item: 
                    unsafe{ self.0.inner.get().as_ref() }.unwrap().clone(),
                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.
    /// 
    /// 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)>
    {
        let read = self.try_read();
                
        if let Some(read_res) = read
        {
            let ret = 
                ICoWCopy
                { 
                    read: read_res, 
                    new_item: new_item, 
                    bind: self 
                };

            return ret.commit().map_err(|e| (e.0, e.1.new_item));
        }
        else
        {
            return Err((ICoWError::ExclusiveLockPending, 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)>
    {
        if let Err(err) = self.int_lock_excl()
        {
            return Err((err, new_item));
        }

        self.make_waker();

        ICoWLock
        { 
            prev_item: 
                unsafe{ self.0.inner.get().as_ref() }.unwrap().clone(),
            item: 
                OnceCell::from(new_item), 
            inst: 
                self 
        }
        .commit();
    
        return Ok(());
        //}
    }
}


impl<ITEM: Sized + 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
            { 
                read: read, 
                new_item: new_item, 
                bind: 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
            { 
                read: read, 
                new_item: new_item, 
                bind: self 
            };

        return Some(ret);
    }

    fn internal_copy_excl(&self) -> Result<ICoWLock<'_, ITEM>, ICoWError>
    {
        self.int_lock_excl()?;

        self.make_waker();

        let prev_item = unsafe{ self.0.inner.get().as_ref() }.unwrap().clone();
        
        let new_val = *prev_item.as_ref();

        return Ok(
            ICoWLock{ prev_item: prev_item, item: OnceCell::from(new_val), inst: self }
        );
    }

    /// 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 bkoff = Backoff::new();
        let mut park_cnt = 1;

        loop 
        {
            let Some(res) = self.try_copy_exclusivly()
                else
                {
                    if bkoff.is_completed() == false
                    {
                        bkoff.snooze();
                        continue;
                    }
                    else
                    {
                        self.park(park_cnt);
                        park_cnt += 1;
                        
                        continue;
                    }
                };  

            return res;
        }
    }

    /// 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.
    #[inline]
    pub 
    fn try_copy_exclusivly(&self) -> Option<ICoWLock<'_, ITEM>>
    {
        return self.internal_copy_excl().ok();
    }

    /*
    /// Copies the `ITEM` sequentially i.e in order after all previous
    /// seq copy operations completes. This type of copy operation is not
    /// `exclusive` and `read` operations are possible.
    pub 
    fn copy_sequentially(&self) -> ICoWSeqCopy<'_, ITEM>
    {
        let bkoff = Backoff::new();

        loop 
        {
            let Some(res) = self.try_copy_exclusivly()
                else
                {
                    if bkoff.is_completed() == false
                    {
                        bkoff.snooze();
                        continue;
                    }
                    else
                    {
                        std::thread::park_timeout(Duration::from_nanos(500));
                        continue;
                    }
                };

            return res;
        }
    }
    */
}

impl<ITEM: Sized + 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
            { 
                read: read, 
                new_item: new_item, 
                bind: 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
            { 
                read: read, 
                new_item: new_item, 
                bind: self 
            };

        return Some(ret);
    }

    fn internal_clone_copy_excl(&self) -> Result<ICoWLock<'_, ITEM>, ICoWError>
    {
        self.int_lock_excl()?;

        self.make_waker();

        let prev_item = unsafe{ self.0.inner.get().as_ref() }.unwrap().clone();
        
        let new_val = prev_item.as_ref().clone();

        return Ok(
            ICoWLock{ prev_item: prev_item, item: OnceCell::from(new_val), 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 bkoff = Backoff::new();
        let mut park_cnt = 1;

        loop 
        {
            let Some(res) = self.try_clone_copy_exclusivly()
                else
                {
                    if bkoff.is_completed() == false
                    {
                        bkoff.snooze();
                        continue;
                    }
                    else
                    {
                        self.park(park_cnt);

                        park_cnt += 1;
                        
                        continue;
                    }
                };

            return res;
        }
    }

    /// > [!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: Sized + 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
            { 
                read: read, 
                new_item: new_item, 
                bind: 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
            { 
                read: read, 
                new_item: new_item, 
                bind: 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 bkoff = Backoff::new();
        let mut park_cnt = 1;

        loop 
        {
            let Some(res) = self.try_default_exclusivly()
                else
                {
                    if bkoff.is_completed() == false
                    {
                        bkoff.snooze();
                        continue;
                    }
                    else
                    {
                        self.park(park_cnt);

                        park_cnt += 1;

                        continue;
                    }
                };

            return res;
        }
    }
      
      

    /// 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>>
    {
        if let Err(_) = self.int_lock_excl()
        {
            return None;
        }

        self.make_waker();
        
        let prev_item = unsafe{ self.0.inner.get().as_ref() }.unwrap().clone();

        let new_val = ITEM::default();

        return Some(
            ICoWLock{ prev_item: prev_item, item: OnceCell::from(new_val), inst: self }
        );
        
    }
}

#[cfg(test)]
mod test
{
    // atomics specific tests
}