1#[cfg(all(test, not(target_os = "emscripten")))]
2mod tests;
3
4use crate::cell::UnsafeCell;
5use crate::fmt;
6use crate::ops::{Deref, DerefMut};
7use crate::ptr::NonNull;
8use crate::sync::{poison, LockResult, TryLockError, TryLockResult};
9use crate::sys::locks as sys;
10
11/// A reader-writer lock
12///
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).
17///
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.
22///
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
27/// `read`, e.g.:
28///
29/// <details><summary>Potential deadlock example</summary>
30///
31/// ```text
32/// // Thread 1 | // Thread 2
33/// let _rg = lock.read(); |
34/// | // will block
35/// | let _wg = lock.write();
36/// // may deadlock |
37/// let _rg = lock.read(); |
38/// ```
39/// </details>
40///
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.
46///
47/// # Poisoning
48///
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.
53///
54/// # Examples
55///
56/// ```
57/// use std::sync::RwLock;
58///
59/// let lock = RwLock::new(5);
60///
61/// // many reader locks can be held at once
62/// {
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
68///
69/// // only one write lock may be held, however
70/// {
71/// let mut w = lock.write().unwrap();
72/// *w += 1;
73/// assert_eq!(*w, 6);
74/// } // write lock is dropped here
75/// ```
76///
77/// [`Mutex`]: super::Mutex
78#[stable(feature = "rust1", since = "1.0.0")]
79#[cfg_attr(not(test), rustc_diagnostic_item = "RwLock")]
80pub struct RwLock<T: ?Sized> {
81 inner: sys::RwLock,
82 poison: poison::Flag,
83 data: UnsafeCell<T>,
84}
85
86#[stable(feature = "rust1", since = "1.0.0")]
87unsafe impl<T: ?Sized + Send> Send for RwLock<T> {}
88#[stable(feature = "rust1", since = "1.0.0")]
89unsafe impl<T: ?Sized + Send + Sync> Sync for RwLock<T> {}
90
91/// RAII structure used to release the shared read access of a lock when
92/// dropped.
93///
94/// This structure is created by the [`read`] and [`try_read`] methods on
95/// [`RwLock`].
96///
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")]
106pub 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.
111 data: NonNull<T>,
112 inner_lock: &'a sys::RwLock,
113}
114
115#[stable(feature = "rust1", since = "1.0.0")]
116impl<T: ?Sized> !Send for RwLockReadGuard<'_, T> {}
117
118#[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
119unsafe impl<T: ?Sized + Sync> Sync for RwLockReadGuard<'_, T> {}
120
121/// RAII structure used to release the exclusive write access of a lock when
122/// dropped.
123///
124/// This structure is created by the [`write`] and [`try_write`] methods
125/// on [`RwLock`].
126///
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")]
136pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> {
137 lock: &'a RwLock<T>,
138 poison: poison::Guard,
139}
140
141#[stable(feature = "rust1", since = "1.0.0")]
142impl<T: ?Sized> !Send for RwLockWriteGuard<'_, T> {}
143
144#[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
145unsafe impl<T: ?Sized + Sync> Sync for RwLockWriteGuard<'_, T> {}
146
147impl<T> RwLock<T> {
148 /// Creates a new instance of an `RwLock<T>` which is unlocked.
149 ///
150 /// # Examples
151 ///
152 /// ```
153 /// use std::sync::RwLock;
154 ///
155 /// let lock = RwLock::new(5);
156 /// ```
157 #[stable(feature = "rust1", since = "1.0.0")]
158 #[rustc_const_stable(feature = "const_locks", since = "1.63.0")]
159 #[inline]
160 pub const fn new(t: T) -> RwLock<T> {
161 RwLock { inner: sys::RwLock::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) }
162 }
163}
164
165impl<T: ?Sized> RwLock<T> {
166 /// Locks this `RwLock` with shared read access, blocking the current thread
167 /// until it can be acquired.
168 ///
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.
174 ///
175 /// Returns an RAII guard which will release this thread's shared access
176 /// once it is dropped.
177 ///
178 /// # Errors
179 ///
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
183 /// acquired.
184 ///
185 /// # Panics
186 ///
187 /// This function might panic when called if the lock is already held by the current thread.
188 ///
189 /// # Examples
190 ///
191 /// ```
192 /// use std::sync::{Arc, RwLock};
193 /// use std::thread;
194 ///
195 /// let lock = Arc::new(RwLock::new(1));
196 /// let c_lock = Arc::clone(&lock);
197 ///
198 /// let n = lock.read().unwrap();
199 /// assert_eq!(*n, 1);
200 ///
201 /// thread::spawn(move || {
202 /// let r = c_lock.read();
203 /// assert!(r.is_ok());
204 /// }).join().unwrap();
205 /// ```
206 #[inline]
207 #[stable(feature = "rust1", since = "1.0.0")]
208 pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>> {
209 unsafe {
210 self.inner.read();
211 RwLockReadGuard::new(self)
212 }
213 }
214
215 /// Attempts to acquire this `RwLock` with shared read access.
216 ///
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.
220 ///
221 /// This function does not block.
222 ///
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.
225 ///
226 /// # Errors
227 ///
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.
232 ///
233 /// This function will return the [`WouldBlock`] error if the `RwLock` could
234 /// not be acquired because it was already locked exclusively.
235 ///
236 /// [`Poisoned`]: TryLockError::Poisoned
237 /// [`WouldBlock`]: TryLockError::WouldBlock
238 ///
239 /// # Examples
240 ///
241 /// ```
242 /// use std::sync::RwLock;
243 ///
244 /// let lock = RwLock::new(1);
245 ///
246 /// match lock.try_read() {
247 /// Ok(n) => assert_eq!(*n, 1),
248 /// Err(_) => unreachable!(),
249 /// };
250 /// ```
251 #[inline]
252 #[stable(feature = "rust1", since = "1.0.0")]
253 pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>> {
254 unsafe {
255 if self.inner.try_read() {
256 Ok(RwLockReadGuard::new(self)?)
257 } else {
258 Err(TryLockError::WouldBlock)
259 }
260 }
261 }
262
263 /// Locks this `RwLock` with exclusive write access, blocking the current
264 /// thread until it can be acquired.
265 ///
266 /// This function will not return while other writers or other readers
267 /// currently have access to the lock.
268 ///
269 /// Returns an RAII guard which will drop the write access of this `RwLock`
270 /// when dropped.
271 ///
272 /// # Errors
273 ///
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.
277 ///
278 /// # Panics
279 ///
280 /// This function might panic when called if the lock is already held by the current thread.
281 ///
282 /// # Examples
283 ///
284 /// ```
285 /// use std::sync::RwLock;
286 ///
287 /// let lock = RwLock::new(1);
288 ///
289 /// let mut n = lock.write().unwrap();
290 /// *n = 2;
291 ///
292 /// assert!(lock.try_read().is_err());
293 /// ```
294 #[inline]
295 #[stable(feature = "rust1", since = "1.0.0")]
296 pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>> {
297 unsafe {
298 self.inner.write();
299 RwLockWriteGuard::new(self)
300 }
301 }
302
303 /// Attempts to lock this `RwLock` with exclusive write access.
304 ///
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
307 /// it is dropped.
308 ///
309 /// This function does not block.
310 ///
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.
313 ///
314 /// # Errors
315 ///
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.
320 ///
321 /// This function will return the [`WouldBlock`] error if the `RwLock` could
322 /// not be acquired because it was already locked exclusively.
323 ///
324 /// [`Poisoned`]: TryLockError::Poisoned
325 /// [`WouldBlock`]: TryLockError::WouldBlock
326 ///
327 ///
328 /// # Examples
329 ///
330 /// ```
331 /// use std::sync::RwLock;
332 ///
333 /// let lock = RwLock::new(1);
334 ///
335 /// let n = lock.read().unwrap();
336 /// assert_eq!(*n, 1);
337 ///
338 /// assert!(lock.try_write().is_err());
339 /// ```
340 #[inline]
341 #[stable(feature = "rust1", since = "1.0.0")]
342 pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>> {
343 unsafe {
344 if self.inner.try_write() {
345 Ok(RwLockWriteGuard::new(self)?)
346 } else {
347 Err(TryLockError::WouldBlock)
348 }
349 }
350 }
351
352 /// Determines whether the lock is poisoned.
353 ///
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.
357 ///
358 /// # Examples
359 ///
360 /// ```
361 /// use std::sync::{Arc, RwLock};
362 /// use std::thread;
363 ///
364 /// let lock = Arc::new(RwLock::new(0));
365 /// let c_lock = Arc::clone(&lock);
366 ///
367 /// let _ = thread::spawn(move || {
368 /// let _lock = c_lock.write().unwrap();
369 /// panic!(); // the lock gets poisoned
370 /// }).join();
371 /// assert_eq!(lock.is_poisoned(), true);
372 /// ```
373 #[inline]
374 #[stable(feature = "sync_poison", since = "1.2.0")]
375 pub fn is_poisoned(&self) -> bool {
376 self.poison.get()
377 }
378
379 /// Clear the poisoned state from a lock
380 ///
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.
386 ///
387 /// # Examples
388 ///
389 /// ```
390 /// use std::sync::{Arc, RwLock};
391 /// use std::thread;
392 ///
393 /// let lock = Arc::new(RwLock::new(0));
394 /// let c_lock = Arc::clone(&lock);
395 ///
396 /// let _ = thread::spawn(move || {
397 /// let _lock = c_lock.write().unwrap();
398 /// panic!(); // the lock gets poisoned
399 /// }).join();
400 ///
401 /// assert_eq!(lock.is_poisoned(), true);
402 /// let guard = lock.write().unwrap_or_else(|mut e| {
403 /// **e.get_mut() = 1;
404 /// lock.clear_poison();
405 /// e.into_inner()
406 /// });
407 /// assert_eq!(lock.is_poisoned(), false);
408 /// assert_eq!(*guard, 1);
409 /// ```
410 #[inline]
411 #[stable(feature = "mutex_unpoison", since = "1.77.0")]
412 pub fn clear_poison(&self) {
413 self.poison.clear();
414 }
415
416 /// Consumes this `RwLock`, returning the underlying data.
417 ///
418 /// # Errors
419 ///
420 /// This function will return an error if the `RwLock` is poisoned. An
421 /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
422 /// lock. An error will only be returned if the lock would have otherwise
423 /// been acquired.
424 ///
425 /// # Examples
426 ///
427 /// ```
428 /// use std::sync::RwLock;
429 ///
430 /// let lock = RwLock::new(String::new());
431 /// {
432 /// let mut s = lock.write().unwrap();
433 /// *s = "modified".to_owned();
434 /// }
435 /// assert_eq!(lock.into_inner().unwrap(), "modified");
436 /// ```
437 #[stable(feature = "rwlock_into_inner", since = "1.6.0")]
438 pub fn into_inner(self) -> LockResult<T>
439 where
440 T: Sized,
441 {
442 let data = self.data.into_inner();
443 poison::map_result(self.poison.borrow(), |()| data)
444 }
445
446 /// Returns a mutable reference to the underlying data.
447 ///
448 /// Since this call borrows the `RwLock` mutably, no actual locking needs to
449 /// take place -- the mutable borrow statically guarantees no locks exist.
450 ///
451 /// # Errors
452 ///
453 /// This function will return an error if the `RwLock` is poisoned. An
454 /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
455 /// lock. An error will only be returned if the lock would have otherwise
456 /// been acquired.
457 ///
458 /// # Examples
459 ///
460 /// ```
461 /// use std::sync::RwLock;
462 ///
463 /// let mut lock = RwLock::new(0);
464 /// *lock.get_mut().unwrap() = 10;
465 /// assert_eq!(*lock.read().unwrap(), 10);
466 /// ```
467 #[stable(feature = "rwlock_get_mut", since = "1.6.0")]
468 pub fn get_mut(&mut self) -> LockResult<&mut T> {
469 let data = self.data.get_mut();
470 poison::map_result(self.poison.borrow(), |()| data)
471 }
472}
473
474#[stable(feature = "rust1", since = "1.0.0")]
475impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
476 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
477 let mut d: DebugStruct<'_, '_> = f.debug_struct(name:"RwLock");
478 match self.try_read() {
479 Ok(guard: RwLockReadGuard<'_, T>) => {
480 d.field(name:"data", &&*guard);
481 }
482 Err(TryLockError::Poisoned(err: PoisonError>)) => {
483 d.field(name:"data", &&**err.get_ref());
484 }
485 Err(TryLockError::WouldBlock) => {
486 d.field(name:"data", &format_args!("<locked>"));
487 }
488 }
489 d.field(name:"poisoned", &self.poison.get());
490 d.finish_non_exhaustive()
491 }
492}
493
494#[stable(feature = "rw_lock_default", since = "1.10.0")]
495impl<T: Default> Default for RwLock<T> {
496 /// Creates a new `RwLock<T>`, with the `Default` value for T.
497 fn default() -> RwLock<T> {
498 RwLock::new(Default::default())
499 }
500}
501
502#[stable(feature = "rw_lock_from", since = "1.24.0")]
503impl<T> From<T> for RwLock<T> {
504 /// Creates a new instance of an `RwLock<T>` which is unlocked.
505 /// This is equivalent to [`RwLock::new`].
506 fn from(t: T) -> Self {
507 RwLock::new(t)
508 }
509}
510
511impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
512 /// Create a new instance of `RwLockReadGuard<T>` from a `RwLock<T>`.
513 // SAFETY: if and only if `lock.inner.read()` (or `lock.inner.try_read()`) has been
514 // successfully called from the same thread before instantiating this object.
515 unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockReadGuard<'rwlock, T>> {
516 poison::map_result(result:lock.poison.borrow(), |()| RwLockReadGuard {
517 data: NonNull::new_unchecked(ptr:lock.data.get()),
518 inner_lock: &lock.inner,
519 })
520 }
521}
522
523impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
524 /// Create a new instance of `RwLockWriteGuard<T>` from a `RwLock<T>`.
525 // SAFETY: if and only if `lock.inner.write()` (or `lock.inner.try_write()`) has been
526 // successfully called from the same thread before instantiating this object.
527 unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockWriteGuard<'rwlock, T>> {
528 poison::map_result(result:lock.poison.guard(), |guard: Guard| RwLockWriteGuard { lock, poison: guard })
529 }
530}
531
532#[stable(feature = "std_debug", since = "1.16.0")]
533impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLockReadGuard<'_, T> {
534 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
535 (**self).fmt(f)
536 }
537}
538
539#[stable(feature = "std_guard_impls", since = "1.20.0")]
540impl<T: ?Sized + fmt::Display> fmt::Display for RwLockReadGuard<'_, T> {
541 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
542 (**self).fmt(f)
543 }
544}
545
546#[stable(feature = "std_debug", since = "1.16.0")]
547impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLockWriteGuard<'_, T> {
548 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
549 (**self).fmt(f)
550 }
551}
552
553#[stable(feature = "std_guard_impls", since = "1.20.0")]
554impl<T: ?Sized + fmt::Display> fmt::Display for RwLockWriteGuard<'_, T> {
555 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
556 (**self).fmt(f)
557 }
558}
559
560#[stable(feature = "rust1", since = "1.0.0")]
561impl<T: ?Sized> Deref for RwLockReadGuard<'_, T> {
562 type Target = T;
563
564 fn deref(&self) -> &T {
565 // SAFETY: the conditions of `RwLockGuard::new` were satisfied when created.
566 unsafe { self.data.as_ref() }
567 }
568}
569
570#[stable(feature = "rust1", since = "1.0.0")]
571impl<T: ?Sized> Deref for RwLockWriteGuard<'_, T> {
572 type Target = T;
573
574 fn deref(&self) -> &T {
575 // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
576 unsafe { &*self.lock.data.get() }
577 }
578}
579
580#[stable(feature = "rust1", since = "1.0.0")]
581impl<T: ?Sized> DerefMut for RwLockWriteGuard<'_, T> {
582 fn deref_mut(&mut self) -> &mut T {
583 // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
584 unsafe { &mut *self.lock.data.get() }
585 }
586}
587
588#[stable(feature = "rust1", since = "1.0.0")]
589impl<T: ?Sized> Drop for RwLockReadGuard<'_, T> {
590 fn drop(&mut self) {
591 // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created.
592 unsafe {
593 self.inner_lock.read_unlock();
594 }
595 }
596}
597
598#[stable(feature = "rust1", since = "1.0.0")]
599impl<T: ?Sized> Drop for RwLockWriteGuard<'_, T> {
600 fn drop(&mut self) {
601 self.lock.poison.done(&self.poison);
602 // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
603 unsafe {
604 self.lock.inner.write_unlock();
605 }
606 }
607}
608