# instance-copy-on-write
<img src="https://cdn.4neko.org/cow_500.webp " width="300"/>
## 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.
<details>
<summary>Policy</summary>
<img src="https://cdn.4neko.org/source_avail2.webp" width="300"/>
- 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).
</details>
<details>
<summary>AI policy</summary>
- AI generated sloppy code is prohibited. AI generates slop "a priori" (anyway).
- Licenses (thank you OSS sectarians ) do not anyhow limit AI training, but f^ck you all - ChatGPT, Co~~ck~~Pilot, especially Claude and rest unidentified cr@p.
- It is strongly discouraged from using the AI based tools to write or enhance the code. AI slope would 100% violate the license by introducing the 3rd party licensed code.
</details>
<details>
<summary>Pull requests</summary>
The pull requests are now supported because the repository was moved to Codeberg. The alternative way is to send patches
over the email to patch\[at\]4neko.org.
In case if you would like to contribute the code, please use pull request. Your pull request should include:
- Description of changes and why it is needed.
- Test the pull request.
In case of you prefer email and patch files please consider the following:
- For each feature or fix, please send patches separatly.
- Please write what your patch is implementing or fixing.
- I can read the code and I am able to understand it, so don't write a poem or essay in the description to the patches.
- Please test your patch.
</details>
## Version
v 0.9.1 Experimental.
<details>
<summary>Changelog</summary>
+ Added export "use".
</details>
<details>
<summary>Changelog v0.9.0</summary>
+ A `aquire` function in `ICoWWeak` is now sets the flag in `ICoWWeakRead` which allows to determine if instance was updated. A `item_updated` returns the result.
</details>
<details>
<summary>Changelog v0.8.0</summary>
+ A `ICoWWeak` was added which allows to store timeless reference to ICoW for reading.
+ Removed some functions to comply with a new r/w model. The internal value's Arc is no longer
leaked.
</details>
<details>
<summary>Changelog v 0.7.0</summary>
+ A new sync mechanism was implemented in atomic base CoW (atomic CoW) to achive fast `read` operations
and slower `write`s.
+ Added experimental `cow_refcell` for sinhgle thread apps.
</details>
<details>
<summary>Changelog v0.6.0</summary>
+ Atomics was updated. Implemented another locking model which utilizes the `transaction` style
which in theory is thread safe.
+ Added convertion into `ICoWCopy` from `ICoWRead`.
+ Added `Weak` referencing which could be obtained from `ICoWRead`. This would allow to detect if
cached `ICoWRead` got outdated.
+ For the atomics, added a `Waker` which should wakeup the thread/s which was/were parked while
waiting for the exclusive lock. Untested!
+ A `ICoW::clone()` and the rest functions which are related to `clone_*()` were renamed to `clone_copy` to avoid collisions with the `Clone::clone()`.
</details>
<details>
<summary>Changelog v0.5.0</summary>
+ Removed Send trait.
</details>
<details>
<summary>Changelog v0.4.0</summary>
+ License change to MIT
+ Added Drop for ICoWLock to avoid dead locks.
</details>
## License:
<img src="https://cdn.4neko.org/mit.webp" width="150"/>
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() │
│ ┌────────▼───────────┐ 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)
<details>
<summary>Example</summary>
```rust
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
```
</details>