4 use crate::panic::{RefUnwindSafe, UnwindSafe};
5 use crate::sys::mutex as sys;
6 use crate::sys_common::poison::{self, LockResult, TryLockError, TryLockResult};
8 /// A re-entrant mutual exclusion
10 /// This mutex will block *other* threads waiting for the lock to become
11 /// available. The thread which has already locked the mutex can lock it
12 /// multiple times without blocking, preventing a common source of deadlocks.
13 pub struct ReentrantMutex<T> {
14 inner: Box<sys::ReentrantMutex>,
19 unsafe impl<T: Send> Send for ReentrantMutex<T> {}
20 unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
22 impl<T> UnwindSafe for ReentrantMutex<T> {}
23 impl<T> RefUnwindSafe for ReentrantMutex<T> {}
25 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
26 /// dropped (falls out of scope), the lock will be unlocked.
28 /// The data protected by the mutex can be accessed through this guard via its
29 /// Deref implementation.
33 /// Unlike `MutexGuard`, `ReentrantMutexGuard` does not implement `DerefMut`,
34 /// because implementation of the trait would violate Rust’s reference aliasing
35 /// rules. Use interior mutability (usually `RefCell`) in order to mutate the
37 #[must_use = "if unused the ReentrantMutex will immediately unlock"]
38 pub struct ReentrantMutexGuard<'a, T: 'a> {
39 // funny underscores due to how Deref currently works (it disregards field
41 __lock: &'a ReentrantMutex<T>,
42 __poison: poison::Guard,
45 impl<T> !marker::Send for ReentrantMutexGuard<'_, T> {}
47 impl<T> ReentrantMutex<T> {
48 /// Creates a new reentrant mutex in an unlocked state.
49 pub fn new(t: T) -> ReentrantMutex<T> {
51 let mut mutex = ReentrantMutex {
52 inner: box sys::ReentrantMutex::uninitialized(),
53 poison: poison::Flag::new(),
61 /// Acquires a mutex, blocking the current thread until it is able to do so.
63 /// This function will block the caller until it is available to acquire the mutex.
64 /// Upon returning, the thread is the only thread with the mutex held. When the thread
65 /// calling this method already holds the lock, the call shall succeed without
70 /// If another user of this mutex panicked while holding the mutex, then
71 /// this call will return failure if the mutex would otherwise be
73 pub fn lock(&self) -> LockResult<ReentrantMutexGuard<'_, T>> {
74 unsafe { self.inner.lock() }
75 ReentrantMutexGuard::new(&self)
78 /// Attempts to acquire this lock.
80 /// If the lock could not be acquired at this time, then `Err` is returned.
81 /// Otherwise, an RAII guard is returned.
83 /// This function does not block.
87 /// If another user of this mutex panicked while holding the mutex, then
88 /// this call will return failure if the mutex would otherwise be
90 pub fn try_lock(&self) -> TryLockResult<ReentrantMutexGuard<'_, T>> {
91 if unsafe { self.inner.try_lock() } {
92 Ok(ReentrantMutexGuard::new(&self)?)
94 Err(TryLockError::WouldBlock)
99 impl<T> Drop for ReentrantMutex<T> {
101 // This is actually safe b/c we know that there is no further usage of
102 // this mutex (it's up to the user to arrange for a mutex to get
103 // dropped, that's not our job)
104 unsafe { self.inner.destroy() }
108 impl<T: fmt::Debug + 'static> fmt::Debug for ReentrantMutex<T> {
109 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
110 match self.try_lock() {
111 Ok(guard) => f.debug_struct("ReentrantMutex").field("data", &*guard).finish(),
112 Err(TryLockError::Poisoned(err)) => {
113 f.debug_struct("ReentrantMutex").field("data", &**err.get_ref()).finish()
115 Err(TryLockError::WouldBlock) => {
116 struct LockedPlaceholder;
117 impl fmt::Debug for LockedPlaceholder {
118 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
119 f.write_str("<locked>")
123 f.debug_struct("ReentrantMutex").field("data", &LockedPlaceholder).finish()
129 impl<'mutex, T> ReentrantMutexGuard<'mutex, T> {
130 fn new(lock: &'mutex ReentrantMutex<T>) -> LockResult<ReentrantMutexGuard<'mutex, T>> {
131 poison::map_result(lock.poison.borrow(), |guard| ReentrantMutexGuard {
138 impl<T> Deref for ReentrantMutexGuard<'_, T> {
141 fn deref(&self) -> &T {
146 impl<T> Drop for ReentrantMutexGuard<'_, T> {
150 self.__lock.poison.done(&self.__poison);
151 self.__lock.inner.unlock();
156 #[cfg(all(test, not(target_os = "emscripten")))]
158 use crate::cell::RefCell;
159 use crate::sync::Arc;
160 use crate::sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
165 let m = ReentrantMutex::new(());
167 let a = m.lock().unwrap();
169 let b = m.lock().unwrap();
171 let c = m.lock().unwrap();
182 let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
184 let lock = m.lock().unwrap();
185 let child = thread::spawn(move || {
186 let lock = m2.lock().unwrap();
187 assert_eq!(*lock.borrow(), 4950);
190 let lock = m.lock().unwrap();
191 *lock.borrow_mut() += i;
194 child.join().unwrap();
199 let m = Arc::new(ReentrantMutex::new(()));
201 let _lock = m.try_lock().unwrap();
202 let _lock2 = m.try_lock().unwrap();
203 thread::spawn(move || {
204 let lock = m2.try_lock();
205 assert!(lock.is_err());
209 let _lock3 = m.try_lock().unwrap();
212 pub struct Answer<'a>(pub ReentrantMutexGuard<'a, RefCell<u32>>);
213 impl Drop for Answer<'_> {
215 *self.0.borrow_mut() = 42;
221 let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
223 let result = thread::spawn(move || {
224 let lock = mc.lock().unwrap();
225 *lock.borrow_mut() = 1;
226 let lock2 = mc.lock().unwrap();
227 *lock.borrow_mut() = 2;
228 let _answer = Answer(lock2);
229 panic!("What the answer to my lifetimes dilemma is?");
232 assert!(result.is_err());
233 let r = m.lock().err().unwrap().into_inner();
234 assert_eq!(*r.borrow(), 42);