shared-buffer-rs
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.
Features:
std- when enabled uses STD otherwise uses COREenable_async- when enabled - enables async codeclone_wait_indef- when enabled does not panic in clone() on timeout, but rather waits until operation completes
[]
= ["std", "default_flags"]
= ["clone_wait_indef", "enable_async"]
Info
- 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).
- 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
ckPilot, 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.
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.
Version
V0.4.1
- Testing nostd
- Eliminated tokio bloat
- Added features to disable specific code
- Instead of SeqCst + Aquire a Aquire + Relaxed
- The SeqCst ordering was replaced with Relaxed on the first attempt.
- Added comments
- Added async_clone.
- 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.
- Fixed errors accure_in_lace().
- Added no_std.
- License changed!
License:
Sources are licensed with: MIT License
Examples
The examples are availabe in the directory examples.
Block diagram
┌─────────────┐ ┌──────────────┐
│ │ │ │
│ RwBuffers ┼────► allocate() │
│ │ │ │
└─────────────┘ └──────┬───────┘
│
│
┌────▼───────┐ ┌───────────┐
│ │ │ │
│ RwBuffer ┼────► write() │
│ │ │ │
└──────┬─────┘ └─────┬─────┘
│ │
│ │
│ ┌─────▼─────┐ ┌───────────┐
│ │ │ │ writing │
│ │ WBuffer ◄──────┼ data() │
│ │ │ │ │
│ └─────┬─────┘ └───────────┘
│ │
│ │
│ │
│ ┌────▼────────┐
│ │ │
│ │ downgrade() │
│ │ │
│ └────┬────────┘
│ │
───────────────────┼────────────────┼─────────────────────────────
WBuffer dropped. │ │
┌───────▼───┐ ┌────▼────────┐
│ │ │ │
│ read() │ │ RBuffer │
│ │ │ │
└───────┬───┘ └─────────────┘
│
│
│
┌───────▼───┐
│ │
│ RBuffer │
│ │
└───────────┘
Usage.
Firstly, the base instance should be created:
// bounded
let mut bufs = new.unwrap;
// or unbounded
let mut bufs = new_unbounded.unwrap;
Then a buffer can be obtained from it.
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:
let buf_w = buf.write.unwrap;
-- or --
let buf0_w = buf0.write_async.await.unwrap;
// ...
async_drop.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:
- Only one shared access
- No exclusive access
- No base i.e
RwBufferleft undropped.
The shared access can be obtained also via:
let buf_r: RBuffer = buf.read;
-- or --
let buf1_rd = buf0.read_async.await.unwrap;
// ...
async_drop.await;
The RBuffer or RwBuffer are Sync and Send. However, by design, only RBuffer should be shared.