]>
Commit | Line | Data |
---|---|---|
532ac7d7 | 1 | use crate::sys::mutex as imp; |
1a4d82fc JJ |
2 | |
3 | /// An OS-based mutual exclusion lock. | |
4 | /// | |
5 | /// This is the thinnest cross-platform wrapper around OS mutexes. All usage of | |
6 | /// this mutex is unsafe and it is recommended to instead use the safe wrapper | |
7 | /// at the top level of the crate instead of this type. | |
8 | pub struct Mutex(imp::Mutex); | |
9 | ||
10 | unsafe impl Sync for Mutex {} | |
11 | ||
1a4d82fc | 12 | impl Mutex { |
62682a34 SL |
13 | /// Creates a new mutex for use. |
14 | /// | |
15 | /// Behavior is undefined if the mutex is moved after it is | |
16 | /// first used with any of the functions below. | |
b7449926 XL |
17 | /// Also, until `init` is called, behavior is undefined if this |
18 | /// mutex is ever used reentrantly, i.e., `raw_lock` or `try_lock` | |
19 | /// are called by the thread currently holding the lock. | |
3dfed10e | 20 | #[rustc_const_stable(feature = "const_sys_mutex_new", since = "1.0.0")] |
dfeec247 XL |
21 | pub const fn new() -> Mutex { |
22 | Mutex(imp::Mutex::new()) | |
23 | } | |
62682a34 | 24 | |
3157f602 XL |
25 | /// Prepare the mutex for use. |
26 | /// | |
27 | /// This should be called once the mutex is at a stable memory address. | |
b7449926 XL |
28 | /// If called, this must be the very first thing that happens to the mutex. |
29 | /// Calling it in parallel with or after any operation (including another | |
30 | /// `init()`) is undefined behavior. | |
3157f602 | 31 | #[inline] |
dfeec247 XL |
32 | pub unsafe fn init(&mut self) { |
33 | self.0.init() | |
34 | } | |
3157f602 | 35 | |
9346a6ac | 36 | /// Locks the mutex blocking the current thread until it is available. |
1a4d82fc JJ |
37 | /// |
38 | /// Behavior is undefined if the mutex has been moved between this and any | |
39 | /// previous function call. | |
40 | #[inline] | |
dfeec247 XL |
41 | pub unsafe fn raw_lock(&self) { |
42 | self.0.lock() | |
43 | } | |
94b46f34 XL |
44 | |
45 | /// Calls raw_lock() and then returns an RAII guard to guarantee the mutex | |
46 | /// will be unlocked. | |
47 | #[inline] | |
532ac7d7 | 48 | pub unsafe fn lock(&self) -> MutexGuard<'_> { |
94b46f34 XL |
49 | self.raw_lock(); |
50 | MutexGuard(&self.0) | |
51 | } | |
1a4d82fc | 52 | |
9346a6ac | 53 | /// Attempts to lock the mutex without blocking, returning whether it was |
1a4d82fc JJ |
54 | /// successfully acquired or not. |
55 | /// | |
56 | /// Behavior is undefined if the mutex has been moved between this and any | |
57 | /// previous function call. | |
58 | #[inline] | |
dfeec247 XL |
59 | pub unsafe fn try_lock(&self) -> bool { |
60 | self.0.try_lock() | |
61 | } | |
1a4d82fc | 62 | |
9346a6ac | 63 | /// Unlocks the mutex. |
1a4d82fc JJ |
64 | /// |
65 | /// Behavior is undefined if the current thread does not actually hold the | |
66 | /// mutex. | |
94b46f34 XL |
67 | /// |
68 | /// Consider switching from the pair of raw_lock() and raw_unlock() to | |
69 | /// lock() whenever possible. | |
1a4d82fc | 70 | #[inline] |
dfeec247 XL |
71 | pub unsafe fn raw_unlock(&self) { |
72 | self.0.unlock() | |
73 | } | |
1a4d82fc | 74 | |
9346a6ac | 75 | /// Deallocates all resources associated with this mutex. |
1a4d82fc JJ |
76 | /// |
77 | /// Behavior is undefined if there are current or will be future users of | |
78 | /// this mutex. | |
79 | #[inline] | |
dfeec247 XL |
80 | pub unsafe fn destroy(&self) { |
81 | self.0.destroy() | |
82 | } | |
1a4d82fc JJ |
83 | } |
84 | ||
85 | // not meant to be exported to the outside world, just the containing module | |
dfeec247 XL |
86 | pub fn raw(mutex: &Mutex) -> &imp::Mutex { |
87 | &mutex.0 | |
88 | } | |
94b46f34 XL |
89 | |
90 | #[must_use] | |
91 | /// A simple RAII utility for the above Mutex without the poisoning semantics. | |
92 | pub struct MutexGuard<'a>(&'a imp::Mutex); | |
93 | ||
9fa01778 | 94 | impl Drop for MutexGuard<'_> { |
94b46f34 XL |
95 | #[inline] |
96 | fn drop(&mut self) { | |
dfeec247 XL |
97 | unsafe { |
98 | self.0.unlock(); | |
99 | } | |
94b46f34 XL |
100 | } |
101 | } |