1 #[cfg(all(test, not(target_os = "emscripten")))]
4 use crate::cell
::UnsafeCell
;
6 use crate::ops
::{Deref, DerefMut}
;
7 use crate::ptr
::NonNull
;
8 use crate::sync
::{poison, LockResult, TryLockError, TryLockResult}
;
9 use crate::sys
::locks
as sys
;
11 /// A reader-writer lock
13 /// This type of lock allows a number of readers or at most one writer at any
14 /// point in time. The write portion of this lock typically allows modification
15 /// of the underlying data (exclusive access) and the read portion of this lock
16 /// typically allows for read-only access (shared access).
18 /// In comparison, a [`Mutex`] does not distinguish between readers or writers
19 /// that acquire the lock, therefore blocking any threads waiting for the lock to
20 /// become available. An `RwLock` will allow any number of readers to acquire the
21 /// lock as long as a writer is not holding the lock.
23 /// The priority policy of the lock is dependent on the underlying operating
24 /// system's implementation, and this type does not guarantee that any
25 /// particular policy will be used. In particular, a writer which is waiting to
26 /// acquire the lock in `write` might or might not block concurrent calls to
29 /// <details><summary>Potential deadlock example</summary>
32 /// // Thread 1 | // Thread 2
33 /// let _rg = lock.read(); |
35 /// | let _wg = lock.write();
37 /// let _rg = lock.read(); |
41 /// The type parameter `T` represents the data that this lock protects. It is
42 /// required that `T` satisfies [`Send`] to be shared across threads and
43 /// [`Sync`] to allow concurrent access through readers. The RAII guards
44 /// returned from the locking methods implement [`Deref`] (and [`DerefMut`]
45 /// for the `write` methods) to allow access to the content of the lock.
49 /// An `RwLock`, like [`Mutex`], will become poisoned on a panic. Note, however,
50 /// that an `RwLock` may only be poisoned if a panic occurs while it is locked
51 /// exclusively (write mode). If a panic occurs in any reader, then the lock
52 /// will not be poisoned.
57 /// use std::sync::RwLock;
59 /// let lock = RwLock::new(5);
61 /// // many reader locks can be held at once
63 /// let r1 = lock.read().unwrap();
64 /// let r2 = lock.read().unwrap();
65 /// assert_eq!(*r1, 5);
66 /// assert_eq!(*r2, 5);
67 /// } // read locks are dropped at this point
69 /// // only one write lock may be held, however
71 /// let mut w = lock.write().unwrap();
73 /// assert_eq!(*w, 6);
74 /// } // write lock is dropped here
77 /// [`Mutex`]: super::Mutex
78 #[stable(feature = "rust1", since = "1.0.0")]
79 #[cfg_attr(not(test), rustc_diagnostic_item = "RwLock")]
80 pub struct RwLock
<T
: ?Sized
> {
86 #[stable(feature = "rust1", since = "1.0.0")]
87 unsafe impl<T
: ?Sized
+ Send
> Send
for RwLock
<T
> {}
88 #[stable(feature = "rust1", since = "1.0.0")]
89 unsafe impl<T
: ?Sized
+ Send
+ Sync
> Sync
for RwLock
<T
> {}
91 /// RAII structure used to release the shared read access of a lock when
94 /// This structure is created by the [`read`] and [`try_read`] methods on
97 /// [`read`]: RwLock::read
98 /// [`try_read`]: RwLock::try_read
99 #[must_use = "if unused the RwLock will immediately unlock"]
100 #[must_not_suspend = "holding a RwLockReadGuard across suspend \
101 points can cause deadlocks, delays, \
102 and cause Futures to not implement `Send`"]
103 #[stable(feature = "rust1", since = "1.0.0")]
104 #[clippy::has_significant_drop]
105 #[cfg_attr(not(test), rustc_diagnostic_item = "RwLockReadGuard")]
106 pub struct RwLockReadGuard
<'a
, T
: ?Sized
+ 'a
> {
107 // NB: we use a pointer instead of `&'a T` to avoid `noalias` violations, because a
108 // `Ref` argument doesn't hold immutability for its whole scope, only until it drops.
109 // `NonNull` is also covariant over `T`, just like we would have with `&T`. `NonNull`
110 // is preferable over `const* T` to allow for niche optimization.
112 inner_lock
: &'a sys
::RwLock
,
115 #[stable(feature = "rust1", since = "1.0.0")]
116 impl<T
: ?Sized
> !Send
for RwLockReadGuard
<'_
, T
> {}
118 #[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
119 unsafe impl<T
: ?Sized
+ Sync
> Sync
for RwLockReadGuard
<'_
, T
> {}
121 /// RAII structure used to release the exclusive write access of a lock when
124 /// This structure is created by the [`write`] and [`try_write`] methods
127 /// [`write`]: RwLock::write
128 /// [`try_write`]: RwLock::try_write
129 #[must_use = "if unused the RwLock will immediately unlock"]
130 #[must_not_suspend = "holding a RwLockWriteGuard across suspend \
131 points can cause deadlocks, delays, \
132 and cause Future's to not implement `Send`"]
133 #[stable(feature = "rust1", since = "1.0.0")]
134 #[clippy::has_significant_drop]
135 #[cfg_attr(not(test), rustc_diagnostic_item = "RwLockWriteGuard")]
136 pub struct RwLockWriteGuard
<'a
, T
: ?Sized
+ 'a
> {
138 poison
: poison
::Guard
,
141 #[stable(feature = "rust1", since = "1.0.0")]
142 impl<T
: ?Sized
> !Send
for RwLockWriteGuard
<'_
, T
> {}
144 #[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
145 unsafe impl<T
: ?Sized
+ Sync
> Sync
for RwLockWriteGuard
<'_
, T
> {}
148 /// Creates a new instance of an `RwLock<T>` which is unlocked.
153 /// use std::sync::RwLock;
155 /// let lock = RwLock::new(5);
157 #[stable(feature = "rust1", since = "1.0.0")]
158 #[rustc_const_stable(feature = "const_locks", since = "1.63.0")]
160 pub const fn new(t
: T
) -> RwLock
<T
> {
161 RwLock { inner: sys::RwLock::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) }
165 impl<T
: ?Sized
> RwLock
<T
> {
166 /// Locks this `RwLock` with shared read access, blocking the current thread
167 /// until it can be acquired.
169 /// The calling thread will be blocked until there are no more writers which
170 /// hold the lock. There may be other readers currently inside the lock when
171 /// this method returns. This method does not provide any guarantees with
172 /// respect to the ordering of whether contentious readers or writers will
173 /// acquire the lock first.
175 /// Returns an RAII guard which will release this thread's shared access
176 /// once it is dropped.
180 /// This function will return an error if the `RwLock` is poisoned. An
181 /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
182 /// lock. The failure will occur immediately after the lock has been
187 /// This function might panic when called if the lock is already held by the current thread.
192 /// use std::sync::{Arc, RwLock};
195 /// let lock = Arc::new(RwLock::new(1));
196 /// let c_lock = Arc::clone(&lock);
198 /// let n = lock.read().unwrap();
199 /// assert_eq!(*n, 1);
201 /// thread::spawn(move || {
202 /// let r = c_lock.read();
203 /// assert!(r.is_ok());
204 /// }).join().unwrap();
207 #[stable(feature = "rust1", since = "1.0.0")]
208 pub fn read(&self) -> LockResult
<RwLockReadGuard
<'_
, T
>> {
211 RwLockReadGuard
::new(self)
215 /// Attempts to acquire this `RwLock` with shared read access.
217 /// If the access could not be granted at this time, then `Err` is returned.
218 /// Otherwise, an RAII guard is returned which will release the shared access
219 /// when it is dropped.
221 /// This function does not block.
223 /// This function does not provide any guarantees with respect to the ordering
224 /// of whether contentious readers or writers will acquire the lock first.
228 /// This function will return the [`Poisoned`] error if the `RwLock` is
229 /// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
230 /// an exclusive lock. `Poisoned` will only be returned if the lock would
231 /// have otherwise been acquired.
233 /// This function will return the [`WouldBlock`] error if the `RwLock` could
234 /// not be acquired because it was already locked exclusively.
236 /// [`Poisoned`]: TryLockError::Poisoned
237 /// [`WouldBlock`]: TryLockError::WouldBlock
242 /// use std::sync::RwLock;
244 /// let lock = RwLock::new(1);
246 /// match lock.try_read() {
247 /// Ok(n) => assert_eq!(*n, 1),
248 /// Err(_) => unreachable!(),
252 #[stable(feature = "rust1", since = "1.0.0")]
253 pub fn try_read(&self) -> TryLockResult
<RwLockReadGuard
<'_
, T
>> {
255 if self.inner
.try_read() {
256 Ok(RwLockReadGuard
::new(self)?
)
258 Err(TryLockError
::WouldBlock
)
263 /// Locks this `RwLock` with exclusive write access, blocking the current
264 /// thread until it can be acquired.
266 /// This function will not return while other writers or other readers
267 /// currently have access to the lock.
269 /// Returns an RAII guard which will drop the write access of this `RwLock`
274 /// This function will return an error if the `RwLock` is poisoned. An
275 /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
276 /// lock. An error will be returned when the lock is acquired.
280 /// This function might panic when called if the lock is already held by the current thread.
285 /// use std::sync::RwLock;
287 /// let lock = RwLock::new(1);
289 /// let mut n = lock.write().unwrap();
292 /// assert!(lock.try_read().is_err());
295 #[stable(feature = "rust1", since = "1.0.0")]
296 pub fn write(&self) -> LockResult
<RwLockWriteGuard
<'_
, T
>> {
299 RwLockWriteGuard
::new(self)
303 /// Attempts to lock this `RwLock` with exclusive write access.
305 /// If the lock could not be acquired at this time, then `Err` is returned.
306 /// Otherwise, an RAII guard is returned which will release the lock when
309 /// This function does not block.
311 /// This function does not provide any guarantees with respect to the ordering
312 /// of whether contentious readers or writers will acquire the lock first.
316 /// This function will return the [`Poisoned`] error if the `RwLock` is
317 /// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
318 /// an exclusive lock. `Poisoned` will only be returned if the lock would
319 /// have otherwise been acquired.
321 /// This function will return the [`WouldBlock`] error if the `RwLock` could
322 /// not be acquired because it was already locked exclusively.
324 /// [`Poisoned`]: TryLockError::Poisoned
325 /// [`WouldBlock`]: TryLockError::WouldBlock
331 /// use std::sync::RwLock;
333 /// let lock = RwLock::new(1);
335 /// let n = lock.read().unwrap();
336 /// assert_eq!(*n, 1);
338 /// assert!(lock.try_write().is_err());
341 #[stable(feature = "rust1", since = "1.0.0")]
342 pub fn try_write(&self) -> TryLockResult
<RwLockWriteGuard
<'_
, T
>> {
344 if self.inner
.try_write() {
345 Ok(RwLockWriteGuard
::new(self)?
)
347 Err(TryLockError
::WouldBlock
)
352 /// Determines whether the lock is poisoned.
354 /// If another thread is active, the lock can still become poisoned at any
355 /// time. You should not trust a `false` value for program correctness
356 /// without additional synchronization.
361 /// use std::sync::{Arc, RwLock};
364 /// let lock = Arc::new(RwLock::new(0));
365 /// let c_lock = Arc::clone(&lock);
367 /// let _ = thread::spawn(move || {
368 /// let _lock = c_lock.write().unwrap();
369 /// panic!(); // the lock gets poisoned
371 /// assert_eq!(lock.is_poisoned(), true);
374 #[stable(feature = "sync_poison", since = "1.2.0")]
375 pub fn is_poisoned(&self) -> bool
{
379 /// Clear the poisoned state from a lock
381 /// If the lock is poisoned, it will remain poisoned until this function is called. This allows
382 /// recovering from a poisoned state and marking that it has recovered. For example, if the
383 /// value is overwritten by a known-good value, then the lock can be marked as un-poisoned. Or
384 /// possibly, the value could be inspected to determine if it is in a consistent state, and if
385 /// so the poison is removed.
390 /// #![feature(mutex_unpoison)]
392 /// use std::sync::{Arc, RwLock};
395 /// let lock = Arc::new(RwLock::new(0));
396 /// let c_lock = Arc::clone(&lock);
398 /// let _ = thread::spawn(move || {
399 /// let _lock = c_lock.write().unwrap();
400 /// panic!(); // the lock gets poisoned
403 /// assert_eq!(lock.is_poisoned(), true);
404 /// let guard = lock.write().unwrap_or_else(|mut e| {
405 /// **e.get_mut() = 1;
406 /// lock.clear_poison();
409 /// assert_eq!(lock.is_poisoned(), false);
410 /// assert_eq!(*guard, 1);
413 #[unstable(feature = "mutex_unpoison", issue = "96469")]
414 pub fn clear_poison(&self) {
418 /// Consumes this `RwLock`, returning the underlying data.
422 /// This function will return an error if the `RwLock` is poisoned. An
423 /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
424 /// lock. An error will only be returned if the lock would have otherwise
430 /// use std::sync::RwLock;
432 /// let lock = RwLock::new(String::new());
434 /// let mut s = lock.write().unwrap();
435 /// *s = "modified".to_owned();
437 /// assert_eq!(lock.into_inner().unwrap(), "modified");
439 #[stable(feature = "rwlock_into_inner", since = "1.6.0")]
440 pub fn into_inner(self) -> LockResult
<T
>
444 let data
= self.data
.into_inner();
445 poison
::map_result(self.poison
.borrow(), |()| data
)
448 /// Returns a mutable reference to the underlying data.
450 /// Since this call borrows the `RwLock` mutably, no actual locking needs to
451 /// take place -- the mutable borrow statically guarantees no locks exist.
455 /// This function will return an error if the `RwLock` is poisoned. An
456 /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
457 /// lock. An error will only be returned if the lock would have otherwise
463 /// use std::sync::RwLock;
465 /// let mut lock = RwLock::new(0);
466 /// *lock.get_mut().unwrap() = 10;
467 /// assert_eq!(*lock.read().unwrap(), 10);
469 #[stable(feature = "rwlock_get_mut", since = "1.6.0")]
470 pub fn get_mut(&mut self) -> LockResult
<&mut T
> {
471 let data
= self.data
.get_mut();
472 poison
::map_result(self.poison
.borrow(), |()| data
)
476 #[stable(feature = "rust1", since = "1.0.0")]
477 impl<T
: ?Sized
+ fmt
::Debug
> fmt
::Debug
for RwLock
<T
> {
478 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
479 let mut d
= f
.debug_struct("RwLock");
480 match self.try_read() {
482 d
.field("data", &&*guard
);
484 Err(TryLockError
::Poisoned(err
)) => {
485 d
.field("data", &&**err
.get_ref());
487 Err(TryLockError
::WouldBlock
) => {
488 d
.field("data", &format_args
!("<locked>"));
491 d
.field("poisoned", &self.poison
.get());
492 d
.finish_non_exhaustive()
496 #[stable(feature = "rw_lock_default", since = "1.10.0")]
497 impl<T
: Default
> Default
for RwLock
<T
> {
498 /// Creates a new `RwLock<T>`, with the `Default` value for T.
499 fn default() -> RwLock
<T
> {
500 RwLock
::new(Default
::default())
504 #[stable(feature = "rw_lock_from", since = "1.24.0")]
505 impl<T
> From
<T
> for RwLock
<T
> {
506 /// Creates a new instance of an `RwLock<T>` which is unlocked.
507 /// This is equivalent to [`RwLock::new`].
508 fn from(t
: T
) -> Self {
513 impl<'rwlock
, T
: ?Sized
> RwLockReadGuard
<'rwlock
, T
> {
514 /// Create a new instance of `RwLockReadGuard<T>` from a `RwLock<T>`.
515 // SAFETY: if and only if `lock.inner.read()` (or `lock.inner.try_read()`) has been
516 // successfully called from the same thread before instantiating this object.
517 unsafe fn new(lock
: &'rwlock RwLock
<T
>) -> LockResult
<RwLockReadGuard
<'rwlock
, T
>> {
518 poison
::map_result(lock
.poison
.borrow(), |()| RwLockReadGuard
{
519 data
: NonNull
::new_unchecked(lock
.data
.get()),
520 inner_lock
: &lock
.inner
,
525 impl<'rwlock
, T
: ?Sized
> RwLockWriteGuard
<'rwlock
, T
> {
526 /// Create a new instance of `RwLockWriteGuard<T>` from a `RwLock<T>`.
527 // SAFETY: if and only if `lock.inner.write()` (or `lock.inner.try_write()`) has been
528 // successfully called from the same thread before instantiating this object.
529 unsafe fn new(lock
: &'rwlock RwLock
<T
>) -> LockResult
<RwLockWriteGuard
<'rwlock
, T
>> {
530 poison
::map_result(lock
.poison
.guard(), |guard
| RwLockWriteGuard { lock, poison: guard }
)
534 #[stable(feature = "std_debug", since = "1.16.0")]
535 impl<T
: ?Sized
+ fmt
::Debug
> fmt
::Debug
for RwLockReadGuard
<'_
, T
> {
536 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
541 #[stable(feature = "std_guard_impls", since = "1.20.0")]
542 impl<T
: ?Sized
+ fmt
::Display
> fmt
::Display
for RwLockReadGuard
<'_
, T
> {
543 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
548 #[stable(feature = "std_debug", since = "1.16.0")]
549 impl<T
: ?Sized
+ fmt
::Debug
> fmt
::Debug
for RwLockWriteGuard
<'_
, T
> {
550 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
555 #[stable(feature = "std_guard_impls", since = "1.20.0")]
556 impl<T
: ?Sized
+ fmt
::Display
> fmt
::Display
for RwLockWriteGuard
<'_
, T
> {
557 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
562 #[stable(feature = "rust1", since = "1.0.0")]
563 impl<T
: ?Sized
> Deref
for RwLockReadGuard
<'_
, T
> {
566 fn deref(&self) -> &T
{
567 // SAFETY: the conditions of `RwLockGuard::new` were satisfied when created.
568 unsafe { self.data.as_ref() }
572 #[stable(feature = "rust1", since = "1.0.0")]
573 impl<T
: ?Sized
> Deref
for RwLockWriteGuard
<'_
, T
> {
576 fn deref(&self) -> &T
{
577 // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
578 unsafe { &*self.lock.data.get() }
582 #[stable(feature = "rust1", since = "1.0.0")]
583 impl<T
: ?Sized
> DerefMut
for RwLockWriteGuard
<'_
, T
> {
584 fn deref_mut(&mut self) -> &mut T
{
585 // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
586 unsafe { &mut *self.lock.data.get() }
590 #[stable(feature = "rust1", since = "1.0.0")]
591 impl<T
: ?Sized
> Drop
for RwLockReadGuard
<'_
, T
> {
593 // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created.
595 self.inner_lock
.read_unlock();
600 #[stable(feature = "rust1", since = "1.0.0")]
601 impl<T
: ?Sized
> Drop
for RwLockWriteGuard
<'_
, T
> {
603 self.lock
.poison
.done(&self.poison
);
604 // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
606 self.lock
.inner
.write_unlock();