Struct parking_lot::RwLock

pub struct RwLock<T: ?Sized> {
    // some 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 will always prioritize writers over readers to avoid 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.

Differences from the standard library RwLock

• Supports atomically downgrading a write lock into a read lock.
• Writer-preferred 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.
• A lock guard can be sent to another thread and unlocked there.
• 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.

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>

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);

fn into_inner(self) -> T

Consumes this RwLock, returning the underlying data.

impl<T: ?Sized> RwLock<T>

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.

Because RwLock prefers writers over readers, attempts to recursively acquire a read lock when the current thread already owns one may result in a deadlock.

Returns an RAII guard which will release this thread's shared access once it is dropped.

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.

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.

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.

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.

impl RwLock<()>

unsafe 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.

unsafe fn raw_try_read(&self) -> bool

Attempts to acquire this rwlock with shared read access.

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

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. The rwlock must be locked with shared read access.

unsafe fn raw_write(&self)

Locks this rwlock with exclusive write 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.

unsafe fn raw_try_write(&self) -> bool

Attempts to lock this rwlock with exclusive write access.

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

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. The rwlock must be locked with exclusive write access.

Trait Implementations

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

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

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

fn default() -> RwLock<T>

Returns the "default value" for a type.

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

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

Formats the value using the given formatter.