library/std/src/sys_common/remutex.rs

   1 #[cfg(all(test, not(target_os = "emscripten")))]
   2 mod tests;
   3
   4 use crate::marker::PhantomPinned;
   5 use crate::ops::Deref;
   6 use crate::panic::{RefUnwindSafe, UnwindSafe};
   7 use crate::pin::Pin;
   8 use crate::sys::mutex as sys;
   9
  10 /// A re-entrant mutual exclusion
  11 ///
  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,
  17     data: T,
  18     _pinned: PhantomPinned,
  19 }
  20
  21 unsafe impl<T: Send> Send for ReentrantMutex<T> {}
  22 unsafe impl<T: Send> Sync for ReentrantMutex<T> {}
  23
  24 impl<T> UnwindSafe for ReentrantMutex<T> {}
  25 impl<T> RefUnwindSafe for ReentrantMutex<T> {}
  26
  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.
  29 ///
  30 /// The data protected by the mutex can be accessed through this guard via its
  31 /// Deref implementation.
  32 ///
  33 /// # Mutability
  34 ///
  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
  38 /// guarded data.
  39 #[must_use = "if unused the ReentrantMutex will immediately unlock"]
  40 pub struct ReentrantMutexGuard<'a, T: 'a> {
  41     lock: Pin<&'a ReentrantMutex<T>>,
  42 }
  43
  44 impl<T> !Send for ReentrantMutexGuard<'_, T> {}
  45
  46 impl<T> ReentrantMutex<T> {
  47     /// Creates a new reentrant mutex in an unlocked state.
  48     ///
  49     /// # Unsafety
  50     ///
  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> {
  55         ReentrantMutex {
  56             inner: sys::ReentrantMutex::uninitialized(),
  57             data: t,
  58             _pinned: PhantomPinned,
  59         }
  60     }
  61
  62     /// Initializes this mutex so it's ready for use.
  63     ///
  64     /// # Unsafety
  65     ///
  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()
  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     /// # Errors
  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: Pin<&Self>) -> ReentrantMutexGuard<'_, T> {
  85         unsafe { self.inner.lock() }
  86         ReentrantMutexGuard { lock: 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     /// # Errors
  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: Pin<&Self>) -> Option<ReentrantMutexGuard<'_, T>> {
 102         if unsafe { self.inner.try_lock() } {
 103             Some(ReentrantMutexGuard { lock: self })
 104         } else {
 105             None
 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> Deref for ReentrantMutexGuard<'_, T> {
 120     type Target = T;
 121
 122     fn deref(&self) -> &T {
 123         &self.lock.data
 124     }
 125 }
 126
 127 impl<T> Drop for ReentrantMutexGuard<'_, T> {
 128     #[inline]
 129     fn drop(&mut self) {
 130         unsafe {
 131             self.lock.inner.unlock();
 132         }
 133     }
 134 }