library/std/src/sync/rwlock.rs

   1 #[cfg(all(test, not(target_os = "emscripten")))]
   2 mod tests;
   3
   4 use crate::cell::UnsafeCell;
   5 use crate::fmt;
   6 use crate::mem;
   7 use crate::ops::{Deref, DerefMut};
   8 use crate::ptr;
   9 use crate::sys_common::poison::{self, LockResult, TryLockError, TryLockResult};
  10 use crate::sys_common::rwlock as sys;
  11
  12 /// A reader-writer lock
  13 ///
  14 /// This type of lock allows a number of readers or at most one writer at any
  15 /// point in time. The write portion of this lock typically allows modification
  16 /// of the underlying data (exclusive access) and the read portion of this lock
  17 /// typically allows for read-only access (shared access).
  18 ///
  19 /// In comparison, a [`Mutex`] does not distinguish between readers or writers
  20 /// that acquire the lock, therefore blocking any threads waiting for the lock to
  21 /// become available. An `RwLock` will allow any number of readers to acquire the
  22 /// lock as long as a writer is not holding the lock.
  23 ///
  24 /// The priority policy of the lock is dependent on the underlying operating
  25 /// system's implementation, and this type does not guarantee that any
  26 /// particular policy will be used.
  27 ///
  28 /// The type parameter `T` represents the data that this lock protects. It is
  29 /// required that `T` satisfies [`Send`] to be shared across threads and
  30 /// [`Sync`] to allow concurrent access through readers. The RAII guards
  31 /// returned from the locking methods implement [`Deref`] (and [`DerefMut`]
  32 /// for the `write` methods) to allow access to the content of the lock.
  33 ///
  34 /// # Poisoning
  35 ///
  36 /// An `RwLock`, like [`Mutex`], will become poisoned on a panic. Note, however,
  37 /// that an `RwLock` may only be poisoned if a panic occurs while it is locked
  38 /// exclusively (write mode). If a panic occurs in any reader, then the lock
  39 /// will not be poisoned.
  40 ///
  41 /// # Examples
  42 ///
  43 /// ```
  44 /// use std::sync::RwLock;
  45 ///
  46 /// let lock = RwLock::new(5);
  47 ///
  48 /// // many reader locks can be held at once
  49 /// {
  50 ///     let r1 = lock.read().unwrap();
  51 ///     let r2 = lock.read().unwrap();
  52 ///     assert_eq!(*r1, 5);
  53 ///     assert_eq!(*r2, 5);
  54 /// } // read locks are dropped at this point
  55 ///
  56 /// // only one write lock may be held, however
  57 /// {
  58 ///     let mut w = lock.write().unwrap();
  59 ///     *w += 1;
  60 ///     assert_eq!(*w, 6);
  61 /// } // write lock is dropped here
  62 /// ```
  63 ///
  64 /// [`Mutex`]: super::Mutex
  65 #[stable(feature = "rust1", since = "1.0.0")]
  66 pub struct RwLock<T: ?Sized> {
  67     inner: Box<sys::RWLock>,
  68     poison: poison::Flag,
  69     data: UnsafeCell<T>,
  70 }
  71
  72 #[stable(feature = "rust1", since = "1.0.0")]
  73 unsafe impl<T: ?Sized + Send> Send for RwLock<T> {}
  74 #[stable(feature = "rust1", since = "1.0.0")]
  75 unsafe impl<T: ?Sized + Send + Sync> Sync for RwLock<T> {}
  76
  77 /// RAII structure used to release the shared read access of a lock when
  78 /// dropped.
  79 ///
  80 /// This structure is created by the [`read`] and [`try_read`] methods on
  81 /// [`RwLock`].
  82 ///
  83 /// [`read`]: RwLock::read
  84 /// [`try_read`]: RwLock::try_read
  85 #[must_use = "if unused the RwLock will immediately unlock"]
  86 #[stable(feature = "rust1", since = "1.0.0")]
  87 pub struct RwLockReadGuard<'a, T: ?Sized + 'a> {
  88     lock: &'a RwLock<T>,
  89 }
  90
  91 #[stable(feature = "rust1", since = "1.0.0")]
  92 impl<T: ?Sized> !Send for RwLockReadGuard<'_, T> {}
  93
  94 #[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
  95 unsafe impl<T: ?Sized + Sync> Sync for RwLockReadGuard<'_, T> {}
  96
  97 /// RAII structure used to release the exclusive write access of a lock when
  98 /// dropped.
  99 ///
 100 /// This structure is created by the [`write`] and [`try_write`] methods
 101 /// on [`RwLock`].
 102 ///
 103 /// [`write`]: RwLock::write
 104 /// [`try_write`]: RwLock::try_write
 105 #[must_use = "if unused the RwLock will immediately unlock"]
 106 #[stable(feature = "rust1", since = "1.0.0")]
 107 pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> {
 108     lock: &'a RwLock<T>,
 109     poison: poison::Guard,
 110 }
 111
 112 #[stable(feature = "rust1", since = "1.0.0")]
 113 impl<T: ?Sized> !Send for RwLockWriteGuard<'_, T> {}
 114
 115 #[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
 116 unsafe impl<T: ?Sized + Sync> Sync for RwLockWriteGuard<'_, T> {}
 117
 118 impl<T> RwLock<T> {
 119     /// Creates a new instance of an `RwLock<T>` which is unlocked.
 120     ///
 121     /// # Examples
 122     ///
 123     /// ```
 124     /// use std::sync::RwLock;
 125     ///
 126     /// let lock = RwLock::new(5);
 127     /// ```
 128     #[stable(feature = "rust1", since = "1.0.0")]
 129     pub fn new(t: T) -> RwLock<T> {
 130         RwLock {
 131             inner: box sys::RWLock::new(),
 132             poison: poison::Flag::new(),
 133             data: UnsafeCell::new(t),
 134         }
 135     }
 136 }
 137
 138 impl<T: ?Sized> RwLock<T> {
 139     /// Locks this rwlock with shared read access, blocking the current thread
 140     /// until it can be acquired.
 141     ///
 142     /// The calling thread will be blocked until there are no more writers which
 143     /// hold the lock. There may be other readers currently inside the lock when
 144     /// this method returns. This method does not provide any guarantees with
 145     /// respect to the ordering of whether contentious readers or writers will
 146     /// acquire the lock first.
 147     ///
 148     /// Returns an RAII guard which will release this thread's shared access
 149     /// once it is dropped.
 150     ///
 151     /// # Errors
 152     ///
 153     /// This function will return an error if the RwLock is poisoned. An RwLock
 154     /// is poisoned whenever a writer panics while holding an exclusive lock.
 155     /// The failure will occur immediately after the lock has been acquired.
 156     ///
 157     /// # Panics
 158     ///
 159     /// This function might panic when called if the lock is already held by the current thread.
 160     ///
 161     /// # Examples
 162     ///
 163     /// ```
 164     /// use std::sync::{Arc, RwLock};
 165     /// use std::thread;
 166     ///
 167     /// let lock = Arc::new(RwLock::new(1));
 168     /// let c_lock = Arc::clone(&lock);
 169     ///
 170     /// let n = lock.read().unwrap();
 171     /// assert_eq!(*n, 1);
 172     ///
 173     /// thread::spawn(move || {
 174     ///     let r = c_lock.read();
 175     ///     assert!(r.is_ok());
 176     /// }).join().unwrap();
 177     /// ```
 178     #[inline]
 179     #[stable(feature = "rust1", since = "1.0.0")]
 180     pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>> {
 181         unsafe {
 182             self.inner.read();
 183             RwLockReadGuard::new(self)
 184         }
 185     }
 186
 187     /// Attempts to acquire this rwlock with shared read access.
 188     ///
 189     /// If the access could not be granted at this time, then `Err` is returned.
 190     /// Otherwise, an RAII guard is returned which will release the shared access
 191     /// when it is dropped.
 192     ///
 193     /// This function does not block.
 194     ///
 195     /// This function does not provide any guarantees with respect to the ordering
 196     /// of whether contentious readers or writers will acquire the lock first.
 197     ///
 198     /// # Errors
 199     ///
 200     /// This function will return an error if the RwLock is poisoned. An RwLock
 201     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 202     /// error will only be returned if the lock would have otherwise been
 203     /// acquired.
 204     ///
 205     /// # Examples
 206     ///
 207     /// ```
 208     /// use std::sync::RwLock;
 209     ///
 210     /// let lock = RwLock::new(1);
 211     ///
 212     /// match lock.try_read() {
 213     ///     Ok(n) => assert_eq!(*n, 1),
 214     ///     Err(_) => unreachable!(),
 215     /// };
 216     /// ```
 217     #[inline]
 218     #[stable(feature = "rust1", since = "1.0.0")]
 219     pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>> {
 220         unsafe {
 221             if self.inner.try_read() {
 222                 Ok(RwLockReadGuard::new(self)?)
 223             } else {
 224                 Err(TryLockError::WouldBlock)
 225             }
 226         }
 227     }
 228
 229     /// Locks this rwlock with exclusive write access, blocking the current
 230     /// thread until it can be acquired.
 231     ///
 232     /// This function will not return while other writers or other readers
 233     /// currently have access to the lock.
 234     ///
 235     /// Returns an RAII guard which will drop the write access of this rwlock
 236     /// when dropped.
 237     ///
 238     /// # Errors
 239     ///
 240     /// This function will return an error if the RwLock is poisoned. An RwLock
 241     /// is poisoned whenever a writer panics while holding an exclusive lock.
 242     /// An error will be returned when the lock is acquired.
 243     ///
 244     /// # Panics
 245     ///
 246     /// This function might panic when called if the lock is already held by the current thread.
 247     ///
 248     /// # Examples
 249     ///
 250     /// ```
 251     /// use std::sync::RwLock;
 252     ///
 253     /// let lock = RwLock::new(1);
 254     ///
 255     /// let mut n = lock.write().unwrap();
 256     /// *n = 2;
 257     ///
 258     /// assert!(lock.try_read().is_err());
 259     /// ```
 260     #[inline]
 261     #[stable(feature = "rust1", since = "1.0.0")]
 262     pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>> {
 263         unsafe {
 264             self.inner.write();
 265             RwLockWriteGuard::new(self)
 266         }
 267     }
 268
 269     /// Attempts to lock this rwlock with exclusive write access.
 270     ///
 271     /// If the lock could not be acquired at this time, then `Err` is returned.
 272     /// Otherwise, an RAII guard is returned which will release the lock when
 273     /// it is dropped.
 274     ///
 275     /// This function does not block.
 276     ///
 277     /// This function does not provide any guarantees with respect to the ordering
 278     /// of whether contentious readers or writers will acquire the lock first.
 279     ///
 280     /// # Errors
 281     ///
 282     /// This function will return an error if the RwLock is poisoned. An RwLock
 283     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 284     /// error will only be returned if the lock would have otherwise been
 285     /// acquired.
 286     ///
 287     /// # Examples
 288     ///
 289     /// ```
 290     /// use std::sync::RwLock;
 291     ///
 292     /// let lock = RwLock::new(1);
 293     ///
 294     /// let n = lock.read().unwrap();
 295     /// assert_eq!(*n, 1);
 296     ///
 297     /// assert!(lock.try_write().is_err());
 298     /// ```
 299     #[inline]
 300     #[stable(feature = "rust1", since = "1.0.0")]
 301     pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>> {
 302         unsafe {
 303             if self.inner.try_write() {
 304                 Ok(RwLockWriteGuard::new(self)?)
 305             } else {
 306                 Err(TryLockError::WouldBlock)
 307             }
 308         }
 309     }
 310
 311     /// Determines whether the lock is poisoned.
 312     ///
 313     /// If another thread is active, the lock can still become poisoned at any
 314     /// time. You should not trust a `false` value for program correctness
 315     /// without additional synchronization.
 316     ///
 317     /// # Examples
 318     ///
 319     /// ```
 320     /// use std::sync::{Arc, RwLock};
 321     /// use std::thread;
 322     ///
 323     /// let lock = Arc::new(RwLock::new(0));
 324     /// let c_lock = Arc::clone(&lock);
 325     ///
 326     /// let _ = thread::spawn(move || {
 327     ///     let _lock = c_lock.write().unwrap();
 328     ///     panic!(); // the lock gets poisoned
 329     /// }).join();
 330     /// assert_eq!(lock.is_poisoned(), true);
 331     /// ```
 332     #[inline]
 333     #[stable(feature = "sync_poison", since = "1.2.0")]
 334     pub fn is_poisoned(&self) -> bool {
 335         self.poison.get()
 336     }
 337
 338     /// Consumes this `RwLock`, returning the underlying data.
 339     ///
 340     /// # Errors
 341     ///
 342     /// This function will return an error if the RwLock is poisoned. An RwLock
 343     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 344     /// error will only be returned if the lock would have otherwise been
 345     /// acquired.
 346     ///
 347     /// # Examples
 348     ///
 349     /// ```
 350     /// use std::sync::RwLock;
 351     ///
 352     /// let lock = RwLock::new(String::new());
 353     /// {
 354     ///     let mut s = lock.write().unwrap();
 355     ///     *s = "modified".to_owned();
 356     /// }
 357     /// assert_eq!(lock.into_inner().unwrap(), "modified");
 358     /// ```
 359     #[stable(feature = "rwlock_into_inner", since = "1.6.0")]
 360     pub fn into_inner(self) -> LockResult<T>
 361     where
 362         T: Sized,
 363     {
 364         // We know statically that there are no outstanding references to
 365         // `self` so there's no need to lock the inner lock.
 366         //
 367         // To get the inner value, we'd like to call `data.into_inner()`,
 368         // but because `RwLock` impl-s `Drop`, we can't move out of it, so
 369         // we'll have to destructure it manually instead.
 370         unsafe {
 371             // Like `let RwLock { inner, poison, data } = self`.
 372             let (inner, poison, data) = {
 373                 let RwLock { ref inner, ref poison, ref data } = self;
 374                 (ptr::read(inner), ptr::read(poison), ptr::read(data))
 375             };
 376             mem::forget(self);
 377             inner.destroy(); // Keep in sync with the `Drop` impl.
 378             drop(inner);
 379
 380             poison::map_result(poison.borrow(), |_| data.into_inner())
 381         }
 382     }
 383
 384     /// Returns a mutable reference to the underlying data.
 385     ///
 386     /// Since this call borrows the `RwLock` mutably, no actual locking needs to
 387     /// take place -- the mutable borrow statically guarantees no locks exist.
 388     ///
 389     /// # Errors
 390     ///
 391     /// This function will return an error if the RwLock is poisoned. An RwLock
 392     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 393     /// error will only be returned if the lock would have otherwise been
 394     /// acquired.
 395     ///
 396     /// # Examples
 397     ///
 398     /// ```
 399     /// use std::sync::RwLock;
 400     ///
 401     /// let mut lock = RwLock::new(0);
 402     /// *lock.get_mut().unwrap() = 10;
 403     /// assert_eq!(*lock.read().unwrap(), 10);
 404     /// ```
 405     #[stable(feature = "rwlock_get_mut", since = "1.6.0")]
 406     pub fn get_mut(&mut self) -> LockResult<&mut T> {
 407         let data = self.data.get_mut();
 408         poison::map_result(self.poison.borrow(), |_| data)
 409     }
 410 }
 411
 412 #[stable(feature = "rust1", since = "1.0.0")]
 413 unsafe impl<#[may_dangle] T: ?Sized> Drop for RwLock<T> {
 414     fn drop(&mut self) {
 415         // IMPORTANT: This code needs to be kept in sync with `RwLock::into_inner`.
 416         unsafe { self.inner.destroy() }
 417     }
 418 }
 419
 420 #[stable(feature = "rust1", since = "1.0.0")]
 421 impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
 422     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 423         match self.try_read() {
 424             Ok(guard) => f.debug_struct("RwLock").field("data", &&*guard).finish(),
 425             Err(TryLockError::Poisoned(err)) => {
 426                 f.debug_struct("RwLock").field("data", &&**err.get_ref()).finish()
 427             }
 428             Err(TryLockError::WouldBlock) => {
 429                 struct LockedPlaceholder;
 430                 impl fmt::Debug for LockedPlaceholder {
 431                     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 432                         f.write_str("<locked>")
 433                     }
 434                 }
 435
 436                 f.debug_struct("RwLock").field("data", &LockedPlaceholder).finish()
 437             }
 438         }
 439     }
 440 }
 441
 442 #[stable(feature = "rw_lock_default", since = "1.10.0")]
 443 impl<T: Default> Default for RwLock<T> {
 444     /// Creates a new `RwLock<T>`, with the `Default` value for T.
 445     fn default() -> RwLock<T> {
 446         RwLock::new(Default::default())
 447     }
 448 }
 449
 450 #[stable(feature = "rw_lock_from", since = "1.24.0")]
 451 impl<T> From<T> for RwLock<T> {
 452     /// Creates a new instance of an `RwLock<T>` which is unlocked.
 453     /// This is equivalent to [`RwLock::new`].
 454     fn from(t: T) -> Self {
 455         RwLock::new(t)
 456     }
 457 }
 458
 459 impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
 460     unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockReadGuard<'rwlock, T>> {
 461         poison::map_result(lock.poison.borrow(), |_| RwLockReadGuard { lock })
 462     }
 463 }
 464
 465 impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
 466     unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockWriteGuard<'rwlock, T>> {
 467         poison::map_result(lock.poison.borrow(), |guard| RwLockWriteGuard { lock, poison: guard })
 468     }
 469 }
 470
 471 #[stable(feature = "std_debug", since = "1.16.0")]
 472 impl<T: fmt::Debug> fmt::Debug for RwLockReadGuard<'_, T> {
 473     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 474         f.debug_struct("RwLockReadGuard").field("lock", &self.lock).finish()
 475     }
 476 }
 477
 478 #[stable(feature = "std_guard_impls", since = "1.20.0")]
 479 impl<T: ?Sized + fmt::Display> fmt::Display for RwLockReadGuard<'_, T> {
 480     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 481         (**self).fmt(f)
 482     }
 483 }
 484
 485 #[stable(feature = "std_debug", since = "1.16.0")]
 486 impl<T: fmt::Debug> fmt::Debug for RwLockWriteGuard<'_, T> {
 487     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 488         f.debug_struct("RwLockWriteGuard").field("lock", &self.lock).finish()
 489     }
 490 }
 491
 492 #[stable(feature = "std_guard_impls", since = "1.20.0")]
 493 impl<T: ?Sized + fmt::Display> fmt::Display for RwLockWriteGuard<'_, T> {
 494     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
 495         (**self).fmt(f)
 496     }
 497 }
 498
 499 #[stable(feature = "rust1", since = "1.0.0")]
 500 impl<T: ?Sized> Deref for RwLockReadGuard<'_, T> {
 501     type Target = T;
 502
 503     fn deref(&self) -> &T {
 504         unsafe { &*self.lock.data.get() }
 505     }
 506 }
 507
 508 #[stable(feature = "rust1", since = "1.0.0")]
 509 impl<T: ?Sized> Deref for RwLockWriteGuard<'_, T> {
 510     type Target = T;
 511
 512     fn deref(&self) -> &T {
 513         unsafe { &*self.lock.data.get() }
 514     }
 515 }
 516
 517 #[stable(feature = "rust1", since = "1.0.0")]
 518 impl<T: ?Sized> DerefMut for RwLockWriteGuard<'_, T> {
 519     fn deref_mut(&mut self) -> &mut T {
 520         unsafe { &mut *self.lock.data.get() }
 521     }
 522 }
 523
 524 #[stable(feature = "rust1", since = "1.0.0")]
 525 impl<T: ?Sized> Drop for RwLockReadGuard<'_, T> {
 526     fn drop(&mut self) {
 527         unsafe {
 528             self.lock.inner.read_unlock();
 529         }
 530     }
 531 }
 532
 533 #[stable(feature = "rust1", since = "1.0.0")]
 534 impl<T: ?Sized> Drop for RwLockWriteGuard<'_, T> {
 535     fn drop(&mut self) {
 536         self.lock.poison.done(&self.poison);
 537         unsafe {
 538             self.lock.inner.write_unlock();
 539         }
 540     }
 541 }