src/libstd/sys/common/remutex.rs

   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.
   4 //
   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")]
  11
  12 use prelude::v1::*;
  13
  14 use fmt;
  15 use marker;
  16 use ops::Deref;
  17 use sys_common::poison::{self, TryLockError, TryLockResult, LockResult};
  18 use sys::mutex as sys;
  19
  20 /// A re-entrant mutual exclusion
  21 ///
  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>,
  27     poison: poison::Flag,
  28     data: T,
  29 }
  30
  31 unsafe impl<T: Send> Send for ReentrantMutex<T> {}
  32 unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
  33
  34
  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.
  37 ///
  38 /// The data protected by the mutex can be accessed through this guard via its
  39 /// Deref implementation.
  40 ///
  41 /// # Mutability
  42 ///
  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
  46 /// guarded data.
  47 #[must_use]
  48 pub struct ReentrantMutexGuard<'a, T: 'a> {
  49     // funny underscores due to how Deref currently works (it disregards field
  50     // privacy).
  51     __lock: &'a ReentrantMutex<T>,
  52     __poison: poison::Guard,
  53 }
  54
  55 impl<'a, T> !marker::Send for ReentrantMutexGuard<'a, T> {}
  56
  57
  58 impl<T> ReentrantMutex<T> {
  59     /// Creates a new reentrant mutex in an unlocked state.
  60     pub fn new(t: T) -> ReentrantMutex<T> {
  61         unsafe {
  62             let mut mutex = ReentrantMutex {
  63                 inner: box sys::ReentrantMutex::uninitialized(),
  64                 poison: poison::Flag::new(),
  65                 data: t,
  66             };
  67             mutex.inner.init();
  68             return mutex
  69         }
  70     }
  71
  72     /// Acquires a mutex, blocking the current thread until it is able to do so.
  73     ///
  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
  77     /// blocking.
  78     ///
  79     /// # Failure
  80     ///
  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
  83     /// acquired.
  84     pub fn lock(&self) -> LockResult<ReentrantMutexGuard<T>> {
  85         unsafe { self.inner.lock() }
  86         ReentrantMutexGuard::new(&self)
  87     }
  88
  89     /// Attempts to acquire this lock.
  90     ///
  91     /// If the lock could not be acquired at this time, then `Err` is returned.
  92     /// Otherwise, an RAII guard is returned.
  93     ///
  94     /// This function does not block.
  95     ///
  96     /// # Failure
  97     ///
  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
 100     /// acquired.
 101     pub fn try_lock(&self) -> TryLockResult<ReentrantMutexGuard<T>> {
 102         if unsafe { self.inner.try_lock() } {
 103             Ok(try!(ReentrantMutexGuard::new(&self)))
 104         } else {
 105             Err(TryLockError::WouldBlock)
 106         }
 107     }
 108 }
 109
 110 impl<T> Drop for ReentrantMutex<T> {
 111     fn drop(&mut self) {
 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() }
 116     }
 117 }
 118
 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())
 125             },
 126             Err(TryLockError::WouldBlock) => write!(f, "ReentrantMutex {{ <locked> }}")
 127         }
 128     }
 129 }
 130
 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 {
 136                 __lock: lock,
 137                 __poison: guard,
 138             }
 139         })
 140     }
 141 }
 142
 143 impl<'mutex, T> Deref for ReentrantMutexGuard<'mutex, T> {
 144     type Target = T;
 145
 146     fn deref<'a>(&'a self) -> &'a T {
 147         &self.__lock.data
 148     }
 149 }
 150
 151 impl<'a, T> Drop for ReentrantMutexGuard<'a, T> {
 152     #[inline]
 153     fn drop(&mut self) {
 154         unsafe {
 155             self.__lock.poison.done(&self.__poison);
 156             self.__lock.inner.unlock();
 157         }
 158     }
 159 }
 160
 161
 162 #[cfg(test)]
 163 mod tests {
 164     use prelude::v1::*;
 165     use sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
 166     use cell::RefCell;
 167     use sync::Arc;
 168     use boxed;
 169     use thread;
 170
 171     #[test]
 172     fn smoke() {
 173         let m = ReentrantMutex::new(());
 174         {
 175             let a = m.lock().unwrap();
 176             {
 177                 let b = m.lock().unwrap();
 178                 {
 179                     let c = m.lock().unwrap();
 180                     assert_eq!(*c, ());
 181                 }
 182                 assert_eq!(*b, ());
 183             }
 184             assert_eq!(*a, ());
 185         }
 186     }
 187
 188     #[test]
 189     fn is_mutex() {
 190         let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
 191         let m2 = m.clone();
 192         let lock = m.lock().unwrap();
 193         let child = thread::spawn(move || {
 194             let lock = m2.lock().unwrap();
 195             assert_eq!(*lock.borrow(), 4950);
 196         });
 197         for i in 0..100 {
 198             let lock = m.lock().unwrap();
 199             *lock.borrow_mut() += i;
 200         }
 201         drop(lock);
 202         child.join().unwrap();
 203     }
 204
 205     #[test]
 206     fn trylock_works() {
 207         let m = Arc::new(ReentrantMutex::new(()));
 208         let m2 = m.clone();
 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());
 214         }).join().unwrap();
 215         let lock3 = m.try_lock().unwrap();
 216     }
 217
 218     pub struct Answer<'a>(pub ReentrantMutexGuard<'a, RefCell<u32>>);
 219     impl<'a> Drop for Answer<'a> {
 220         fn drop(&mut self) {
 221             *self.0.borrow_mut() = 42;
 222         }
 223     }
 224
 225     #[test]
 226     fn poison_works() {
 227         let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
 228         let mc = m.clone();
 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?");
 236             drop(answer);
 237         }).join();
 238         assert!(result.is_err());
 239         let r = m.lock().err().unwrap().into_inner();
 240         assert_eq!(*r.borrow(), 42);
 241     }
 242 }