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
  11 #![unstable(feature = "reentrant_mutex", reason = "new API",
  12             issue = "27738")]
  13
  14 use prelude::v1::*;
  15
  16 use fmt;
  17 use marker;
  18 use ops::Deref;
  19 use sys_common::poison::{self, TryLockError, TryLockResult, LockResult};
  20 use sys::mutex as sys;
  21
  22 /// A re-entrant mutual exclusion
  23 ///
  24 /// This mutex will block *other* threads waiting for the lock to become
  25 /// available. The thread which has already locked the mutex can lock it
  26 /// multiple times without blocking, preventing a common source of deadlocks.
  27 pub struct ReentrantMutex<T> {
  28     inner: Box<sys::ReentrantMutex>,
  29     poison: poison::Flag,
  30     data: T,
  31 }
  32
  33 unsafe impl<T: Send> Send for ReentrantMutex<T> {}
  34 unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
  35
  36
  37 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
  38 /// dropped (falls out of scope), the lock will be unlocked.
  39 ///
  40 /// The data protected by the mutex can be accessed through this guard via its
  41 /// Deref implementation.
  42 ///
  43 /// # Mutability
  44 ///
  45 /// Unlike `MutexGuard`, `ReentrantMutexGuard` does not implement `DerefMut`,
  46 /// because implementation of the trait would violate Rust’s reference aliasing
  47 /// rules. Use interior mutability (usually `RefCell`) in order to mutate the
  48 /// guarded data.
  49 #[must_use]
  50 pub struct ReentrantMutexGuard<'a, T: 'a> {
  51     // funny underscores due to how Deref currently works (it disregards field
  52     // privacy).
  53     __lock: &'a ReentrantMutex<T>,
  54     __poison: poison::Guard,
  55 }
  56
  57 impl<'a, T> !marker::Send for ReentrantMutexGuard<'a, T> {}
  58
  59
  60 impl<T> ReentrantMutex<T> {
  61     /// Creates a new reentrant mutex in an unlocked state.
  62     pub fn new(t: T) -> ReentrantMutex<T> {
  63         unsafe {
  64             let mut mutex = ReentrantMutex {
  65                 inner: box sys::ReentrantMutex::uninitialized(),
  66                 poison: poison::Flag::new(),
  67                 data: t,
  68             };
  69             mutex.inner.init();
  70             mutex
  71         }
  72     }
  73
  74     /// Acquires a mutex, blocking the current thread until it is able to do so.
  75     ///
  76     /// This function will block the caller until it is available to acquire the mutex.
  77     /// Upon returning, the thread is the only thread with the mutex held. When the thread
  78     /// calling this method already holds the lock, the call shall succeed without
  79     /// blocking.
  80     ///
  81     /// # Failure
  82     ///
  83     /// If another user of this mutex panicked while holding the mutex, then
  84     /// this call will return failure if the mutex would otherwise be
  85     /// acquired.
  86     pub fn lock(&self) -> LockResult<ReentrantMutexGuard<T>> {
  87         unsafe { self.inner.lock() }
  88         ReentrantMutexGuard::new(&self)
  89     }
  90
  91     /// Attempts to acquire this lock.
  92     ///
  93     /// If the lock could not be acquired at this time, then `Err` is returned.
  94     /// Otherwise, an RAII guard is returned.
  95     ///
  96     /// This function does not block.
  97     ///
  98     /// # Failure
  99     ///
 100     /// If another user of this mutex panicked while holding the mutex, then
 101     /// this call will return failure if the mutex would otherwise be
 102     /// acquired.
 103     pub fn try_lock(&self) -> TryLockResult<ReentrantMutexGuard<T>> {
 104         if unsafe { self.inner.try_lock() } {
 105             Ok(try!(ReentrantMutexGuard::new(&self)))
 106         } else {
 107             Err(TryLockError::WouldBlock)
 108         }
 109     }
 110 }
 111
 112 impl<T> Drop for ReentrantMutex<T> {
 113     fn drop(&mut self) {
 114         // This is actually safe b/c we know that there is no further usage of
 115         // this mutex (it's up to the user to arrange for a mutex to get
 116         // dropped, that's not our job)
 117         unsafe { self.inner.destroy() }
 118     }
 119 }
 120
 121 impl<T: fmt::Debug + 'static> fmt::Debug for ReentrantMutex<T> {
 122     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 123         match self.try_lock() {
 124             Ok(guard) => write!(f, "ReentrantMutex {{ data: {:?} }}", &*guard),
 125             Err(TryLockError::Poisoned(err)) => {
 126                 write!(f, "ReentrantMutex {{ data: Poisoned({:?}) }}", &**err.get_ref())
 127             },
 128             Err(TryLockError::WouldBlock) => write!(f, "ReentrantMutex {{ <locked> }}")
 129         }
 130     }
 131 }
 132
 133 impl<'mutex, T> ReentrantMutexGuard<'mutex, T> {
 134     fn new(lock: &'mutex ReentrantMutex<T>)
 135             -> LockResult<ReentrantMutexGuard<'mutex, T>> {
 136         poison::map_result(lock.poison.borrow(), |guard| {
 137             ReentrantMutexGuard {
 138                 __lock: lock,
 139                 __poison: guard,
 140             }
 141         })
 142     }
 143 }
 144
 145 impl<'mutex, T> Deref for ReentrantMutexGuard<'mutex, T> {
 146     type Target = T;
 147
 148     fn deref(&self) -> &T {
 149         &self.__lock.data
 150     }
 151 }
 152
 153 impl<'a, T> Drop for ReentrantMutexGuard<'a, T> {
 154     #[inline]
 155     fn drop(&mut self) {
 156         unsafe {
 157             self.__lock.poison.done(&self.__poison);
 158             self.__lock.inner.unlock();
 159         }
 160     }
 161 }
 162
 163
 164 #[cfg(test)]
 165 mod tests {
 166     use prelude::v1::*;
 167     use sys_common::remutex::{ReentrantMutex, ReentrantMutexGuard};
 168     use cell::RefCell;
 169     use sync::Arc;
 170     use boxed;
 171     use thread;
 172
 173     #[test]
 174     fn smoke() {
 175         let m = ReentrantMutex::new(());
 176         {
 177             let a = m.lock().unwrap();
 178             {
 179                 let b = m.lock().unwrap();
 180                 {
 181                     let c = m.lock().unwrap();
 182                     assert_eq!(*c, ());
 183                 }
 184                 assert_eq!(*b, ());
 185             }
 186             assert_eq!(*a, ());
 187         }
 188     }
 189
 190     #[test]
 191     fn is_mutex() {
 192         let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
 193         let m2 = m.clone();
 194         let lock = m.lock().unwrap();
 195         let child = thread::spawn(move || {
 196             let lock = m2.lock().unwrap();
 197             assert_eq!(*lock.borrow(), 4950);
 198         });
 199         for i in 0..100 {
 200             let lock = m.lock().unwrap();
 201             *lock.borrow_mut() += i;
 202         }
 203         drop(lock);
 204         child.join().unwrap();
 205     }
 206
 207     #[test]
 208     fn trylock_works() {
 209         let m = Arc::new(ReentrantMutex::new(()));
 210         let m2 = m.clone();
 211         let lock = m.try_lock().unwrap();
 212         let lock2 = m.try_lock().unwrap();
 213         thread::spawn(move || {
 214             let lock = m2.try_lock();
 215             assert!(lock.is_err());
 216         }).join().unwrap();
 217         let lock3 = m.try_lock().unwrap();
 218     }
 219
 220     pub struct Answer<'a>(pub ReentrantMutexGuard<'a, RefCell<u32>>);
 221     impl<'a> Drop for Answer<'a> {
 222         fn drop(&mut self) {
 223             *self.0.borrow_mut() = 42;
 224         }
 225     }
 226
 227     #[test]
 228     fn poison_works() {
 229         let m = Arc::new(ReentrantMutex::new(RefCell::new(0)));
 230         let mc = m.clone();
 231         let result = thread::spawn(move ||{
 232             let lock = mc.lock().unwrap();
 233             *lock.borrow_mut() = 1;
 234             let lock2 = mc.lock().unwrap();
 235             *lock.borrow_mut() = 2;
 236             let answer = Answer(lock2);
 237             panic!("What the answer to my lifetimes dilemma is?");
 238             drop(answer);
 239         }).join();
 240         assert!(result.is_err());
 241         let r = m.lock().err().unwrap().into_inner();
 242         assert_eq!(*r.borrow(), 42);
 243     }
 244 }