Struct serenity::prelude::RwLock

pub struct RwLock<T> where
    T: ?Sized,  { /* fields omitted */ }

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 performance 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 performance. 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 performance impact compared to 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 (requires the const_fn nightly feature).
• 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 and RwLockWriteGuard::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

Methods

impl<T> RwLock<T>

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

Creates a new instance of an RwLock<T> which is unlocked.

Examples

use parking_lot::RwLock;

let lock = RwLock::new(5);

pub fn into_inner(self) -> T

Consumes this RwLock, returning the underlying data.

impl<T> RwLock<T> where
    T: ?Sized, 

pub fn read(&self) -> RwLockReadGuard<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.

pub fn try_read(&self) -> Option<RwLockReadGuard<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.

pub fn try_read_for(&self, timeout: Duration) -> Option<RwLockReadGuard<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.

pub fn try_read_until(&self, timeout: Instant) -> Option<RwLockReadGuard<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.

pub fn read_recursive(&self) -> RwLockReadGuard<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.

pub fn try_read_recursive(&self) -> Option<RwLockReadGuard<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.

pub fn try_read_recursive_for(
    &self,
    timeout: Duration
) -> Option<RwLockReadGuard<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.

pub fn try_read_recursive_until(
    &self,
    timeout: Instant
) -> Option<RwLockReadGuard<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.

pub fn write(&self) -> RwLockWriteGuard<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.

pub fn try_write(&self) -> Option<RwLockWriteGuard<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.

pub fn try_write_for(&self, timeout: Duration) -> Option<RwLockWriteGuard<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.

pub fn try_write_until(&self, timeout: Instant) -> Option<RwLockWriteGuard<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.

pub fn upgradable_read(&self) -> RwLockUpgradableReadGuard<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.

pub fn try_upgradable_read(&self) -> Option<RwLockUpgradableReadGuard<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.

pub fn try_upgradable_read_for(
    &self,
    timeout: Duration
) -> Option<RwLockUpgradableReadGuard<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.

pub fn try_upgradable_read_until(
    &self,
    timeout: Instant
) -> Option<RwLockUpgradableReadGuard<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.

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.

pub unsafe fn raw_unlock_read(&self)

Releases shared read access of the rwlock.

Safety

This function must only be called if the rwlock was locked using raw_read or raw_try_read, or if an RwLockReadGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with shared read access.

pub unsafe fn raw_unlock_write(&self)

Releases exclusive write access of the rwlock.

Safety

This function must only be called if the rwlock was locked using raw_write or raw_try_write, or if an RwLockWriteGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with exclusive write access.

pub unsafe fn raw_unlock_upgradable_read(&self)

Releases upgradable read access of the rwlock.

Safety

This function must only be called if the rwlock was locked using raw_upgradable_read or raw_try_upgradable_read, or if an RwLockUpgradableReadGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with upgradable read access.

pub unsafe fn raw_unlock_read_fair(&self)

Releases shared read access of the rwlock using a fair unlock protocol.

See RwLockReadGuard::unlock_fair.

Safety

This function must only be called if the rwlock was locked using raw_write or raw_try_write, a raw upgradable read lock was upgraded using raw_upgrade or raw_try_upgrade, or if an RwLockWriteGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with exclusive write access.

pub unsafe fn raw_unlock_write_fair(&self)

Releases exclusive write access of the rwlock using a fair unlock protocol.

See RwLockWriteGuard::unlock_fair.

Safety

This function must only be called if the rwlock was locked using raw_write or raw_try_write, a raw upgradable read lock was upgraded using raw_upgrade or raw_try_upgrade, or if an RwLockWriteGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with exclusive write access.

pub unsafe fn raw_unlock_upgradable_read_fair(&self)

Releases upgradable read access of the rwlock using a fair unlock protocol.

Safety

This function must only be called if the rwlock was locked using raw_upgradable_read or raw_try_upgradable_read, or if an RwLockUpgradableReadGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with upgradable read access.

pub unsafe fn raw_downgrade(&self)

Atomically downgrades a write lock into a shared read lock without allowing any writers to take exclusive access of the lock in the meantime.

See RwLockWriteGuard::downgrade.

Safety

This function must only be called if the rwlock was locked using raw_write or raw_try_write, or if an RwLockWriteGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with exclusive write access.

pub unsafe fn raw_downgrade_upgradable_read(&self)

Atomically downgrades an upgradable read lock into a shared read lock without allowing any writers to take exclusive access of the lock in the meantime.

See RwLockUpgradableReadGuard::downgrade.

Safety

This function must only be called if the rwlock was locked using raw_upgradable_read or raw_try_upgradable_read, or if an RwLockUpgradableReadGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with upgradable read access.

impl RwLock<()>

pub fn raw_read(&self)

Locks this rwlock with shared read access, blocking the current thread until it can be acquired.

This is similar to read, except that a RwLockReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_try_read(&self) -> bool

Attempts to acquire this rwlock with shared read access.

This is similar to try_read, except that a RwLockReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_read_recursive(&self)

Locks this rwlock with shared read access, blocking the current thread until it can be acquired.

This is similar to read_recursive, except that a RwLockReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_try_read_recursive(&self) -> bool

Attempts to acquire this rwlock with shared read access.

This is similar to try_read_recursive, except that a RwLockReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_write(&self)

Locks this rwlock with exclusive write access, blocking the current thread until it can be acquired.

This is similar to write, except that a RwLockReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_try_write(&self) -> bool

Attempts to lock this rwlock with exclusive write access.

This is similar to try_write, except that a RwLockReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_upgradable_read(&self)

Locks this rwlock with upgradable read access, blocking the current thread until it can be acquired.

This is similar to upgradable_read, except that a RwLockUpgradableReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub fn raw_try_upgradable_read(&self) -> bool

Attempts to acquire this rwlock with upgradable read access.

This is similar to try_upgradable_read, except that a RwLockUpgradableReadGuard is not returned. Instead you will need to call raw_unlock to release the rwlock.

pub unsafe fn raw_upgrade(&self)

Upgrades this rwlock from upgradable read access to exclusive write access, blocking the current thread until it can be acquired.

See RwLockUpgradableReadGuard::upgrade.

Safety

This function must only be called if the rwlock was locked using raw_upgradable_read or raw_try_upgradable_read, or if an RwLockUpgradableReadGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with upgradable read access.

pub unsafe fn raw_try_upgrade(&self) -> bool

Attempts to upgrade this rwlock from upgradable read access to exclusive write access.

See RwLockUpgradableReadGuard::try_upgrade.

Safety

This function must only be called if the rwlock was locked using raw_upgradable_read or raw_try_upgradable_read, or if an RwLockUpgradableReadGuard from this rwlock was leaked (e.g. with mem::forget). The rwlock must be locked with upgradable read access.

Trait Implementations

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

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

Formats the value using the given formatter.

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

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

fn default() -> RwLock<T>

Returns the "default value" for a type.

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