1 use crate::cell
::UnsafeCell
;
4 use crate::ops
::{Deref, DerefMut}
;
6 use crate::sys_common
::mutex
as sys
;
7 use crate::sys_common
::poison
::{self, LockResult, TryLockError, TryLockResult}
;
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(),
111 /// It is sometimes necessary to manually drop the mutex guard to unlock it
112 /// sooner than the end of the enclosing scope.
115 /// use std::sync::{Arc, Mutex};
118 /// const N: usize = 3;
120 /// let data_mutex = Arc::new(Mutex::new(vec![1, 2, 3, 4]));
121 /// let res_mutex = Arc::new(Mutex::new(0));
123 /// let mut threads = Vec::with_capacity(N);
124 /// (0..N).for_each(|_| {
125 /// let data_mutex_clone = Arc::clone(&data_mutex);
126 /// let res_mutex_clone = Arc::clone(&res_mutex);
128 /// threads.push(thread::spawn(move || {
129 /// let mut data = data_mutex_clone.lock().unwrap();
130 /// // This is the result of some important and long-ish work.
131 /// let result = data.iter().fold(0, |acc, x| acc + x * 2);
132 /// data.push(result);
134 /// *res_mutex_clone.lock().unwrap() += result;
138 /// let mut data = data_mutex.lock().unwrap();
139 /// // This is the result of some important and long-ish work.
140 /// let result = data.iter().fold(0, |acc, x| acc + x * 2);
141 /// data.push(result);
142 /// // We drop the `data` explicitly because it's not necessary anymore and the
143 /// // thread still has work to do. This allow other threads to start working on
144 /// // the data immediately, without waiting for the rest of the unrelated work
145 /// // to be done here.
147 /// // It's even more important here than in the threads because we `.join` the
148 /// // threads after that. If we had not dropped the mutex guard, a thread could
149 /// // be waiting forever for it, causing a deadlock.
151 /// // Here the mutex guard is not assigned to a variable and so, even if the
152 /// // scope does not end after this line, the mutex is still released: there is
154 /// *res_mutex.lock().unwrap() += result;
156 /// threads.into_iter().for_each(|thread| {
159 /// .expect("The thread creating or execution failed !")
162 /// assert_eq!(*res_mutex.lock().unwrap(), 800);
164 #[stable(feature = "rust1", since = "1.0.0")]
165 #[cfg_attr(not(test), rustc_diagnostic_item = "mutex_type")]
166 pub struct Mutex
<T
: ?Sized
> {
167 // Note that this mutex is in a *box*, not inlined into the struct itself.
168 // Once a native mutex has been used once, its address can never change (it
169 // can't be moved). This mutex type can be safely moved at any time, so to
170 // ensure that the native mutex is used correctly we box the inner mutex to
171 // give it a constant address.
172 inner
: Box
<sys
::Mutex
>,
173 poison
: poison
::Flag
,
177 // these are the only places where `T: Send` matters; all other
178 // functionality works fine on a single thread.
179 #[stable(feature = "rust1", since = "1.0.0")]
180 unsafe impl<T
: ?Sized
+ Send
> Send
for Mutex
<T
> {}
181 #[stable(feature = "rust1", since = "1.0.0")]
182 unsafe impl<T
: ?Sized
+ Send
> Sync
for Mutex
<T
> {}
184 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
185 /// dropped (falls out of scope), the lock will be unlocked.
187 /// The data protected by the mutex can be accessed through this guard via its
188 /// [`Deref`] and [`DerefMut`] implementations.
190 /// This structure is created by the [`lock`] and [`try_lock`] methods on
193 /// [`Deref`]: ../../std/ops/trait.Deref.html
194 /// [`DerefMut`]: ../../std/ops/trait.DerefMut.html
195 /// [`lock`]: struct.Mutex.html#method.lock
196 /// [`try_lock`]: struct.Mutex.html#method.try_lock
197 /// [`Mutex`]: struct.Mutex.html
198 #[must_use = "if unused the Mutex will immediately unlock"]
199 #[stable(feature = "rust1", since = "1.0.0")]
200 pub struct MutexGuard
<'a
, T
: ?Sized
+ 'a
> {
202 poison
: poison
::Guard
,
205 #[stable(feature = "rust1", since = "1.0.0")]
206 impl<T
: ?Sized
> !Send
for MutexGuard
<'_
, T
> {}
207 #[stable(feature = "mutexguard", since = "1.19.0")]
208 unsafe impl<T
: ?Sized
+ Sync
> Sync
for MutexGuard
<'_
, T
> {}
211 /// Creates a new mutex in an unlocked state ready for use.
216 /// use std::sync::Mutex;
218 /// let mutex = Mutex::new(0);
220 #[stable(feature = "rust1", since = "1.0.0")]
221 pub fn new(t
: T
) -> Mutex
<T
> {
223 inner
: box sys
::Mutex
::new(),
224 poison
: poison
::Flag
::new(),
225 data
: UnsafeCell
::new(t
),
234 impl<T
: ?Sized
> Mutex
<T
> {
235 /// Acquires a mutex, blocking the current thread until it is able to do so.
237 /// This function will block the local thread until it is available to acquire
238 /// the mutex. Upon returning, the thread is the only thread with the lock
239 /// held. An RAII guard is returned to allow scoped unlock of the lock. When
240 /// the guard goes out of scope, the mutex will be unlocked.
242 /// The exact behavior on locking a mutex in the thread which already holds
243 /// the lock is left unspecified. However, this function will not return on
244 /// the second call (it might panic or deadlock, for example).
248 /// If another user of this mutex panicked while holding the mutex, then
249 /// this call will return an error once the mutex is acquired.
253 /// This function might panic when called if the lock is already held by
254 /// the current thread.
259 /// use std::sync::{Arc, Mutex};
262 /// let mutex = Arc::new(Mutex::new(0));
263 /// let c_mutex = mutex.clone();
265 /// thread::spawn(move || {
266 /// *c_mutex.lock().unwrap() = 10;
267 /// }).join().expect("thread::spawn failed");
268 /// assert_eq!(*mutex.lock().unwrap(), 10);
270 #[stable(feature = "rust1", since = "1.0.0")]
271 pub fn lock(&self) -> LockResult
<MutexGuard
<'_
, T
>> {
273 self.inner
.raw_lock();
274 MutexGuard
::new(self)
278 /// Attempts to acquire this lock.
280 /// If the lock could not be acquired at this time, then [`Err`] is returned.
281 /// Otherwise, an RAII guard is returned. The lock will be unlocked when the
282 /// guard is dropped.
284 /// This function does not block.
288 /// If another user of this mutex panicked while holding the mutex, then
289 /// this call will return failure if the mutex would otherwise be
292 /// [`Err`]: ../../std/result/enum.Result.html#variant.Err
297 /// use std::sync::{Arc, Mutex};
300 /// let mutex = Arc::new(Mutex::new(0));
301 /// let c_mutex = mutex.clone();
303 /// thread::spawn(move || {
304 /// let mut lock = c_mutex.try_lock();
305 /// if let Ok(ref mut mutex) = lock {
308 /// println!("try_lock failed");
310 /// }).join().expect("thread::spawn failed");
311 /// assert_eq!(*mutex.lock().unwrap(), 10);
313 #[stable(feature = "rust1", since = "1.0.0")]
314 pub fn try_lock(&self) -> TryLockResult
<MutexGuard
<'_
, T
>> {
316 if self.inner
.try_lock() {
317 Ok(MutexGuard
::new(self)?
)
319 Err(TryLockError
::WouldBlock
)
324 /// Determines whether the mutex is poisoned.
326 /// If another thread is active, the mutex can still become poisoned at any
327 /// time. You should not trust a `false` value for program correctness
328 /// without additional synchronization.
333 /// use std::sync::{Arc, Mutex};
336 /// let mutex = Arc::new(Mutex::new(0));
337 /// let c_mutex = mutex.clone();
339 /// let _ = thread::spawn(move || {
340 /// let _lock = c_mutex.lock().unwrap();
341 /// panic!(); // the mutex gets poisoned
343 /// assert_eq!(mutex.is_poisoned(), true);
346 #[stable(feature = "sync_poison", since = "1.2.0")]
347 pub fn is_poisoned(&self) -> bool
{
351 /// Consumes this mutex, returning the underlying data.
355 /// If another user of this mutex panicked while holding the mutex, then
356 /// this call will return an error instead.
361 /// use std::sync::Mutex;
363 /// let mutex = Mutex::new(0);
364 /// assert_eq!(mutex.into_inner().unwrap(), 0);
366 #[stable(feature = "mutex_into_inner", since = "1.6.0")]
367 pub fn into_inner(self) -> LockResult
<T
>
371 // We know statically that there are no outstanding references to
372 // `self` so there's no need to lock the inner mutex.
374 // To get the inner value, we'd like to call `data.into_inner()`,
375 // but because `Mutex` impl-s `Drop`, we can't move out of it, so
376 // we'll have to destructure it manually instead.
378 // Like `let Mutex { inner, poison, data } = self`.
379 let (inner
, poison
, data
) = {
380 let Mutex { ref inner, ref poison, ref data }
= self;
381 (ptr
::read(inner
), ptr
::read(poison
), ptr
::read(data
))
384 inner
.destroy(); // Keep in sync with the `Drop` impl.
387 poison
::map_result(poison
.borrow(), |_
| data
.into_inner())
391 /// Returns a mutable reference to the underlying data.
393 /// Since this call borrows the `Mutex` mutably, no actual locking needs to
394 /// take place -- the mutable borrow statically guarantees no locks exist.
398 /// If another user of this mutex panicked while holding the mutex, then
399 /// this call will return an error instead.
404 /// use std::sync::Mutex;
406 /// let mut mutex = Mutex::new(0);
407 /// *mutex.get_mut().unwrap() = 10;
408 /// assert_eq!(*mutex.lock().unwrap(), 10);
410 #[stable(feature = "mutex_get_mut", since = "1.6.0")]
411 pub fn get_mut(&mut self) -> LockResult
<&mut T
> {
412 // We know statically that there are no other references to `self`, so
413 // there's no need to lock the inner mutex.
414 let data
= unsafe { &mut *self.data.get() }
;
415 poison
::map_result(self.poison
.borrow(), |_
| data
)
419 #[stable(feature = "rust1", since = "1.0.0")]
420 unsafe impl<#[may_dangle] T: ?Sized> Drop for Mutex<T> {
422 // This is actually safe b/c we know that there is no further usage of
423 // this mutex (it's up to the user to arrange for a mutex to get
424 // dropped, that's not our job)
426 // IMPORTANT: This code must be kept in sync with `Mutex::into_inner`.
427 unsafe { self.inner.destroy() }
431 #[stable(feature = "mutex_from", since = "1.24.0")]
432 impl<T
> From
<T
> for Mutex
<T
> {
433 /// Creates a new mutex in an unlocked state ready for use.
434 /// This is equivalent to [`Mutex::new`].
436 /// [`Mutex::new`]: ../../std/sync/struct.Mutex.html#method.new
437 fn from(t
: T
) -> Self {
442 #[stable(feature = "mutex_default", since = "1.10.0")]
443 impl<T
: ?Sized
+ Default
> Default
for Mutex
<T
> {
444 /// Creates a `Mutex<T>`, with the `Default` value for T.
445 fn default() -> Mutex
<T
> {
446 Mutex
::new(Default
::default())
450 #[stable(feature = "rust1", since = "1.0.0")]
451 impl<T
: ?Sized
+ fmt
::Debug
> fmt
::Debug
for Mutex
<T
> {
452 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
453 match self.try_lock() {
454 Ok(guard
) => f
.debug_struct("Mutex").field("data", &&*guard
).finish(),
455 Err(TryLockError
::Poisoned(err
)) => {
456 f
.debug_struct("Mutex").field("data", &&**err
.get_ref()).finish()
458 Err(TryLockError
::WouldBlock
) => {
459 struct LockedPlaceholder
;
460 impl fmt
::Debug
for LockedPlaceholder
{
461 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
462 f
.write_str("<locked>")
466 f
.debug_struct("Mutex").field("data", &LockedPlaceholder
).finish()
472 impl<'mutex
, T
: ?Sized
> MutexGuard
<'mutex
, T
> {
473 unsafe fn new(lock
: &'mutex Mutex
<T
>) -> LockResult
<MutexGuard
<'mutex
, T
>> {
474 poison
::map_result(lock
.poison
.borrow(), |guard
| MutexGuard { lock, poison: guard }
)
478 #[stable(feature = "rust1", since = "1.0.0")]
479 impl<T
: ?Sized
> Deref
for MutexGuard
<'_
, T
> {
482 fn deref(&self) -> &T
{
483 unsafe { &*self.lock.data.get() }
487 #[stable(feature = "rust1", since = "1.0.0")]
488 impl<T
: ?Sized
> DerefMut
for MutexGuard
<'_
, T
> {
489 fn deref_mut(&mut self) -> &mut T
{
490 unsafe { &mut *self.lock.data.get() }
494 #[stable(feature = "rust1", since = "1.0.0")]
495 impl<T
: ?Sized
> Drop
for MutexGuard
<'_
, T
> {
499 self.lock
.poison
.done(&self.poison
);
500 self.lock
.inner
.raw_unlock();
505 #[stable(feature = "std_debug", since = "1.16.0")]
506 impl<T
: ?Sized
+ fmt
::Debug
> fmt
::Debug
for MutexGuard
<'_
, T
> {
507 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
508 fmt
::Debug
::fmt(&**self, f
)
512 #[stable(feature = "std_guard_impls", since = "1.20.0")]
513 impl<T
: ?Sized
+ fmt
::Display
> fmt
::Display
for MutexGuard
<'_
, T
> {
514 fn fmt(&self, f
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
519 pub fn guard_lock
<'a
, T
: ?Sized
>(guard
: &MutexGuard
<'a
, T
>) -> &'a sys
::Mutex
{
523 pub fn guard_poison
<'a
, T
: ?Sized
>(guard
: &MutexGuard
<'a
, T
>) -> &'a poison
::Flag
{
527 #[cfg(all(test, not(target_os = "emscripten")))]
529 use crate::sync
::atomic
::{AtomicUsize, Ordering}
;
530 use crate::sync
::mpsc
::channel
;
531 use crate::sync
::{Arc, Condvar, Mutex}
;
534 struct Packet
<T
>(Arc
<(Mutex
<T
>, Condvar
)>);
536 #[derive(Eq, PartialEq, Debug)]
541 let m
= Mutex
::new(());
542 drop(m
.lock().unwrap());
543 drop(m
.lock().unwrap());
551 let m
= Arc
::new(Mutex
::new(0));
553 fn inc(m
: &Mutex
<u32>) {
555 *m
.lock().unwrap() += 1;
559 let (tx
, rx
) = channel();
561 let tx2
= tx
.clone();
563 thread
::spawn(move || {
565 tx2
.send(()).unwrap();
567 let tx2
= tx
.clone();
569 thread
::spawn(move || {
571 tx2
.send(()).unwrap();
579 assert_eq
!(*m
.lock().unwrap(), J
* K
* 2);
584 let m
= Mutex
::new(());
585 *m
.try_lock().unwrap() = ();
589 fn test_into_inner() {
590 let m
= Mutex
::new(NonCopy(10));
591 assert_eq
!(m
.into_inner().unwrap(), NonCopy(10));
595 fn test_into_inner_drop() {
596 struct Foo(Arc
<AtomicUsize
>);
599 self.0.fetch_add
(1, Ordering
::SeqCst
);
602 let num_drops
= Arc
::new(AtomicUsize
::new(0));
603 let m
= Mutex
::new(Foo(num_drops
.clone()));
604 assert_eq
!(num_drops
.load(Ordering
::SeqCst
), 0);
606 let _inner
= m
.into_inner().unwrap();
607 assert_eq
!(num_drops
.load(Ordering
::SeqCst
), 0);
609 assert_eq
!(num_drops
.load(Ordering
::SeqCst
), 1);
613 fn test_into_inner_poison() {
614 let m
= Arc
::new(Mutex
::new(NonCopy(10)));
616 let _
= thread
::spawn(move || {
617 let _lock
= m2
.lock().unwrap();
618 panic
!("test panic in inner thread to poison mutex");
622 assert
!(m
.is_poisoned());
623 match Arc
::try_unwrap(m
).unwrap().into_inner() {
624 Err(e
) => assert_eq
!(e
.into_inner(), NonCopy(10)),
625 Ok(x
) => panic
!("into_inner of poisoned Mutex is Ok: {:?}", x
),
631 let mut m
= Mutex
::new(NonCopy(10));
632 *m
.get_mut().unwrap() = NonCopy(20);
633 assert_eq
!(m
.into_inner().unwrap(), NonCopy(20));
637 fn test_get_mut_poison() {
638 let m
= Arc
::new(Mutex
::new(NonCopy(10)));
640 let _
= thread
::spawn(move || {
641 let _lock
= m2
.lock().unwrap();
642 panic
!("test panic in inner thread to poison mutex");
646 assert
!(m
.is_poisoned());
647 match Arc
::try_unwrap(m
).unwrap().get_mut() {
648 Err(e
) => assert_eq
!(*e
.into_inner(), NonCopy(10)),
649 Ok(x
) => panic
!("get_mut of poisoned Mutex is Ok: {:?}", x
),
654 fn test_mutex_arc_condvar() {
655 let packet
= Packet(Arc
::new((Mutex
::new(false), Condvar
::new())));
656 let packet2
= Packet(packet
.0.clone());
657 let (tx
, rx
) = channel();
658 let _t
= thread
::spawn(move || {
659 // wait until parent gets in
661 let &(ref lock
, ref cvar
) = &*packet2
.0
;
662 let mut lock
= lock
.lock().unwrap();
667 let &(ref lock
, ref cvar
) = &*packet
.0;
668 let mut lock
= lock
.lock().unwrap();
669 tx
.send(()).unwrap();
672 lock
= cvar
.wait(lock
).unwrap();
677 fn test_arc_condvar_poison() {
678 let packet
= Packet(Arc
::new((Mutex
::new(1), Condvar
::new())));
679 let packet2
= Packet(packet
.0.clone());
680 let (tx
, rx
) = channel();
682 let _t
= thread
::spawn(move || -> () {
684 let &(ref lock
, ref cvar
) = &*packet2
.0
;
685 let _g
= lock
.lock().unwrap();
687 // Parent should fail when it wakes up.
691 let &(ref lock
, ref cvar
) = &*packet
.0;
692 let mut lock
= lock
.lock().unwrap();
693 tx
.send(()).unwrap();
695 match cvar
.wait(lock
) {
698 assert_eq
!(*lock
, 1);
706 fn test_mutex_arc_poison() {
707 let arc
= Arc
::new(Mutex
::new(1));
708 assert
!(!arc
.is_poisoned());
709 let arc2
= arc
.clone();
710 let _
= thread
::spawn(move || {
711 let lock
= arc2
.lock().unwrap();
712 assert_eq
!(*lock
, 2);
715 assert
!(arc
.lock().is_err());
716 assert
!(arc
.is_poisoned());
720 fn test_mutex_arc_nested() {
721 // Tests nested mutexes and access
722 // to underlying data.
723 let arc
= Arc
::new(Mutex
::new(1));
724 let arc2
= Arc
::new(Mutex
::new(arc
));
725 let (tx
, rx
) = channel();
726 let _t
= thread
::spawn(move || {
727 let lock
= arc2
.lock().unwrap();
728 let lock2
= lock
.lock().unwrap();
729 assert_eq
!(*lock2
, 1);
730 tx
.send(()).unwrap();
736 fn test_mutex_arc_access_in_unwind() {
737 let arc
= Arc
::new(Mutex
::new(1));
738 let arc2
= arc
.clone();
739 let _
= thread
::spawn(move || -> () {
743 impl Drop
for Unwinder
{
745 *self.i
.lock().unwrap() += 1;
748 let _u
= Unwinder { i: arc2 }
;
752 let lock
= arc
.lock().unwrap();
753 assert_eq
!(*lock
, 2);
757 fn test_mutex_unsized() {
758 let mutex
: &Mutex
<[i32]> = &Mutex
::new([1, 2, 3]);
760 let b
= &mut *mutex
.lock().unwrap();
764 let comp
: &[i32] = &[4, 2, 5];
765 assert_eq
!(&*mutex
.lock().unwrap(), comp
);