# shared-buffer-rs
<img src="https://cdn.4neko.org/shared_buffer_rs.webp" width="450"/>
## A combination of Arc and RefCell for buffer exclusive/shared accessing and sharing between threads.
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 SeqCst ordering.
This crate IS experimental.
It may not work as intended on multithreading tokio instances, but should work in tokio single thread
mode or with threads.
### 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>
<details>
<summary>Questions about license MPL-2.0</summary>
- Can I use the MPL-2.0 licensed code (crate) in larger project licensed with more permissive license like BSD or MIT.
>I want to distribute (outside my organization) executable programs or libraries that I have compiled from someone else's unchanged MPL-licensed source code, either standalone or part of a larger work. What do I have to do?
>You must inform the recipients where they can get the source for the MPLed code in the executable program or library you are distributing (i.e., you must comply with Section 3.2). You may distribute any executables you create under a license of your choosing, as long as that license does not interfere with the recipients' rights to the source under the terms of the MPL.
[MPL2.0 FAQ](https://www.mozilla.org/en-US/MPL/2.0/FAQ/)
> Yes, MPL- and Apache-licensed code can be used with an MIT codebase (so in that sense, they are "compatible").
However, the MPL- / Apache-licensed code remains under its original license. (So although compatible, you cannot relicense someone else's MPL or Apache code into the MIT license.) This means that your final codebase will contain a mix of MPL, Apache, and MIT licensed code.
As an example, MPL has weak copyleft, so if you modified an MPL file, that file (including your changes) must remain under the MPL license.
[Answer1](https://www.reddit.com/r/learnprogramming/comments/1dn58or/comment/la0jt4c/?utm_source=share&utm_medium=web3x&utm_name=web3xcss&utm_term=1&utm_content=share_button)
</details>
<details>
<summary>Questions about license EUPL-1.2</summary>
You should use this license if you are located in the EU which gives you more advantages over GPL because
in case of any disputes, the license allows you to defend your rights in a European Union country, in this case it will be Spain. It has also been translated into all languages of the EU member states.
[Matrix of EUPL compatible open source licences](https://interoperable-europe.ec.europa.eu/collection/eupl/matrix-eupl-compatible-open-source-licences)
`EUPL-1.2` is incompatiable with `GPL` according to [GNU ORG](https://www.gnu.org/licenses/license-list.html)
> This is a free software license. By itself, it has a copyleft comparable to the GPL's, and incompatible with it.
</details>
## Version
V0.3.2
<details>
<summary>Changelog</summary>
+ The SeqCst ordering was replaced with Relaxed on the first attempt.
+ Added comments
+ Added async_clone.
</details>
<details>
<summary>Changelog v0.3.1</summary>
+ Locking logic was re-implemented.
+ Added async code to obtain read and write as futures. But it still drops the buffers in the sync manner blocking the thread.
</details>
<details>
<summary>V0.2.0</summary>
- Fixed errors accure_in_lace().
- Added no_std.
- License changed!
</details>
## License:
<img src="https://cdn.4neko.org/mpl_or_eupl_500.webp" width="300"/>
Sources are available under: **MPL-2.0 OR EUPL-1.2**
## Examples
The examples are availabe in the directory `examples`.
## Block diagram
```text
┌─────────────┐ ┌──────────────┐
│ │ │ │
│ RwBuffers ┼────► allocate() │
│ │ │ │
└─────────────┘ └──────┬───────┘
│
│
┌────▼───────┐ ┌───────────┐
│ │ │ │
│ RwBuffer ┼────► write() │
│ │ │ │
└──────┬─────┘ └─────┬─────┘
│ │
│ │
│ ┌─────▼─────┐ ┌───────────┐
│ │ │ │ writing │
│ │ WBuffer ◄──────┼ data() │
│ │ │ │ │
│ └─────┬─────┘ └───────────┘
│ │
│ │
│ │
│ ┌────▼────────┐
│ │ │
│ │ downgrade() │
│ │ │
│ └────┬────────┘
│ │
───────────────────┼────────────────┼─────────────────────────────
WBuffer dropped. │ │
┌───────▼───┐ ┌────▼────────┐
│ │ │ │
│ read() │ │ RBuffer │
│ │ │ │
└───────┬───┘ └─────────────┘
│
│
│
┌───────▼───┐
│ │
│ RBuffer │
│ │
└───────────┘
```
## 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();
```
-- or --
```Rust
let buf0_w = buf0.write_async().await.unwrap();
// ...
async_drop(buf0_w).await;
```
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();
```
-- or --
```Rust
let buf1_rd = buf0.read_async().await.unwrap();
// ...
async_drop(buf1_rd).await;
```
The `RBuffer` or `RwBuffer` are Sync and Send. However, by design, only `RBuffer` should be shared.