pub struct RwLock<T: ?Sized> {/* private fields */ }Expand description
A reader-writer lock
This type of lock allows a number of readers or at most one writer at anypoint in time. The write portion of this lock typically allows modificationof the underlying data (exclusive access) and the read portion of this locktypically allows for read-only access (shared access).
In comparison, aMutex does not distinguish between readers or writersthat acquire the lock, therefore blocking any threads waiting for the lock tobecome available. AnRwLock will allow any number of readers to acquire thelock as long as a writer is not holding the lock.
The priority policy of the lock is dependent on the underlying operatingsystem’s implementation, and this type does not guarantee that anyparticular policy will be used. In particular, a writer which is waiting toacquire the lock inwrite might or might not block concurrent calls toread, e.g.:
Potential deadlock example
// Thread 1 | // Thread 2let _rg1 = lock.read(); | | // will block | let _wg = lock.write();// may deadlock |let _rg2 = lock.read(); |The type parameterT represents the data that this lock protects. It isrequired thatT satisfiesSend to be shared across threads andSync to allow concurrent access through readers. The RAII guardsreturned from the locking methods implementDeref (andDerefMutfor thewrite methods) to allow access to the content of the lock.
§Poisoning
AnRwLock, likeMutex, willusually become poisoned on a panic. Note,however, that anRwLock may only be poisoned if a panic occurs while it islocked exclusively (write mode). If a panic occurs in any reader, then thelock will not be poisoned.
§Examples
usestd::sync::RwLock;letlock = RwLock::new(5);// many reader locks can be held at once{letr1 = lock.read().unwrap();letr2 = lock.read().unwrap();assert_eq!(*r1,5);assert_eq!(*r2,5);}// read locks are dropped at this point// only one write lock may be held, however{letmutw = lock.write().unwrap();*w +=1;assert_eq!(*w,6);}// write lock is dropped hereImplementations§
Source§impl<T>RwLock<T>
impl<T>RwLock<T>
1.0.0 (const: 1.63.0) ·Sourcepub const fnnew(t: T) ->RwLock<T>
pub const fnnew(t: T) ->RwLock<T>
Creates a new instance of anRwLock<T> which is unlocked.
§Examples
Sourcepub fnget_cloned(&self) ->Result<T,PoisonError<()>>where T:Clone,
🔬This is a nightly-only experimental API. (lock_value_accessors #133407)
pub fnget_cloned(&self) ->Result<T,PoisonError<()>>where T:Clone,
lock_value_accessors #133407)Sourcepub fnset(&self, value: T) ->Result<(),PoisonError<T>>
🔬This is a nightly-only experimental API. (lock_value_accessors #133407)
pub fnset(&self, value: T) ->Result<(),PoisonError<T>>
lock_value_accessors #133407)Sourcepub fnreplace(&self, value: T) ->LockResult<T>
🔬This is a nightly-only experimental API. (lock_value_accessors #133407)
pub fnreplace(&self, value: T) ->LockResult<T>
lock_value_accessors #133407)Source§impl<T: ?Sized>RwLock<T>
impl<T: ?Sized>RwLock<T>
1.0.0 ·Sourcepub fnread(&self) ->LockResult<RwLockReadGuard<'_, T>>
pub fnread(&self) ->LockResult<RwLockReadGuard<'_, T>>
Locks thisRwLock with shared read access, blocking the current threaduntil it can be acquired.
The calling thread will be blocked until there are no more writers whichhold the lock. There may be other readers currently inside the lock whenthis method returns. This method does not provide any guarantees withrespect to the ordering of whether contentious readers or writers willacquire the lock first.
Returns an RAII guard which will release this thread’s shared accessonce it is dropped.
§Errors
This function will return an error if theRwLock is poisoned. AnRwLock is poisoned whenever a writer panics while holding an exclusivelock. The failure will occur immediately after the lock has beenacquired. The acquired lock guard will be contained in the returnederror.
§Panics
This function might panic when called if the lock is already held by the current thread.
§Examples
1.0.0 ·Sourcepub fntry_read(&self) ->TryLockResult<RwLockReadGuard<'_, T>>
pub fntry_read(&self) ->TryLockResult<RwLockReadGuard<'_, T>>
Attempts to acquire thisRwLock with shared read access.
If the access could not be granted at this time, thenErr is returned.Otherwise, an RAII guard is returned which will release the shared accesswhen it is dropped.
This function does not block.
This function does not provide any guarantees with respect to the orderingof whether contentious readers or writers will acquire the lock first.
§Errors
This function will return thePoisoned error if theRwLock ispoisoned. AnRwLock is poisoned whenever a writer panics while holdingan exclusive lock.Poisoned will only be returned if the lock wouldhave otherwise been acquired. An acquired lock guard will be containedin the returned error.
This function will return theWouldBlock error if theRwLock couldnot be acquired because it was already locked exclusively.
§Examples
1.0.0 ·Sourcepub fnwrite(&self) ->LockResult<RwLockWriteGuard<'_, T>>
pub fnwrite(&self) ->LockResult<RwLockWriteGuard<'_, T>>
Locks thisRwLock with exclusive write access, blocking the currentthread until it can be acquired.
This function will not return while other writers or other readerscurrently have access to the lock.
Returns an RAII guard which will drop the write access of thisRwLockwhen dropped.
§Errors
This function will return an error if theRwLock is poisoned. AnRwLock is poisoned whenever a writer panics while holding an exclusivelock. An error will be returned when the lock is acquired. The acquiredlock guard will be contained in the returned error.
§Panics
This function might panic when called if the lock is already held by the current thread.
§Examples
1.0.0 ·Sourcepub fntry_write(&self) ->TryLockResult<RwLockWriteGuard<'_, T>>
pub fntry_write(&self) ->TryLockResult<RwLockWriteGuard<'_, T>>
Attempts to lock thisRwLock with exclusive write access.
If the lock could not be acquired at this time, thenErr is returned.Otherwise, an RAII guard is returned which will release the lock whenit is dropped.
This function does not block.
This function does not provide any guarantees with respect to the orderingof whether contentious readers or writers will acquire the lock first.
§Errors
This function will return thePoisoned error if theRwLock ispoisoned. AnRwLock is poisoned whenever a writer panics while holdingan exclusive lock.Poisoned will only be returned if the lock wouldhave otherwise been acquired. An acquired lock guard will be containedin the returned error.
This function will return theWouldBlock error if theRwLock couldnot be acquired because it was already locked.
§Examples
1.2.0 ·Sourcepub fnis_poisoned(&self) ->bool
pub fnis_poisoned(&self) ->bool
Determines whether the lock is poisoned.
If another thread is active, the lock can still become poisoned at anytime. You should not trust afalse value for program correctnesswithout additional synchronization.
§Examples
1.77.0 ·Sourcepub fnclear_poison(&self)
pub fnclear_poison(&self)
Clear the poisoned state from a lock.
If the lock is poisoned, it will remain poisoned until this function is called. This allowsrecovering from a poisoned state and marking that it has recovered. For example, if thevalue is overwritten by a known-good value, then the lock can be marked as un-poisoned. Orpossibly, the value could be inspected to determine if it is in a consistent state, and ifso the poison is removed.
§Examples
usestd::sync::{Arc, RwLock};usestd::thread;letlock = Arc::new(RwLock::new(0));letc_lock = Arc::clone(&lock);let _= thread::spawn(move|| {let_lock = c_lock.write().unwrap();panic!();// the lock gets poisoned}).join();assert_eq!(lock.is_poisoned(),true);letguard = lock.write().unwrap_or_else(|mute| {**e.get_mut() =1; lock.clear_poison(); e.into_inner()});assert_eq!(lock.is_poisoned(),false);assert_eq!(*guard,1);1.6.0 ·Sourcepub fninto_inner(self) ->LockResult<T>where T:Sized,
pub fninto_inner(self) ->LockResult<T>where T:Sized,
Consumes thisRwLock, returning the underlying data.
§Errors
This function will return an error containing the underlying data iftheRwLock is poisoned. AnRwLock is poisoned whenever a writerpanics while holding an exclusive lock. An error will only be returnedif the lock would have otherwise been acquired.
§Examples
1.6.0 ·Sourcepub fnget_mut(&mut self) ->LockResult<&mut T>
pub fnget_mut(&mut self) ->LockResult<&mut T>
Returns a mutable reference to the underlying data.
Since this call borrows theRwLock mutably, no actual locking needs totake place – the mutable borrow statically guarantees no new locks can be acquiredwhile this reference exists. Note that this method does not clear any previously abandonedlocks (e.g., viaforget() on aRwLockReadGuard orRwLockWriteGuard).
§Errors
This function will return an error containing a mutable reference tothe underlying data if theRwLock is poisoned. AnRwLock ispoisoned whenever a writer panics while holding an exclusive lock.An error will only be returned if the lock would have otherwise beenacquired.
§Examples
Sourcepub const fndata_ptr(&self) ->*mut T
🔬This is a nightly-only experimental API. (rwlock_data_ptr #140368)
pub const fndata_ptr(&self) ->*mut T
rwlock_data_ptr #140368)Returns a raw pointer to the underlying data.
The returned pointer is always non-null and properly aligned, but it isthe user’s responsibility to ensure that any reads and writes through itare properly synchronized to avoid data races, and that it is not reador written through after the lock is dropped.
Trait Implementations§
1.24.0 ·Source§impl<T>From<T> forRwLock<T>
impl<T>From<T> forRwLock<T>
Source§fnfrom(t: T) -> Self
fnfrom(t: T) -> Self
Creates a new instance of anRwLock<T> which is unlocked.This is equivalent toRwLock::new.