temporary_owner_rs/

lib.rs

/*-
 * temporary-owner-rs - A crate which provides a temporary exclusive ownership 
 * over the data which can be Send to other thread.
 * 
 * Copyright (C) 2025 Aleksandr Morozov
 * 
 * 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
 */

//! # This is an experimental crate!
//! 
//! <img src="https://cdn.4neko.org/ow_temp_transf_500.webp" width="280"/> <img src="https://cdn.4neko.org/source_avail.webp" width="280"/> <img src="https://cdn.4neko.org/mpl_or_eupl_500.webp" width="280"/>
//! 
//! A crate which provides a temporary transfer of the ownership over the 
//! data structure to any other instance i.e thread. This is a sort of
//! an exclusive access to the inner instance without the shared access.
//! 
//! There is no proofs yet that there is no single event which may 
//! cause a race condition. The CPU must support `atomic` operation reordering
//! otherwise it will not work.
//! 
//! Supports ![no_std] if feature `std` is not enabled.
//! 
//! ```text
//!                      ┌───────────────────┐                                         
//!                      │                   │                                         
//!                      │     ItemOwner     │◄───────────────────────────────────────┐
//!                      │                   │                                        │
//!                      └────────┬──────────┘                                        │
//!                               │                                                   │
//!                               │                                                   │
//!                               │                                                   │
//!                               │                                                   │
//!                     ┌─────────▼──────────────┐                                    │
//!                     │                        │                                    │
//!                     │  transfer_ownership()  │                                    │
//!                     │                        │                                    │
//!                     └────┬──┬──┬─────────────┘                                    │
//!                          │  │  │                                                  │
//!                          │  │  │  ───────────────────────────────────────         │
//!                          │  │  │         EXCLUSIVE ACCESS                         │
//! ┌──────────────────┐     │  │  │     ┌───────────────────────────┐                │
//! │                  │     │  │  │     │         INSTANCE          │                │
//! │                  ◄─────┘  │  └─────►                           │                │
//! │  TransferError   │        │        │    ItemOwnershipTransfer  │                │
//! ├──────────────────┘        │        └────────────┬──────────────┘                │
//! │                           │                     │                               │
//! ├── AlreadyTransfered       │                     │                               │
//! │                           │          ┌──────────▼─────────────┐                 │
//! │                           │          │     send_over_MPSC     │                 │
//! ├── AlreadyReturned         │          └────────────────────────┘                 │
//! │                           │                                                     │
//! │                                                                                 │
//! └── Poisoned                ───────    ────    ─────   ──────    ───    ───       │
//!                                                                                   │
//!                               ┌─────────────┐                                     │
//!                               │  Thread N   │                                     │
//!                               └─────────────┘─────────────────────┐               │
//!                                       │       MPSC_RECV           │               │
//!                                       │                           │               │
//!                                       │   ItemOwnershipTransfer   │               │
//!                                       └────────────┬──────────────┘               │
//!                                                    │                              │
//!                                                    │                              │
//!                                            ┌───────▼──────────┐                   │
//!                                            │   as_ref()       │                   │
//!                                            │                  │                   │
//!                                            │   as_mut()       │                   │
//!                                            └───────┬──────────┘                   │
//!                                                    │                              │
//!                                                    │                              │
//!                                            ┌───────▼──────────┐                   │
//!                                            │   drop()         │                   │
//!                                            │                  ┼───────────────────┘
//!                                            └──────────────────┘                    
//! ```
//! 
//! ## Examples
//! 
//! ```ignore
//! use std::{fmt, sync::{atomic::{AtomicU32, Ordering}, mpsc}, time::Duration};
//! 
//! use crate::{ItemOwner, ItemOwnershipTransfer, OwnershipFlags, TransferError};
//! 
//! // used for example only
//! pub trait PeriodicTask: Send + fmt::Debug
//! {
//!     fn exec(&mut self) -> Result<(), String>;
//!     fn get_val(&self) -> u32;
//! }
//! 
//! pub type PeriodicTaskHndl = Box<dyn PeriodicTask>;
//! 
//! 
//! #[derive(Debug)]
//! pub struct Task1
//! {
//!     val: u32
//! }
//! 
//! impl Drop for Task1
//! {
//!     fn drop(&mut self) 
//!     {
//!         println!("dropped!");
//!     }
//! }
//! 
//! impl PeriodicTask for Task1
//! {
//!     fn get_val(&self) -> u32
//!     {
//!         return self.val;
//!     }
//! 
//!     fn exec(&mut self) -> Result<(), String> 
//!     {
//!         println!("task {} called", self.val);
//! 
//!         return Ok(());
//!     }
//! }
//! 
//! fn main()
//! {
//!     let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
//! 
//!     // creating new instance
//!     let owner = ItemOwner::new(task1);
//! 
//!     // creating channel to send the shared item
//!     let (se, rc) = 
//!         mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();
//! 
//!     let thread_hndl = 
//!         std::thread::spawn(move || 
//!             {
//!                 // receive the transfered ownership
//!                 let mut task = rc.recv().unwrap();
//! 
//!                 std::thread::sleep(Duration::from_secs(2));
//! 
//!                 // call task
//!                 task.as_mut().exec().unwrap();
//! 
//!                 return;
//!             }
//!         );
//! 
//! 
//!     se.send(owner.transfer_ownership().unwrap()).unwrap();
//! 
//!     // wait when the ownership will be returned
//!     while owner.is_owned() == false
//!     {
//!         std::thread::sleep(Duration::from_secs(1));
//!     }
//! 
//!     println!("completed round 1");
//! 
//!     thread_hndl.join().unwrap();
//! 
//!     let (se, rc) = 
//!         mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();
//! 
//!     let thread_hndl = 
//!         std::thread::spawn(move || 
//!             {
//!                 let mut task = rc.recv().unwrap();
//! 
//!                 std::thread::sleep(Duration::from_secs(2));
//!                 task.as_mut().exec().unwrap();
//! 
//!                 return;
//!             }
//!         );
//! 
//!     se.send(owner.transfer_ownership().unwrap()).unwrap();
//! 
//!     while owner.is_owned() == false
//!     {
//!         std::thread::sleep(Duration::from_secs(1));
//!     }
//! 
//!     println!("completed round 2");
//! 
//!     thread_hndl.join().unwrap();
//! 
//! 
//!     return;
//! }
//! ```

#![cfg_attr(not(feature = "std"), no_std)]

#[cfg(not(feature = "std"))]
extern crate alloc;

#[cfg(not(feature = "std"))]
use alloc::boxed::Box;

#[cfg(not(feature = "std"))]
use core::
{
    fmt, 
    mem, 
    ops::{Deref, DerefMut}, 
    ptr::{self, NonNull}, 
    sync::atomic::{AtomicU32, Ordering}
};

#[cfg(not(feature = "std"))]
use alloc::string::ToString;

#[cfg(feature = "std")]
use std::
{
    fmt, 
    mem, 
    ops::{Deref, DerefMut}, 
    ptr::{self, NonNull}, 
    sync::atomic::{AtomicU32, Ordering}
};


/// Error code which describes what happened.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum TransferError
{
    /// A ownership has been already transferred and have not yet been released i.e WouldBlock.
    AlreadyTransfered,

    /// A ownership have been already returned. This is normally used for the assertions trap and
    /// never returned to the user.
    AlreadyReturned,

    /// A transfer is not possible because the instance is poisoned due to the thread which owns a
    /// transfer has paniced.
    Poisoned,
}

impl fmt::Display for TransferError
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        match self
        {
            Self::AlreadyTransfered => 
                write!(f, "instance have been already transferred!"),
            Self::AlreadyReturned => 
                write!(f, "instance have been already returned!"),
            Self::Poisoned => 
                write!(f, "transfer was not returned due to the thread panic"),
        }
    }
}

/// A guard which is assigned to the [ItemOwnershipTransfer] for the execution flow
/// control. 
#[derive(Clone, Debug)]
struct TransferPanicGuard
{
    #[cfg(all(panic = "unwind", feature = "std"))]
    panicking: bool,
}

#[cfg(all(panic = "unwind", feature = "std"))]
impl Default for TransferPanicGuard
{
    fn default() -> Self 
    {
        use std::thread;

        Self { panicking: thread::panicking() }
    }
}

#[cfg(any(not(panic = "unwind"), not(feature = "std")))]
impl Default for TransferPanicGuard
{
    fn default() -> Self 
    {
        Self { }
    }
}

/// A flags which defines the current state of the instance.
#[repr(align(4))]
#[derive(Debug, Clone, PartialEq, Eq)]
struct OwnershipFlags
{
    /// Tells if instance is owned (true) or transferred.
    owned: bool, 

    /// The last transfer was not completed i.e thread paniced.
    poisoned: bool,

    /// If set to true, the transfer should deallocate the inner type in drop
    drop_in_place: bool,
}

impl fmt::Display for OwnershipFlags
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        let o = 
            if self.owned == true
            {
                "Owned"
            }
            else
            {
                "~Owned"
            };

        let p = 
            if self.poisoned == true
            {
                "Poisoned"
            }
            else
            {
                "~Poisoned"
            };

        let d = 
            if self.drop_in_place == true
            {
                "Drop"
            }
            else
            {
                "~Drop"
            };

        write!(f, "{},{},{}", o, p ,d)
    }
}

impl From<u32> for OwnershipFlags
{
    fn from(value: u32) -> Self
    {
        return unsafe { mem::transmute(value) };
    }
}

impl From<OwnershipFlags> for u32
{
    fn from(value: OwnershipFlags) -> Self
    {
        return unsafe { mem::transmute(value) };
    }
}

impl Default for OwnershipFlags
{
    fn default() -> Self
    {
        return
            Self
            {
                owned: true,
                poisoned: false,
                drop_in_place: false,
            };
    }
}



impl OwnershipFlags
{
    #[inline]
    const 
    fn make_transfer() -> OwnershipFlags
    {
        return OwnershipFlags { owned: false, poisoned: false, drop_in_place: false };
    }

    #[inline] 
    fn make_return(poison_guarg: &TransferPanicGuard) -> OwnershipFlags
    {
        let mut val = OwnershipFlags { owned: true, poisoned: false, drop_in_place: false };

        val.return_transfer(poison_guarg);

        return val;
    }

    /// Returns `true` if instance is owned by the [ItemOwner]. 
    /// Should not be called from the [ItemOwnershipTransfer].
    #[inline]
    fn is_owned(&self) -> bool
    {
        return self.owned;
    }

    /// Transfers the `ownership` temporary if it was not previously:
    /// 
    /// * already presented to other [ItemOwnershipTransfer] instance.
    /// 
    /// * the instance is not poisoned.
    #[inline]
    fn transfer(&mut self) -> Result<TransferPanicGuard, TransferError>
    {
        let guard = TransferPanicGuard::default();

        if self.owned == true && self.poisoned == false
        {
            self.owned = false;

            return Ok(guard);
        }
        else if self.poisoned == true
        {
            return Err(TransferError::Poisoned);
        }

        return Err(TransferError::AlreadyTransfered);
    }

    /// A [ItemOwnershipTransfer] returns the thransferred exclusive right.
    /// 
    /// Panics if race condition or misuse happens (when returned multiple times)
    fn return_transfer(&mut self, poison_guarg: &TransferPanicGuard)
    {
        #[cfg(all(panic = "unwind", feature = "std"))]
        if poison_guarg.panicking == false && std::thread::panicking() == true
        {
            self.poisoned = true;
            self.owned = true;

            return;
        }

        #[cfg(not(all(panic = "unwind", feature = "std")))]
        let _ = poison_guarg;

        if self.owned == false
        {
            self.owned = true;
        }

        return;
    }

    /// Clears the poisoned status.
    fn clear_poison(&mut self)
    {
        self.poisoned = false;
    }

    /// Sets the `drop-in-place` status.
    fn drop_in_place(&mut self)
    {
        self.drop_in_place = true;
    }
}


#[cfg(target_has_atomic = "64")]
mod has_atomics
{
    use super::*;

    /// Inner type which is not exposed.
    #[derive(Debug)]
    pub struct OwnerInner<ITEM: Send + fmt::Debug>
    {
        /// A [OwnershipFlags] represented as atomic u32.
        flags: AtomicU32,

        /// An item to share.
        item: Option<ITEM>,
    }

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

    impl<ITEM: Send + fmt::Debug> Deref for OwnerInner<ITEM>
    {
        type Target = ITEM;

        #[inline]
        fn deref(&self) -> &Self::Target
        {
            return self.item.as_ref().unwrap();
        }
    }

    impl<ITEM: Send + fmt::Debug> DerefMut for OwnerInner<ITEM>
    {
        #[inline]
        fn deref_mut(&mut self) -> &mut Self::Target
        {
            return self.item.as_mut().unwrap();
        }
    }

    impl<ITEM: Send  + fmt::Debug> OwnerInner<ITEM>
    {
        pub(crate) 
        fn new(item: ITEM) -> Self
        {
            return
                Self
                {
                    flags: 
                        AtomicU32::new(OwnershipFlags::default().into()),
                    item: 
                        Some(item)
                };
        }

        pub(crate) 
        fn transfer_ownership(&self) -> Result<TransferPanicGuard, TransferError>
        {
           // let inner = self.inner();

            let cur: OwnershipFlags = self.flags.load(Ordering::Relaxed).into();
            let mut new = cur.clone();
            let transfer = new.transfer()?;
            
            let res = 
                self
                    .flags
                    .compare_exchange_weak(cur.into(), new.into(), Ordering::SeqCst, Ordering::Acquire);

            match res 
            {
                Ok(_) =>
                    return Ok( transfer ),
                Err(e) =>
                {
                    let mut cur: OwnershipFlags = self.flags.load(Ordering::Relaxed).into();

                    let _ = cur.transfer()?;

                    return Err(TransferError::AlreadyReturned);
                }
            }
        }

        /// Returns `true` if drop-in-place is required.
        pub(crate) 
        fn return_ownership(&self, poison_guard: &TransferPanicGuard) -> bool
        {
            let new_flags = OwnershipFlags::make_return(poison_guard);

            let res = 
                self
                    .flags
                    .compare_exchange_weak(
                        new_flags.clone().into(), 
                        new_flags.clone().into(), 
                        Ordering::SeqCst, 
                        Ordering::Acquire
                    );

            if let Ok(val) = res
            {
                panic!("assertion trap: already returned val: {}, valflags: {}", val, OwnershipFlags::from(val));
            }

            let cur_flags: OwnershipFlags = res.err().unwrap().into();

            if cur_flags.drop_in_place == true
            {
                return true;
            }
            
            let res = 
                self
                    .flags
                    .compare_exchange_weak(
                        cur_flags.clone().into(), 
                        new_flags.clone().into(), 
                        Ordering::SeqCst, 
                        Ordering::Acquire
                    );

            if let Err(e) = res
            {
                panic!("assertion trap: can not return ownership, expected: '{}', got: '{}", cur_flags, new_flags);
            }

            return false;
        }

        pub(crate) 
        fn get_owner_flags(&self) -> Option<OwnershipFlags>
        {
            return Some(
                self
                    .flags
                    .load(Ordering::Relaxed)
                    .into()
            );
        }

        pub(crate) 
        fn get_item(&self) -> Option<&ITEM>
        {
            return self.item.as_ref();
        }

        pub(crate) 
        fn is_owned(&self) -> bool
        {
            let flags: OwnershipFlags = self.flags.load(Ordering::SeqCst).into();

            return flags.is_owned();
        }

        pub(crate) 
        fn clear_poisoned_mut<F>(&mut self, check_f: F) -> Result<(), TransferError>
        where F: FnOnce(&mut ITEM)
        {
            let mut flags: OwnershipFlags = self.flags.load(Ordering::Relaxed).into();

            if flags.is_owned() == false
            {
                return Err(TransferError::AlreadyTransfered);
            }

            (check_f)(self.item.as_mut().unwrap());

            flags.clear_poison();

            self.flags.store(flags.into(), Ordering::Relaxed);

            return Ok(());
        }

        pub(crate) 
        fn clear_poisoned<F>(&self, check_f: F) -> Result<(), TransferError>
        where F: FnOnce(&ITEM)
        {
            let mut flags: OwnershipFlags = self.flags.load(Ordering::Relaxed).into();

            if flags.is_owned() == false
            {
                return Err(TransferError::AlreadyTransfered);
            }

            (check_f)(self.item.as_ref().unwrap());

            flags.clear_poison();

            self.flags.store(flags.into(), Ordering::Relaxed);

            return Ok(());
        }


        pub(crate)  
        fn try_into_inner(&mut self, is_drop: bool) -> Result<ITEM, TransferError>
        {
            let mut flags: OwnershipFlags = self.flags.load(Ordering::Relaxed).into();

            if flags.owned == true 
            {
                let buf = self.item.take().unwrap();

                return Ok(buf);
            }
            else 
            {
                if is_drop == true
                {
                    let cur_flags = flags.clone();
                    flags.drop_in_place();

                    let res = 
                        self
                            .flags
                            .compare_exchange_weak(cur_flags.clone().into(), flags.clone().into(), Ordering::SeqCst, Ordering::Acquire);
                    
                    if let Ok(_) = res
                    {
                        return Err(TransferError::AlreadyTransfered);
                    }

                    return self.try_into_inner(is_drop);
                }

                return Err(TransferError::AlreadyTransfered);
            }
        }
    }
}

#[cfg(target_has_atomic = "64")]
use self::has_atomics::*;


#[cfg(not(target_has_atomic = "64"))]
mod not_atomics
{
    use std::sync::Mutex;

    use super::*;
    
    /// Inner type which is not exposed.
    #[derive(Debug)]
    pub struct OwnerInner<ITEM: Send + fmt::Debug>
    {
        /// A [OwnershipFlags] represented as atomic u32.
        flags: Mutex<OwnershipFlags>,

        /// An item to share.
        item: Option<ITEM>,
    }

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

    impl<ITEM: Send + fmt::Debug> Deref for OwnerInner<ITEM>
    {
        type Target = ITEM;

        #[inline]
        fn deref(&self) -> &Self::Target
        {
            return self.item.as_ref().unwrap();
        }
    }

    impl<ITEM: Send + fmt::Debug> DerefMut for OwnerInner<ITEM>
    {
        #[inline]
        fn deref_mut(&mut self) -> &mut Self::Target
        {
            return self.item.as_mut().unwrap();
        }
    }

    impl<ITEM: Send  + fmt::Debug> OwnerInner<ITEM>
    {
        pub(crate) 
        fn new(item: ITEM) -> Self
        {
            return
                Self
                {
                    flags: 
                        Mutex::new(OwnershipFlags::default()),
                    item: 
                        Some(item)
                };
        }

        pub(crate) 
        fn transfer_ownership(&self) -> Result<TransferPanicGuard, TransferError>
        {
            let mut lock = self.flags.lock().unwrap_or_else(std::sync::PoisonError::into_inner);

           return lock.transfer();
        }

        /// Returns `true` if drop-in-place is required.
        pub(crate) 
        fn return_ownership(&self, poison_guard: &TransferPanicGuard) -> bool
        {
            // it is safe because the ItemOwnershipTransfer presents as signle instance
            let mut lock = self.flags.lock().unwrap_or_else(std::sync::PoisonError::into_inner);

            lock.return_transfer(poison_guard);

            if lock.drop_in_place == true
            {
                return true;
            }
            
            return false;
        }

        pub(crate) 
        fn get_owner_flags(&self) -> Option<OwnershipFlags>
        {
            return 
                self
                    .flags
                    .try_lock()
                    .map_or(None, |f| Some(f.clone()));
        }

        pub(crate) 
        fn get_item(&self) -> Option<&ITEM>
        {
            return self.item.as_ref();
        }

        #[inline]
        pub(crate) 
        fn is_owned(&self) -> bool
        {
            return self.flags.lock().unwrap_or_else(std::sync::PoisonError::into_inner).owned;
        }

        pub(crate) 
        fn clear_poisoned_mut<F>(&mut self, check_f: F) -> Result<(), TransferError>
        where F: FnOnce(&mut ITEM)
        {
            let mut lock = 
                self
                    .flags
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner);

            (check_f)(self.item.as_mut().unwrap());

            lock.clear_poison();

            return Ok(());
        }

        pub(crate) 
        fn clear_poisoned<F>(&self, check_f: F) -> Result<(), TransferError>
        where F: FnOnce(&ITEM)
        {
            let mut lock = 
                self
                    .flags
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner);

            (check_f)(self.item.as_ref().unwrap());

            lock.clear_poison();

            return Ok(());
        }

        pub(crate) 
        fn try_into_inner(&mut self, is_drop: bool) -> Result<ITEM, TransferError>
        {
            let mut lock = 
                self
                    .flags
                    .lock()
                    .unwrap_or_else(std::sync::PoisonError::into_inner);

            if lock.owned == true 
            {
                let buf = self.item.take().unwrap();

                return Ok(buf);
            }
            else 
            {
                if is_drop == true
                {
                    lock.drop_in_place = true;
                }

                return Err(TransferError::AlreadyTransfered);
            }
        }
    }
}

#[cfg(not(target_has_atomic = "64"))]
use self::not_atomics::*;
    


/// An instance which holds the exclusive lock and provides `ref` and `mut`
/// dereferencing. This instance can be [Send] over to other threads which 
/// would like to gain a temporary access.
/// 
/// If thread panics, the owner of the `ITEM` will be `poisoned` and should be
/// restored manually.
#[derive(Debug)]
pub struct ItemOwnershipTransfer<ITEM: Send + fmt::Debug>
{
    poison_guard: TransferPanicGuard,
    owner_inner: NonNull<OwnerInner<ITEM>>,
}


impl<ITEM: Send + fmt::Debug> ItemOwnershipTransfer<ITEM>
{
    #[inline]
    fn new(inner: NonNull<OwnerInner<ITEM>>, poison_guard: TransferPanicGuard,) -> Self
    {
        return 
            Self
            {   poison_guard: poison_guard,
                owner_inner: inner
            };
    }

    #[cfg(test)]
    #[inline]
    fn inner(&self) -> &OwnerInner<ITEM>
    {
        return unsafe { self.owner_inner.as_ref() };
    }
}

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

impl<ITEM: Send + fmt::Debug> Deref for ItemOwnershipTransfer<ITEM>
{
    type Target = ITEM;

    fn deref(&self) -> &Self::Target
    {
        let inner = unsafe { self.owner_inner.as_ref() };

        return inner;
    }
}

impl<ITEM: Send + fmt::Debug> DerefMut for ItemOwnershipTransfer<ITEM>
{
    fn deref_mut(&mut self) -> &mut Self::Target
    {
        let inner = unsafe { self.owner_inner.as_mut() };

        return inner;
    }
}

impl<ITEM: Send + fmt::Debug> Drop for ItemOwnershipTransfer<ITEM>
{
    /// The instance may perform `drop_in_place` if there is no `base` references.
    fn drop(&mut self)
    {
        let inner = unsafe { self.owner_inner.as_ref() };

        if inner.return_ownership(&self.poison_guard) == true
        {
            // call descrutor
            unsafe { ptr::drop_in_place(self.owner_inner.as_ptr()) };

            return;
        }
    }
}

/// An owner of the intance `ITEM` which holds the exclusive rights.
/// It may temporary transfer the ownership over `ITEM` and `Send` it
/// to other thread. The transfered ownership is defined by [ItemOwnershipTransfer]
/// which is a temporary container.
/// 
/// The ownership cannot be transferred simultaniously twice, so the exclusive 
/// R/W access is guaranteed.
/// 
/// In case of the [ItemOwner] dropeed before the [ItemOwnershipTransfer] releases 
/// the transfer, the [ItemOwnershipTransfer] would drop the data in place.
/// 
/// The `ITEM` can be returned from the instance only if no-exclusive transfer is
/// pending.
/// 
/// The `ITEM` must be [Send] and implement [fmt::Debug].
#[derive(Debug, PartialEq, Eq)]
pub struct ItemOwner<ITEM: Send + fmt::Debug>( NonNull<OwnerInner<ITEM>> );

impl<ITEM: Send + fmt::Debug> fmt::Display for  ItemOwner<ITEM>
{
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result 
    {
        let flags = 
            self
                .inner()
                .get_owner_flags()
                .map_or("locked".into(), |f| f.to_string());

        write!(f, "flags: {}, item: {:?}", flags, self.inner().get_item())
    }
}

impl<ITEM: Send + fmt::Debug>  ItemOwner<ITEM>
{
    /// Creates new instance.
    pub 
    fn new(item: ITEM) -> Self
    {
        let status = Box::new(OwnerInner::new(item));

        return Self(Box::leak(status).into());
    }

    /// Returns the reference to the`inner` [OwnerInner] type. Must never be exposed outside.
    #[inline]
    fn inner(&self) -> &OwnerInner<ITEM>
    {
        return unsafe { self.0.as_ref() };
    }

    /// Returns the reference to the`inner` [OwnerInner] type. Must never be exposed outside.
    #[inline]
    fn inner_mut(&mut self) -> &mut OwnerInner<ITEM>
    {
        return unsafe { self.0.as_mut() };
    }

    /// Checks if the instance owns the `ITEM`. If transfer is still pending `false` will be 
    /// retruned and no `transfer_ownership` is possible.
    #[inline]
    pub 
    fn is_owned(&self) -> bool
    {
        return self.inner().is_owned();
    }

    /// Initiates the tmporary transfer of the ownership. If the exclusive lock is available
    /// i.e no transfer is penfing an [ItemOwnershipTransfer] will be returned which can be
    /// [Send] i.e over channel. 
    /// 
    /// Returns [Result::Err] 
    /// 
    /// * with [TransferError::AlreadyTransfered] only if transfer is still pending.
    /// 
    /// * with [TransferError::Poisoned] only if thread which used the trnasfer paniced.
    /// 
    /// * with [TransferError::AlreadyReturned] only if attempt faild and should be repeated.
    pub 
    fn transfer_ownership(&self) -> Result<ItemOwnershipTransfer<ITEM>, TransferError>
    {
        let inner = self.inner();

        let transfer = inner.transfer_ownership()?;

        return Ok( ItemOwnershipTransfer::new(self.0.clone(), transfer) );
    }

    /// Attempts to clear the poisoned status. If instance is `poisoned` i.e thread to which
    /// the ownership was temporary transferred paniced, it should be cleaned manyally otherwise
    /// the `transfer_ownership` would return [TransferError::Poisoned].
    pub 
    fn clear_poisoned_mut<F>(&mut self, check_f: F) -> Result<(), TransferError>
    where F: FnOnce(&mut ITEM)
    {
        let inner = self.inner_mut();

        return inner.clear_poisoned_mut(check_f);
    }

    /// Attempts to clear the poisoned status. If instance is `poisoned` i.e thread to which
    /// the ownership was temporary transferred paniced, it should be cleaned manyally otherwise
    /// the `transfer_ownership` would return [TransferError::Poisoned].
    pub 
    fn clear_poisoned<F>(&self, check_f: F) -> Result<(), TransferError>
    where F: FnOnce(&ITEM)
    {
        let inner = self.inner();

        return inner.clear_poisoned(check_f);
    }

    /// Attempts to consume `Self` to return the `ITEM` from the instance.
    /// 
    /// This is only possible if instance is not `poisoned` and `owned`.
    /// 
    /// In case of success, the `ITEM` will be returned, otherwise the 
    /// `Self` and [TransferError] will be returned.
    /// 
    /// * [TransferError::AlreadyTransfered] - if item is still stransferred.
    pub 
    fn try_into_inner(mut self) -> Result<ITEM, (Self, TransferError)>
    {
        let res =
            self
                .inner_mut()
                .try_into_inner(false);

        if let Ok(r) = res
        {
            drop(self);

            return Ok(r);
        }

        return res.map_err(|e| (self, e));
    }
}

impl<ITEM: Send + fmt::Debug> Drop for ItemOwner<ITEM>
{
    fn drop(&mut self) 
    {
        let res =
            self
                .inner_mut()
                .try_into_inner(true);

        if let Ok(_) = res
        {
            // call descrutor
            unsafe { ptr::drop_in_place(self.0.as_ptr()) };
        }
        
        return;
    }
}


#[cfg(all(feature = "std", target_has_atomic = "64"))]
#[cfg(test)]
mod test 
{
    use std::{fmt, sync::{atomic::{AtomicU32, Ordering}, mpsc}, time::Duration};

    use crate::{ItemOwner, ItemOwnershipTransfer, OwnershipFlags, TransferError};

    pub trait PeriodicTask: Send + fmt::Debug
    {
        fn exec(&mut self) -> Result<(), String>;
        fn get_val(&self) -> u32;
    }

    pub type PeriodicTaskHndl = Box<dyn PeriodicTask>;

    static DROP_FLAG: AtomicU32 = AtomicU32::new(0);

    #[derive(Debug)]
    pub struct Task1
    {
        val: u32
    }

    impl Drop for Task1
    {
        fn drop(&mut self) 
        {
            DROP_FLAG.fetch_add(1, Ordering::AcqRel);
            println!("dropped!");
        }
    }

    impl PeriodicTask for Task1
    {
        fn get_val(&self) -> u32
        {
            return self.val;
        }

        fn exec(&mut self) -> Result<(), String> 
        {
            println!("task {} called", self.val);

            return Ok(());
        }
    }

    #[test]
    fn test_a1()
    {
        let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
        let owner = ItemOwner::new(task1);

        let transf = owner.transfer_ownership().unwrap();

        assert_eq!(owner.is_owned(), false);
        
        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, false);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, false);

        assert_eq!(transf.as_ref().get_val(), 2);

        drop(transf);
        
        assert_eq!(owner.is_owned(), true);

        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, true);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, false);


        let mut transf = owner.transfer_ownership().unwrap();
        let transf_dup = owner.transfer_ownership();
        assert_eq!(transf_dup.is_err(), true);
        assert_eq!(transf_dup.err(), Some(TransferError::AlreadyTransfered));

        // just call to avoid optimizing
        transf.as_mut().exec().unwrap();

        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, false);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, false);

        println!("{}", owner);

        // drop the owner to test the drop in place
        drop(owner);

        let flags: OwnershipFlags = transf.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, false);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, true);

        drop(transf);

        assert_eq!(DROP_FLAG.load(Ordering::Acquire), 1);
    }
    
    #[test]
    #[should_panic(expected = "should panic!")]
    fn test_a2()
    {
        DROP_FLAG.store(0, Ordering::SeqCst);

        let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
        let owner = ItemOwner::new(task1);

        let (se, rc) = 
            mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();

            
        let thread_hndl = 
            std::thread::spawn(move || 
                {
                    let _task = rc.recv().unwrap();

                    panic!("should panic!");

                }
            );

        

        // send ownership transfer over
        se.send(owner.transfer_ownership().unwrap()).unwrap();

        let _ = thread_hndl.join();

        // check if poisoned.
        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, true);
        assert_eq!(owner.is_owned(), true);
        assert_eq!(flags.poisoned, true);
        assert_eq!(flags.drop_in_place, false);


        let transf = owner.transfer_ownership();
        assert_eq!(transf.is_err(), true);
        assert_eq!(transf.err(), Some(TransferError::Poisoned));

        // clear poison
        owner.clear_poisoned(|v| {}).unwrap();

        // reaquie transfer
        let transf = owner.transfer_ownership();
        assert_eq!(transf.is_ok(), true);

        drop(transf);
        drop(owner);

        assert_eq!(DROP_FLAG.load(Ordering::Acquire), 1);

        panic!("should panic!");
    }

    #[test]
    fn test_a3()
    {
        DROP_FLAG.store(0, Ordering::SeqCst);
        
        let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
        let owner = ItemOwner::new(task1);

        let (se, rc) = 
            mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();

        let thread_hndl = 
            std::thread::spawn(move || 
                {
                    let mut task = rc.recv().unwrap();

                    std::thread::sleep(Duration::from_secs(2));
                    task.as_mut().exec().unwrap();

                    return;
                }
            );


        se.send(owner.transfer_ownership().unwrap()).unwrap();

        while owner.is_owned() == false
        {
            std::thread::sleep(Duration::from_secs(1));
        }

        println!("completed round 1");

        thread_hndl.join().unwrap();

        let (se, rc) = 
            mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();

        let thread_hndl = 
            std::thread::spawn(move || 
                {
                    let mut task = rc.recv().unwrap();

                    std::thread::sleep(Duration::from_secs(2));
                    task.as_mut().exec().unwrap();

                    return;
                }
            );

        se.send(owner.transfer_ownership().unwrap()).unwrap();

        while owner.is_owned() == false
        {
            std::thread::sleep(Duration::from_secs(1));
        }

        println!("completed round 2");

        thread_hndl.join().unwrap();


        return;
    }

    
}
    

#[cfg(all(feature = "std", not(target_has_atomic = "64")))]
#[cfg(test)]
mod test 
{
    use std::{fmt, sync::{atomic::{AtomicU32, Ordering}, mpsc}, time::Duration};

    use crate::{ItemOwner, ItemOwnershipTransfer, OwnershipFlags, TransferError};

    pub trait PeriodicTask: Send + fmt::Debug
    {
        fn exec(&mut self) -> Result<(), String>;
        fn get_val(&self) -> u32;
    }

    pub type PeriodicTaskHndl = Box<dyn PeriodicTask>;

    static DROP_FLAG: AtomicU32 = AtomicU32::new(0);

    #[derive(Debug)]
    pub struct Task1
    {
        val: u32
    }

    impl Drop for Task1
    {
        fn drop(&mut self) 
        {
            DROP_FLAG.fetch_add(1, Ordering::AcqRel);
            println!("dropped!");
        }
    }

    impl PeriodicTask for Task1
    {
        fn get_val(&self) -> u32
        {
            return self.val;
        }

        fn exec(&mut self) -> Result<(), String> 
        {
            println!("task {} called", self.val);

            return Ok(());
        }
    }

    #[test]
    fn test_a1()
    {
        let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
        let owner = ItemOwner::new(task1);

        let transf = owner.transfer_ownership().unwrap();

        assert_eq!(owner.is_owned(), false);
        
        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, false);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, false);

        assert_eq!(transf.as_ref().get_val(), 2);

        drop(transf);
        
        assert_eq!(owner.is_owned(), true);

        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, true);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, false);


        let mut transf = owner.transfer_ownership().unwrap();
        let transf_dup = owner.transfer_ownership();
        assert_eq!(transf_dup.is_err(), true);
        assert_eq!(transf_dup.err(), Some(TransferError::AlreadyTransfered));

        // just call to avoid optimizing
        transf.as_mut().exec().unwrap();

        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, false);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, false);

        println!("{}", owner);

        // drop the owner to test the drop in place
        drop(owner);

        let flags: OwnershipFlags = transf.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, false);
        assert_eq!(flags.poisoned, false);
        assert_eq!(flags.drop_in_place, true);

        drop(transf);

        assert_eq!(DROP_FLAG.load(Ordering::Acquire), 1);
    }
    
    #[test]
    #[should_panic(expected = "should panic!")]
    fn test_a2()
    {
        DROP_FLAG.store(0, Ordering::SeqCst);

        let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
        let owner = ItemOwner::new(task1);

        let (se, rc) = 
            mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();

            
        let thread_hndl = 
            std::thread::spawn(move || 
                {
                    let _task = rc.recv().unwrap();

                    panic!("should panic!");

                }
            );

        

        // send ownership transfer over
        se.send(owner.transfer_ownership().unwrap()).unwrap();

        let _ = thread_hndl.join();

        // check if poisoned.
        let flags: OwnershipFlags = owner.inner().get_owner_flags().unwrap();
        assert_eq!(flags.owned, true);
        assert_eq!(owner.is_owned(), true);
        assert_eq!(flags.poisoned, true);
        assert_eq!(flags.drop_in_place, false);


        let transf = owner.transfer_ownership();
        assert_eq!(transf.is_err(), true);
        assert_eq!(transf.err(), Some(TransferError::Poisoned));

        // clear poison
        owner.clear_poisoned(|itme| {}).unwrap();

        // reaquie transfer
        let transf = owner.transfer_ownership();
        assert_eq!(transf.is_ok(), true);

        drop(transf);
        drop(owner);

        assert_eq!(DROP_FLAG.load(Ordering::Acquire), 1);

        panic!("should panic!");
    }

    #[test]
    fn test_a3()
    {
        DROP_FLAG.store(0, Ordering::SeqCst);
        
        let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
        let owner = ItemOwner::new(task1);

        let (se, rc) = 
            mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();

        let thread_hndl = 
            std::thread::spawn(move || 
                {
                    let mut task = rc.recv().unwrap();

                    std::thread::sleep(Duration::from_secs(2));
                    task.as_mut().exec().unwrap();

                    return;
                }
            );


        se.send(owner.transfer_ownership().unwrap()).unwrap();

        while owner.is_owned() == false
        {
            std::thread::sleep(Duration::from_secs(1));
        }

        println!("completed round 1");

        thread_hndl.join().unwrap();

        let (se, rc) = 
            mpsc::channel::<ItemOwnershipTransfer<PeriodicTaskHndl>>();

        let thread_hndl = 
            std::thread::spawn(move || 
                {
                    let mut task = rc.recv().unwrap();

                    std::thread::sleep(Duration::from_secs(2));
                    task.as_mut().exec().unwrap();

                    return;
                }
            );

        se.send(owner.transfer_ownership().unwrap()).unwrap();

        while owner.is_owned() == false
        {
            std::thread::sleep(Duration::from_secs(1));
        }

        println!("completed round 2");

        thread_hndl.join().unwrap();


        return;
    }

    
}