armv7a/usr/lib/rustlib/src/rust/library/std/src/sync/rwlock.rs - manifest_repos/toolchain - Git at Google

 #[cfg(all(test, not(target_os = "emscripten")))]
 mod tests;

 use crate::cell::UnsafeCell;
 use crate::fmt;
 use crate::ops::{Deref, DerefMut};
 use crate::ptr::NonNull;
 use crate::sync::{poison, LockResult, TryLockError, TryLockResult};
 use crate::sys::locks as sys;

 /// 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).
 ///
 /// In comparison, a [`Mutex`] does not distinguish between readers or writers
 /// that acquire the lock, therefore blocking any threads waiting for the lock to
 /// become available. An `RwLock` will allow any number of readers to acquire the
 /// lock as long as a writer is not holding the lock.
 ///
 /// The priority policy of the lock is dependent on the underlying operating
 /// system's implementation, and this type does not guarantee that any
 /// particular policy will be used. In particular, a writer which is waiting to
 /// acquire the lock in `write` might or might not block concurrent calls to
 /// `read`, e.g.:
 ///
 /// <details><summary>Potential deadlock example</summary>
 ///
 /// ```text
 /// // Thread 1             |  // Thread 2
 /// let _rg = lock.read();  |
 ///                         |  // will block
 ///                         |  let _wg = lock.write();
 /// // may deadlock         |
 /// let _rg = lock.read();  |
 /// ```
 /// </details>
 ///
 /// 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 content of the lock.
 ///
 /// # Poisoning
 ///
 /// An `RwLock`, like [`Mutex`], will become poisoned on a panic. Note, however,
 /// that an `RwLock` may only be poisoned if a panic occurs while it is locked
 /// exclusively (write mode). If a panic occurs in any reader, then the lock
 /// will not be poisoned.
 ///
 /// # Examples
 ///
 /// ```
 /// use std::sync::RwLock;
 ///
 /// let lock = RwLock::new(5);
 ///
 /// // many reader locks can be held at once
 /// {
 ///     let r1 = lock.read().unwrap();
 ///     let r2 = 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
 /// {
 ///     let mut w = lock.write().unwrap();
 ///     *w += 1;
 ///     assert_eq!(*w, 6);
 /// } // write lock is dropped here
 /// ```
 ///
 /// [`Mutex`]: super::Mutex
 #[stable(feature = "rust1", since = "1.0.0")]
 #[cfg_attr(not(test), rustc_diagnostic_item = "RwLock")]
 pub struct RwLock<T: ?Sized> {
     inner: sys::RwLock,
     poison: poison::Flag,
     data: UnsafeCell<T>,
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 unsafe impl<T: ?Sized + Send> Send for RwLock<T> {}
 #[stable(feature = "rust1", since = "1.0.0")]
 unsafe impl<T: ?Sized + Send + Sync> Sync for RwLock<T> {}

 /// RAII structure used to release the shared read access of a lock when
 /// dropped.
 ///
 /// This structure is created by the [`read`] and [`try_read`] methods on
 /// [`RwLock`].
 ///
 /// [`read`]: RwLock::read
 /// [`try_read`]: RwLock::try_read
 #[must_use = "if unused the RwLock will immediately unlock"]
 #[must_not_suspend = "holding a RwLockReadGuard across suspend \
                       points can cause deadlocks, delays, \
                       and cause Futures to not implement `Send`"]
 #[stable(feature = "rust1", since = "1.0.0")]
 #[clippy::has_significant_drop]
 #[cfg_attr(not(test), rustc_diagnostic_item = "RwLockReadGuard")]
 pub struct RwLockReadGuard<'a, T: ?Sized + 'a> {
     // NB: we use a pointer instead of `&'a T` to avoid `noalias` violations, because a
     // `Ref` argument doesn't hold immutability for its whole scope, only until it drops.
     // `NonNull` is also covariant over `T`, just like we would have with `&T`. `NonNull`
     // is preferable over `const* T` to allow for niche optimization.
     data: NonNull<T>,
     inner_lock: &'a sys::RwLock,
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> !Send for RwLockReadGuard<'_, T> {}

 #[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
 unsafe impl<T: ?Sized + Sync> Sync for RwLockReadGuard<'_, T> {}

 /// RAII structure used to release the exclusive write access of a lock when
 /// dropped.
 ///
 /// This structure is created by the [`write`] and [`try_write`] methods
 /// on [`RwLock`].
 ///
 /// [`write`]: RwLock::write
 /// [`try_write`]: RwLock::try_write
 #[must_use = "if unused the RwLock will immediately unlock"]
 #[must_not_suspend = "holding a RwLockWriteGuard across suspend \
                       points can cause deadlocks, delays, \
                       and cause Future's to not implement `Send`"]
 #[stable(feature = "rust1", since = "1.0.0")]
 #[clippy::has_significant_drop]
 #[cfg_attr(not(test), rustc_diagnostic_item = "RwLockWriteGuard")]
 pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> {
     lock: &'a RwLock<T>,
     poison: poison::Guard,
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> !Send for RwLockWriteGuard<'_, T> {}

 #[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
 unsafe impl<T: ?Sized + Sync> Sync for RwLockWriteGuard<'_, T> {}

 impl<T> RwLock<T> {
     /// Creates a new instance of an `RwLock<T>` which is unlocked.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::RwLock;
     ///
     /// let lock = RwLock::new(5);
     /// ```
     #[stable(feature = "rust1", since = "1.0.0")]
     #[rustc_const_stable(feature = "const_locks", since = "1.63.0")]
     #[inline]
     pub const fn new(t: T) -> RwLock<T> {
         RwLock { inner: sys::RwLock::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) }
     }
 }

 impl<T: ?Sized> RwLock<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. This method does not provide any guarantees with
     /// respect to the ordering of whether contentious readers or writers will
     /// acquire the lock first.
     ///
     /// Returns an RAII guard which will release this thread's shared access
     /// once it is dropped.
     ///
     /// # Errors
     ///
     /// This function will return an error if the `RwLock` is poisoned. An
     /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
     /// lock. The failure will occur immediately after the lock has been
     /// acquired.
     ///
     /// # Panics
     ///
     /// This function might panic when called if the lock is already held by the current thread.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::{Arc, RwLock};
     /// use std::thread;
     ///
     /// let lock = Arc::new(RwLock::new(1));
     /// let c_lock = Arc::clone(&lock);
     ///
     /// let n = lock.read().unwrap();
     /// assert_eq!(*n, 1);
     ///
     /// thread::spawn(move || {
     ///     let r = c_lock.read();
     ///     assert!(r.is_ok());
     /// }).join().unwrap();
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>> {
         unsafe {
             self.inner.read();
             RwLockReadGuard::new(self)
         }
     }

     /// Attempts to acquire this `RwLock` with shared read access.
     ///
     /// If the access could not be granted at this time, then `Err` is returned.
     /// Otherwise, an RAII guard is returned which will release the shared access
     /// when it is dropped.
     ///
     /// This function does not block.
     ///
     /// This function does not provide any guarantees with respect to the ordering
     /// of whether contentious readers or writers will acquire the lock first.
     ///
     /// # Errors
     ///
     /// This function will return the [`Poisoned`] error if the `RwLock` is
     /// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
     /// an exclusive lock. `Poisoned` will only be returned if the lock would
     /// have otherwise been acquired.
     ///
     /// This function will return the [`WouldBlock`] error if the `RwLock` could
     /// not be acquired because it was already locked exclusively.
     ///
     /// [`Poisoned`]: TryLockError::Poisoned
     /// [`WouldBlock`]: TryLockError::WouldBlock
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::RwLock;
     ///
     /// let lock = RwLock::new(1);
     ///
     /// match lock.try_read() {
     ///     Ok(n) => assert_eq!(*n, 1),
     ///     Err(_) => unreachable!(),
     /// };
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>> {
         unsafe {
             if self.inner.try_read() {
                 Ok(RwLockReadGuard::new(self)?)
             } else {
                 Err(TryLockError::WouldBlock)
             }
         }
     }

     /// 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.
     ///
     /// Returns an RAII guard which will drop the write access of this `RwLock`
     /// when dropped.
     ///
     /// # Errors
     ///
     /// This function will return an error if the `RwLock` is poisoned. An
     /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
     /// lock. An error will be returned when the lock is acquired.
     ///
     /// # Panics
     ///
     /// This function might panic when called if the lock is already held by the current thread.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::RwLock;
     ///
     /// let lock = RwLock::new(1);
     ///
     /// let mut n = lock.write().unwrap();
     /// *n = 2;
     ///
     /// assert!(lock.try_read().is_err());
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>> {
         unsafe {
             self.inner.write();
             RwLockWriteGuard::new(self)
         }
     }

     /// Attempts to lock this `RwLock` with exclusive write access.
     ///
     /// If the lock could not be acquired at this time, then `Err` is returned.
     /// Otherwise, an RAII guard is returned which will release the lock when
     /// it is dropped.
     ///
     /// This function does not block.
     ///
     /// This function does not provide any guarantees with respect to the ordering
     /// of whether contentious readers or writers will acquire the lock first.
     ///
     /// # Errors
     ///
     /// This function will return the [`Poisoned`] error if the `RwLock` is
     /// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
     /// an exclusive lock. `Poisoned` will only be returned if the lock would
     /// have otherwise been acquired.
     ///
     /// This function will return the [`WouldBlock`] error if the `RwLock` could
     /// not be acquired because it was already locked exclusively.
     ///
     /// [`Poisoned`]: TryLockError::Poisoned
     /// [`WouldBlock`]: TryLockError::WouldBlock
     ///
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::RwLock;
     ///
     /// let lock = RwLock::new(1);
     ///
     /// let n = lock.read().unwrap();
     /// assert_eq!(*n, 1);
     ///
     /// assert!(lock.try_write().is_err());
     /// ```
     #[inline]
     #[stable(feature = "rust1", since = "1.0.0")]
     pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>> {
         unsafe {
             if self.inner.try_write() {
                 Ok(RwLockWriteGuard::new(self)?)
             } else {
                 Err(TryLockError::WouldBlock)
             }
         }
     }

     /// Determines whether the lock is poisoned.
     ///
     /// If another thread is active, the lock can still become poisoned at any
     /// time. You should not trust a `false` value for program correctness
     /// without additional synchronization.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::{Arc, RwLock};
     /// use std::thread;
     ///
     /// let lock = Arc::new(RwLock::new(0));
     /// let c_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);
     /// ```
     #[inline]
     #[stable(feature = "sync_poison", since = "1.2.0")]
     pub fn is_poisoned(&self) -> bool {
         self.poison.get()
     }

     /// Clear the poisoned state from a lock
     ///
     /// If the lock is poisoned, it will remain poisoned until this function is called. This allows
     /// recovering from a poisoned state and marking that it has recovered. For example, if the
     /// value is overwritten by a known-good value, then the mutex can be marked as un-poisoned. Or
     /// possibly, the value could be inspected to determine if it is in a consistent state, and if
     /// so the poison is removed.
     ///
     /// # Examples
     ///
     /// ```
     /// #![feature(mutex_unpoison)]
     ///
     /// use std::sync::{Arc, RwLock};
     /// use std::thread;
     ///
     /// let lock = Arc::new(RwLock::new(0));
     /// let c_lock = Arc::clone(&lock);
     ///
     /// let _ = thread::spawn(move || {
     ///     let _lock = c_lock.write().unwrap();
     ///     panic!(); // the mutex gets poisoned
     /// }).join();
     ///
     /// assert_eq!(lock.is_poisoned(), true);
     /// let guard = lock.write().unwrap_or_else(|mut e| {
     ///     **e.get_mut() = 1;
     ///     lock.clear_poison();
     ///     e.into_inner()
     /// });
     /// assert_eq!(lock.is_poisoned(), false);
     /// assert_eq!(*guard, 1);
     /// ```
     #[inline]
     #[unstable(feature = "mutex_unpoison", issue = "96469")]
     pub fn clear_poison(&self) {
         self.poison.clear();
     }

     /// Consumes this `RwLock`, returning the underlying data.
     ///
     /// # Errors
     ///
     /// This function will return an error if the `RwLock` is poisoned. An
     /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
     /// lock. An error will only be returned if the lock would have otherwise
     /// been acquired.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::RwLock;
     ///
     /// let lock = RwLock::new(String::new());
     /// {
     ///     let mut s = lock.write().unwrap();
     ///     *s = "modified".to_owned();
     /// }
     /// assert_eq!(lock.into_inner().unwrap(), "modified");
     /// ```
     #[stable(feature = "rwlock_into_inner", since = "1.6.0")]
     pub fn into_inner(self) -> LockResult<T>
     where
         T: Sized,
     {
         let data = self.data.into_inner();
         poison::map_result(self.poison.borrow(), |()| data)
     }

     /// 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 locks exist.
     ///
     /// # Errors
     ///
     /// This function will return an error if the `RwLock` is poisoned. An
     /// `RwLock` is poisoned whenever a writer panics while holding an exclusive
     /// lock. An error will only be returned if the lock would have otherwise
     /// been acquired.
     ///
     /// # Examples
     ///
     /// ```
     /// use std::sync::RwLock;
     ///
     /// let mut lock = RwLock::new(0);
     /// *lock.get_mut().unwrap() = 10;
     /// assert_eq!(*lock.read().unwrap(), 10);
     /// ```
     #[stable(feature = "rwlock_get_mut", since = "1.6.0")]
     pub fn get_mut(&mut self) -> LockResult<&mut T> {
         let data = self.data.get_mut();
         poison::map_result(self.poison.borrow(), |()| data)
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         let mut d = f.debug_struct("RwLock");
         match self.try_read() {
             Ok(guard) => {
                 d.field("data", &&*guard);
             }
             Err(TryLockError::Poisoned(err)) => {
                 d.field("data", &&**err.get_ref());
             }
             Err(TryLockError::WouldBlock) => {
                 struct LockedPlaceholder;
                 impl fmt::Debug for LockedPlaceholder {
                     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
                         f.write_str("<locked>")
                     }
                 }
                 d.field("data", &LockedPlaceholder);
             }
         }
         d.field("poisoned", &self.poison.get());
         d.finish_non_exhaustive()
     }
 }

 #[stable(feature = "rw_lock_default", since = "1.10.0")]
 impl<T: Default> Default for RwLock<T> {
     /// Creates a new `RwLock<T>`, with the `Default` value for T.
     fn default() -> RwLock<T> {
         RwLock::new(Default::default())
     }
 }

 #[stable(feature = "rw_lock_from", since = "1.24.0")]
 impl<T> From<T> for RwLock<T> {
     /// Creates a new instance of an `RwLock<T>` which is unlocked.
     /// This is equivalent to [`RwLock::new`].
     fn from(t: T) -> Self {
         RwLock::new(t)
     }
 }

 impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
     /// Create a new instance of `RwLockReadGuard<T>` from a `RwLock<T>`.
     // SAFETY: if and only if `lock.inner.read()` (or `lock.inner.try_read()`) has been
     // successfully called from the same thread before instantiating this object.
     unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockReadGuard<'rwlock, T>> {
         poison::map_result(lock.poison.borrow(), |()| RwLockReadGuard {
             data: NonNull::new_unchecked(lock.data.get()),
             inner_lock: &lock.inner,
         })
     }
 }

 impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
     /// Create a new instance of `RwLockWriteGuard<T>` from a `RwLock<T>`.
     // SAFETY: if and only if `lock.inner.write()` (or `lock.inner.try_write()`) has been
     // successfully called from the same thread before instantiating this object.
     unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockWriteGuard<'rwlock, T>> {
         poison::map_result(lock.poison.guard(), |guard| RwLockWriteGuard { lock, poison: guard })
     }
 }

 #[stable(feature = "std_debug", since = "1.16.0")]
 impl<T: fmt::Debug> fmt::Debug for RwLockReadGuard<'_, T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         (**self).fmt(f)
     }
 }

 #[stable(feature = "std_guard_impls", since = "1.20.0")]
 impl<T: ?Sized + fmt::Display> fmt::Display for RwLockReadGuard<'_, T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         (**self).fmt(f)
     }
 }

 #[stable(feature = "std_debug", since = "1.16.0")]
 impl<T: fmt::Debug> fmt::Debug for RwLockWriteGuard<'_, T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         (**self).fmt(f)
     }
 }

 #[stable(feature = "std_guard_impls", since = "1.20.0")]
 impl<T: ?Sized + fmt::Display> fmt::Display for RwLockWriteGuard<'_, T> {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         (**self).fmt(f)
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Deref for RwLockReadGuard<'_, T> {
     type Target = T;

     fn deref(&self) -> &T {
         // SAFETY: the conditions of `RwLockGuard::new` were satisfied when created.
         unsafe { self.data.as_ref() }
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Deref for RwLockWriteGuard<'_, T> {
     type Target = T;

     fn deref(&self) -> &T {
         // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
         unsafe { &*self.lock.data.get() }
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> DerefMut for RwLockWriteGuard<'_, T> {
     fn deref_mut(&mut self) -> &mut T {
         // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
         unsafe { &mut *self.lock.data.get() }
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Drop for RwLockReadGuard<'_, T> {
     fn drop(&mut self) {
         // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created.
         unsafe {
             self.inner_lock.read_unlock();
         }
     }
 }

 #[stable(feature = "rust1", since = "1.0.0")]
 impl<T: ?Sized> Drop for RwLockWriteGuard<'_, T> {
     fn drop(&mut self) {
         self.lock.poison.done(&self.poison);
         // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
         unsafe {
             self.lock.inner.write_unlock();
         }
     }
 }
	#[cfg(all(test, not(target_os = "emscripten")))]
	mod tests;

	use crate::cell::UnsafeCell;
	use crate::fmt;
	use crate::ops::{Deref, DerefMut};
	use crate::ptr::NonNull;
	use crate::sync::{poison, LockResult, TryLockError, TryLockResult};
	use crate::sys::locks as sys;

	/// 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).
	///
	/// In comparison, a [`Mutex`] does not distinguish between readers or writers
	/// that acquire the lock, therefore blocking any threads waiting for the lock to
	/// become available. An `RwLock` will allow any number of readers to acquire the
	/// lock as long as a writer is not holding the lock.
	///
	/// The priority policy of the lock is dependent on the underlying operating
	/// system's implementation, and this type does not guarantee that any
	/// particular policy will be used. In particular, a writer which is waiting to
	/// acquire the lock in `write` might or might not block concurrent calls to
	/// `read`, e.g.:
	///
	/// <details><summary>Potential deadlock example</summary>
	///
	/// ```text
	/// // Thread 1 \| // Thread 2
	/// let _rg = lock.read(); \|
	/// \| // will block
	/// \| let _wg = lock.write();
	/// // may deadlock \|
	/// let _rg = lock.read(); \|
	/// ```
	/// </details>
	///
	/// 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 content of the lock.
	///
	/// # Poisoning
	///
	/// An `RwLock`, like [`Mutex`], will become poisoned on a panic. Note, however,
	/// that an `RwLock` may only be poisoned if a panic occurs while it is locked
	/// exclusively (write mode). If a panic occurs in any reader, then the lock
	/// will not be poisoned.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let lock = RwLock::new(5);
	///
	/// // many reader locks can be held at once
	/// {
	/// let r1 = lock.read().unwrap();
	/// let r2 = 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
	/// {
	/// let mut w = lock.write().unwrap();
	/// *w += 1;
	/// assert_eq!(*w, 6);
	/// } // write lock is dropped here
	/// ```
	///
	/// [`Mutex`]: super::Mutex
	#[stable(feature = "rust1", since = "1.0.0")]
	#[cfg_attr(not(test), rustc_diagnostic_item = "RwLock")]
	pub struct RwLock<T: ?Sized> {
	inner: sys::RwLock,
	poison: poison::Flag,
	data: UnsafeCell<T>,
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	unsafe impl<T: ?Sized + Send> Send for RwLock<T> {}
	#[stable(feature = "rust1", since = "1.0.0")]
	unsafe impl<T: ?Sized + Send + Sync> Sync for RwLock<T> {}

	/// RAII structure used to release the shared read access of a lock when
	/// dropped.
	///
	/// This structure is created by the [`read`] and [`try_read`] methods on
	/// [`RwLock`].
	///
	/// [`read`]: RwLock::read
	/// [`try_read`]: RwLock::try_read
	#[must_use = "if unused the RwLock will immediately unlock"]
	#[must_not_suspend = "holding a RwLockReadGuard across suspend \
	points can cause deadlocks, delays, \
	and cause Futures to not implement `Send`"]
	#[stable(feature = "rust1", since = "1.0.0")]
	#[clippy::has_significant_drop]
	#[cfg_attr(not(test), rustc_diagnostic_item = "RwLockReadGuard")]
	pub struct RwLockReadGuard<'a, T: ?Sized + 'a> {
	// NB: we use a pointer instead of `&'a T` to avoid `noalias` violations, because a
	// `Ref` argument doesn't hold immutability for its whole scope, only until it drops.
	// `NonNull` is also covariant over `T`, just like we would have with `&T`. `NonNull`
	// is preferable over `const* T` to allow for niche optimization.
	data: NonNull<T>,
	inner_lock: &'a sys::RwLock,
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> !Send for RwLockReadGuard<'_, T> {}

	#[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
	unsafe impl<T: ?Sized + Sync> Sync for RwLockReadGuard<'_, T> {}

	/// RAII structure used to release the exclusive write access of a lock when
	/// dropped.
	///
	/// This structure is created by the [`write`] and [`try_write`] methods
	/// on [`RwLock`].
	///
	/// [`write`]: RwLock::write
	/// [`try_write`]: RwLock::try_write
	#[must_use = "if unused the RwLock will immediately unlock"]
	#[must_not_suspend = "holding a RwLockWriteGuard across suspend \
	points can cause deadlocks, delays, \
	and cause Future's to not implement `Send`"]
	#[stable(feature = "rust1", since = "1.0.0")]
	#[clippy::has_significant_drop]
	#[cfg_attr(not(test), rustc_diagnostic_item = "RwLockWriteGuard")]
	pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> {
	lock: &'a RwLock<T>,
	poison: poison::Guard,
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> !Send for RwLockWriteGuard<'_, T> {}

	#[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
	unsafe impl<T: ?Sized + Sync> Sync for RwLockWriteGuard<'_, T> {}

	impl<T> RwLock<T> {
	/// Creates a new instance of an `RwLock<T>` which is unlocked.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let lock = RwLock::new(5);
	/// ```
	#[stable(feature = "rust1", since = "1.0.0")]
	#[rustc_const_stable(feature = "const_locks", since = "1.63.0")]
	#[inline]
	pub const fn new(t: T) -> RwLock<T> {
	RwLock { inner: sys::RwLock::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) }
	}
	}

	impl<T: ?Sized> RwLock<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. This method does not provide any guarantees with
	/// respect to the ordering of whether contentious readers or writers will
	/// acquire the lock first.
	///
	/// Returns an RAII guard which will release this thread's shared access
	/// once it is dropped.
	///
	/// # Errors
	///
	/// This function will return an error if the `RwLock` is poisoned. An
	/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
	/// lock. The failure will occur immediately after the lock has been
	/// acquired.
	///
	/// # Panics
	///
	/// This function might panic when called if the lock is already held by the current thread.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::{Arc, RwLock};
	/// use std::thread;
	///
	/// let lock = Arc::new(RwLock::new(1));
	/// let c_lock = Arc::clone(&lock);
	///
	/// let n = lock.read().unwrap();
	/// assert_eq!(*n, 1);
	///
	/// thread::spawn(move \|\| {
	/// let r = c_lock.read();
	/// assert!(r.is_ok());
	/// }).join().unwrap();
	/// ```
	#[inline]
	#[stable(feature = "rust1", since = "1.0.0")]
	pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>> {
	unsafe {
	self.inner.read();
	RwLockReadGuard::new(self)
	}
	}

	/// Attempts to acquire this `RwLock` with shared read access.
	///
	/// If the access could not be granted at this time, then `Err` is returned.
	/// Otherwise, an RAII guard is returned which will release the shared access
	/// when it is dropped.
	///
	/// This function does not block.
	///
	/// This function does not provide any guarantees with respect to the ordering
	/// of whether contentious readers or writers will acquire the lock first.
	///
	/// # Errors
	///
	/// This function will return the [`Poisoned`] error if the `RwLock` is
	/// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
	/// an exclusive lock. `Poisoned` will only be returned if the lock would
	/// have otherwise been acquired.
	///
	/// This function will return the [`WouldBlock`] error if the `RwLock` could
	/// not be acquired because it was already locked exclusively.
	///
	/// [`Poisoned`]: TryLockError::Poisoned
	/// [`WouldBlock`]: TryLockError::WouldBlock
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let lock = RwLock::new(1);
	///
	/// match lock.try_read() {
	/// Ok(n) => assert_eq!(*n, 1),
	/// Err(_) => unreachable!(),
	/// };
	/// ```
	#[inline]
	#[stable(feature = "rust1", since = "1.0.0")]
	pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>> {
	unsafe {
	if self.inner.try_read() {
	Ok(RwLockReadGuard::new(self)?)
	} else {
	Err(TryLockError::WouldBlock)
	}
	}
	}

	/// 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.
	///
	/// Returns an RAII guard which will drop the write access of this `RwLock`
	/// when dropped.
	///
	/// # Errors
	///
	/// This function will return an error if the `RwLock` is poisoned. An
	/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
	/// lock. An error will be returned when the lock is acquired.
	///
	/// # Panics
	///
	/// This function might panic when called if the lock is already held by the current thread.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let lock = RwLock::new(1);
	///
	/// let mut n = lock.write().unwrap();
	/// *n = 2;
	///
	/// assert!(lock.try_read().is_err());
	/// ```
	#[inline]
	#[stable(feature = "rust1", since = "1.0.0")]
	pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>> {
	unsafe {
	self.inner.write();
	RwLockWriteGuard::new(self)
	}
	}

	/// Attempts to lock this `RwLock` with exclusive write access.
	///
	/// If the lock could not be acquired at this time, then `Err` is returned.
	/// Otherwise, an RAII guard is returned which will release the lock when
	/// it is dropped.
	///
	/// This function does not block.
	///
	/// This function does not provide any guarantees with respect to the ordering
	/// of whether contentious readers or writers will acquire the lock first.
	///
	/// # Errors
	///
	/// This function will return the [`Poisoned`] error if the `RwLock` is
	/// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
	/// an exclusive lock. `Poisoned` will only be returned if the lock would
	/// have otherwise been acquired.
	///
	/// This function will return the [`WouldBlock`] error if the `RwLock` could
	/// not be acquired because it was already locked exclusively.
	///
	/// [`Poisoned`]: TryLockError::Poisoned
	/// [`WouldBlock`]: TryLockError::WouldBlock
	///
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let lock = RwLock::new(1);
	///
	/// let n = lock.read().unwrap();
	/// assert_eq!(*n, 1);
	///
	/// assert!(lock.try_write().is_err());
	/// ```
	#[inline]
	#[stable(feature = "rust1", since = "1.0.0")]
	pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>> {
	unsafe {
	if self.inner.try_write() {
	Ok(RwLockWriteGuard::new(self)?)
	} else {
	Err(TryLockError::WouldBlock)
	}
	}
	}

	/// Determines whether the lock is poisoned.
	///
	/// If another thread is active, the lock can still become poisoned at any
	/// time. You should not trust a `false` value for program correctness
	/// without additional synchronization.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::{Arc, RwLock};
	/// use std::thread;
	///
	/// let lock = Arc::new(RwLock::new(0));
	/// let c_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);
	/// ```
	#[inline]
	#[stable(feature = "sync_poison", since = "1.2.0")]
	pub fn is_poisoned(&self) -> bool {
	self.poison.get()
	}

	/// Clear the poisoned state from a lock
	///
	/// If the lock is poisoned, it will remain poisoned until this function is called. This allows
	/// recovering from a poisoned state and marking that it has recovered. For example, if the
	/// value is overwritten by a known-good value, then the mutex can be marked as un-poisoned. Or
	/// possibly, the value could be inspected to determine if it is in a consistent state, and if
	/// so the poison is removed.
	///
	/// # Examples
	///
	/// ```
	/// #![feature(mutex_unpoison)]
	///
	/// use std::sync::{Arc, RwLock};
	/// use std::thread;
	///
	/// let lock = Arc::new(RwLock::new(0));
	/// let c_lock = Arc::clone(&lock);
	///
	/// let _ = thread::spawn(move \|\| {
	/// let _lock = c_lock.write().unwrap();
	/// panic!(); // the mutex gets poisoned
	/// }).join();
	///
	/// assert_eq!(lock.is_poisoned(), true);
	/// let guard = lock.write().unwrap_or_else(\|mut e\| {
	/// **e.get_mut() = 1;
	/// lock.clear_poison();
	/// e.into_inner()
	/// });
	/// assert_eq!(lock.is_poisoned(), false);
	/// assert_eq!(*guard, 1);
	/// ```
	#[inline]
	#[unstable(feature = "mutex_unpoison", issue = "96469")]
	pub fn clear_poison(&self) {
	self.poison.clear();
	}

	/// Consumes this `RwLock`, returning the underlying data.
	///
	/// # Errors
	///
	/// This function will return an error if the `RwLock` is poisoned. An
	/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
	/// lock. An error will only be returned if the lock would have otherwise
	/// been acquired.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let lock = RwLock::new(String::new());
	/// {
	/// let mut s = lock.write().unwrap();
	/// *s = "modified".to_owned();
	/// }
	/// assert_eq!(lock.into_inner().unwrap(), "modified");
	/// ```
	#[stable(feature = "rwlock_into_inner", since = "1.6.0")]
	pub fn into_inner(self) -> LockResult<T>
	where
	T: Sized,
	{
	let data = self.data.into_inner();
	poison::map_result(self.poison.borrow(), \|()\| data)
	}

	/// 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 locks exist.
	///
	/// # Errors
	///
	/// This function will return an error if the `RwLock` is poisoned. An
	/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
	/// lock. An error will only be returned if the lock would have otherwise
	/// been acquired.
	///
	/// # Examples
	///
	/// ```
	/// use std::sync::RwLock;
	///
	/// let mut lock = RwLock::new(0);
	/// *lock.get_mut().unwrap() = 10;
	/// assert_eq!(*lock.read().unwrap(), 10);
	/// ```
	#[stable(feature = "rwlock_get_mut", since = "1.6.0")]
	pub fn get_mut(&mut self) -> LockResult<&mut T> {
	let data = self.data.get_mut();
	poison::map_result(self.poison.borrow(), \|()\| data)
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	let mut d = f.debug_struct("RwLock");
	match self.try_read() {
	Ok(guard) => {
	d.field("data", &&*guard);
	}
	Err(TryLockError::Poisoned(err)) => {
	d.field("data", &&**err.get_ref());
	}
	Err(TryLockError::WouldBlock) => {
	struct LockedPlaceholder;
	impl fmt::Debug for LockedPlaceholder {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	f.write_str("<locked>")
	}
	}
	d.field("data", &LockedPlaceholder);
	}
	}
	d.field("poisoned", &self.poison.get());
	d.finish_non_exhaustive()
	}
	}

	#[stable(feature = "rw_lock_default", since = "1.10.0")]
	impl<T: Default> Default for RwLock<T> {
	/// Creates a new `RwLock<T>`, with the `Default` value for T.
	fn default() -> RwLock<T> {
	RwLock::new(Default::default())
	}
	}

	#[stable(feature = "rw_lock_from", since = "1.24.0")]
	impl<T> From<T> for RwLock<T> {
	/// Creates a new instance of an `RwLock<T>` which is unlocked.
	/// This is equivalent to [`RwLock::new`].
	fn from(t: T) -> Self {
	RwLock::new(t)
	}
	}

	impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
	/// Create a new instance of `RwLockReadGuard<T>` from a `RwLock<T>`.
	// SAFETY: if and only if `lock.inner.read()` (or `lock.inner.try_read()`) has been
	// successfully called from the same thread before instantiating this object.
	unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockReadGuard<'rwlock, T>> {
	poison::map_result(lock.poison.borrow(), \|()\| RwLockReadGuard {
	data: NonNull::new_unchecked(lock.data.get()),
	inner_lock: &lock.inner,
	})
	}
	}

	impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
	/// Create a new instance of `RwLockWriteGuard<T>` from a `RwLock<T>`.
	// SAFETY: if and only if `lock.inner.write()` (or `lock.inner.try_write()`) has been
	// successfully called from the same thread before instantiating this object.
	unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockWriteGuard<'rwlock, T>> {
	poison::map_result(lock.poison.guard(), \|guard\| RwLockWriteGuard { lock, poison: guard })
	}
	}

	#[stable(feature = "std_debug", since = "1.16.0")]
	impl<T: fmt::Debug> fmt::Debug for RwLockReadGuard<'_, T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	(**self).fmt(f)
	}
	}

	#[stable(feature = "std_guard_impls", since = "1.20.0")]
	impl<T: ?Sized + fmt::Display> fmt::Display for RwLockReadGuard<'_, T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	(**self).fmt(f)
	}
	}

	#[stable(feature = "std_debug", since = "1.16.0")]
	impl<T: fmt::Debug> fmt::Debug for RwLockWriteGuard<'_, T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	(**self).fmt(f)
	}
	}

	#[stable(feature = "std_guard_impls", since = "1.20.0")]
	impl<T: ?Sized + fmt::Display> fmt::Display for RwLockWriteGuard<'_, T> {
	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
	(**self).fmt(f)
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> Deref for RwLockReadGuard<'_, T> {
	type Target = T;

	fn deref(&self) -> &T {
	// SAFETY: the conditions of `RwLockGuard::new` were satisfied when created.
	unsafe { self.data.as_ref() }
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> Deref for RwLockWriteGuard<'_, T> {
	type Target = T;

	fn deref(&self) -> &T {
	// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
	unsafe { &*self.lock.data.get() }
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> DerefMut for RwLockWriteGuard<'_, T> {
	fn deref_mut(&mut self) -> &mut T {
	// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
	unsafe { &mut *self.lock.data.get() }
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> Drop for RwLockReadGuard<'_, T> {
	fn drop(&mut self) {
	// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created.
	unsafe {
	self.inner_lock.read_unlock();
	}
	}
	}

	#[stable(feature = "rust1", since = "1.0.0")]
	impl<T: ?Sized> Drop for RwLockWriteGuard<'_, T> {
	fn drop(&mut self) {
	self.lock.poison.done(&self.poison);
	// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
	unsafe {
	self.lock.inner.write_unlock();
	}
	}
	}