1 // Copyright 2015 The Rust Project Developers. See the COPYRIGHT
2 // file at the top-level directory of this distribution and at
3 // http://rust-lang.org/COPYRIGHT.
5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
8 // option. This file may not be copied, modified, or distributed
9 // except according to those terms.
10 #![unstable(feature = "reentrant_mutex", reason = "new API")]
17 use sys_common::poison::{self, TryLockError, TryLockResult, LockResult};
18 use sys::mutex as sys;
20 /// A re-entrant mutual exclusion
22 /// This mutex will block *other* threads waiting for the lock to become
23 /// available. The thread which has already locked the mutex can lock it
24 /// multiple times without blocking, preventing a common source of deadlocks.
25 pub struct ReentrantMutex<T> {
26 inner: Box<sys::ReentrantMutex>,
31 unsafe impl<T: Send> Send for ReentrantMutex<T> {}
32 unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
35 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
36 /// dropped (falls out of scope), the lock will be unlocked.
38 /// The data protected by the mutex can be accessed through this guard via its
39 /// Deref implementation.
43 /// Unlike `MutexGuard`, `ReentrantMutexGuard` does not implement `DerefMut`,
44 /// because implementation of the trait would violate Rust’s reference aliasing
45 /// rules. Use interior mutability (usually `RefCell`) in order to mutate the
48 pub struct ReentrantMutexGuard<'a, T: 'a> {
49 // funny underscores due to how Deref currently works (it disregards field
51 __lock: &'a ReentrantMutex<T>,
52 __poison: poison::Guard,
55 impl<'a, T> !marker::Send for ReentrantMutexGuard<'a, T> {}
58 impl<T> ReentrantMutex<T> {
59 /// Creates a new reentrant mutex in an unlocked state.
60 pub fn new(t: T) -> ReentrantMutex<T> {
62 let mut mutex = ReentrantMutex {
63 inner: box sys::ReentrantMutex::uninitialized(),
64 poison: poison::Flag::new(),
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) -> LockResult<ReentrantMutexGuard<T>> {
85 unsafe { self.inner.lock() }
86 ReentrantMutexGuard::new(&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) -> TryLockResult<ReentrantMutexGuard<T>> {
102 if unsafe { self.inner.try_lock() } {
103 Ok(try!(ReentrantMutexGuard::new(&self)))
105 Err(TryLockError::WouldBlock)
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: fmt::Debug + 'static> fmt::Debug for ReentrantMutex<T> {
120 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
121 match self.try_lock() {
122 Ok(guard) => write!(f, "ReentrantMutex {{ data: {:?} }}", &*guard),
123 Err(TryLockError::Poisoned(err)) => {
124 write!(f, "ReentrantMutex {{ data: Poisoned({:?}) }}", &**err.get_ref())
126 Err(TryLockError::WouldBlock) => write!(f, "ReentrantMutex {{ <locked> }}")
131 impl<'mutex, T> ReentrantMutexGuard<'mutex, T> {
132 fn new(lock: &'mutex ReentrantMutex<T>)
133 -> LockResult<ReentrantMutexGuard<'mutex, T>> {
134 poison::map_result(lock.poison.borrow(), |guard| {
135 ReentrantMutexGuard {
143 impl<'mutex, T> Deref for ReentrantMutexGuard<'mutex, T> {
146 fn deref<'a>(&'a self) -> &'a T {
151 impl<'a, T> Drop for ReentrantMutexGuard<'a, T> {
155 self.__lock.poison.done(&self.__poison);
156 self.__lock.inner.unlock();
165 use sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
173 let m = ReentrantMutex::new(());
175 let a = m.lock().unwrap();
177 let b = m.lock().unwrap();
179 let c = m.lock().unwrap();
190 let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
192 let lock = m.lock().unwrap();
193 let child = thread::spawn(move || {
194 let lock = m2.lock().unwrap();
195 assert_eq!(*lock.borrow(), 4950);
198 let lock = m.lock().unwrap();
199 *lock.borrow_mut() += i;
202 child.join().unwrap();
207 let m = Arc::new(ReentrantMutex::new(()));
209 let lock = m.try_lock().unwrap();
210 let lock2 = m.try_lock().unwrap();
211 thread::spawn(move || {
212 let lock = m2.try_lock();
213 assert!(lock.is_err());
215 let lock3 = m.try_lock().unwrap();
218 pub struct Answer<'a>(pub ReentrantMutexGuard<'a, RefCell<u32>>);
219 impl<'a> Drop for Answer<'a> {
221 *self.0.borrow_mut() = 42;
227 let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
229 let result = thread::spawn(move ||{
230 let lock = mc.lock().unwrap();
231 *lock.borrow_mut() = 1;
232 let lock2 = mc.lock().unwrap();
233 *lock.borrow_mut() = 2;
234 let answer = Answer(lock2);
235 panic!("What the answer to my lifetimes dilemma is?");
238 assert!(result.is_err());
239 let r = m.lock().err().unwrap().into_inner();
240 assert_eq!(*r.borrow(), 42);