Crate temporary_owner_rs 

This is an experimental crate!

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.

                     ┌───────────────────┐                                         
                     │                   │                                         
                     │     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

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;
}

Structs

ItemOwner

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.

ItemOwnershipTransfer

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.

Enums

TransferError

Error code which describes what happened.