Struct ArcAsyncRwLock 

pub struct ArcAsyncRwLock<T> { /* private fields */ }

Asynchronous Read-Write Lock Wrapper

Provides an encapsulation of asynchronous read-write lock, supporting multiple read operations or a single write operation. Read operations can execute concurrently, while write operations have exclusive access.

Features

• Supports multiple concurrent read operations
• Write operations have exclusive access, mutually exclusive with read operations
• Asynchronously acquires locks, does not block threads
• Thread-safe, supports multi-threaded sharing
• Automatic lock management through RAII ensures proper lock release
• Implements Deref and AsRef to expose the underlying tokio::sync::RwLock API when guard-based access is needed

Use Cases

Suitable for read-heavy scenarios such as caching, configuration management, etc.

Usage Example

use qubit_lock::lock::{ArcAsyncRwLock, AsyncLock};

let rt = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()
    .unwrap();
rt.block_on(async {
    let data = ArcAsyncRwLock::new(String::from("Hello"));

    // Multiple read operations can execute concurrently
    data.read(|s| {
        println!("Read: {}", s);
    }).await;

    // Write operations have exclusive access
    data.write(|s| {
        s.push_str(" World!");
        println!("Write: {}", s);
    }).await;
});

Implementations

impl<T> ArcAsyncRwLock<T>

pub fn new(data: T) -> Self

Creates a new asynchronous read-write lock

Arguments

• data - The data to be protected

Returns

Returns a new ArcAsyncRwLock instance

Example

use qubit_lock::lock::ArcAsyncRwLock;

let rw_lock = ArcAsyncRwLock::new(vec![1, 2, 3]);

Methods from Deref<Target = AsyncRwLock<T>>

pub async fn read(&self) -> RwLockReadGuard<'_, T>

Locks this RwLock with shared read access, causing the current task to yield until the lock has been acquired.

The calling task will yield until there are no writers which hold the lock. There may be other readers inside the lock when the task resumes.

Note that under the priority policy of RwLock, read locks are not granted until prior write locks, to prevent starvation. Therefore deadlock may occur if a read lock is held by the current task, a write lock attempt is made, and then a subsequent read lock attempt is made by the current task.

Returns an RAII guard which will drop this read access of the RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to read makes you lose your place in the queue.

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

let lock = Arc::new(RwLock::new(1));
let c_lock = lock.clone();

let n = lock.read().await;
assert_eq!(*n, 1);

tokio::spawn(async move {
    // While main has an active read lock, we acquire one too.
    let r = c_lock.read().await;
    assert_eq!(*r, 1);
}).await.expect("The spawned task has panicked");

// Drop the guard after the spawned task finishes.
drop(n);

pub fn blocking_read(&self) -> RwLockReadGuard<'_, T>

Blockingly locks this RwLock with shared read access.

This method is intended for use cases where you need to use this rwlock in asynchronous code as well as in synchronous code.

Returns an RAII guard which will drop the read access of this RwLock when dropped.

Panics

This function panics if called within an asynchronous execution context.

• If you find yourself in an asynchronous execution context and needing to call some (synchronous) function which performs one of these blocking_ operations, then consider wrapping that call inside [spawn_blocking()][crate::runtime::Handle::spawn_blocking] (or [block_in_place()][crate::task::block_in_place]).

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

#[tokio::main]
async fn main() {
    let rwlock = Arc::new(RwLock::new(1));
    let mut write_lock = rwlock.write().await;

    let blocking_task = tokio::task::spawn_blocking({
        let rwlock = Arc::clone(&rwlock);
        move || {
            // This shall block until the `write_lock` is released.
            let read_lock = rwlock.blocking_read();
            assert_eq!(*read_lock, 0);
        }
    });

    *write_lock -= 1;
    drop(write_lock); // release the lock.

    // Await the completion of the blocking task.
    blocking_task.await.unwrap();

    // Assert uncontended.
    assert!(rwlock.try_write().is_ok());
}

pub async fn read_owned(self: Arc<RwLock<T>>) -> OwnedRwLockReadGuard<T>

Locks this RwLock with shared read access, causing the current task to yield until the lock has been acquired.

The calling task will yield until there are no writers which hold the lock. There may be other readers inside the lock when the task resumes.

This method is identical to RwLock::read, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Note that under the priority policy of RwLock, read locks are not granted until prior write locks, to prevent starvation. Therefore deadlock may occur if a read lock is held by the current task, a write lock attempt is made, and then a subsequent read lock attempt is made by the current task.

Returns an RAII guard which will drop this read access of the RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to read_owned makes you lose your place in the queue.

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

let lock = Arc::new(RwLock::new(1));
let c_lock = lock.clone();

let n = lock.read_owned().await;
assert_eq!(*n, 1);

tokio::spawn(async move {
    // While main has an active read lock, we acquire one too.
    let r = c_lock.read_owned().await;
    assert_eq!(*r, 1);
}).await.expect("The spawned task has panicked");

// Drop the guard after the spawned task finishes.
drop(n);
}

pub fn try_read(&self) -> Result<RwLockReadGuard<'_, T>, TryLockError>

Attempts to acquire this RwLock with shared read access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release read access when dropped.

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

let lock = Arc::new(RwLock::new(1));
let c_lock = lock.clone();

let v = lock.try_read().unwrap();
assert_eq!(*v, 1);

tokio::spawn(async move {
    // While main has an active read lock, we acquire one too.
    let n = c_lock.read().await;
    assert_eq!(*n, 1);
}).await.expect("The spawned task has panicked");

// Drop the guard when spawned task finishes.
drop(v);

pub fn try_read_owned( self: Arc<RwLock<T>>, ) -> Result<OwnedRwLockReadGuard<T>, TryLockError>

Attempts to acquire this RwLock with shared read access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release read access when dropped.

This method is identical to RwLock::try_read, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

let lock = Arc::new(RwLock::new(1));
let c_lock = lock.clone();

let v = lock.try_read_owned().unwrap();
assert_eq!(*v, 1);

tokio::spawn(async move {
    // While main has an active read lock, we acquire one too.
    let n = c_lock.read_owned().await;
    assert_eq!(*n, 1);
}).await.expect("The spawned task has panicked");

// Drop the guard when spawned task finishes.
drop(v);

pub async fn write(&self) -> RwLockWriteGuard<'_, T>

Locks this RwLock with exclusive write access, causing the current task to yield until the lock has been acquired.

The calling task will yield while other writers or readers currently have access to the lock.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to write makes you lose your place in the queue.

Examples

use tokio::sync::RwLock;

let lock = RwLock::new(1);

let mut n = lock.write().await;
*n = 2;

pub fn blocking_write(&self) -> RwLockWriteGuard<'_, T>

Blockingly locks this RwLock with exclusive write access.

This method is intended for use cases where you need to use this rwlock in asynchronous code as well as in synchronous code.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Panics

This function panics if called within an asynchronous execution context.

• If you find yourself in an asynchronous execution context and needing to call some (synchronous) function which performs one of these blocking_ operations, then consider wrapping that call inside [spawn_blocking()][crate::runtime::Handle::spawn_blocking] (or [block_in_place()][crate::task::block_in_place]).

Examples

use std::sync::Arc;
use tokio::{sync::RwLock};

#[tokio::main]
async fn main() {
    let rwlock =  Arc::new(RwLock::new(1));
    let read_lock = rwlock.read().await;

    let blocking_task = tokio::task::spawn_blocking({
        let rwlock = Arc::clone(&rwlock);
        move || {
            // This shall block until the `read_lock` is released.
            let mut write_lock = rwlock.blocking_write();
            *write_lock = 2;
        }
    });

    assert_eq!(*read_lock, 1);
    // Release the last outstanding read lock.
    drop(read_lock);

    // Await the completion of the blocking task.
    blocking_task.await.unwrap();

    // Assert uncontended.
    let read_lock = rwlock.try_read().unwrap();
    assert_eq!(*read_lock, 2);
}

pub async fn write_owned(self: Arc<RwLock<T>>) -> OwnedRwLockWriteGuard<T>

Locks this RwLock with exclusive write access, causing the current task to yield until the lock has been acquired.

The calling task will yield while other writers or readers currently have access to the lock.

This method is identical to RwLock::write, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Cancel safety

This method uses a queue to fairly distribute locks in the order they were requested. Cancelling a call to write_owned makes you lose your place in the queue.

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

let lock = Arc::new(RwLock::new(1));

let mut n = lock.write_owned().await;
*n = 2;
}

pub fn try_write(&self) -> Result<RwLockWriteGuard<'_, T>, TryLockError>

Attempts to acquire this RwLock with exclusive write access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release write access when dropped.

Examples

use tokio::sync::RwLock;

let rw = RwLock::new(1);

let v = rw.read().await;
assert_eq!(*v, 1);

assert!(rw.try_write().is_err());

pub fn try_write_owned( self: Arc<RwLock<T>>, ) -> Result<OwnedRwLockWriteGuard<T>, TryLockError>

Attempts to acquire this RwLock with exclusive write access.

If the access couldn’t be acquired immediately, returns TryLockError. Otherwise, an RAII guard is returned which will release write access when dropped.

This method is identical to RwLock::try_write, except that the returned guard references the RwLock with an Arc rather than by borrowing it. Therefore, the RwLock must be wrapped in an Arc to call this method, and the guard will live for the 'static lifetime, as it keeps the RwLock alive by holding an Arc.

Examples

use std::sync::Arc;
use tokio::sync::RwLock;

let rw = Arc::new(RwLock::new(1));

let v = Arc::clone(&rw).read_owned().await;
assert_eq!(*v, 1);

assert!(rw.try_write_owned().is_err());

Trait Implementations

impl<T> AsRef<RwLock<T>> for ArcAsyncRwLock<T>

fn as_ref(&self) -> &AsyncRwLock<T>

Returns a reference to the underlying Tokio read-write lock.

This is useful when callers need guard-based APIs such as AsyncRwLock::read or AsyncRwLock::write instead of the closure-based AsyncLock methods.

impl<T> AsyncLock<T> for ArcAsyncRwLock<T>

where T: Send + Sync,

async fn read<R, F>(&self, f: F) -> R

where F: FnOnce(&T) -> R + Send, R: Send,

Acquires the read lock and executes an operation

Asynchronously acquires the read lock, executes the provided closure, and then automatically releases the lock. Multiple read operations can execute concurrently.

Arguments

• f - The closure to be executed while holding the read lock, can only read data

Returns

Returns a future that resolves to the result of executing the closure

Example

use qubit_lock::lock::{ArcAsyncRwLock, AsyncLock};

let rt = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()
    .unwrap();
rt.block_on(async {
    let data = ArcAsyncRwLock::new(vec![1, 2, 3]);

    let length = data.read(|v| v.len()).await;
    println!("Vector length: {}", length);
});

async fn write<R, F>(&self, f: F) -> R

where F: FnOnce(&mut T) -> R + Send, R: Send,

Acquires the write lock and executes an operation

Asynchronously acquires the write lock, executes the provided closure, and then automatically releases the lock. Write operations have exclusive access, mutually exclusive with read operations.

Arguments

• f - The closure to be executed while holding the write lock, can modify data

Returns

Returns a future that resolves to the result of executing the closure

Example

use qubit_lock::lock::{ArcAsyncRwLock, AsyncLock};

let rt = tokio::runtime::Builder::new_current_thread()
    .enable_all()
    .build()
    .unwrap();
rt.block_on(async {
    let data = ArcAsyncRwLock::new(vec![1, 2, 3]);

    data.write(|v| {
        v.push(4);
        println!("Added element, new length: {}", v.len());
    }).await;
});

fn try_read<R, F>(&self, f: F) -> Result<R, TryLockError>

where F: FnOnce(&T) -> R,

Attempts to acquire the read lock without waiting.

Arguments

• f - Closure receiving immutable access when a read lock is available.

Returns

Ok(result) if a read lock was acquired, or TryLockError::WouldBlock if the lock was busy.

fn try_write<R, F>(&self, f: F) -> Result<R, TryLockError>

where F: FnOnce(&mut T) -> R,

Attempts to acquire the write lock without waiting.

Arguments

• f - Closure receiving mutable access when a write lock is available.

Returns

Ok(result) if a write lock was acquired, or TryLockError::WouldBlock if the lock was busy.

impl<T> Clone for ArcAsyncRwLock<T>

fn clone(&self) -> Self

Clones the asynchronous read-write lock

Creates a new ArcAsyncRwLock instance that shares the same underlying lock with the original instance. This allows multiple tasks to hold references to the same lock simultaneously.

Returns

A new handle sharing the same underlying async read-write lock and protected value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<T> Deref for ArcAsyncRwLock<T>

fn deref(&self) -> &Self::Target

Dereferences this wrapper to the underlying Tokio read-write lock.

When AsyncLock is in scope, read and write with closure arguments still call the trait methods on this wrapper. Use explicit dereferencing or AsRef::as_ref when you want the native guard-based AsyncRwLock methods.

type Target = RwLock<T>

The resulting type after dereferencing.