Struct RwLock

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

A reader-writer lock that allows multiple readers or a single writer at a time.

See the module level documentation for more.

Implementations

impl<T: ?Sized> RwLock<T>

pub async fn read_owned(self: Arc<Self>) -> 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 mea::rwlock::RwLock;

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

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

tokio::spawn(async move {
    // while the outer read lock is held, we acquire a read lock, too
    let r = lock_clone.read_owned().await;
    assert_eq!(*r, 1);
})
.await
.unwrap();

pub fn try_read_owned(self: Arc<Self>) -> Option<OwnedRwLockReadGuard<T>>

Attempts to acquire this RwLock with shared read access.

If the access couldn’t be acquired immediately, returns None. 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 mea::rwlock::RwLock;

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

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

let v = lock.try_write().unwrap();
assert!(lock.clone().try_read_owned().is_none());

impl<T: ?Sized> RwLock<T>

pub async fn write_owned(self: Arc<Self>) -> 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 mea::rwlock::RwLock;

let lock = Arc::new(RwLock::new(1));
let mut n = lock.write_owned().await;
*n = 2;

pub fn try_write_owned(self: Arc<Self>) -> Option<OwnedRwLockWriteGuard<T>>

Attempts to acquire this RwLock with exclusive write access.

If the access couldn’t be acquired immediately, returns None. 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 mea::rwlock::RwLock;

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

let v = lock.try_read().unwrap();
assert!(lock.clone().try_write_owned().is_none());
drop(v);

let mut v = lock.try_write_owned().unwrap();
*v = 2;

impl<T: ?Sized> RwLock<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 mea::rwlock::RwLock;

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

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

tokio::spawn(async move {
    // while the outer read lock is held, we acquire a read lock, too
    let r = lock_clone.read().await;
    assert_eq!(*r, 1);
})
.await
.unwrap();

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

Attempts to acquire this RwLock with shared read access.

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

Examples

use std::sync::Arc;

use mea::rwlock::RwLock;

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

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

let v = lock.try_write().unwrap();
assert!(lock.try_read().is_none());

impl<T: ?Sized> RwLock<T>

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 mea::rwlock::RwLock;

let lock = RwLock::new(1);
let mut n = lock.write().await;
*n = 2;

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

Attempts to acquire this RwLock with exclusive write access.

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

Examples

use std::sync::Arc;

use mea::rwlock::RwLock;

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

let v = lock.try_read().unwrap();
assert!(lock.try_write().is_none());
drop(v);

let mut v = lock.try_write().unwrap();
*v = 2;

impl<T> RwLock<T>

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

Creates a new reader-writer lock in an unlocked state ready for use.

Examples

use mea::rwlock::RwLock;

let rwlock = RwLock::new(5);

pub fn with_max_readers(t: T, max_readers: usize) -> RwLock<T>

Creates a new reader-writer lock in an unlocked state, and allows a maximum of max_readers concurrent readers.

This method is typically used for debugging and testing purposes.

Examples

use mea::rwlock::RwLock;

let rwlock = RwLock::with_max_readers(5, 1024);

pub fn into_inner(self) -> T

Consumes the lock, returning the underlying data.

Examples

use mea::rwlock::RwLock;

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

impl<T: ?Sized> RwLock<T>

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

Returns a mutable reference to the underlying data.

Since this call borrows the RwLock mutably, no actual locking needs to take place: the mutable borrow statically guarantees no locks exist.

Examples

use mea::rwlock::RwLock;

let mut lock = RwLock::new(1);
let n = lock.get_mut();
*n = 2;

Trait Implementations

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

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

Formats the value using the given formatter.

impl<T: Default> Default for RwLock<T>

fn default() -> Self

Returns the “default value” for a type.

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

fn from(t: T) -> Self

Converts to this type from the input type.

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

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