instance-copy-on-write

An experimental thread access synchronization primitive which is based on CoW Copy-on-Write and also exclusive lock.

The purpose of this crate to attempt to introduce a CoW model of data access synchronization. The create is based on the crossbeam and atomics.

• The ICoWRead provides read only which is binded to ICoW and until ICoW is valid. The data will not be updated until re-read.

• The ICoWWeak provides read only until ICoW is valid.

• The ICoWCopy provides a Copied instance which is modified and commmited back.

• The ICoWLock provides an exclusive lock which locks reading and writing.

[!ATTENTION] By default an RwLock based implementation is used, because the atomics based implementation is still not ready. It can be activated by enabling the feature prefer_atomic.

The ICoWRead<DATA> instance with inner value DATA obtained from the ICoW<DATA> is valid even after the inner value was copied and copy was commited back. All readers which will will read the ICoW instance after the commit will receive a ICoWRead<DATA> with updated DATA.

Exclusive copying prevents readers from reading while simple non-exclusive copy allows to access the inner data for reading and further copying. But, the non-exclusive copies are not in sync, so each copy is uniq. The sequential commit of copied data is not yet supported.

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 must 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

v 0.9.1 Experimental.

License:

Sources are licensed with: MIT License

Description

There are three types of the operations:

• Read-only reference

• Copy-on-Write writing and storing

• Exclusive copy-on-write (giant lock).

All read instances are valid all the time until dropeed, even if the CoW operation was performed.

After CoW instance commited, all new readers will see new value, all previous readers the previous value.

It was designed for the short period and small structures which can be copied. Also, where write operations can fail and the program is ok to use updated value.

An atocis-based CoW operation.

                              ┌─────────────────┐                                   
             ┌────────────────┤  ICoW<Instance> ┼───────────────┐                   
             ▼                └─────────┬───────┘               ▼                   
                                        │                                           
                                        ▼                                           
        ┌──────────┐             ┌─────────────┐      ┌────────────────────┐        
┌──────►│  read()  │◄────────────┤    copy(),  │      │ copy_exclusivly()  │        
│       └────┬─────┘          ^  │    clone()  │      │ clone_exclusivly() │        
│excl.lock   │                |  └─────────────┘      └─────────┬──────────┘        
│ repeat     │                |                                 │                   
│   ┌────────▼───────────┐    V  ┌────────────┐       ┌─────────▼──────────┐        
└───┼ compare_exchange() │    ┌► │ ICowCopy   │       │ compare_exchange() │        
    └────────┬───────────┘    │  └─────┬──────┘       │ self <- null_ptr   │        
             │  success       │        │              └─────────┬──────────┘        
             │                │        │                        │                   
      ┌──────▼──────┐         │        │               ┌────────▼──────────┐ locked 
      │   clone()   │         │        │               │      IF           │already 
      └──────┬──────┘         │        │               │ self == null_ptr  ┼───────┐
             │                │        │               └───────┬───────────┘       │
             │                │        │                       │                   │
             │                │        │                       │                   │
    ┌────────▼────────────┐   │        │              ┌────────▼────────────┐      │
    │ ICowRead<Instance>  ├───┘        │              │ ICowLock<Instance>  │      │
    └────────┬────────────┘            │              └────────┬────────────┘      │
             │                         │                       │                   │
             │                         ▼                       │                   │
             ▼                                                 │                   │
      ┌──────────────┐           ┌─────────────┐               │                   │
      │   / ... /    │           │  / ... /    │◄──────────────┘                   │
      └──────┬───────┘           └───┬────────┬┘                                   │
             │                       │  OR    │                                    │
             │                       │        │                                    │
     ┌───────▼─────┐         ┌───────▼──┐   ┌─▼────────┐                           │
     │  drop()     │         │ drop()   │   │ commit() │                           ▼
     └─────────────┘         └──────────┘   └──────────┘                            

Examples

Sync syslog (Local Shared)

let val = 
    ICoW::new(TestStruct::new(1, 2));

// read only 
let read1 = val.read();
//..
drop(read1);

// ...

// copy on write NON-exclusively, read is possible
let mut transaction = val.clone_copy();

transaction.start = 5;
transaction.stop = 6;

// update, after calling this function, all reades who 
// read before will still see old version.
// all reades after, new
transaction.commit();
//or
drop(transaction); // to drop changes


// exclusive lock, read is also not possible

let res = val.clone_copy_exclusivly();
// ..
// commit changes releasing lock
commit(val); //or
drop(val); // to drop changes and release lock