Struct RwLock 

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

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

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 contents of the lock.

Implementations

impl<R: RawRwLock, T> RwLock<R, T>

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

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

pub fn into_inner(self) -> T

Consumes this RwLock, returning the underlying data.

impl<R, T> RwLock<R, T>

pub const fn from_raw(raw_rwlock: R, val: T) -> RwLock<R, T>

Creates a new instance of an RwLock<T> based on a pre-existing raw rwlock.

pub fn into_inner_with_raw(self) -> (R, T)

Consumes this read-write lock, returning the underlying data and raw lock.

impl<R: RawRwLock, T: ?Sized> RwLock<R, T>

pub unsafe fn make_read_guard_unchecked( &self, guard: R::SharedGuard, ) -> 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 behavior unless the guard was forgotten with mem::forget.

The caller must ensure that existing references to the protected data remain valid when the returned guard is used or dropped. In particular, the returned guard must not permit accesses that conflict with existing references.

guard must be the state for this acquisition of this lock.

pub unsafe fn make_write_guard_unchecked( &self, guard: R::ExclusiveGuard, ) -> RwLockWriteGuard<'_, R, T>

Creates a new RwLockWriteGuard 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 behavior unless the guard was forgotten with mem::forget.

The caller must ensure that existing references to the protected data remain valid when the returned guard is used or dropped. In particular, the returned guard must not permit accesses that conflict with existing references.

guard must be the state for this acquisition of this lock.

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.

Whether recursive read locking is supported depends on the raw lock implementation. Implementations which block new readers while a writer is waiting may deadlock if the current thread already holds a read lock.

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

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

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.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

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.

The exact behavior when the current thread already holds the lock is unspecified. The call will not return; it may panic or deadlock, for example.

Returns an RAII guard which will drop the write access of this RwLock when dropped.

Panics

This function may panic if the lock is already held by the current thread.

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.

pub const 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 new locks can be acquired while the reference exists. This method does not clear locks previously abandoned by forgetting a RwLockReadGuard or RwLockWriteGuard.

pub fn is_locked(&self) -> bool

Checks whether this RwLock is currently locked in any way.

The result is a momentary snapshot and may be stale by the time it is returned.

pub fn is_locked_exclusive(&self) -> bool

Checks whether this RwLock is currently exclusively locked.

The result is a momentary snapshot and may be stale by the time it is returned.

pub unsafe fn force_unlock_read(&self, guard: R::SharedGuard)

Forcibly unlocks a read lock.

This is useful when the raw acquisition state is managed separately, for example when dealing with FFI.

Safety

The current context must hold the lock using the supplied acquisition state, with no live guard responsible for unlocking it. Behavior is undefined if a rwlock is read-unlocked when not read-locked.

The caller must ensure that releasing the lock does not invalidate any outstanding references to the protected data. Any subsequent access through previously obtained pointers must be properly synchronized.

guard must be the state for this acquisition of this lock.

pub unsafe fn force_unlock_write(&self, guard: R::ExclusiveGuard)

Forcibly unlocks a write lock.

This is useful when the raw acquisition state is managed separately, for example when dealing with FFI.

Safety

The current context must hold the lock using the supplied acquisition state, with no live guard responsible for unlocking it. Behavior is undefined if a rwlock is write-unlocked when not write-locked.

The caller must ensure that releasing the lock does not invalidate any outstanding references to the protected data. Any subsequent access through previously obtained pointers must be properly synchronized.

guard must be the state for this acquisition of this lock.

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

The caller must ensure that operations on the raw lock preserve the validity of all live guards and references to the protected data. A guard must not be used or dropped while its lock is released, and any access through previously obtained pointers must be properly synchronized.

pub const fn data_ptr(&self) -> *mut T

Returns a raw pointer to the underlying data.

The returned pointer is always non-null and properly aligned, but the caller must ensure that reads and writes through it are properly synchronized and that the pointer is not used after the rwlock is dropped.

impl<R: RawRwLockFair, T: ?Sized> RwLock<R, T>

pub unsafe fn force_unlock_read_fair(&self, guard: R::SharedGuard)

Forcibly unlocks a read lock using a fair unlock protocol.

This is useful when the raw acquisition state is managed separately, for example when dealing with FFI.

Safety

The current context must hold the lock using the supplied acquisition state, with no live guard responsible for unlocking it. Behavior is undefined if a rwlock is read-unlocked when not read-locked.

The caller must ensure that releasing the lock does not invalidate any outstanding references to the protected data. Any subsequent access through previously obtained pointers must be properly synchronized.

guard must be the state for this acquisition of this lock.

pub unsafe fn force_unlock_write_fair(&self, guard: R::ExclusiveGuard)

Forcibly unlocks a write lock using a fair unlock protocol.

This is useful when the raw acquisition state is managed separately, for example when dealing with FFI.

Safety

The current context must hold the lock using the supplied acquisition state, with no live guard responsible for unlocking it. Behavior is undefined if a rwlock is write-unlocked when not write-locked.

The caller must ensure that releasing the lock does not invalidate any outstanding references to the protected data. Any subsequent access through previously obtained pointers must be properly synchronized.

guard must be the state for this acquisition of this lock.

impl<R: RawRwLockTimed, T: ?Sized> RwLock<R, T>

pub fn try_read_for( &self, timeout: R::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.

See RawRwLockTimed::try_lock_shared_for for timeout behavior.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

pub fn try_read_until( &self, timeout: R::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.

See RawRwLockTimed::try_lock_shared_until for timeout behavior.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

pub fn try_write_for( &self, timeout: R::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.

See RawRwLockTimed::try_lock_exclusive_for for timeout behavior.

pub fn try_write_until( &self, timeout: R::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.

See RawRwLockTimed::try_lock_exclusive_until for timeout behavior.

impl<R: RawRwLockUpgrade, T: ?Sized> RwLock<R, T>

pub unsafe fn make_upgradable_guard_unchecked( &self, guard: R::UpgradableGuard, ) -> 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 behavior unless the guard was forgotten with mem::forget.

The caller must ensure that existing references to the protected data remain valid when the returned guard is used or dropped. In particular, the returned guard must not permit accesses that conflict with existing references.

guard must be the state for this acquisition of this lock.

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.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

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.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

impl<R: RawRwLockUpgradeTimed, T: ?Sized> RwLock<R, T>

pub fn try_upgradable_read_for( &self, timeout: R::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.

See RawRwLockUpgradeTimed::try_lock_upgradable_for for timeout behavior.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

pub fn try_upgradable_read_until( &self, timeout: R::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.

See RawRwLockUpgradeTimed::try_lock_upgradable_until for timeout behavior.

Panics

This method may panic if the maximum number of readers supported by the raw lock has been reached.

Trait Implementations

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

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

Formats the value using the given formatter.

impl<R: RawRwLock, T: Default> Default for RwLock<R, T>

fn default() -> RwLock<R, T>

Returns the “default value” for a type.

impl<R: RawRwLock, T> From<T> for RwLock<R, T>

fn from(t: T) -> RwLock<R, T>

Converts to this type from the input type.

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