pub struct RwMutex<T> { /* private fields */ }Expand description
A mutex that provides data access to either one writer or many readers.
§Overview
This mutex allows for multiple readers, or at most one writer to access at any point in time. The writer of this mutex 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 sleep. This is suitable for scenarios where the mutex is expected to be held for a period of time, which can avoid wasting CPU resources.
This implementation provides the upgradeable read mutex (upread mutex).
The upread mutex can be upgraded to write mutex atomically, useful in
scenarios where a decision to write is made after reading.
The type parameter T represents the data that this mutex 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 mutex is held.
§Usage
The mutex can be used in scenarios where data needs to be read frequently but written to occasionally.
Use upread mutex in scenarios where related checking is performed before
modification to effectively avoid deadlocks and improve efficiency.
§Safety
Avoid using RwMutex in an interrupt context, as it may result in sleeping
and never being awakened.
§Examples
use ostd::sync::RwMutex;
let mutex = RwMutex::new(5)
// many read mutexes can be held at once
{
let r1 = mutex.read();
let r2 = mutex.read();
assert_eq!(*r1, 5);
assert_eq!(*r2, 5);
// Upgradeable read mutex can share access to data with read mutexes
let r3 = mutex.upread();
assert_eq!(*r3, 5);
drop(r1);
drop(r2);
// read mutexes are dropped at this point
// An upread mutex can only be upgraded successfully after all the
// read mutexes are released, otherwise it will spin-wait.
let mut w1 = r3.upgrade();
*w1 += 1;
assert_eq!(*w1, 6);
} // upread mutex are dropped at this point
{
// Only one write mutex can be held at a time
let mut w2 = mutex.write();
*w2 += 1;
assert_eq!(*w2, 7);
} // write mutex is dropped at this pointImplementations§
Source§impl<T> RwMutex<T>
impl<T> RwMutex<T>
Sourcepub closed spec fn core_token_id(self) -> Loc
pub closed spec fn core_token_id(self) -> Loc
Sourcepub closed spec fn upread_retract_token_id(self) -> Loc
pub closed spec fn upread_retract_token_id(self) -> Loc
Sourcepub closed spec fn read_guard_token_id(self) -> Loc
pub closed spec fn read_guard_token_id(self) -> Loc
Source§impl<T> RwMutex<T>
impl<T> RwMutex<T>
Sourcepub exec fn read(&self) -> RwMutexReadGuard<'_, T>
pub exec fn read(&self) -> RwMutexReadGuard<'_, T>
Acquires a read mutex and sleep until it can be acquired.
The calling thread will sleep until there are no writers or upgrading
upreaders present. The implementation of WaitQueue guarantees the
order in which other concurrent readers or writers waiting simultaneously
will acquire the mutex.
Sourcepub exec fn write(&self) -> RwMutexWriteGuard<'_, T>
pub exec fn write(&self) -> RwMutexWriteGuard<'_, T>
Acquires a write mutex and sleep until it can be acquired.
The calling thread will sleep until there are no writers, upreaders,
or readers present. The implementation of WaitQueue guarantees the
order in which other concurrent readers or writers waiting simultaneously
will acquire the mutex.
Sourcepub exec fn upread(&self) -> RwMutexUpgradeableGuard<'_, T>
pub exec fn upread(&self) -> RwMutexUpgradeableGuard<'_, T>
Acquires a upread mutex and sleep until it can be acquired.
The calling thread will sleep until there are no writers or upreaders present.
The implementation of WaitQueue guarantees the order in which other concurrent
readers or writers waiting simultaneously will acquire the mutex.
Upreader will not block new readers until it tries to upgrade. Upreader and reader do not differ before invoking the upgrade method. However, only one upreader can exist at any time to avoid deadlock in the upgrade method.
Sourcepub exec fn try_read(&self) -> Option<RwMutexReadGuard<'_, T>>
pub exec fn try_read(&self) -> Option<RwMutexReadGuard<'_, T>>
Attempts to acquire a read mutex.
This function will never sleep and will return immediately.
Sourcepub exec fn try_write(&self) -> Option<RwMutexWriteGuard<'_, T>>
pub exec fn try_write(&self) -> Option<RwMutexWriteGuard<'_, T>>
Attempts to acquire a write mutex.
This function will never sleep and will return immediately.
Sourcepub exec fn try_upread(&self) -> Option<RwMutexUpgradeableGuard<'_, T>>
pub exec fn try_upread(&self) -> Option<RwMutexUpgradeableGuard<'_, T>>
Attempts to acquire a upread mutex.
This function will never sleep and will return immediately.
Trait Implementations§
impl<T: Send> Send for RwMutex<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.