Struct RwLock

pub struct RwLock<T: ?Sized> { /* private fields */ }

An async reader-writer lock.

This type of lock allows multiple readers or one writer at any point in time.

The locking strategy is write-preferring, which means writers are never starved. Releasing a write lock wakes the next blocked reader and the next blocked writer.

Examples

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

Implementations

impl<T> RwLock<T>

pub const fn new(t: T) -> RwLock<T>

Creates a new reader-writer lock.

Examples

use async_lock::RwLock;

let lock = RwLock::new(0);

pub fn into_inner(self) -> T

Unwraps the lock and returns the inner value.

Examples

use async_lock::RwLock;

let lock = RwLock::new(5);
assert_eq!(lock.into_inner(), 5);

pub fn try_read_arc(self: &Arc<Self>) -> Option<RwLockReadGuardArc<T>>

Attempts to acquire an an owned, reference-counted read lock.

If a read lock could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the lock when dropped.

Examples

use std::sync::Arc;
use async_lock::RwLock;

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

let reader = lock.read_arc().await;
assert_eq!(*reader, 1);

assert!(lock.try_read_arc().is_some());

pub fn read_arc<'a>(self: &'a Arc<Self>) -> ReadArc<'a, T>

Acquires an owned, reference-counted read lock.

Returns a guard that releases the lock when dropped.

Note that attempts to acquire a read lock will block if there are also concurrent attempts to acquire a write lock.

Examples

use std::sync::Arc;
use async_lock::RwLock;

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

let reader = lock.read_arc().await;
assert_eq!(*reader, 1);

assert!(lock.try_read_arc().is_some());

pub fn read_arc_blocking(self: &Arc<Self>) -> RwLockReadGuardArc<T>

Acquires an owned, reference-counted read lock.

Returns a guard that releases the lock when dropped.

Note that attempts to acquire a read lock will block if there are also concurrent attempts to acquire a write lock.

Blocking

Rather than using asynchronous waiting, like the read_arc method, this method will block the current thread until the read lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a lock can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

Examples

use std::sync::Arc;
use async_lock::RwLock;

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

let reader = lock.read_arc_blocking();
assert_eq!(*reader, 1);

assert!(lock.try_read().is_some());

impl<T: ?Sized> RwLock<T>

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

Attempts to acquire a read lock.

If a read lock could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the lock when dropped.

Examples

use async_lock::RwLock;

let lock = RwLock::new(1);

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

assert!(lock.try_read().is_some());

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

Acquires a read lock.

Returns a guard that releases the lock when dropped.

Note that attempts to acquire a read lock will block if there are also concurrent attempts to acquire a write lock.

Examples

use async_lock::RwLock;

let lock = RwLock::new(1);

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

assert!(lock.try_read().is_some());

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

Acquires a read lock.

Returns a guard that releases the lock when dropped.

Note that attempts to acquire a read lock will block if there are also concurrent attempts to acquire a write lock.

Blocking

Rather than using asynchronous waiting, like the read method, this method will block the current thread until the read lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a lock can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

Examples

use async_lock::RwLock;

let lock = RwLock::new(1);

let reader = lock.read_blocking();
assert_eq!(*reader, 1);

assert!(lock.try_read().is_some());

pub fn try_upgradable_read(&self) -> Option<RwLockUpgradableReadGuard<'_, T>>

Attempts to acquire a read lock with the possiblity to upgrade to a write lock.

If a read lock could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the lock when dropped.

Upgradable read lock reserves the right to be upgraded to a write lock, which means there can be at most one upgradable read lock at a time.

Examples

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;

pub fn upgradable_read(&self) -> UpgradableRead<'_, T>

Acquires a read lock with the possiblity to upgrade to a write lock.

Returns a guard that releases the lock when dropped.

Upgradable read lock reserves the right to be upgraded to a write lock, which means there can be at most one upgradable read lock at a time.

Note that attempts to acquire an upgradable read lock will block if there are concurrent attempts to acquire another upgradable read lock or a write lock.

Examples

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;

pub fn upgradable_read_blocking(&self) -> RwLockUpgradableReadGuard<'_, T>

Attempts to acquire a read lock with the possiblity to upgrade to a write lock.

Returns a guard that releases the lock when dropped.

Upgradable read lock reserves the right to be upgraded to a write lock, which means there can be at most one upgradable read lock at a time.

Note that attempts to acquire an upgradable read lock will block if there are concurrent attempts to acquire another upgradable read lock or a write lock.

Blocking

Rather than using asynchronous waiting, like the upgradable_read method, this method will block the current thread until the read lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a lock can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

Examples

use async_lock::{RwLock, RwLockUpgradableReadGuard};

let lock = RwLock::new(1);

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

let mut writer = RwLockUpgradableReadGuard::upgrade_blocking(reader);
*writer = 2;

pub fn upgradable_read_arc_blocking( self: &Arc<Self>, ) -> RwLockUpgradableReadGuardArc<T>

Attempts to acquire an owned, reference-counted read lock with the possiblity to upgrade to a write lock.

Returns a guard that releases the lock when dropped.

Upgradable read lock reserves the right to be upgraded to a write lock, which means there can be at most one upgradable read lock at a time.

Note that attempts to acquire an upgradable read lock will block if there are concurrent attempts to acquire another upgradable read lock or a write lock.

Blocking

Rather than using asynchronous waiting, like the upgradable_read_arc method, this method will block the current thread until the read lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a lock can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

Examples

use std::sync::Arc;
use async_lock::{RwLock, RwLockUpgradableReadGuardArc};

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

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

let mut writer = RwLockUpgradableReadGuardArc::upgrade_blocking(reader);
*writer = 2;

pub fn try_upgradable_read_arc( self: &Arc<Self>, ) -> Option<RwLockUpgradableReadGuardArc<T>>

Attempts to acquire an owned, reference-counted read lock with the possiblity to upgrade to a write lock.

If a read lock could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the lock when dropped.

Upgradable read lock reserves the right to be upgraded to a write lock, which means there can be at most one upgradable read lock at a time.

Examples

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_eq!(*lock.try_read_arc().unwrap(), 1);

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

pub fn upgradable_read_arc<'a>(self: &'a Arc<Self>) -> UpgradableReadArc<'a, T>

Acquires an owned, reference-counted read lock with the possiblity to upgrade to a write lock.

Returns a guard that releases the lock when dropped.

Upgradable read lock reserves the right to be upgraded to a write lock, which means there can be at most one upgradable read lock at a time.

Note that attempts to acquire an upgradable read lock will block if there are concurrent attempts to acquire another upgradable read lock or a write lock.

Examples

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_eq!(*lock.try_read_arc().unwrap(), 1);

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

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

Attempts to acquire a write lock.

If a write lock could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the lock when dropped.

Examples

use async_lock::RwLock;

let lock = RwLock::new(1);

assert!(lock.try_write().is_some());
let reader = lock.read().await;
assert!(lock.try_write().is_none());

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

Acquires a write lock.

Returns a guard that releases the lock when dropped.

Examples

use async_lock::RwLock;

let lock = RwLock::new(1);

let writer = lock.write().await;
assert!(lock.try_read().is_none());

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

Acquires a write lock.

Returns a guard that releases the lock when dropped.

Blocking

Rather than using asynchronous waiting, like the write method, this method will block the current thread until the write lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a lock can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

Examples

use async_lock::RwLock;

let lock = RwLock::new(1);

let writer = lock.write_blocking();
assert!(lock.try_read().is_none());

pub fn try_write_arc(self: &Arc<Self>) -> Option<RwLockWriteGuardArc<T>>

Attempts to acquire an owned, reference-counted write lock.

If a write lock could not be acquired at this time, then None is returned. Otherwise, a guard is returned that releases the lock when dropped.

Examples

use std::sync::Arc;
use async_lock::RwLock;

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

assert!(lock.try_write_arc().is_some());
let reader = lock.read_arc().await;
assert!(lock.try_write_arc().is_none());

pub fn write_arc<'a>(self: &'a Arc<Self>) -> WriteArc<'a, T>

Acquires an owned, reference-counted write lock.

Returns a guard that releases the lock when dropped.

Examples

use std::sync::Arc;
use async_lock::RwLock;

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

let writer = lock.write_arc().await;
assert!(lock.try_read_arc().is_none());

pub fn write_arc_blocking(self: &Arc<Self>) -> RwLockWriteGuardArc<T>

Acquires an owned, reference-counted write lock.

Returns a guard that releases the lock when dropped.

Blocking

Rather than using asynchronous waiting, like the write_arc method, this method will block the current thread until the write lock is acquired.

This method should not be used in an asynchronous context. It is intended to be used in a way that a lock can be used in both asynchronous and synchronous contexts. Calling this method in an asynchronous context may result in a deadlock.

Examples

use std::sync::Arc;
use async_lock::RwLock;

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

let writer = lock.write_arc_blocking();
assert!(lock.try_read().is_none());

pub fn get_mut(&mut self) -> &mut T

Returns a mutable reference to the inner value.

Since this call borrows the lock mutably, no actual locking takes place. The mutable borrow statically guarantees no locks exist.

Examples

use async_lock::RwLock;

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

*lock.get_mut() = 2;
assert_eq!(*lock.read().await, 2);

Trait Implementations

impl<T: Debug + ?Sized> Debug for RwLock<T>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<T: Default + ?Sized> Default for RwLock<T>

fn default() -> RwLock<T>

Returns the “default value” for a type.

impl<T> From<T> for RwLock<T>

fn from(val: T) -> RwLock<T>

Converts to this type from the input type.

impl<T: Send + ?Sized> Send for RwLock<T>

impl<T: Send + Sync + ?Sized> Sync for RwLock<T>