4 use ops::{Deref, DerefMut};
6 use sys_common::mutex as sys;
7 use sys_common::poison::{self, TryLockError, TryLockResult, LockResult};
9 /// A mutual exclusion primitive useful for protecting shared data
11 /// This mutex will block threads waiting for the lock to become available. The
12 /// mutex can also be statically initialized or created via a [`new`]
13 /// constructor. Each mutex has a type parameter which represents the data that
14 /// it is protecting. The data can only be accessed through the RAII guards
15 /// returned from [`lock`] and [`try_lock`], which guarantees that the data is only
16 /// ever accessed when the mutex is locked.
20 /// The mutexes in this module implement a strategy called "poisoning" where a
21 /// mutex is considered poisoned whenever a thread panics while holding the
22 /// mutex. Once a mutex is poisoned, all other threads are unable to access the
23 /// data by default as it is likely tainted (some invariant is not being
26 /// For a mutex, this means that the [`lock`] and [`try_lock`] methods return a
27 /// [`Result`] which indicates whether a mutex has been poisoned or not. Most
28 /// usage of a mutex will simply [`unwrap()`] these results, propagating panics
29 /// among threads to ensure that a possibly invalid invariant is not witnessed.
31 /// A poisoned mutex, however, does not prevent all access to the underlying
32 /// data. The [`PoisonError`] type has an [`into_inner`] method which will return
33 /// the guard that would have otherwise been returned on a successful lock. This
34 /// allows access to the data, despite the lock being poisoned.
36 /// [`new`]: #method.new
37 /// [`lock`]: #method.lock
38 /// [`try_lock`]: #method.try_lock
39 /// [`Result`]: ../../std/result/enum.Result.html
40 /// [`unwrap()`]: ../../std/result/enum.Result.html#method.unwrap
41 /// [`PoisonError`]: ../../std/sync/struct.PoisonError.html
42 /// [`into_inner`]: ../../std/sync/struct.PoisonError.html#method.into_inner
47 /// use std::sync::{Arc, Mutex};
49 /// use std::sync::mpsc::channel;
51 /// const N: usize = 10;
53 /// // Spawn a few threads to increment a shared variable (non-atomically), and
54 /// // let the main thread know once all increments are done.
56 /// // Here we're using an Arc to share memory among threads, and the data inside
57 /// // the Arc is protected with a mutex.
58 /// let data = Arc::new(Mutex::new(0));
60 /// let (tx, rx) = channel();
62 /// let (data, tx) = (Arc::clone(&data), tx.clone());
63 /// thread::spawn(move || {
64 /// // The shared state can only be accessed once the lock is held.
65 /// // Our non-atomic increment is safe because we're the only thread
66 /// // which can access the shared state when the lock is held.
68 /// // We unwrap() the return value to assert that we are not expecting
69 /// // threads to ever fail while holding the lock.
70 /// let mut data = data.lock().unwrap();
73 /// tx.send(()).unwrap();
75 /// // the lock is unlocked here when `data` goes out of scope.
79 /// rx.recv().unwrap();
82 /// To recover from a poisoned mutex:
85 /// use std::sync::{Arc, Mutex};
88 /// let lock = Arc::new(Mutex::new(0_u32));
89 /// let lock2 = lock.clone();
91 /// let _ = thread::spawn(move || -> () {
92 /// // This thread will acquire the mutex first, unwrapping the result of
93 /// // `lock` because the lock has not been poisoned.
94 /// let _guard = lock2.lock().unwrap();
96 /// // This panic while holding the lock (`_guard` is in scope) will poison
101 /// // The lock is poisoned by this point, but the returned result can be
102 /// // pattern matched on to return the underlying guard on both branches.
103 /// let mut guard = match lock.lock() {
104 /// Ok(guard) => guard,
105 /// Err(poisoned) => poisoned.into_inner(),
110 #[stable(feature = "rust1", since = "1.0.0")]
111 pub struct Mutex<T: ?Sized> {
112 // Note that this mutex is in a *box*, not inlined into the struct itself.
113 // Once a native mutex has been used once, its address can never change (it
114 // can't be moved). This mutex type can be safely moved at any time, so to
115 // ensure that the native mutex is used correctly we box the inner mutex to
116 // give it a constant address.
117 inner: Box<sys::Mutex>,
118 poison: poison::Flag,
122 // these are the only places where `T: Send` matters; all other
123 // functionality works fine on a single thread.
124 #[stable(feature = "rust1", since = "1.0.0")]
125 unsafe impl<T: ?Sized + Send> Send for Mutex<T> { }
126 #[stable(feature = "rust1", since = "1.0.0")]
127 unsafe impl<T: ?Sized + Send> Sync for Mutex<T> { }
129 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
130 /// dropped (falls out of scope), the lock will be unlocked.
132 /// The data protected by the mutex can be accessed through this guard via its
133 /// [`Deref`] and [`DerefMut`] implementations.
135 /// This structure is created by the [`lock`] and [`try_lock`] methods on
138 /// [`Deref`]: ../../std/ops/trait.Deref.html
139 /// [`DerefMut`]: ../../std/ops/trait.DerefMut.html
140 /// [`lock`]: struct.Mutex.html#method.lock
141 /// [`try_lock`]: struct.Mutex.html#method.try_lock
142 /// [`Mutex`]: struct.Mutex.html
143 #[must_use = "if unused the Mutex will immediately unlock"]
144 #[stable(feature = "rust1", since = "1.0.0")]
145 pub struct MutexGuard<'a, T: ?Sized + 'a> {
146 // funny underscores due to how Deref/DerefMut currently work (they
147 // disregard field privacy).
148 __lock: &'a Mutex<T>,
149 __poison: poison::Guard,
152 #[stable(feature = "rust1", since = "1.0.0")]
153 impl<'a, T: ?Sized> !Send for MutexGuard<'a, T> { }
154 #[stable(feature = "mutexguard", since = "1.19.0")]
155 unsafe impl<'a, T: ?Sized + Sync> Sync for MutexGuard<'a, T> { }
158 /// Creates a new mutex in an unlocked state ready for use.
163 /// use std::sync::Mutex;
165 /// let mutex = Mutex::new(0);
167 #[stable(feature = "rust1", since = "1.0.0")]
168 pub fn new(t: T) -> Mutex<T> {
170 inner: box sys::Mutex::new(),
171 poison: poison::Flag::new(),
172 data: UnsafeCell::new(t),
181 impl<T: ?Sized> Mutex<T> {
182 /// Acquires a mutex, blocking the current thread until it is able to do so.
184 /// This function will block the local thread until it is available to acquire
185 /// the mutex. Upon returning, the thread is the only thread with the lock
186 /// held. An RAII guard is returned to allow scoped unlock of the lock. When
187 /// the guard goes out of scope, the mutex will be unlocked.
189 /// The exact behavior on locking a mutex in the thread which already holds
190 /// the lock is left unspecified. However, this function will not return on
191 /// the second call (it might panic or deadlock, for example).
195 /// If another user of this mutex panicked while holding the mutex, then
196 /// this call will return an error once the mutex is acquired.
200 /// This function might panic when called if the lock is already held by
201 /// the current thread.
206 /// use std::sync::{Arc, Mutex};
209 /// let mutex = Arc::new(Mutex::new(0));
210 /// let c_mutex = mutex.clone();
212 /// thread::spawn(move || {
213 /// *c_mutex.lock().unwrap() = 10;
214 /// }).join().expect("thread::spawn failed");
215 /// assert_eq!(*mutex.lock().unwrap(), 10);
217 #[stable(feature = "rust1", since = "1.0.0")]
218 pub fn lock(&self) -> LockResult<MutexGuard<T>> {
220 self.inner.raw_lock();
221 MutexGuard::new(self)
225 /// Attempts to acquire this lock.
227 /// If the lock could not be acquired at this time, then [`Err`] is returned.
228 /// Otherwise, an RAII guard is returned. The lock will be unlocked when the
229 /// guard is dropped.
231 /// This function does not block.
235 /// If another user of this mutex panicked while holding the mutex, then
236 /// this call will return failure if the mutex would otherwise be
239 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
244 /// use std::sync::{Arc, Mutex};
247 /// let mutex = Arc::new(Mutex::new(0));
248 /// let c_mutex = mutex.clone();
250 /// thread::spawn(move || {
251 /// let mut lock = c_mutex.try_lock();
252 /// if let Ok(ref mut mutex) = lock {
255 /// println!("try_lock failed");
257 /// }).join().expect("thread::spawn failed");
258 /// assert_eq!(*mutex.lock().unwrap(), 10);
260 #[stable(feature = "rust1", since = "1.0.0")]
261 pub fn try_lock(&self) -> TryLockResult<MutexGuard<T>> {
263 if self.inner.try_lock() {
264 Ok(MutexGuard::new(self)?)
266 Err(TryLockError::WouldBlock)
271 /// Determines whether the mutex is poisoned.
273 /// If another thread is active, the mutex can still become poisoned at any
274 /// time. You should not trust a `false` value for program correctness
275 /// without additional synchronization.
280 /// use std::sync::{Arc, Mutex};
283 /// let mutex = Arc::new(Mutex::new(0));
284 /// let c_mutex = mutex.clone();
286 /// let _ = thread::spawn(move || {
287 /// let _lock = c_mutex.lock().unwrap();
288 /// panic!(); // the mutex gets poisoned
290 /// assert_eq!(mutex.is_poisoned(), true);
293 #[stable(feature = "sync_poison", since = "1.2.0")]
294 pub fn is_poisoned(&self) -> bool {
298 /// Consumes this mutex, returning the underlying data.
302 /// If another user of this mutex panicked while holding the mutex, then
303 /// this call will return an error instead.
308 /// use std::sync::Mutex;
310 /// let mutex = Mutex::new(0);
311 /// assert_eq!(mutex.into_inner().unwrap(), 0);
313 #[stable(feature = "mutex_into_inner", since = "1.6.0")]
314 pub fn into_inner(self) -> LockResult<T> where T: Sized {
315 // We know statically that there are no outstanding references to
316 // `self` so there's no need to lock the inner mutex.
318 // To get the inner value, we'd like to call `data.into_inner()`,
319 // but because `Mutex` impl-s `Drop`, we can't move out of it, so
320 // we'll have to destructure it manually instead.
322 // Like `let Mutex { inner, poison, data } = self`.
323 let (inner, poison, data) = {
324 let Mutex { ref inner, ref poison, ref data } = self;
325 (ptr::read(inner), ptr::read(poison), ptr::read(data))
328 inner.destroy(); // Keep in sync with the `Drop` impl.
331 poison::map_result(poison.borrow(), |_| data.into_inner())
335 /// Returns a mutable reference to the underlying data.
337 /// Since this call borrows the `Mutex` mutably, no actual locking needs to
338 /// take place---the mutable borrow statically guarantees no locks exist.
342 /// If another user of this mutex panicked while holding the mutex, then
343 /// this call will return an error instead.
348 /// use std::sync::Mutex;
350 /// let mut mutex = Mutex::new(0);
351 /// *mutex.get_mut().unwrap() = 10;
352 /// assert_eq!(*mutex.lock().unwrap(), 10);
354 #[stable(feature = "mutex_get_mut", since = "1.6.0")]
355 pub fn get_mut(&mut self) -> LockResult<&mut T> {
356 // We know statically that there are no other references to `self`, so
357 // there's no need to lock the inner mutex.
358 let data = unsafe { &mut *self.data.get() };
359 poison::map_result(self.poison.borrow(), |_| data )
363 #[stable(feature = "rust1", since = "1.0.0")]
364 unsafe impl<#[may_dangle] T: ?Sized> Drop for Mutex<T> {
366 // This is actually safe b/c we know that there is no further usage of
367 // this mutex (it's up to the user to arrange for a mutex to get
368 // dropped, that's not our job)
370 // IMPORTANT: This code must be kept in sync with `Mutex::into_inner`.
371 unsafe { self.inner.destroy() }
375 #[stable(feature = "mutex_from", since = "1.24.0")]
376 impl<T> From<T> for Mutex<T> {
377 /// Creates a new mutex in an unlocked state ready for use.
378 /// This is equivalent to [`Mutex::new`].
379 fn from(t: T) -> Self {
384 #[stable(feature = "mutex_default", since = "1.10.0")]
385 impl<T: ?Sized + Default> Default for Mutex<T> {
386 /// Creates a `Mutex<T>`, with the `Default` value for T.
387 fn default() -> Mutex<T> {
388 Mutex::new(Default::default())
392 #[stable(feature = "rust1", since = "1.0.0")]
393 impl<T: ?Sized + fmt::Debug> fmt::Debug for Mutex<T> {
394 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
395 match self.try_lock() {
396 Ok(guard) => f.debug_struct("Mutex").field("data", &&*guard).finish(),
397 Err(TryLockError::Poisoned(err)) => {
398 f.debug_struct("Mutex").field("data", &&**err.get_ref()).finish()
400 Err(TryLockError::WouldBlock) => {
401 struct LockedPlaceholder;
402 impl fmt::Debug for LockedPlaceholder {
403 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { f.write_str("<locked>") }
406 f.debug_struct("Mutex").field("data", &LockedPlaceholder).finish()
412 impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> {
413 unsafe fn new(lock: &'mutex Mutex<T>) -> LockResult<MutexGuard<'mutex, T>> {
414 poison::map_result(lock.poison.borrow(), |guard| {
423 #[stable(feature = "rust1", since = "1.0.0")]
424 impl<'mutex, T: ?Sized> Deref for MutexGuard<'mutex, T> {
427 fn deref(&self) -> &T {
428 unsafe { &*self.__lock.data.get() }
432 #[stable(feature = "rust1", since = "1.0.0")]
433 impl<'mutex, T: ?Sized> DerefMut for MutexGuard<'mutex, T> {
434 fn deref_mut(&mut self) -> &mut T {
435 unsafe { &mut *self.__lock.data.get() }
439 #[stable(feature = "rust1", since = "1.0.0")]
440 impl<'a, T: ?Sized> Drop for MutexGuard<'a, T> {
444 self.__lock.poison.done(&self.__poison);
445 self.__lock.inner.raw_unlock();
450 #[stable(feature = "std_debug", since = "1.16.0")]
451 impl<'a, T: ?Sized + fmt::Debug> fmt::Debug for MutexGuard<'a, T> {
452 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
453 f.debug_struct("MutexGuard")
454 .field("lock", &self.__lock)
459 #[stable(feature = "std_guard_impls", since = "1.20.0")]
460 impl<'a, T: ?Sized + fmt::Display> fmt::Display for MutexGuard<'a, T> {
461 fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
466 pub fn guard_lock<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a sys::Mutex {
470 pub fn guard_poison<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a poison::Flag {
474 #[cfg(all(test, not(target_os = "emscripten")))]
476 use sync::mpsc::channel;
477 use sync::{Arc, Mutex, Condvar};
478 use sync::atomic::{AtomicUsize, Ordering};
481 struct Packet<T>(Arc<(Mutex<T>, Condvar)>);
483 #[derive(Eq, PartialEq, Debug)]
488 let m = Mutex::new(());
489 drop(m.lock().unwrap());
490 drop(m.lock().unwrap());
498 let m = Arc::new(Mutex::new(0));
500 fn inc(m: &Mutex<u32>) {
502 *m.lock().unwrap() += 1;
506 let (tx, rx) = channel();
508 let tx2 = tx.clone();
510 thread::spawn(move|| { inc(&m2); tx2.send(()).unwrap(); });
511 let tx2 = tx.clone();
513 thread::spawn(move|| { inc(&m2); tx2.send(()).unwrap(); });
520 assert_eq!(*m.lock().unwrap(), J * K * 2);
525 let m = Mutex::new(());
526 *m.try_lock().unwrap() = ();
530 fn test_into_inner() {
531 let m = Mutex::new(NonCopy(10));
532 assert_eq!(m.into_inner().unwrap(), NonCopy(10));
536 fn test_into_inner_drop() {
537 struct Foo(Arc<AtomicUsize>);
540 self.0.fetch_add(1, Ordering::SeqCst);
543 let num_drops = Arc::new(AtomicUsize::new(0));
544 let m = Mutex::new(Foo(num_drops.clone()));
545 assert_eq!(num_drops.load(Ordering::SeqCst), 0);
547 let _inner = m.into_inner().unwrap();
548 assert_eq!(num_drops.load(Ordering::SeqCst), 0);
550 assert_eq!(num_drops.load(Ordering::SeqCst), 1);
554 fn test_into_inner_poison() {
555 let m = Arc::new(Mutex::new(NonCopy(10)));
557 let _ = thread::spawn(move || {
558 let _lock = m2.lock().unwrap();
559 panic!("test panic in inner thread to poison mutex");
562 assert!(m.is_poisoned());
563 match Arc::try_unwrap(m).unwrap().into_inner() {
564 Err(e) => assert_eq!(e.into_inner(), NonCopy(10)),
565 Ok(x) => panic!("into_inner of poisoned Mutex is Ok: {:?}", x),
571 let mut m = Mutex::new(NonCopy(10));
572 *m.get_mut().unwrap() = NonCopy(20);
573 assert_eq!(m.into_inner().unwrap(), NonCopy(20));
577 fn test_get_mut_poison() {
578 let m = Arc::new(Mutex::new(NonCopy(10)));
580 let _ = thread::spawn(move || {
581 let _lock = m2.lock().unwrap();
582 panic!("test panic in inner thread to poison mutex");
585 assert!(m.is_poisoned());
586 match Arc::try_unwrap(m).unwrap().get_mut() {
587 Err(e) => assert_eq!(*e.into_inner(), NonCopy(10)),
588 Ok(x) => panic!("get_mut of poisoned Mutex is Ok: {:?}", x),
593 fn test_mutex_arc_condvar() {
594 let packet = Packet(Arc::new((Mutex::new(false), Condvar::new())));
595 let packet2 = Packet(packet.0.clone());
596 let (tx, rx) = channel();
597 let _t = thread::spawn(move|| {
598 // wait until parent gets in
600 let &(ref lock, ref cvar) = &*packet2.0;
601 let mut lock = lock.lock().unwrap();
606 let &(ref lock, ref cvar) = &*packet.0;
607 let mut lock = lock.lock().unwrap();
608 tx.send(()).unwrap();
611 lock = cvar.wait(lock).unwrap();
616 fn test_arc_condvar_poison() {
617 let packet = Packet(Arc::new((Mutex::new(1), Condvar::new())));
618 let packet2 = Packet(packet.0.clone());
619 let (tx, rx) = channel();
621 let _t = thread::spawn(move || -> () {
623 let &(ref lock, ref cvar) = &*packet2.0;
624 let _g = lock.lock().unwrap();
626 // Parent should fail when it wakes up.
630 let &(ref lock, ref cvar) = &*packet.0;
631 let mut lock = lock.lock().unwrap();
632 tx.send(()).unwrap();
634 match cvar.wait(lock) {
637 assert_eq!(*lock, 1);
645 fn test_mutex_arc_poison() {
646 let arc = Arc::new(Mutex::new(1));
647 assert!(!arc.is_poisoned());
648 let arc2 = arc.clone();
649 let _ = thread::spawn(move|| {
650 let lock = arc2.lock().unwrap();
651 assert_eq!(*lock, 2);
653 assert!(arc.lock().is_err());
654 assert!(arc.is_poisoned());
658 fn test_mutex_arc_nested() {
659 // Tests nested mutexes and access
660 // to underlying data.
661 let arc = Arc::new(Mutex::new(1));
662 let arc2 = Arc::new(Mutex::new(arc));
663 let (tx, rx) = channel();
664 let _t = thread::spawn(move|| {
665 let lock = arc2.lock().unwrap();
666 let lock2 = lock.lock().unwrap();
667 assert_eq!(*lock2, 1);
668 tx.send(()).unwrap();
674 fn test_mutex_arc_access_in_unwind() {
675 let arc = Arc::new(Mutex::new(1));
676 let arc2 = arc.clone();
677 let _ = thread::spawn(move|| -> () {
681 impl Drop for Unwinder {
683 *self.i.lock().unwrap() += 1;
686 let _u = Unwinder { i: arc2 };
689 let lock = arc.lock().unwrap();
690 assert_eq!(*lock, 2);
694 fn test_mutex_unsized() {
695 let mutex: &Mutex<[i32]> = &Mutex::new([1, 2, 3]);
697 let b = &mut *mutex.lock().unwrap();
701 let comp: &[i32] = &[4, 2, 5];
702 assert_eq!(&*mutex.lock().unwrap(), comp);