rasi_ext/utils/sync/
api.rs

1use std::{future::Future, task::Context};
2
3/// Any mutex object should implement this trait
4pub trait Lockable {
5    /// RAII scoped lock guard type.
6    type GuardMut<'a>
7    where
8        Self: 'a;
9
10    /// Lock self and returns RAII locker guard object.
11    fn lock(&self) -> Self::GuardMut<'_>;
12
13    /// Attempts to acquire this lock.
14    ///
15    /// If the lock could not be acquired at this time, then `None` is returned.
16    /// Otherwise, an RAII guard is returned. The lock will be unlocked when the guard is dropped.
17    fn try_lock(&self) -> Option<Self::GuardMut<'_>>;
18
19    /// Immediately drops the `guard`, and consequently unlocks the `Lockable` object.
20    ///
21    /// The return value is the associated [`Lockable`] object of this `guard`
22    fn unlock(guard: Self::GuardMut<'_>) -> &Self;
23}
24
25pub trait LockableNew: Lockable {
26    type Value;
27    fn new(value: Self::Value) -> Self;
28}
29
30/// A futures-aware lockable mutex object should implement this trait.
31pub trait AsyncLockable {
32    /// RAII scoped lock guard type.
33    ///
34    /// A guard of futures-aware mutex must be able to transfer between threads
35    /// In other words, this guard must not track any thread-specific details
36    type GuardMut<'a>: AsyncGuardMut<'a, Locker = Self> + Send + Unpin
37    where
38        Self: 'a;
39
40    /// Future created by [`lock`](AsyncLockable::lock) function
41    type GuardMutFuture<'a>: Future<Output = Self::GuardMut<'a>> + Send
42    where
43        Self: 'a;
44
45    /// Acquire the lock asynchronously.
46    fn lock(&self) -> Self::GuardMutFuture<'_>;
47
48    /// Immediately drops the `guard`, and consequently unlocks the `Lockable` object.
49    ///
50    /// The return value is the associated [`Lockable`] object of this `guard`
51    fn unlock<'a>(guard: Self::GuardMut<'a>) -> &'a Self;
52}
53
54/// Trait for guard of [`AsyncLockable`]
55pub trait AsyncGuardMut<'a> {
56    type Locker: AsyncLockable<GuardMut<'a> = Self>
57    where
58        Self: 'a;
59}
60
61/// Event manager for [`AsyncLockable`] listeners.
62pub trait AsyncLockableMediator {
63    /// Block the current task and wait for lockable event.
64    ///
65    /// Return the unique wait key.
66    #[cfg(not(feature = "trace_lock"))]
67    fn wait_lockable(&mut self, cx: &mut Context<'_>) -> usize;
68
69    #[cfg(feature = "trace_lock")]
70    fn wait_lockable(
71        &mut self,
72        cx: &mut Context<'_>,
73        tracer: &'static std::panic::Location<'static>,
74    ) -> usize;
75
76    /// Cancel the waker by key value.
77    /// Returns true if remove waker successfully.
78    fn cancel(&mut self, key: usize) -> bool;
79
80    /// Randomly notify one listener that it can try to lock this mutex again.
81    #[cfg(feature = "trace_lock")]
82    fn notify_one(&mut self, id: usize, tracer: &'static std::panic::Location<'static>);
83
84    #[cfg(not(feature = "trace_lock"))]
85    fn notify_one(&mut self);
86
87    /// notify all listeners that they can try to lock this mutex again.
88    fn notify_all(&mut self);
89}
rasi_ext/utils/sync/api.rs

rasi_ext/utils/sync/
api.rs
