1 #[cfg(all(test, not(target_os = "emscripten")))]
4 use crate::marker::PhantomPinned;
6 use crate::panic::{RefUnwindSafe, UnwindSafe};
8 use crate::sys::mutex as sys;
10 /// A re-entrant mutual exclusion
12 /// This mutex will block *other* threads waiting for the lock to become
13 /// available. The thread which has already locked the mutex can lock it
14 /// multiple times without blocking, preventing a common source of deadlocks.
15 pub struct ReentrantMutex<T> {
16 inner: sys::ReentrantMutex,
18 _pinned: PhantomPinned,
21 unsafe impl<T: Send> Send for ReentrantMutex<T> {}
22 unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
24 impl<T> UnwindSafe for ReentrantMutex<T> {}
25 impl<T> RefUnwindSafe for ReentrantMutex<T> {}
27 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
28 /// dropped (falls out of scope), the lock will be unlocked.
30 /// The data protected by the mutex can be accessed through this guard via its
31 /// Deref implementation.
35 /// Unlike `MutexGuard`, `ReentrantMutexGuard` does not implement `DerefMut`,
36 /// because implementation of the trait would violate Rust’s reference aliasing
37 /// rules. Use interior mutability (usually `RefCell`) in order to mutate the
39 #[must_use = "if unused the ReentrantMutex will immediately unlock"]
40 pub struct ReentrantMutexGuard<'a, T: 'a> {
41 lock: Pin<&'a ReentrantMutex<T>>,
44 impl<T> !Send for ReentrantMutexGuard<'_, T> {}
46 impl<T> ReentrantMutex<T> {
47 /// Creates a new reentrant mutex in an unlocked state.
51 /// This function is unsafe because it is required that `init` is called
52 /// once this mutex is in its final resting place, and only then are the
53 /// lock/unlock methods safe.
54 pub const unsafe fn new(t: T) -> ReentrantMutex<T> {
56 inner: sys::ReentrantMutex::uninitialized(),
58 _pinned: PhantomPinned,
62 /// Initializes this mutex so it's ready for use.
66 /// Unsafe to call more than once, and must be called after this will no
67 /// longer move in memory.
68 pub unsafe fn init(self: Pin<&mut Self>) {
69 self.get_unchecked_mut().inner.init()
72 /// Acquires a mutex, blocking the current thread until it is able to do so.
74 /// This function will block the caller until it is available to acquire the mutex.
75 /// Upon returning, the thread is the only thread with the mutex held. When the thread
76 /// calling this method already holds the lock, the call shall succeed without
81 /// If another user of this mutex panicked while holding the mutex, then
82 /// this call will return failure if the mutex would otherwise be
84 pub fn lock(self: Pin<&Self>) -> ReentrantMutexGuard<'_, T> {
85 unsafe { self.inner.lock() }
86 ReentrantMutexGuard { lock: self }
89 /// Attempts to acquire this lock.
91 /// If the lock could not be acquired at this time, then `Err` is returned.
92 /// Otherwise, an RAII guard is returned.
94 /// This function does not block.
98 /// If another user of this mutex panicked while holding the mutex, then
99 /// this call will return failure if the mutex would otherwise be
101 pub fn try_lock(self: Pin<&Self>) -> Option<ReentrantMutexGuard<'_, T>> {
102 if unsafe { self.inner.try_lock() } {
103 Some(ReentrantMutexGuard { lock: self })
110 impl<T> Drop for ReentrantMutex<T> {
112 // This is actually safe b/c we know that there is no further usage of
113 // this mutex (it's up to the user to arrange for a mutex to get
114 // dropped, that's not our job)
115 unsafe { self.inner.destroy() }
119 impl<T> Deref for ReentrantMutexGuard<'_, T> {
122 fn deref(&self) -> &T {
127 impl<T> Drop for ReentrantMutexGuard<'_, T> {
131 self.lock.inner.unlock();