Type Alias parking_lot::RwLock
source · pub type RwLock<T> = RwLock<RawRwLock, T>;
Expand description
A reader-writer lock
This type of lock allows a number of readers or at most one writer at any point in time. The write portion of this lock typically allows modification of the underlying data (exclusive access) and the read portion of this lock typically allows for read-only access (shared access).
This lock uses a task-fair locking policy which avoids both reader and writer starvation. This means that readers trying to acquire the lock will block even if the lock is unlocked when there are writers waiting to acquire the lock. Because of this, attempts to recursively acquire a read lock within a single thread may result in a deadlock.
The type parameter T
represents the data that this lock protects. It is
required that T
satisfies Send
to be shared across threads and Sync
to
allow concurrent access through readers. The RAII guards returned from the
locking methods implement Deref
(and DerefMut
for the write
methods)
to allow access to the contained of the lock.
§Fairness
A typical unfair lock can often end up in a situation where a single thread quickly acquires and releases the same lock in succession, which can starve other threads waiting to acquire the rwlock. While this improves throughput because it doesn’t force a context switch when a thread tries to re-acquire a rwlock it has just released, this can starve other threads.
This rwlock uses eventual fairness to ensure that the lock will be fair on average without sacrificing throughput. This is done by forcing a fair unlock on average every 0.5ms, which will force the lock to go to the next thread waiting for the rwlock.
Additionally, any critical section longer than 1ms will always use a fair unlock, which has a negligible impact on throughput considering the length of the critical section.
You can also force a fair unlock by calling RwLockReadGuard::unlock_fair
or RwLockWriteGuard::unlock_fair
when unlocking a mutex instead of simply
dropping the guard.
§Differences from the standard library RwLock
- Supports atomically downgrading a write lock into a read lock.
- Task-fair locking policy instead of an unspecified platform default.
- No poisoning, the lock is released normally on panic.
- Only requires 1 word of space, whereas the standard library boxes the
RwLock
due to platform limitations. - Can be statically constructed.
- Does not require any drop glue when dropped.
- Inline fast path for the uncontended case.
- Efficient handling of micro-contention using adaptive spinning.
- Allows raw locking & unlocking without a guard.
- Supports eventual fairness so that the rwlock is fair on average.
- Optionally allows making the rwlock fair by calling
RwLockReadGuard::unlock_fair
andRwLockWriteGuard::unlock_fair
.
§Examples
use parking_lot::RwLock;
let lock = RwLock::new(5);
// many reader locks can be held at once
{
let r1 = lock.read();
let r2 = lock.read();
assert_eq!(*r1, 5);
assert_eq!(*r2, 5);
} // read locks are dropped at this point
// only one write lock may be held, however
{
let mut w = lock.write();
*w += 1;
assert_eq!(*w, 6);
} // write lock is dropped here
Aliased Type§
struct RwLock<T> { /* private fields */ }
Implementations
source§impl<R, T> RwLock<R, T>where
R: RawRwLockUpgrade,
T: ?Sized,
impl<R, T> RwLock<R, T>where
R: RawRwLockUpgrade,
T: ?Sized,
sourcepub unsafe fn make_upgradable_guard_unchecked(
&self,
) -> RwLockUpgradableReadGuard<'_, R, T>
pub unsafe fn make_upgradable_guard_unchecked( &self, ) -> RwLockUpgradableReadGuard<'_, R, T>
Creates a new RwLockUpgradableReadGuard
without checking if the lock is held.
§Safety
This method must only be called if the thread logically holds an upgradable read lock.
This function does not increment the read count of the lock. Calling this function when a
guard has already been produced is undefined behaviour unless the guard was forgotten
with mem::forget
.
sourcepub fn upgradable_read(&self) -> RwLockUpgradableReadGuard<'_, R, T>
pub fn upgradable_read(&self) -> RwLockUpgradableReadGuard<'_, R, T>
Locks this RwLock
with upgradable read access, blocking the current thread
until it can be acquired.
The calling thread will be blocked until there are no more writers or other upgradable reads which hold the lock. There may be other readers currently inside the lock when this method returns.
Returns an RAII guard which will release this thread’s shared access once it is dropped.
sourcepub fn try_upgradable_read(&self) -> Option<RwLockUpgradableReadGuard<'_, R, T>>
pub fn try_upgradable_read(&self) -> Option<RwLockUpgradableReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with upgradable read access.
If the access could not be granted at this time, then None
is returned.
Otherwise, an RAII guard is returned which will release the shared access
when it is dropped.
This function does not block.
source§impl<R, T> RwLock<R, T>where
R: RawRwLockUpgradeTimed,
T: ?Sized,
impl<R, T> RwLock<R, T>where
R: RawRwLockUpgradeTimed,
T: ?Sized,
sourcepub fn try_upgradable_read_for(
&self,
timeout: <R as RawRwLockTimed>::Duration,
) -> Option<RwLockUpgradableReadGuard<'_, R, T>>
pub fn try_upgradable_read_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockUpgradableReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with upgradable read access until a timeout
is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the shared access when it is dropped.
sourcepub fn try_upgradable_read_until(
&self,
timeout: <R as RawRwLockTimed>::Instant,
) -> Option<RwLockUpgradableReadGuard<'_, R, T>>
pub fn try_upgradable_read_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockUpgradableReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with upgradable read access until a timeout
is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the shared access when it is dropped.
source§impl<R, T> RwLock<R, T>where
R: RawRwLock,
impl<R, T> RwLock<R, T>where
R: RawRwLock,
sourcepub const fn new(val: T) -> RwLock<R, T>
pub const fn new(val: T) -> RwLock<R, T>
Creates a new instance of an RwLock<T>
which is unlocked.
sourcepub fn into_inner(self) -> T
pub fn into_inner(self) -> T
Consumes this RwLock
, returning the underlying data.
source§impl<R, T> RwLock<R, T>
impl<R, T> RwLock<R, T>
source§impl<R, T> RwLock<R, T>
impl<R, T> RwLock<R, T>
sourcepub unsafe fn make_read_guard_unchecked(&self) -> RwLockReadGuard<'_, R, T>
pub unsafe fn make_read_guard_unchecked(&self) -> RwLockReadGuard<'_, R, T>
Creates a new RwLockReadGuard
without checking if the lock is held.
§Safety
This method must only be called if the thread logically holds a read lock.
This function does not increment the read count of the lock. Calling this function when a
guard has already been produced is undefined behaviour unless the guard was forgotten
with mem::forget
.
sourcepub unsafe fn make_write_guard_unchecked(&self) -> RwLockWriteGuard<'_, R, T>
pub unsafe fn make_write_guard_unchecked(&self) -> RwLockWriteGuard<'_, R, T>
Creates a new RwLockReadGuard
without checking if the lock is held.
§Safety
This method must only be called if the thread logically holds a write lock.
Calling this function when a guard has already been produced is undefined behaviour unless
the guard was forgotten with mem::forget
.
sourcepub fn read(&self) -> RwLockReadGuard<'_, R, T>
pub fn read(&self) -> RwLockReadGuard<'_, R, T>
Locks this RwLock
with shared read access, blocking the current thread
until it can be acquired.
The calling thread will be blocked until there are no more writers which hold the lock. There may be other readers currently inside the lock when this method returns.
Note that attempts to recursively acquire a read lock on a RwLock
when
the current thread already holds one may result in a deadlock.
Returns an RAII guard which will release this thread’s shared access once it is dropped.
sourcepub fn try_read(&self) -> Option<RwLockReadGuard<'_, R, T>>
pub fn try_read(&self) -> Option<RwLockReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with shared read access.
If the access could not be granted at this time, then None
is returned.
Otherwise, an RAII guard is returned which will release the shared access
when it is dropped.
This function does not block.
sourcepub fn write(&self) -> RwLockWriteGuard<'_, R, T>
pub fn write(&self) -> RwLockWriteGuard<'_, R, T>
Locks this RwLock
with exclusive write access, blocking the current
thread until it can be acquired.
This function will not return while other writers or other readers currently have access to the lock.
Returns an RAII guard which will drop the write access of this RwLock
when dropped.
sourcepub fn try_write(&self) -> Option<RwLockWriteGuard<'_, R, T>>
pub fn try_write(&self) -> Option<RwLockWriteGuard<'_, R, T>>
Attempts to lock this RwLock
with exclusive write access.
If the lock could not be acquired at this time, then None
is returned.
Otherwise, an RAII guard is returned which will release the lock when
it is dropped.
This function does not block.
sourcepub fn get_mut(&mut self) -> &mut 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.
sourcepub fn is_locked_exclusive(&self) -> bool
pub fn is_locked_exclusive(&self) -> bool
Check if this RwLock
is currently exclusively locked.
sourcepub unsafe fn force_unlock_read(&self)
pub unsafe fn force_unlock_read(&self)
Forcibly unlocks a read lock.
This is useful when combined with mem::forget
to hold a lock without
the need to maintain a RwLockReadGuard
object alive, for example when
dealing with FFI.
§Safety
This method must only be called if the current thread logically owns a
RwLockReadGuard
but that guard has be discarded using mem::forget
.
Behavior is undefined if a rwlock is read-unlocked when not read-locked.
sourcepub unsafe fn force_unlock_write(&self)
pub unsafe fn force_unlock_write(&self)
Forcibly unlocks a write lock.
This is useful when combined with mem::forget
to hold a lock without
the need to maintain a RwLockWriteGuard
object alive, for example when
dealing with FFI.
§Safety
This method must only be called if the current thread logically owns a
RwLockWriteGuard
but that guard has be discarded using mem::forget
.
Behavior is undefined if a rwlock is write-unlocked when not write-locked.
sourcepub unsafe fn raw(&self) -> &R
pub unsafe fn raw(&self) -> &R
Returns the underlying raw reader-writer lock object.
Note that you will most likely need to import the RawRwLock
trait from
lock_api
to be able to call functions on the raw
reader-writer lock.
§Safety
This method is unsafe because it allows unlocking a mutex while still holding a reference to a lock guard.
sourcepub fn data_ptr(&self) -> *mut T
pub fn data_ptr(&self) -> *mut T
Returns a raw pointer to the underlying data.
This is useful when combined with mem::forget
to hold a lock without
the need to maintain a RwLockReadGuard
or RwLockWriteGuard
object
alive, for example when dealing with FFI.
§Safety
You must ensure that there are no data races when dereferencing the
returned pointer, for example if the current thread logically owns a
RwLockReadGuard
or RwLockWriteGuard
but that guard has been discarded
using mem::forget
.
source§impl<R, T> RwLock<R, T>where
R: RawRwLockFair,
T: ?Sized,
impl<R, T> RwLock<R, T>where
R: RawRwLockFair,
T: ?Sized,
sourcepub unsafe fn force_unlock_read_fair(&self)
pub unsafe fn force_unlock_read_fair(&self)
Forcibly unlocks a read lock using a fair unlock protocol.
This is useful when combined with mem::forget
to hold a lock without
the need to maintain a RwLockReadGuard
object alive, for example when
dealing with FFI.
§Safety
This method must only be called if the current thread logically owns a
RwLockReadGuard
but that guard has be discarded using mem::forget
.
Behavior is undefined if a rwlock is read-unlocked when not read-locked.
sourcepub unsafe fn force_unlock_write_fair(&self)
pub unsafe fn force_unlock_write_fair(&self)
Forcibly unlocks a write lock using a fair unlock protocol.
This is useful when combined with mem::forget
to hold a lock without
the need to maintain a RwLockWriteGuard
object alive, for example when
dealing with FFI.
§Safety
This method must only be called if the current thread logically owns a
RwLockWriteGuard
but that guard has be discarded using mem::forget
.
Behavior is undefined if a rwlock is write-unlocked when not write-locked.
source§impl<R, T> RwLock<R, T>where
R: RawRwLockTimed,
T: ?Sized,
impl<R, T> RwLock<R, T>where
R: RawRwLockTimed,
T: ?Sized,
sourcepub fn try_read_for(
&self,
timeout: <R as RawRwLockTimed>::Duration,
) -> Option<RwLockReadGuard<'_, R, T>>
pub fn try_read_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with shared read access until a timeout
is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the shared access when it is dropped.
sourcepub fn try_read_until(
&self,
timeout: <R as RawRwLockTimed>::Instant,
) -> Option<RwLockReadGuard<'_, R, T>>
pub fn try_read_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with shared read access until a timeout
is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the shared access when it is dropped.
sourcepub fn try_write_for(
&self,
timeout: <R as RawRwLockTimed>::Duration,
) -> Option<RwLockWriteGuard<'_, R, T>>
pub fn try_write_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockWriteGuard<'_, R, T>>
Attempts to acquire this RwLock
with exclusive write access until a
timeout is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the exclusive access when it is dropped.
sourcepub fn try_write_until(
&self,
timeout: <R as RawRwLockTimed>::Instant,
) -> Option<RwLockWriteGuard<'_, R, T>>
pub fn try_write_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockWriteGuard<'_, R, T>>
Attempts to acquire this RwLock
with exclusive write access until a
timeout is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the exclusive access when it is dropped.
source§impl<R, T> RwLock<R, T>where
R: RawRwLockRecursive,
T: ?Sized,
impl<R, T> RwLock<R, T>where
R: RawRwLockRecursive,
T: ?Sized,
sourcepub fn read_recursive(&self) -> RwLockReadGuard<'_, R, T>
pub fn read_recursive(&self) -> RwLockReadGuard<'_, R, T>
Locks this RwLock
with shared read access, blocking the current thread
until it can be acquired.
The calling thread will be blocked until there are no more writers which hold the lock. There may be other readers currently inside the lock when this method returns.
Unlike read
, this method is guaranteed to succeed without blocking if
another read lock is held at the time of the call. This allows a thread
to recursively lock a RwLock
. However using this method can cause
writers to starve since readers no longer block if a writer is waiting
for the lock.
Returns an RAII guard which will release this thread’s shared access once it is dropped.
sourcepub fn try_read_recursive(&self) -> Option<RwLockReadGuard<'_, R, T>>
pub fn try_read_recursive(&self) -> Option<RwLockReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with shared read access.
If the access could not be granted at this time, then None
is returned.
Otherwise, an RAII guard is returned which will release the shared access
when it is dropped.
This method is guaranteed to succeed if another read lock is held at the
time of the call. See the documentation for read_recursive
for details.
This function does not block.
source§impl<R, T> RwLock<R, T>where
R: RawRwLockRecursiveTimed,
T: ?Sized,
impl<R, T> RwLock<R, T>where
R: RawRwLockRecursiveTimed,
T: ?Sized,
sourcepub fn try_read_recursive_for(
&self,
timeout: <R as RawRwLockTimed>::Duration,
) -> Option<RwLockReadGuard<'_, R, T>>
pub fn try_read_recursive_for( &self, timeout: <R as RawRwLockTimed>::Duration, ) -> Option<RwLockReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with shared read access until a timeout
is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the shared access when it is dropped.
This method is guaranteed to succeed without blocking if another read
lock is held at the time of the call. See the documentation for
read_recursive
for details.
sourcepub fn try_read_recursive_until(
&self,
timeout: <R as RawRwLockTimed>::Instant,
) -> Option<RwLockReadGuard<'_, R, T>>
pub fn try_read_recursive_until( &self, timeout: <R as RawRwLockTimed>::Instant, ) -> Option<RwLockReadGuard<'_, R, T>>
Attempts to acquire this RwLock
with shared read access until a timeout
is reached.
If the access could not be granted before the timeout expires, then
None
is returned. Otherwise, an RAII guard is returned which will
release the shared access when it is dropped.