async-lock

An upgradable read lock allows a single reader to reserve the right to upgrade to a write lock. There can be at most one upgradable read lock held at a time.

Methods for RwLock:

• upgradable_read(): Asynchronously acquires an upgradable read lock. Returns an UpgradableRead guard.
• try_upgradable_read(): Attempts to acquire an upgradable read lock immediately.
• upgradable_read_blocking(): Blocks the current thread until acquired.

Methods for RwLockUpgradableReadGuard:

• upgrade(guard): Asynchronously upgrades the guard to a write lock. Returns an Upgrade future.
• try_upgrade(guard): Attempts to upgrade immediately. Returns Result<RwLockWriteGuard, Self>.
• downgrade(guard): Downgrades the upgradable lock into a regular RwLockReadGuard.
• upgrade_blocking(guard): Blocks the thread until the upgrade is complete.

# futures_lite::future::block_on(async {
use async_lock::{RwLock, RwLockUpgradableReadGuard};

let lock = RwLock::new(1);
let reader = lock.upgradable_read().await;
assert_eq!(*reader, 1);
assert_eq!(*lock.try_read().unwrap(), 1);

let mut writer = RwLockUpgradableReadGuard::upgrade(reader).await;
*writer = 2;
# });

An async RwLock allows multiple readers or a single writer at any point in time. The locking strategy is write-preferring, meaning writers are never starved. Releasing a write lock wakes the next blocked reader and the next blocked writer.

Common operations include:

• new(t): Creates a new lock with value t.
• read(): Acquires an asynchronous read lock.
• write(): Acquires an asynchronous write lock.
• try_read() / try_write(): Attempts to acquire a lock without waiting, returning None if unavailable.
• into_inner(): Consumes the lock and returns the inner value.

# futures_lite::future::block_on(async {
use async_lock::RwLock;

let lock = RwLock::new(5);

// Multiple read locks can be held at a time.
let r1 = lock.read().await;
let r2 = lock.read().await;
assert_eq!(*r1, 5);
assert_eq!(*r2, 5);
drop((r1, r2));

// Only one write lock can be held at a time.
let mut w = lock.write().await;
*w += 1;
assert_eq!(*w, 6);
# });

If you need to interact with a OnceCell from a synchronous thread (e.g., a thread spawned via std::thread::spawn) that is waiting on a value initialized in an async context, use the _blocking variants:

• wait_blocking(): Blocks the thread until the cell is initialized.
• get_or_init_blocking(): Blocks the thread to initialize the cell if it is not yet set.
• get_or_try_init_blocking(): Blocks the thread to initialize the cell with a result-bearing closure.
• set_blocking(): Blocks the thread to set the value.

CRITICAL: Never call these methods inside an async function or an async executor, as they will block the executor thread and likely cause a deadlock.

// Inside a synchronous thread
let cell = std::sync::Arc::new(OnceCell::new());
let cell_clone = cell.clone();

std::thread::spawn(move || {
    // This blocks the thread until the async task calls .set()
    let val = cell_clone.wait_blocking();
    println!("Got value: {}", val);
});

To initialize a OnceCell using an asynchronous closure, use get_or_init or get_or_try_init.

• get_or_init: Takes a closure that returns a Future<Output = T>. If the cell is already initialized, it returns the existing value. If not, it runs the closure and sets the value.
• get_or_try_init: Takes a closure that returns a Future<Output = Result<T, E>>. The cell will not be initialized if the closure returns an error, allowing for retry logic or error handling.

Multiple tasks calling these methods concurrently will result in only one closure being invoked; others will await the result of the first initialization.

use async_lock::OnceCell;

// Using get_or_init
let cell = OnceCell::new();
let value = cell.get_or_init(|| async { 1 }).await;
assert_eq!(value, &1);

// Using get_or_try_init with error handling
let cell = OnceCell::new();
let result = cell.get_or_try_init(|| async { 
    if some_condition() { Ok(1) } else { Err("failed") }
}).await;

When using RwLock inside an Arc, use the _arc variants of the locking methods to ensure the lock guard maintains a reference to the underlying data.

Methods for Arc<RwLock<T>>:

• read_arc(): Asynchronously acquires a reference-counted read lock. Returns ReadArc.
• try_read_arc(): Attempts to acquire a reference-counted read lock. Returns Option<RwLockReadGuardArc>.
• read_arc_blocking(): Blocks the thread until a reference-counted read lock is acquired.
• write_arc(): Asynchronously acquires a reference-counted write lock. Returns WriteArc.
• try_write_arc(): Attempts to acquire a reference-counted write lock. Returns Option<RwLockWriteGuardArc>.
• write_arc_blocking(): Blocks the thread until a reference-counted write lock is acquired.
• upgradable_read_arc(): Asynchronously acquires a reference-counted upgradable read lock. Returns UpgradableReadArc.
• try_upgradable_read_arc(): Attempts to acquire a reference-counted upgradable read lock. Returns Option<RwLockUpgradableReadGuardArc>.
• upgradable_read_arc_blocking(): Blocks the thread until an upgradable read lock is acquired.

Methods for RwLockUpgradableReadGuardArc:

• upgrade(guard): Asynchronously upgrades to a write lock. Returns UpgradeArc.
• try_upgrade(guard): Attempts to upgrade immediately. Returns Result<RwLockWriteGuardArc, Self>.
• downgrade(guard): Downgrades to a RwLockReadGuardArc.

# futures_lite::future::block_on(async {
use std::sync::Arc;
use async_lock::{RwLock, RwLockUpgradableReadGuardArc};

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

let reader = lock.upgradable_read_arc().await;
assert_eq!(*reader, 1);
assert!(lock.try_read_arc().is_some());

let mut writer = RwLockUpgradableReadGuardArc::upgrade(reader).await;
*writer = 2;
# });