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.

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

V0.3.2

License:

Sources are available under: MPL-2.0 OR EUPL-1.2

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 = 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.

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(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:

    let buf_r: RBuffer = buf.read();

-- or --

  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.