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