fast-able 1.20.2

//! Common guard types for synchronized collections
//! 同步集合的通用守护类型
//!
//! This module provides reusable guard types that can be shared between
//! `SyncVec`, `SyncHashMap`, and other synchronized collections.
//! 此模块提供可在 `SyncVec`、`SyncHashMap` 和其他同步集合之间共享的可重用守护类型。

use spin::{RwLockReadGuard, RwLockWriteGuard};
use std::fmt::{Debug, Formatter};
use std::ops::{Deref, DerefMut};

/// Read guard without value lock, only structure lock (read-only access)
/// 无值锁的读守护者，只有结构锁（只读访问）
///
/// # Safety
/// 此结构绕过了保护值的 `RwLock`，仅当您确定没有其他线程正在修改该值时才应使用。
/// This struct bypasses the `RwLock` protecting the value.
/// It should only be used when you are sure that no other thread is modifying the value.
pub struct RefGuard<'a, V> {
    /// Structure-level read lock guardian
    /// 结构级别的读锁守护者
    pub(crate) _lock: RwLockReadGuard<'a, ()>,
    /// Value pointer (no lock)
    /// 值指针（无锁）
    pub(crate) _value: &'a V,
}

impl<'a, V> Deref for RefGuard<'a, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        self._value
    }
}

impl<'a, V> Debug for RefGuard<'a, V>
where
    V: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?}", self._value)
    }
}

impl<'a, V> PartialEq for RefGuard<'a, V>
where
    V: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        self._value.eq(other._value)
    }
}

impl<'a, V> Eq for RefGuard<'a, V> where V: Eq {}

impl<'a, V> std::fmt::Display for RefGuard<'a, V>
where
    V: std::fmt::Display,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        self._value.fmt(f)
    }
}

impl<'a, V> AsRef<V> for RefGuard<'a, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        self._value
    }
}

/// Mutable guard without value lock, only structure lock (mutable access)
/// 无值锁的可变守护者，只有结构锁（可变访问）
///
/// # Safety
/// 此结构绕过了保护值的 `RwLock`，仅当您确定没有其他线程正在修改该值时才应使用。
/// This struct bypasses the `RwLock` protecting the value.
/// It should only be used when you are sure that no other thread is modifying the value.
pub struct MutRefGuard<'a, V> {
    /// Structure-level read lock guardian
    /// 结构级别的读锁守护者
    pub(crate) _lock: RwLockReadGuard<'a, ()>,
    /// Mutable value pointer (no lock)
    /// 可变值指针（无锁）
    pub(crate) _value: &'a mut V,
}

impl<'a, V> Deref for MutRefGuard<'a, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &*self._value
    }
}

impl<'a, V> DerefMut for MutRefGuard<'a, V> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut *self._value
    }
}

impl<'a, V> Debug for MutRefGuard<'a, V>
where
    V: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?}", &*self._value)
    }
}

impl<'a, V> PartialEq for MutRefGuard<'a, V>
where
    V: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        (*self._value).eq(&*other._value)
    }
}

impl<'a, V> Eq for MutRefGuard<'a, V> where V: Eq {}

impl<'a, V> std::fmt::Display for MutRefGuard<'a, V>
where
    V: std::fmt::Display,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        (*self._value).fmt(f)
    }
}

impl<'a, V> AsRef<V> for MutRefGuard<'a, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        &*self._value
    }
}

impl<'a, V> AsMut<V> for MutRefGuard<'a, V> {
    #[inline]
    fn as_mut(&mut self) -> &mut V {
        &mut *self._value
    }
}

/// Read guard with value read lock, holding structure read lock and value read lock
/// 带值读锁的读守护者，持有结构读锁和值的读锁
pub struct ReadGuard<'a, V> {
    /// Structure-level read lock guardian
    /// 结构级别的读锁守护者
    pub(crate) _lock: RwLockReadGuard<'a, ()>,
    /// Value-level read lock guardian
    /// 值级别的读锁守护者
    pub(crate) _value_lock: RwLockReadGuard<'a, V>,
}

impl<'a, V> Deref for ReadGuard<'a, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &*self._value_lock
    }
}

impl<'a, V> Debug for ReadGuard<'a, V>
where
    V: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?}", &*self._value_lock)
    }
}

impl<'a, V> PartialEq for ReadGuard<'a, V>
where
    V: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        (*self._value_lock).eq(&*other._value_lock)
    }
}

impl<'a, V> Eq for ReadGuard<'a, V> where V: Eq {}

impl<'a, V> std::fmt::Display for ReadGuard<'a, V>
where
    V: std::fmt::Display,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        (*self._value_lock).fmt(f)
    }
}

impl<'a, V> AsRef<V> for ReadGuard<'a, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        &*self._value_lock
    }
}

/// Write guard with value write lock, holding structure read lock and value write lock
/// 带值写锁的写守护者，持有结构读锁和值的写锁
///
/// This allows other threads to still read/write other values, but cannot access this value
/// 这样其他线程仍可读写其他值，但不能访问此值
pub struct WriteGuard<'a, V> {
    /// Structure-level read lock guardian
    /// 结构级别的读锁守护者
    pub(crate) _lock: RwLockReadGuard<'a, ()>,
    /// Value-level write lock guardian
    /// 值级别的写锁守护者
    pub(crate) _value_lock: RwLockWriteGuard<'a, V>,
}

impl<'a, V> Deref for WriteGuard<'a, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &*self._value_lock
    }
}

impl<'a, V> DerefMut for WriteGuard<'a, V> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut *self._value_lock
    }
}

impl<'a, V> Debug for WriteGuard<'a, V>
where
    V: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?}", &*self._value_lock)
    }
}

impl<'a, V> PartialEq for WriteGuard<'a, V>
where
    V: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        (*self._value_lock).eq(&*other._value_lock)
    }
}

impl<'a, V> Eq for WriteGuard<'a, V> where V: Eq {}

impl<'a, V> std::fmt::Display for WriteGuard<'a, V>
where
    V: std::fmt::Display,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        (*self._value_lock).fmt(f)
    }
}

impl<'a, V> AsRef<V> for WriteGuard<'a, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        &*self._value_lock
    }
}

impl<'a, V> AsMut<V> for WriteGuard<'a, V> {
    #[inline]
    fn as_mut(&mut self) -> &mut V {
        &mut *self._value_lock
    }
}

/// Write guard for entry operations, holding structure write lock and value write lock
/// 用于 entry 操作的写守护者，持有结构写锁和值的写锁
///
/// Requires structure write lock because it may involve insertion/removal operations
/// 因为可能涉及插入/移除操作，需要结构写锁
pub struct EntryGuard<'a, V> {
    /// Structure-level write lock guardian
    /// 结构级别的写锁守护者
    pub(crate) _lock: RwLockWriteGuard<'a, ()>,
    /// Value-level write lock guardian
    /// 值级别的写锁守护者
    pub(crate) _value_lock: RwLockWriteGuard<'a, V>,
}

impl<'a, V> Deref for EntryGuard<'a, V> {
    type Target = V;

    #[inline]
    fn deref(&self) -> &Self::Target {
        &*self._value_lock
    }
}

impl<'a, V> DerefMut for EntryGuard<'a, V> {
    #[inline]
    fn deref_mut(&mut self) -> &mut Self::Target {
        &mut *self._value_lock
    }
}

impl<'a, V> Debug for EntryGuard<'a, V>
where
    V: Debug,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        write!(f, "{:?}", &*self._value_lock)
    }
}

impl<'a, V> PartialEq for EntryGuard<'a, V>
where
    V: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        (*self._value_lock).eq(&*other._value_lock)
    }
}

impl<'a, V> Eq for EntryGuard<'a, V> where V: Eq {}

impl<'a, V> std::fmt::Display for EntryGuard<'a, V>
where
    V: std::fmt::Display,
{
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        (*self._value_lock).fmt(f)
    }
}

impl<'a, V> AsRef<V> for EntryGuard<'a, V> {
    #[inline]
    fn as_ref(&self) -> &V {
        &*self._value_lock
    }
}

impl<'a, V> AsMut<V> for EntryGuard<'a, V> {
    #[inline]
    fn as_mut(&mut self) -> &mut V {
        &mut *self._value_lock
    }
}