Struct aster_frame::sync::RwLock

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

Spin-based Read-write Lock

Overview

This lock allows for multiple readers, or at most one writer to access at any point in time. The writer of this lock has exclusive access to modify the underlying data, while the readers are allowed shared and read-only access.

The writing and reading portions cannot be active simultaneously, when one portion is in progress, the other portion will spin-wait. This is suitable for scenarios where the lock is expected to be held for short periods of time, and the overhead of context switching is higher than the cost of spinning.

The lock provides methods to safely acquire locks with interrupts disabled, preventing deadlocks in scenarios where locks are used within interrupt handlers.

In addition to traditional read and write locks, this implementation provides the upgradeable read lock (upread lock). The upread lock can be upgraded to write locks atomically, useful in scenarios where a decision to write is made after reading.

The type parameter T represents the data that this lock is protecting. It is necessary for T to satisfy [Send] to be shared across tasks and [Sync] to permit concurrent access via readers. The [Deref] method (and [DerefMut] for the writer) is implemented for the RAII guards returned by the locking methods, which allows for the access to the protected data while the lock is held.

Usage

The lock can be used in scenarios where data needs to be read frequently but written to occasionally.

Use upread lock in scenarios where related checking is performed before modification to effectively avoid deadlocks and improve efficiency.

This lock should not be used in scenarios where lock-holding times are long as it can lead to CPU resource wastage due to spinning.

Safety

Use interrupt-disabled version methods when dealing with interrupt-related read-write locks, as nested interrupts may lead to a deadlock if not properly handled.

Examples

use aster_frame::sync::RwLock;

let lock = RwLock::new(5)

// many read locks can be held at once
{
    let r1 = lock.read();
    let r2 = lock.read();
    assert_eq!(*r1, 5);
    assert_eq!(*r2, 5);
     
    // Upgradeable read lock can share access to data with read locks
    let r3 = lock.upread();
    assert_eq!(*r3, 5);
    drop(r1);
    drop(r2);
    // read locks are dropped at this point

    // An upread lock can only be upgraded successfully after all the
    // read locks are released, otherwise it will spin-wait.
    let mut w1 = r3.upgrade();
    *w1 += 1;
    assert_eq!(*w1, 6);
}   // upread lock are dropped at this point

{   
    // Only one write lock can be held at a time
    let mut w2 = lock.write();
    *w2 += 1;
    assert_eq!(*w2, 7);
}   // write lock is dropped at this point

Implementations

impl<T> RwLock<T>

pub const fn new(val: T) -> Self

Creates a new spin-based read-write lock with an initial value.

impl<T: ?Sized> RwLock<T>

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

Acquires a read lock while disabling the local IRQs and spin-wait until it can be acquired.

The calling thread will spin-wait until there are no writers or upgrading upreaders present. There is no guarantee for the order in which other readers or writers waiting simultaneously will obtain the lock. Once this lock is acquired, the calling thread will not be interrupted.

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

Acquires a write lock while disabling the local IRQs and spin-wait until it can be acquired.

The calling thread will spin-wait until there are no other writers, upreaders or readers present. There is no guarantee for the order in which other readers or writers waiting simultaneously will obtain the lock. Once this lock is acquired, the calling thread will not be interrupted.

pub fn upread_irq_disabled(&self) -> RwLockUpgradeableGuard<'_, T>

Acquires an upgradeable reader (upreader) while disabling local IRQs and spin-wait until it can be acquired.

The calling thread will spin-wait until there are no other writers, or upreaders. There is no guarantee for the order in which other readers or writers waiting simultaneously will obtain the lock. Once this lock is acquired, the calling thread will not be interrupted.

Upreader will not block new readers until it tries to upgrade. Upreader and reader do not differ before invoking the upgread method. However, only one upreader can exist at any time to avoid deadlock in the upgread method.

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

Attempts to acquire a read lock while disabling local IRQs.

This function will never spin-wait and will return immediately. When multiple readers or writers attempt to acquire the lock, this method does not guarantee any order. Interrupts will automatically be restored when acquiring fails.

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

Attempts to acquire a write lock while disabling local IRQs.

This function will never spin-wait and will return immediately. When multiple readers or writers attempt to acquire the lock, this method does not guarantee any order. Interrupts will automatically be restored when acquiring fails.

pub fn try_upread_irq_disabled(&self) -> Option<RwLockUpgradeableGuard<'_, T>>

Attempts to acquire a upread lock while disabling local IRQs.

This function will never spin-wait and will return immediately. When multiple readers or writers attempt to acquire the lock, this method does not guarantee any order. Interrupts will automatically be restored when acquiring fails.

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

Acquires a read lock and spin-wait until it can be acquired.

The calling thread will spin-wait until there are no writers or upgrading upreaders present. There is no guarantee for the order in which other readers or writers waiting simultaneously will obtain the lock.

This method does not disable interrupts, so any locks related to interrupt context should avoid using this method, and use read_irq_disabled instead. When IRQ handlers are allowed to be executed while holding this lock, it is preferable to use this method over the read_irq_disabled method as it has a higher efficiency.

pub fn read_arc(self: &Arc<Self>) -> ArcRwLockReadGuard<T>

Acquires a read lock through an [Arc].

The method is similar to read, but it doesn’t have the requirement for compile-time checked lifetimes of the read guard.

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

Acquires a write lock and spin-wait until it can be acquired.

The calling thread will spin-wait until there are no other writers, upreaders or readers present. There is no guarantee for the order in which other readers or writers waiting simultaneously will obtain the lock.

This method does not disable interrupts, so any locks related to interrupt context should avoid using this method, and use write_irq_disabled instead. When IRQ handlers are allowed to be executed while holding this lock, it is preferable to use this method over the write_irq_disabled method as it has a higher efficiency.

pub fn write_arc(self: &Arc<Self>) -> ArcRwLockWriteGuard<T>

Acquires a write lock through an [Arc].

The method is similar to write, but it doesn’t have the requirement for compile-time checked lifetimes of the lock guard.

pub fn upread(&self) -> RwLockUpgradeableGuard<'_, T>

Acquires an upreader and spin-wait until it can be acquired.

The calling thread will spin-wait until there are no other writers, or upreaders. There is no guarantee for the order in which other readers or writers waiting simultaneously will obtain the lock.

Upreader will not block new readers until it tries to upgrade. Upreader and reader do not differ before invoking the upgread method. However, only one upreader can exist at any time to avoid deadlock in the upgread method.

This method does not disable interrupts, so any locks related to interrupt context should avoid using this method, and use upread_irq_disabled instead. When IRQ handlers are allowed to be executed while holding this lock, it is preferable to use this method over the upread_irq_disabled method as it has a higher efficiency.

pub fn upread_arc(self: &Arc<Self>) -> ArcRwLockUpgradeableGuard<T>

Acquires an upgradeable read lock through an [Arc].

The method is similar to upread, but it doesn’t have the requirement for compile-time checked lifetimes of the lock guard.

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

Attempts to acquire a read lock.

This function will never spin-wait and will return immediately.

This method does not disable interrupts, so any locks related to interrupt context should avoid using this method, and use try_read_irq_disabled instead. When IRQ handlers are allowed to be executed while holding this lock, it is preferable to use this method over the try_read_irq_disabled method as it has a higher efficiency.

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

Attempts to acquire an read lock through an [Arc].

The method is similar to try_read, but it doesn’t have the requirement for compile-time checked lifetimes of the lock guard.

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

Attempts to acquire a write lock.

This function will never spin-wait and will return immediately.

This method does not disable interrupts, so any locks related to interrupt context should avoid using this method, and use try_write_irq_disabled instead. When IRQ handlers are allowed to be executed while holding this lock, it is preferable to use this method over the try_write_irq_disabled method as it has a higher efficiency.

pub fn try_upread(&self) -> Option<RwLockUpgradeableGuard<'_, T>>

Attempts to acquire an upread lock.

This function will never spin-wait and will return immediately.

This method does not disable interrupts, so any locks related to interrupt context should avoid using this method, and use try_upread_irq_disabled instead. When IRQ handlers are allowed to be executed while holding this lock, it is preferable to use this method over the try_upread_irq_disabled method as it has a higher efficiency.

pub fn try_upread_arc(self: &Arc<Self>) -> Option<ArcRwLockUpgradeableGuard<T>>

Attempts to acquire an upgradeable read lock through an [Arc].

The method is similar to try_upread, but it doesn’t have the requirement for compile-time checked lifetimes of the lock guard.

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: ?Sized + Send> Send for RwLock<T>

Because there can be more than one readers to get the T’s immutable ref, so T must be Sync to guarantee the sharing safety.

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