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.
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.
16 use ops
::{Deref, DerefMut}
;
17 use sys_common
::mutex
as sys
;
18 use sys_common
::poison
::{self, TryLockError, TryLockResult, LockResult}
;
20 /// A mutual exclusion primitive useful for protecting shared data
22 /// This mutex will block threads waiting for the lock to become available. The
23 /// mutex can also be statically initialized or created via a `new`
24 /// constructor. Each mutex has a type parameter which represents the data that
25 /// it is protecting. The data can only be accessed through the RAII guards
26 /// returned from `lock` and `try_lock`, which guarantees that the data is only
27 /// ever accessed when the mutex is locked.
31 /// The mutexes in this module implement a strategy called "poisoning" where a
32 /// mutex is considered poisoned whenever a thread panics while holding the
33 /// lock. Once a mutex is poisoned, all other threads are unable to access the
34 /// data by default as it is likely tainted (some invariant is not being
37 /// For a mutex, this means that the `lock` and `try_lock` methods return a
38 /// `Result` which indicates whether a mutex has been poisoned or not. Most
39 /// usage of a mutex will simply `unwrap()` these results, propagating panics
40 /// among threads to ensure that a possibly invalid invariant is not witnessed.
42 /// A poisoned mutex, however, does not prevent all access to the underlying
43 /// data. The `PoisonError` type has an `into_inner` method which will return
44 /// the guard that would have otherwise been returned on a successful lock. This
45 /// allows access to the data, despite the lock being poisoned.
50 /// use std::sync::{Arc, Mutex};
52 /// use std::sync::mpsc::channel;
54 /// const N: usize = 10;
56 /// // Spawn a few threads to increment a shared variable (non-atomically), and
57 /// // let the main thread know once all increments are done.
59 /// // Here we're using an Arc to share memory among threads, and the data inside
60 /// // the Arc is protected with a mutex.
61 /// let data = Arc::new(Mutex::new(0));
63 /// let (tx, rx) = channel();
65 /// let (data, tx) = (data.clone(), tx.clone());
66 /// thread::spawn(move || {
67 /// // The shared static can only be accessed once the lock is held.
68 /// // Our non-atomic increment is safe because we're the only thread
69 /// // which can access the shared state when the lock is held.
71 /// // We unwrap() the return value to assert that we are not expecting
72 /// // threads to ever fail while holding the lock.
73 /// let mut data = data.lock().unwrap();
76 /// tx.send(()).unwrap();
78 /// // the lock is unlocked here when `data` goes out of scope.
82 /// rx.recv().unwrap();
85 /// To recover from a poisoned mutex:
88 /// use std::sync::{Arc, Mutex};
91 /// let lock = Arc::new(Mutex::new(0_u32));
92 /// let lock2 = lock.clone();
94 /// let _ = thread::spawn(move || -> () {
95 /// // This thread will acquire the mutex first, unwrapping the result of
96 /// // `lock` because the lock has not been poisoned.
97 /// let _lock = lock2.lock().unwrap();
99 /// // This panic while holding the lock (`_guard` is in scope) will poison
104 /// // The lock is poisoned by this point, but the returned result can be
105 /// // pattern matched on to return the underlying guard on both branches.
106 /// let mut guard = match lock.lock() {
107 /// Ok(guard) => guard,
108 /// Err(poisoned) => poisoned.into_inner(),
113 #[stable(feature = "rust1", since = "1.0.0")]
114 pub struct Mutex
<T
: ?Sized
> {
115 // Note that this static mutex is in a *box*, not inlined into the struct
116 // itself. Once a native mutex has been used once, its address can never
117 // change (it can't be moved). This mutex type can be safely moved at any
118 // time, so to ensure that the native mutex is used correctly we box the
119 // inner lock to give it a constant address.
120 inner
: Box
<StaticMutex
>,
124 // these are the only places where `T: Send` matters; all other
125 // functionality works fine on a single thread.
126 unsafe impl<T
: ?Sized
+ Send
> Send
for Mutex
<T
> { }
128 unsafe impl<T
: ?Sized
+ Send
> Sync
for Mutex
<T
> { }
130 /// The static mutex type is provided to allow for static allocation of mutexes.
132 /// Note that this is a separate type because using a Mutex correctly means that
133 /// it needs to have a destructor run. In Rust, statics are not allowed to have
134 /// destructors. As a result, a `StaticMutex` has one extra method when compared
135 /// to a `Mutex`, a `destroy` method. This method is unsafe to call, and
136 /// documentation can be found directly on the method.
141 /// #![feature(static_mutex)]
143 /// use std::sync::{StaticMutex, MUTEX_INIT};
145 /// static LOCK: StaticMutex = MUTEX_INIT;
148 /// let _g = LOCK.lock().unwrap();
149 /// // do some productive work
151 /// // lock is unlocked here.
153 #[unstable(feature = "static_mutex",
154 reason
= "may be merged with Mutex in the future")]
155 pub struct StaticMutex
{
157 poison
: poison
::Flag
,
160 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
161 /// dropped (falls out of scope), the lock will be unlocked.
163 /// The data protected by the mutex can be access through this guard via its
164 /// `Deref` and `DerefMut` implementations
166 #[stable(feature = "rust1", since = "1.0.0")]
167 pub struct MutexGuard
<'a
, T
: ?Sized
+ 'a
> {
168 // funny underscores due to how Deref/DerefMut currently work (they
169 // disregard field privacy).
170 __lock
: &'a StaticMutex
,
171 __data
: &'a UnsafeCell
<T
>,
172 __poison
: poison
::Guard
,
175 impl<'a
, T
: ?Sized
> !marker
::Send
for MutexGuard
<'a
, T
> {}
177 /// Static initialization of a mutex. This constant can be used to initialize
178 /// other mutex constants.
179 #[unstable(feature = "static_mutex",
180 reason
= "may be merged with Mutex in the future")]
181 pub const MUTEX_INIT
: StaticMutex
= StaticMutex
::new();
184 /// Creates a new mutex in an unlocked state ready for use.
185 #[stable(feature = "rust1", since = "1.0.0")]
186 pub fn new(t
: T
) -> Mutex
<T
> {
188 inner
: box StaticMutex
::new(),
189 data
: UnsafeCell
::new(t
),
194 impl<T
: ?Sized
> Mutex
<T
> {
195 /// Acquires a mutex, blocking the current thread until it is able to do so.
197 /// This function will block the local thread until it is available to acquire
198 /// the mutex. Upon returning, the thread is the only thread with the mutex
199 /// held. An RAII guard is returned to allow scoped unlock of the lock. When
200 /// the guard goes out of scope, the mutex will be unlocked.
204 /// If another user of this mutex panicked while holding the mutex, then
205 /// this call will return an error once the mutex is acquired.
206 #[stable(feature = "rust1", since = "1.0.0")]
207 pub fn lock(&self) -> LockResult
<MutexGuard
<T
>> {
208 unsafe { self.inner.lock.lock() }
209 MutexGuard
::new(&*self.inner
, &self.data
)
212 /// Attempts to acquire this lock.
214 /// If the lock could not be acquired at this time, then `Err` is returned.
215 /// Otherwise, an RAII guard is returned. The lock will be unlocked when the
216 /// guard is dropped.
218 /// This function does not block.
222 /// If another user of this mutex panicked while holding the mutex, then
223 /// this call will return failure if the mutex would otherwise be
225 #[stable(feature = "rust1", since = "1.0.0")]
226 pub fn try_lock(&self) -> TryLockResult
<MutexGuard
<T
>> {
227 if unsafe { self.inner.lock.try_lock() }
{
228 Ok(try
!(MutexGuard
::new(&*self.inner
, &self.data
)))
230 Err(TryLockError
::WouldBlock
)
234 /// Determines whether the lock is poisoned.
236 /// If another thread is active, the lock can still become poisoned at any
237 /// time. You should not trust a `false` value for program correctness
238 /// without additional synchronization.
240 #[stable(feature = "sync_poison", since = "1.2.0")]
241 pub fn is_poisoned(&self) -> bool
{
242 self.inner
.poison
.get()
246 #[stable(feature = "rust1", since = "1.0.0")]
247 impl<T
: ?Sized
> Drop
for Mutex
<T
> {
249 // This is actually safe b/c we know that there is no further usage of
250 // this mutex (it's up to the user to arrange for a mutex to get
251 // dropped, that's not our job)
252 unsafe { self.inner.lock.destroy() }
256 #[stable(feature = "rust1", since = "1.0.0")]
257 impl<T
: ?Sized
+ fmt
::Debug
+ '
static> fmt
::Debug
for Mutex
<T
> {
258 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
259 match self.try_lock() {
260 Ok(guard
) => write
!(f
, "Mutex {{ data: {:?} }}", &*guard
),
261 Err(TryLockError
::Poisoned(err
)) => {
262 write
!(f
, "Mutex {{ data: Poisoned({:?}) }}", &**err
.get_ref())
264 Err(TryLockError
::WouldBlock
) => write
!(f
, "Mutex {{ <locked> }}")
269 struct Dummy(UnsafeCell
<()>);
270 unsafe impl Sync
for Dummy {}
271 static DUMMY
: Dummy
= Dummy(UnsafeCell
::new(()));
273 #[unstable(feature = "static_mutex",
274 reason
= "may be merged with Mutex in the future")]
276 /// Creates a new mutex in an unlocked state ready for use.
277 pub const fn new() -> StaticMutex
{
279 lock
: sys
::Mutex
::new(),
280 poison
: poison
::Flag
::new(),
284 /// Acquires this lock, see `Mutex::lock`
286 pub fn lock(&'
static self) -> LockResult
<MutexGuard
<()>> {
287 unsafe { self.lock.lock() }
288 MutexGuard
::new(self, &DUMMY
.0)
291 /// Attempts to grab this lock, see `Mutex::try_lock`
293 pub fn try_lock(&'
static self) -> TryLockResult
<MutexGuard
<()>> {
294 if unsafe { self.lock.try_lock() }
{
295 Ok(try
!(MutexGuard
::new(self, &DUMMY
.0)))
297 Err(TryLockError
::WouldBlock
)
301 /// Deallocates resources associated with this static mutex.
303 /// This method is unsafe because it provides no guarantees that there are
304 /// no active users of this mutex, and safety is not guaranteed if there are
305 /// active users of this mutex.
307 /// This method is required to ensure that there are no memory leaks on
308 /// *all* platforms. It may be the case that some platforms do not leak
309 /// memory if this method is not called, but this is not guaranteed to be
310 /// true on all platforms.
311 pub unsafe fn destroy(&'
static self) {
316 impl<'mutex
, T
: ?Sized
> MutexGuard
<'mutex
, T
> {
318 fn new(lock
: &'mutex StaticMutex
, data
: &'mutex UnsafeCell
<T
>)
319 -> LockResult
<MutexGuard
<'mutex
, T
>> {
320 poison
::map_result(lock
.poison
.borrow(), |guard
| {
330 #[stable(feature = "rust1", since = "1.0.0")]
331 impl<'mutex
, T
: ?Sized
> Deref
for MutexGuard
<'mutex
, T
> {
334 fn deref
<'a
>(&'a
self) -> &'a T
{
335 unsafe { &*self.__data.get() }
338 #[stable(feature = "rust1", since = "1.0.0")]
339 impl<'mutex
, T
: ?Sized
> DerefMut
for MutexGuard
<'mutex
, T
> {
340 fn deref_mut
<'a
>(&'a
mut self) -> &'a
mut T
{
341 unsafe { &mut *self.__data.get() }
345 #[stable(feature = "rust1", since = "1.0.0")]
346 impl<'a
, T
: ?Sized
> Drop
for MutexGuard
<'a
, T
> {
350 self.__lock
.poison
.done(&self.__poison
);
351 self.__lock
.lock
.unlock();
356 pub fn guard_lock
<'a
, T
: ?Sized
>(guard
: &MutexGuard
<'a
, T
>) -> &'a sys
::Mutex
{
360 pub fn guard_poison
<'a
, T
: ?Sized
>(guard
: &MutexGuard
<'a
, T
>) -> &'a poison
::Flag
{
368 use sync
::mpsc
::channel
;
369 use sync
::{Arc, Mutex, StaticMutex, Condvar}
;
372 struct Packet
<T
: Send
>(Arc
<(Mutex
<T
>, Condvar
)>);
374 unsafe impl<T
: Send
> Send
for Packet
<T
> {}
375 unsafe impl<T
> Sync
for Packet
<T
> {}
379 let m
= Mutex
::new(());
380 drop(m
.lock().unwrap());
381 drop(m
.lock().unwrap());
386 static M
: StaticMutex
= StaticMutex
::new();
388 drop(M
.lock().unwrap());
389 drop(M
.lock().unwrap());
396 static M
: StaticMutex
= StaticMutex
::new();
397 static mut CNT
: u32 = 0;
404 let _g
= M
.lock().unwrap();
410 let (tx
, rx
) = channel();
412 let tx2
= tx
.clone();
413 thread
::spawn(move|| { inc(); tx2.send(()).unwrap(); }
);
414 let tx2
= tx
.clone();
415 thread
::spawn(move|| { inc(); tx2.send(()).unwrap(); }
);
422 assert_eq
!(unsafe {CNT}
, J
* K
* 2);
430 let m
= Mutex
::new(());
431 *m
.try_lock().unwrap() = ();
435 fn test_mutex_arc_condvar() {
436 let packet
= Packet(Arc
::new((Mutex
::new(false), Condvar
::new())));
437 let packet2
= Packet(packet
.0.clone());
438 let (tx
, rx
) = channel();
439 let _t
= thread
::spawn(move|| {
440 // wait until parent gets in
442 let &(ref lock
, ref cvar
) = &*packet2
.0
;
443 let mut lock
= lock
.lock().unwrap();
448 let &(ref lock
, ref cvar
) = &*packet
.0;
449 let mut lock
= lock
.lock().unwrap();
450 tx
.send(()).unwrap();
453 lock
= cvar
.wait(lock
).unwrap();
458 fn test_arc_condvar_poison() {
459 let packet
= Packet(Arc
::new((Mutex
::new(1), Condvar
::new())));
460 let packet2
= Packet(packet
.0.clone());
461 let (tx
, rx
) = channel();
463 let _t
= thread
::spawn(move || -> () {
465 let &(ref lock
, ref cvar
) = &*packet2
.0
;
466 let _g
= lock
.lock().unwrap();
468 // Parent should fail when it wakes up.
472 let &(ref lock
, ref cvar
) = &*packet
.0;
473 let mut lock
= lock
.lock().unwrap();
474 tx
.send(()).unwrap();
476 match cvar
.wait(lock
) {
479 assert_eq
!(*lock
, 1);
487 fn test_mutex_arc_poison() {
488 let arc
= Arc
::new(Mutex
::new(1));
489 assert
!(!arc
.is_poisoned());
490 let arc2
= arc
.clone();
491 let _
= thread
::spawn(move|| {
492 let lock
= arc2
.lock().unwrap();
493 assert_eq
!(*lock
, 2);
495 assert
!(arc
.lock().is_err());
496 assert
!(arc
.is_poisoned());
500 fn test_mutex_arc_nested() {
501 // Tests nested mutexes and access
502 // to underlying data.
503 let arc
= Arc
::new(Mutex
::new(1));
504 let arc2
= Arc
::new(Mutex
::new(arc
));
505 let (tx
, rx
) = channel();
506 let _t
= thread
::spawn(move|| {
507 let lock
= arc2
.lock().unwrap();
508 let lock2
= lock
.lock().unwrap();
509 assert_eq
!(*lock2
, 1);
510 tx
.send(()).unwrap();
516 fn test_mutex_arc_access_in_unwind() {
517 let arc
= Arc
::new(Mutex
::new(1));
518 let arc2
= arc
.clone();
519 let _
= thread
::spawn(move|| -> () {
523 impl Drop
for Unwinder
{
525 *self.i
.lock().unwrap() += 1;
528 let _u
= Unwinder { i: arc2 }
;
531 let lock
= arc
.lock().unwrap();
532 assert_eq
!(*lock
, 2);
535 // FIXME(#25351) needs deeply nested coercions of DST structs.
537 // fn test_mutex_unsized() {
538 // let mutex: &Mutex<[i32]> = &Mutex::new([1, 2, 3]);
540 // let b = &mut *mutex.lock().unwrap();
544 // let comp: &[i32] = &[4, 2, 5];
545 // assert_eq!(&*mutex.lock().unwrap(), comp);