#[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;

/// reader-writer 锁
///
/// 这种类型的锁定在任何时间点都允许多个 readers 或最多一个 writer。
/// 此锁的写入部分通常允许修改底层数据 (独占访问)，而此锁的读取部分通常允许进行只读访问 (共享访问)。
///
///
/// 相比之下，[`Mutex`] 不会区分获取锁定的 readers 或 writers，因此会阻塞等待锁定变为可用的所有线程。
/// `RwLock` 将允许任意数量的 readers 获取锁，只要 writer 不持有该锁即可。
///
/// 锁定的优先级策略取决于底层操作系统的实现，并且这种类型不能保证将使用任何特定的策略。
/// 特别是，等待获取 `write` 中的锁的 writer 可能会也可能不会阻止对 `read` 的并发调用，例如：
///
/// <details><summary>潜在的死锁示例</summary>
///
/// ```text
/// // Thread 1             |  // Thread 2
/// let _rg = lock.read();  |
///                         |  // 会阻塞
///                         |  let _wg = lock.write();
/// // 可能会陷入僵局         |
/// let _rg = lock.read();  |
/// ```
/// </details>
///
/// 类型参数 `T` 表示此锁保护的数据。
/// 要求 `T` 满足 [`Send`] 在线程之间共享，并且 [`Sync`] 允许通过 readers 进行并发访问。
/// 从锁定方法返回的 RAII 防护实现 [`Deref`] (对于 `write` 方法为 [`DerefMut`]) 以允许访问锁的内容。
///
/// # Poisoning
///
/// `RwLock` 和 [`Mutex`] 一样，将在 panic 上中毒。
/// 但是请注意，仅当 0panic 处于独占锁定状态 (写模式) 时，`RwLock` 才可能中毒。如果在任何 reader 中出现 panic，则锁不会中毒。
///
/// # Examples
///
/// ```
/// use std::sync::RwLock;
///
/// let lock = RwLock::new(5);
///
/// // 可以一次持有许多 reader 锁
/// {
///     let r1 = lock.read().unwrap();
///     let r2 = lock.read().unwrap();
///     assert_eq!(*r1, 5);
///     assert_eq!(*r2, 5);
/// } // 此时将丢弃读锁
///
/// // 只能持有一个写锁，但是
/// {
///     let mut w = lock.write().unwrap();
///     *w += 1;
///     assert_eq!(*w, 6);
/// } // 写锁在这里被丢弃
/// ```
///
/// [`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 结构，用于在丢弃锁时释放锁的共享读取访问。
///
/// 该结构体由 [`RwLock`] 上的 [`read`] 和 [`try_read`] 方法创建。
///
///
/// [`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: 我们使用指针而不是 `&'a T` 来避免 `noalias` 违规，因为 `Ref` 不会在其整个作用域中保持不可不变的参数，直到它丢弃为止。
    //
    // `NonNull` 在 `T` 上也是协变的，就像我们对 `&T` 所做的那样。`NonNull` 优于 `const* T` 以允许 niche 优化。
    //
    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 结构，用于在锁被丢弃时释放对锁的独占写访问。
///
/// 该结构体由 [`RwLock`] 上的 [`write`] 和 [`try_write`] 方法创建。
///
///
/// [`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> {
    /// 创建一个已解锁的 `RwLock<T>` 的新实例。
    ///
    /// # 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> {
    /// 用共享读访问锁定这个 `RwLock`，阻塞当前线程直到它可以被获取。
    ///
    /// 调用线程将被阻塞，直到没有其他持有该锁的 writers 为止。
    /// 当此方法返回时，锁中可能当前存在其他 readers。
    /// 对于有争议的 readers 或 writers 将首先获取锁的顺序，此方法不提供任何保证。
    ///
    ///
    /// 返回 RAII 保护，一旦该线程被丢弃，它将释放该线程的共享访问。
    ///
    /// # Errors
    ///
    /// 如果 `RwLock` 中毒，此函数将返回错误。
    /// 每当 writer 在持有排他锁时发生 panic 时，`RwLock` 就会中毒。
    /// 获取锁定后，将立即发生故障。
    ///
    /// # Panics
    ///
    /// 如果当前线程已锁定，则调用此函数时可能为 panic。
    ///
    /// # 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)
        }
    }

    /// 尝试使用共享读取访问权限获取此 `RwLock`。
    ///
    /// 如果此时不能授予访问权限，则返回 `Err`。
    /// 否则，将返回 RAII 保护，当该保护被丢弃时，该保护将释放共享访问。
    ///
    /// 该函数不会阻止。
    ///
    /// 对于有争议的 readers 或 writers 将首先获取锁的顺序，此函数不提供任何保证。
    ///
    ///
    /// # Errors
    ///
    /// 如果 `RwLock` 中毒，此函数将返回 [`Poisoned`] 错误。
    /// 每当 writer 在持有排他锁时发生 panic 时，`RwLock` 就会中毒。
    /// `Poisoned` 只有在可以获取锁的情况下才会返回。
    ///
    /// 如果由于 `RwLock` 已被独占锁定而无法获取，此函数将返回 [`WouldBlock`] 错误。
    ///
    /// [`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)
            }
        }
    }

    /// 用独占写访问锁定这个 `RwLock`，阻塞当前线程，直到它可以被获取。
    ///
    ///
    /// 当前其他 writers 或其他 readers 可以访问该锁时，此函数将不会返回。
    ///
    /// 返回 RAII 守卫，它会在丢弃时丢弃此 `RwLock` 的写访问。
    ///
    /// # Errors
    ///
    /// 如果 `RwLock` 中毒，此函数将返回错误。
    /// 每当 writer 在持有排他锁时发生 panic 时，`RwLock` 就会中毒。
    /// 获取锁时将返回错误。
    ///
    /// # Panics
    ///
    /// 如果当前线程已锁定，则调用此函数时可能为 panic。
    ///
    /// # 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)
        }
    }

    /// 尝试使用独占写入访问锁定此 `RwLock`。
    ///
    /// 如果此时无法获取锁，则返回 `Err`。
    /// 否则，将返回 RAII 守卫，它将在锁被丢弃时释放锁。
    ///
    /// 该函数不会阻止。
    ///
    /// 对于有争议的 readers 或 writers 将首先获取锁的顺序，此函数不提供任何保证。
    ///
    ///
    /// # Errors
    ///
    /// 如果 `RwLock` 中毒，此函数将返回 [`Poisoned`] 错误。
    /// 每当 writer 在持有排他锁时发生 panic 时，`RwLock` 就会中毒。
    /// `Poisoned` 只有在可以获取锁的情况下才会返回。
    ///
    /// 如果由于 `RwLock` 已被独占锁定而无法获取，此函数将返回 [`WouldBlock`] 错误。
    ///
    /// [`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)
            }
        }
    }

    /// 确定锁是否中毒。
    ///
    /// 如果另一个线程处于活动状态，则锁定仍可能随时中毒。
    /// 如果没有其他同步，则不应信任 `false` 值来确保程序正确性。
    ///
    ///
    /// # 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!(); // 锁被毒死了
    /// }).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()
    }

    /// 从锁中清除中毒状态
    ///
    /// 如果锁中毒了，它将保持中毒状态，直到这个函数被调用为止。
    /// 这允许从中毒状态中恢复并标记它已经恢复。
    /// 例如，如果该值被已知良好的值覆盖，则互斥锁可以被标记为未中毒。
    /// 或者可能，可以检查该值，以确定它是否处于一致状态，如果是，则会清除中毒状态。
    ///
    ///
    /// # 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!(); // 互斥锁中毒
    /// }).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();
    }

    /// 消耗这个 `RwLock`，返回底层数据。
    ///
    /// # Errors
    ///
    /// 如果 `RwLock` 中毒，此函数将返回错误。
    /// 每当 writer 在持有排他锁时发生 panic 时，`RwLock` 就会中毒。
    ///
    /// 仅当以其他方式获取锁时，才会返回错误。
    ///
    /// # 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)
    }

    /// 返回对底层数据的可变引用。
    ///
    /// 由于此调用借用 `RwLock` 是可变的，因此不需要进行实际的锁定 - 可变借用可以静态地保证不存在任何锁定。
    ///
    ///
    /// # Errors
    ///
    /// 如果 `RwLock` 中毒，此函数将返回错误。
    /// 每当 writer 在持有排他锁时发生 panic 时，`RwLock` 就会中毒。
    /// 仅当以其他方式获取锁时，才会返回错误。
    ///
    /// # 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> {
    /// 用 T 的 `Default` 值创建一个新的 `RwLock<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> {
    /// 创建一个已解锁的 `RwLock<T>` 的新实例。
    /// 这等效于 [`RwLock::new`]。
    fn from(t: T) -> Self {
        RwLock::new(t)
    }
}

impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
    /// 从 `RwLock<T>` 创建一个新的 `RwLockReadGuard<T>` 实例。
    // SAFETY: 当且仅当在实例化此 object 之前已从同一线程成功调用 `lock.inner.read()` (或 `lock.inner.try_read()`)。
    //
    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> {
    /// 从 `RwLock<T>` 创建一个新的 `RwLockWriteGuard<T>` 实例。
    // SAFETY: 当且仅当在实例化此 object 之前已从同一线程成功调用 `lock.inner.write()` (或 `lock.inner.try_write()`)。
    //
    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: 创建时满足 `RwLockGuard::new` 的条件。
        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: 创建时满足 `RwLockWriteGuard::new` 的条件。
        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: 创建时满足 `RwLockWriteGuard::new` 的条件。
        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: 创建时满足 `RwLockReadGuard::new` 的条件。
        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: 创建时满足 `RwLockWriteGuard::new` 的条件。
        unsafe {
            self.lock.inner.write_unlock();
        }
    }
}