temporary-owner-rs

A kind of a RefCell which temporary transfers the owner rights to other thread providing exclusive access to the provided data.

The purpose of this crate is to provide an access to the inner item via temporary transferring the owner rights providing the exclusive access. The inner item must be Sync and Send because the main purpose is to share the instance with other threads by sending it via channel.

The locking is provided by the atomics with the Accure-Release ordering.

This crate is not tested completly!

Supports ![no_std] if feature std is not enabled.

Dual licensed crate.

Policy

• This crate i.e code is NOT an Open Source software. This is a FREE (gratis) software and follows the principle of Sources Available/Disclosed software which should be fairly used.
• It is published under FSF/OSI approved licenses however author does not follow/share/respect OSI and FSF principles and phylosophy.
• License is subject to be changed in further versions without warning.
• If you are using code in non-free (in terms of gratis) software you MUST NEVER demand a development of any features which are missing and needed for your business if you are not sponsoring/contributing those changes.
• Access to the code can be limited by author to specific entities due to the local laws (not my bad or fault)(despite what is said in the license).

Version

V0.2.0

License:

Sources are available under: MPL-2.0 OR EUPL-1.2

Examples

The examples are availabe in the directory examples.

Block diagram

                     ┌───────────────────┐                                         
                     │                   │                                         
                     │     ItemOwner     │◄───────────────────────────────────────┐
                     │                   │                                        │
                     └────────┬──────────┘                                        │
                              │                                                   │
                              │                                                   │
                              │                                                   │
                              │                                                   │
                    ┌─────────▼──────────────┐                                    │
                    │                        │                                    │
                    │  transfer_ownership()  │                                    │
                    │                        │                                    │
                    └────┬──┬──┬─────────────┘                                    │
                         │  │  │                                                  │
                         │  │  │  ───────────────────────────────────────         │
                         │  │  │         EXCLUSIVE ACCESS                         │
┌──────────────────┐     │  │  │     ┌───────────────────────────┐                │
│                  │     │  │  │     │         INSTANCE          │                │
│                  ◄─────┘  │  └─────►                           │                │
│  TransferError   │        │        │    ItemOwnershipTransfer  │                │
├──────────────────┘        │        └────────────┬──────────────┘                │
│                           │                     │                               │
├── AlreadyTransfered       │                     │                               │
│                           │          ┌──────────▼─────────────┐                 │
│                           │          │     send_over_MPSC     │                 │
│                           │          └────────────────────────┘                 │
│                           │                                                     │
│                                                                                 │
└── Poisoned                ───────    ────    ─────   ──────    ───    ───       │
                                                                                  │
                              ┌─────────────┐                                     │
                              │  Thread N   │                                     │
                              └─────────────┘─────────────────────┐               │
                                      │       MPSC_RECV           │               │
                                      │                           │               │
                                      │   ItemOwnershipTransfer   │               │
                                      └────────────┬──────────────┘               │
                                                   │                              │
                                                   │                              │
                                           ┌───────▼──────────┐                   │
                                           │   as_ref()       │                   │
                                           │                  │                   │
                                           │   as_mut()       │                   │
                                           └───────┬──────────┘                   │
                                                   │                              │
                                                   │                              │
                                           ┌───────▼──────────┐                   │
                                           │   drop()         │                   │
                                           │                  ┼───────────────────┘
                                           └──────────────────┘                                                            

Usage.

Firstly, the inner item should be initialized and the Owner container should be created with the inner item.

/// The inenr type. It is not necessary that it should be in the `Box`.
let task1: PeriodicTaskHndl = Box::new(Task1{ val: 2 });
 
// creating new instance
let owner = ItemOwner::new(task1);

A ownership can be transfered. Like RefCell provides borrow, here an exclusive transfer can be perfromed.

let transfer: ItemOwnershipTransfer<PeriodicTaskHndl> = owner.transfer_ownership().unwrap()

The obtained ItemOwnershipTransfer can be send over the MPSC or any other way because it is Sync + Send.

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

    se.send(transfer);

The ownership can be returned by droppping the transfer.

    let mut task: ItemOwnershipTransfer<PeriodicTaskHndl> = rc.recv().unwrap();
    task.as_mut().exec().unwrap();

    // return the borrow
    drop(task);

The inner value can be accessed via dereferencing. In case if receiving thread panics before returning the borrowed ownership, the instance becomes poisoned (like mutex) and this status should be cleared manually.

The ItemOwnershipTransfer cannot be cloned and must never be copied to have multiple instances. it is not dsigned to handle this properly.

Example

use std::{fmt, sync::{atomic::{AtomicU32, Ordering}, mpsc}, time::Duration};

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

pub trait PeriodicTask: Send + Sync + 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(());
    }
}

fn main()
{
    
    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;
}