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

Version

V2.0

• Fixed errors accure_in_lace().
• Added no_std.
• License changed!

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();

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();

The RBuffer or RwBuffer are Sync and Send. However, by design, only RBuffer should be shared.