# A combination of Arc and RefCell for buffer sharing.
The purpose of this crate to manage and provide the buffer allocation and access to the
buffer in a RefCell manner but in a way the Arc does.
The crate provides a managing instance to the allocated buffer memeory which can be accessed
exclusivly (write-read) access in the current thread or shared access (read-only) in any thread.
The locking is provided by the atomics with the Accure-Release ordering.
This crate is not tested completly.
It may not work as intended on multithreading tokio instances, but should work in tokio single thread
mode or with threads.
# Examples
The examples are availabe in the directory `examples`.
# Usage.
Firstly, the base instance should be created:
```Rust
// bounded
let mut bufs = RwBuffers::new(4096, 1, 3).unwrap();
// or unbounded
let mut bufs = RwBuffers::new_unbounded(4096, 1).unwrap();
```
Then a buffer can be obtained from it.
```Rust
let buf: RwBuffer = bufs.allocate().unwrap();
```
The allocate buf `RwBuffer` is stored on the list in `RwBuffers` and another instance
is returned. If it is not required to reuse the instance, the `allocate_in_place` function
allocates the instance without storing it into the `RwBuffers`.
To obtain an exclusive access, use:
```Rust
let buf_w = buf.write().unwrap();
```
The inner buffer can be accessed via dereferencing. The write instance can be downgraded to
shared lock. The `exclusive` instance can not be clonned, send or sync.
In order to obtain a `shared` access, the `exclusive` access should be either downgraded and
clonned (if needed) or dropped.
In order to obtain an `exclusive` access again, all `shared` accesses must be dropped.
The `shared` access can be consumed to return the inner buffer vector, however it should
satisfy the following conditions:
1. Only one shared access
2. No exclusive access
3. No base i.e `RwBuffer` left undropped.
The shared access can be obtained also via:
```Rust
let buf_r: RBuffer = buf.read();
```
The `RBuffer` or `RwBuffer` are Sync and Send. However, by design, only `RBuffer` should be shared.