fast_able/
guard_common.rs

1//! Common guard types for synchronized collections
2//! 同步集合的通用守护类型
3//!
4//! This module provides reusable guard types that can be shared between
5//! `SyncVec`, `SyncHashMap`, and other synchronized collections.
6//! 此模块提供可在 `SyncVec`、`SyncHashMap` 和其他同步集合之间共享的可重用守护类型。
7
8use spin::{RwLockReadGuard, RwLockWriteGuard};
9use std::fmt::{Debug, Formatter};
10use std::ops::{Deref, DerefMut};
11
12/// Read guard without value lock, only structure lock (read-only access)
13/// 无值锁的读守护者，只有结构锁（只读访问）
14///
15/// # Safety
16/// 此结构绕过了保护值的 `RwLock`，仅当您确定没有其他线程正在修改该值时才应使用。
17/// This struct bypasses the `RwLock` protecting the value.
18/// It should only be used when you are sure that no other thread is modifying the value.
19pub struct RefGuard<'a, V> {
20    /// Structure-level read lock guardian
21    /// 结构级别的读锁守护者
22    pub(crate) _lock: RwLockReadGuard<'a, ()>,
23    /// Value pointer (no lock)
24    /// 值指针（无锁）
25    pub(crate) _value: &'a V,
26}
27
28impl<'a, V> Deref for RefGuard<'a, V> {
29    type Target = V;
30
31    #[inline]
32    fn deref(&self) -> &Self::Target {
33        self._value
34    }
35}
36
37impl<'a, V> Debug for RefGuard<'a, V>
38where
39    V: Debug,
40{
41    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
42        write!(f, "{:?}", self._value)
43    }
44}
45
46impl<'a, V> PartialEq for RefGuard<'a, V>
47where
48    V: PartialEq,
49{
50    fn eq(&self, other: &Self) -> bool {
51        self._value.eq(other._value)
52    }
53}
54
55impl<'a, V> Eq for RefGuard<'a, V> where V: Eq {}
56
57impl<'a, V> std::fmt::Display for RefGuard<'a, V>
58where
59    V: std::fmt::Display,
60{
61    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
62        self._value.fmt(f)
63    }
64}
65
66impl<'a, V> AsRef<V> for RefGuard<'a, V> {
67    #[inline]
68    fn as_ref(&self) -> &V {
69        self._value
70    }
71}
72
73/// Mutable guard without value lock, only structure lock (mutable access)
74/// 无值锁的可变守护者，只有结构锁（可变访问）
75///
76/// # Safety
77/// 此结构绕过了保护值的 `RwLock`，仅当您确定没有其他线程正在修改该值时才应使用。
78/// This struct bypasses the `RwLock` protecting the value.
79/// It should only be used when you are sure that no other thread is modifying the value.
80pub struct MutRefGuard<'a, V> {
81    /// Structure-level read lock guardian
82    /// 结构级别的读锁守护者
83    pub(crate) _lock: RwLockReadGuard<'a, ()>,
84    /// Mutable value pointer (no lock)
85    /// 可变值指针（无锁）
86    pub(crate) _value: &'a mut V,
87}
88
89impl<'a, V> Deref for MutRefGuard<'a, V> {
90    type Target = V;
91
92    #[inline]
93    fn deref(&self) -> &Self::Target {
94        &*self._value
95    }
96}
97
98impl<'a, V> DerefMut for MutRefGuard<'a, V> {
99    #[inline]
100    fn deref_mut(&mut self) -> &mut Self::Target {
101        &mut *self._value
102    }
103}
104
105impl<'a, V> Debug for MutRefGuard<'a, V>
106where
107    V: Debug,
108{
109    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
110        write!(f, "{:?}", &*self._value)
111    }
112}
113
114impl<'a, V> PartialEq for MutRefGuard<'a, V>
115where
116    V: PartialEq,
117{
118    fn eq(&self, other: &Self) -> bool {
119        (*self._value).eq(&*other._value)
120    }
121}
122
123impl<'a, V> Eq for MutRefGuard<'a, V> where V: Eq {}
124
125impl<'a, V> std::fmt::Display for MutRefGuard<'a, V>
126where
127    V: std::fmt::Display,
128{
129    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
130        (*self._value).fmt(f)
131    }
132}
133
134impl<'a, V> AsRef<V> for MutRefGuard<'a, V> {
135    #[inline]
136    fn as_ref(&self) -> &V {
137        &*self._value
138    }
139}
140
141impl<'a, V> AsMut<V> for MutRefGuard<'a, V> {
142    #[inline]
143    fn as_mut(&mut self) -> &mut V {
144        &mut *self._value
145    }
146}
147
148/// Read guard with value read lock, holding structure read lock and value read lock
149/// 带值读锁的读守护者，持有结构读锁和值的读锁
150pub struct ReadGuard<'a, V> {
151    /// Structure-level read lock guardian
152    /// 结构级别的读锁守护者
153    pub(crate) _lock: RwLockReadGuard<'a, ()>,
154    /// Value-level read lock guardian
155    /// 值级别的读锁守护者
156    pub(crate) _value_lock: RwLockReadGuard<'a, V>,
157}
158
159impl<'a, V> Deref for ReadGuard<'a, V> {
160    type Target = V;
161
162    #[inline]
163    fn deref(&self) -> &Self::Target {
164        &*self._value_lock
165    }
166}
167
168impl<'a, V> Debug for ReadGuard<'a, V>
169where
170    V: Debug,
171{
172    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
173        write!(f, "{:?}", &*self._value_lock)
174    }
175}
176
177impl<'a, V> PartialEq for ReadGuard<'a, V>
178where
179    V: PartialEq,
180{
181    fn eq(&self, other: &Self) -> bool {
182        (*self._value_lock).eq(&*other._value_lock)
183    }
184}
185
186impl<'a, V> Eq for ReadGuard<'a, V> where V: Eq {}
187
188impl<'a, V> std::fmt::Display for ReadGuard<'a, V>
189where
190    V: std::fmt::Display,
191{
192    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
193        (*self._value_lock).fmt(f)
194    }
195}
196
197impl<'a, V> AsRef<V> for ReadGuard<'a, V> {
198    #[inline]
199    fn as_ref(&self) -> &V {
200        &*self._value_lock
201    }
202}
203
204/// Write guard with value write lock, holding structure read lock and value write lock
205/// 带值写锁的写守护者，持有结构读锁和值的写锁
206///
207/// This allows other threads to still read/write other values, but cannot access this value
208/// 这样其他线程仍可读写其他值，但不能访问此值
209pub struct WriteGuard<'a, V> {
210    /// Structure-level read lock guardian
211    /// 结构级别的读锁守护者
212    pub(crate) _lock: RwLockReadGuard<'a, ()>,
213    /// Value-level write lock guardian
214    /// 值级别的写锁守护者
215    pub(crate) _value_lock: RwLockWriteGuard<'a, V>,
216}
217
218impl<'a, V> Deref for WriteGuard<'a, V> {
219    type Target = V;
220
221    #[inline]
222    fn deref(&self) -> &Self::Target {
223        &*self._value_lock
224    }
225}
226
227impl<'a, V> DerefMut for WriteGuard<'a, V> {
228    #[inline]
229    fn deref_mut(&mut self) -> &mut Self::Target {
230        &mut *self._value_lock
231    }
232}
233
234impl<'a, V> Debug for WriteGuard<'a, V>
235where
236    V: Debug,
237{
238    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
239        write!(f, "{:?}", &*self._value_lock)
240    }
241}
242
243impl<'a, V> PartialEq for WriteGuard<'a, V>
244where
245    V: PartialEq,
246{
247    fn eq(&self, other: &Self) -> bool {
248        (*self._value_lock).eq(&*other._value_lock)
249    }
250}
251
252impl<'a, V> Eq for WriteGuard<'a, V> where V: Eq {}
253
254impl<'a, V> std::fmt::Display for WriteGuard<'a, V>
255where
256    V: std::fmt::Display,
257{
258    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
259        (*self._value_lock).fmt(f)
260    }
261}
262
263impl<'a, V> AsRef<V> for WriteGuard<'a, V> {
264    #[inline]
265    fn as_ref(&self) -> &V {
266        &*self._value_lock
267    }
268}
269
270impl<'a, V> AsMut<V> for WriteGuard<'a, V> {
271    #[inline]
272    fn as_mut(&mut self) -> &mut V {
273        &mut *self._value_lock
274    }
275}
276
277/// Write guard for entry operations, holding structure write lock and value write lock
278/// 用于 entry 操作的写守护者，持有结构写锁和值的写锁
279///
280/// Requires structure write lock because it may involve insertion/removal operations
281/// 因为可能涉及插入/移除操作，需要结构写锁
282pub struct EntryGuard<'a, V> {
283    /// Structure-level write lock guardian
284    /// 结构级别的写锁守护者
285    pub(crate) _lock: RwLockWriteGuard<'a, ()>,
286    /// Value-level write lock guardian
287    /// 值级别的写锁守护者
288    pub(crate) _value_lock: RwLockWriteGuard<'a, V>,
289}
290
291impl<'a, V> Deref for EntryGuard<'a, V> {
292    type Target = V;
293
294    #[inline]
295    fn deref(&self) -> &Self::Target {
296        &*self._value_lock
297    }
298}
299
300impl<'a, V> DerefMut for EntryGuard<'a, V> {
301    #[inline]
302    fn deref_mut(&mut self) -> &mut Self::Target {
303        &mut *self._value_lock
304    }
305}
306
307impl<'a, V> Debug for EntryGuard<'a, V>
308where
309    V: Debug,
310{
311    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
312        write!(f, "{:?}", &*self._value_lock)
313    }
314}
315
316impl<'a, V> PartialEq for EntryGuard<'a, V>
317where
318    V: PartialEq,
319{
320    fn eq(&self, other: &Self) -> bool {
321        (*self._value_lock).eq(&*other._value_lock)
322    }
323}
324
325impl<'a, V> Eq for EntryGuard<'a, V> where V: Eq {}
326
327impl<'a, V> std::fmt::Display for EntryGuard<'a, V>
328where
329    V: std::fmt::Display,
330{
331    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
332        (*self._value_lock).fmt(f)
333    }
334}
335
336impl<'a, V> AsRef<V> for EntryGuard<'a, V> {
337    #[inline]
338    fn as_ref(&self) -> &V {
339        &*self._value_lock
340    }
341}
342
343impl<'a, V> AsMut<V> for EntryGuard<'a, V> {
344    #[inline]
345    fn as_mut(&mut self) -> &mut V {
346        &mut *self._value_lock
347    }
348}
fast_able/guard_common.rs

fast_able/
guard_common.rs
