1use crate::cell::UnsafeCell;
2use crate::fmt;
3use crate::marker::PhantomData;
4use crate::mem::{self, ManuallyDrop};
5use crate::ops::{Deref, DerefMut};
6use crate::ptr::NonNull;
7use crate::sync::{LockResult, PoisonError, TryLockError, TryLockResult, poison};
8use crate::sys::sync as sys;
9
10/// A mutual exclusion primitive useful for protecting shared data
11///
12/// This mutex will block threads waiting for the lock to become available. The
13/// mutex can be created via a [`new`] constructor. Each mutex has a type parameter
14/// which represents the data that it is protecting. The data can only be accessed
15/// through the RAII guards returned from [`lock`] and [`try_lock`], which
16/// guarantees that the data is only ever accessed when the mutex is locked.
17///
18/// # Poisoning
19///
20/// The mutexes in this module implement a strategy called "poisoning" where a
21/// mutex becomes poisoned if it recognizes that the thread holding it has
22/// panicked.
23///
24/// Once a mutex is poisoned, all other threads are unable to access the data by
25/// default as it is likely tainted (some invariant is not being upheld). For a
26/// 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.
30///
31/// Poisoning is only advisory: the [`PoisonError`] type has an [`into_inner`]
32/// method which will return the guard that would have otherwise been returned
33/// on a successful lock. This allows access to the data, despite the lock being
34/// poisoned.
35///
36/// In addition, the panic detection is not ideal, so even unpoisoned mutexes
37/// need to be handled with care, since certain panics may have been skipped.
38/// Here is a non-exhaustive list of situations where this might occur:
39///
40/// - If a mutex is locked while a panic is underway, e.g. within a [`Drop`]
41/// implementation or a [panic hook], panicking for the second time while the
42/// lock is held will leave the mutex unpoisoned. Note that while double panic
43/// usually aborts the program, [`catch_unwind`] can prevent this.
44///
45/// - Locking and unlocking the mutex across different panic contexts, e.g. by
46/// storing the guard to a [`Cell`] within [`Drop::drop`] and accessing it
47/// outside, or vice versa, can affect poisoning status in an unexpected way.
48///
49/// - Foreign exceptions do not currently trigger poisoning even in absence of
50/// other panics.
51///
52/// While this rarely happens in realistic code, `unsafe` code cannot rely on
53/// poisoning for soundness, since the behavior of poisoning can depend on
54/// outside context. Here's an example of **incorrect** use of poisoning:
55///
56/// ```rust
57/// use std::sync::Mutex;
58///
59/// struct MutexBox<T> {
60/// data: Mutex<*mut T>,
61/// }
62///
63/// impl<T> MutexBox<T> {
64/// pub fn new(value: T) -> Self {
65/// Self {
66/// data: Mutex::new(Box::into_raw(Box::new(value))),
67/// }
68/// }
69///
70/// pub fn replace_with(&self, f: impl FnOnce(T) -> T) {
71/// let ptr = self.data.lock().expect("poisoned");
72/// // While `f` is running, the data is moved out of `*ptr`. If `f`
73/// // panics, `*ptr` keeps pointing at a dropped value. The intention
74/// // is that this will poison the mutex, so the following calls to
75/// // `replace_with` will panic without reading `*ptr`. But since
76/// // poisoning is not guaranteed to occur if this is run from a panic
77/// // hook, this can lead to use-after-free.
78/// unsafe {
79/// (*ptr).write(f((*ptr).read()));
80/// }
81/// }
82/// }
83/// ```
84///
85/// [`new`]: Self::new
86/// [`lock`]: Self::lock
87/// [`try_lock`]: Self::try_lock
88/// [`unwrap()`]: Result::unwrap
89/// [`PoisonError`]: super::PoisonError
90/// [`into_inner`]: super::PoisonError::into_inner
91/// [panic hook]: crate::panic::set_hook
92/// [`catch_unwind`]: crate::panic::catch_unwind
93/// [`Cell`]: crate::cell::Cell
94///
95/// # Examples
96///
97/// ```
98/// use std::sync::{Arc, Mutex};
99/// use std::thread;
100/// use std::sync::mpsc::channel;
101///
102/// const N: usize = 10;
103///
104/// // Spawn a few threads to increment a shared variable (non-atomically), and
105/// // let the main thread know once all increments are done.
106/// //
107/// // Here we're using an Arc to share memory among threads, and the data inside
108/// // the Arc is protected with a mutex.
109/// let data = Arc::new(Mutex::new(0));
110///
111/// let (tx, rx) = channel();
112/// for _ in 0..N {
113/// let (data, tx) = (Arc::clone(&data), tx.clone());
114/// thread::spawn(move || {
115/// // The shared state can only be accessed once the lock is held.
116/// // Our non-atomic increment is safe because we're the only thread
117/// // which can access the shared state when the lock is held.
118/// //
119/// // We unwrap() the return value to assert that we are not expecting
120/// // threads to ever fail while holding the lock.
121/// let mut data = data.lock().unwrap();
122/// *data += 1;
123/// if *data == N {
124/// tx.send(()).unwrap();
125/// }
126/// // the lock is unlocked here when `data` goes out of scope.
127/// });
128/// }
129///
130/// rx.recv().unwrap();
131/// ```
132///
133/// To recover from a poisoned mutex:
134///
135/// ```
136/// use std::sync::{Arc, Mutex};
137/// use std::thread;
138///
139/// let lock = Arc::new(Mutex::new(0_u32));
140/// let lock2 = Arc::clone(&lock);
141///
142/// let _ = thread::spawn(move || -> () {
143/// // This thread will acquire the mutex first, unwrapping the result of
144/// // `lock` because the lock has not been poisoned.
145/// let _guard = lock2.lock().unwrap();
146///
147/// // This panic while holding the lock (`_guard` is in scope) will poison
148/// // the mutex.
149/// panic!();
150/// }).join();
151///
152/// // The lock is poisoned by this point, but the returned result can be
153/// // pattern matched on to return the underlying guard on both branches.
154/// let mut guard = match lock.lock() {
155/// Ok(guard) => guard,
156/// Err(poisoned) => poisoned.into_inner(),
157/// };
158///
159/// *guard += 1;
160/// ```
161///
162/// To unlock a mutex guard sooner than the end of the enclosing scope,
163/// either create an inner scope or drop the guard manually.
164///
165/// ```
166/// use std::sync::{Arc, Mutex};
167/// use std::thread;
168///
169/// const N: usize = 3;
170///
171/// let data_mutex = Arc::new(Mutex::new(vec![1, 2, 3, 4]));
172/// let res_mutex = Arc::new(Mutex::new(0));
173///
174/// let mut threads = Vec::with_capacity(N);
175/// (0..N).for_each(|_| {
176/// let data_mutex_clone = Arc::clone(&data_mutex);
177/// let res_mutex_clone = Arc::clone(&res_mutex);
178///
179/// threads.push(thread::spawn(move || {
180/// // Here we use a block to limit the lifetime of the lock guard.
181/// let result = {
182/// let mut data = data_mutex_clone.lock().unwrap();
183/// // This is the result of some important and long-ish work.
184/// let result = data.iter().fold(0, |acc, x| acc + x * 2);
185/// data.push(result);
186/// result
187/// // The mutex guard gets dropped here, together with any other values
188/// // created in the critical section.
189/// };
190/// // The guard created here is a temporary dropped at the end of the statement, i.e.
191/// // the lock would not remain being held even if the thread did some additional work.
192/// *res_mutex_clone.lock().unwrap() += result;
193/// }));
194/// });
195///
196/// let mut data = data_mutex.lock().unwrap();
197/// // This is the result of some important and long-ish work.
198/// let result = data.iter().fold(0, |acc, x| acc + x * 2);
199/// data.push(result);
200/// // We drop the `data` explicitly because it's not necessary anymore and the
201/// // thread still has work to do. This allows other threads to start working on
202/// // the data immediately, without waiting for the rest of the unrelated work
203/// // to be done here.
204/// //
205/// // It's even more important here than in the threads because we `.join` the
206/// // threads after that. If we had not dropped the mutex guard, a thread could
207/// // be waiting forever for it, causing a deadlock.
208/// // As in the threads, a block could have been used instead of calling the
209/// // `drop` function.
210/// drop(data);
211/// // Here the mutex guard is not assigned to a variable and so, even if the
212/// // scope does not end after this line, the mutex is still released: there is
213/// // no deadlock.
214/// *res_mutex.lock().unwrap() += result;
215///
216/// threads.into_iter().for_each(|thread| {
217/// thread
218/// .join()
219/// .expect("The thread creating or execution failed !")
220/// });
221///
222/// assert_eq!(*res_mutex.lock().unwrap(), 800);
223/// ```
224///
225#[stable(feature = "rust1", since = "1.0.0")]
226#[cfg_attr(not(test), rustc_diagnostic_item = "Mutex")]
227pub struct Mutex<T: ?Sized> {
228 inner: sys::Mutex,
229 poison: poison::Flag,
230 data: UnsafeCell<T>,
231}
232
233/// `T` must be `Send` for a [`Mutex`] to be `Send` because it is possible to acquire
234/// the owned `T` from the `Mutex` via [`into_inner`].
235///
236/// [`into_inner`]: Mutex::into_inner
237#[stable(feature = "rust1", since = "1.0.0")]
238unsafe impl<T: ?Sized + Send> Send for Mutex<T> {}
239
240/// `T` must be `Send` for [`Mutex`] to be `Sync`.
241/// This ensures that the protected data can be accessed safely from multiple threads
242/// without causing data races or other unsafe behavior.
243///
244/// [`Mutex<T>`] provides mutable access to `T` to one thread at a time. However, it's essential
245/// for `T` to be `Send` because it's not safe for non-`Send` structures to be accessed in
246/// this manner. For instance, consider [`Rc`], a non-atomic reference counted smart pointer,
247/// which is not `Send`. With `Rc`, we can have multiple copies pointing to the same heap
248/// allocation with a non-atomic reference count. If we were to use `Mutex<Rc<_>>`, it would
249/// only protect one instance of `Rc` from shared access, leaving other copies vulnerable
250/// to potential data races.
251///
252/// Also note that it is not necessary for `T` to be `Sync` as `&T` is only made available
253/// to one thread at a time if `T` is not `Sync`.
254///
255/// [`Rc`]: crate::rc::Rc
256#[stable(feature = "rust1", since = "1.0.0")]
257unsafe impl<T: ?Sized + Send> Sync for Mutex<T> {}
258
259/// An RAII implementation of a "scoped lock" of a mutex. When this structure is
260/// dropped (falls out of scope), the lock will be unlocked.
261///
262/// The data protected by the mutex can be accessed through this guard via its
263/// [`Deref`] and [`DerefMut`] implementations.
264///
265/// This structure is created by the [`lock`] and [`try_lock`] methods on
266/// [`Mutex`].
267///
268/// [`lock`]: Mutex::lock
269/// [`try_lock`]: Mutex::try_lock
270#[must_use = "if unused the Mutex will immediately unlock"]
271#[must_not_suspend = "holding a MutexGuard across suspend \
272 points can cause deadlocks, delays, \
273 and cause Futures to not implement `Send`"]
274#[stable(feature = "rust1", since = "1.0.0")]
275#[clippy::has_significant_drop]
276#[cfg_attr(not(test), rustc_diagnostic_item = "MutexGuard")]
277pub struct MutexGuard<'a, T: ?Sized + 'a> {
278 lock: &'a Mutex<T>,
279 poison: poison::Guard,
280}
281
282/// A [`MutexGuard`] is not `Send` to maximize platform portability.
283///
284/// On platforms that use POSIX threads (commonly referred to as pthreads) there is a requirement to
285/// release mutex locks on the same thread they were acquired.
286/// For this reason, [`MutexGuard`] must not implement `Send` to prevent it being dropped from
287/// another thread.
288#[stable(feature = "rust1", since = "1.0.0")]
289impl<T: ?Sized> !Send for MutexGuard<'_, T> {}
290
291/// `T` must be `Sync` for a [`MutexGuard<T>`] to be `Sync`
292/// because it is possible to get a `&T` from `&MutexGuard` (via `Deref`).
293#[stable(feature = "mutexguard", since = "1.19.0")]
294unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
295
296/// An RAII mutex guard returned by `MutexGuard::map`, which can point to a
297/// subfield of the protected data. When this structure is dropped (falls out
298/// of scope), the lock will be unlocked.
299///
300/// The main difference between `MappedMutexGuard` and [`MutexGuard`] is that the
301/// former cannot be used with [`Condvar`], since that
302/// could introduce soundness issues if the locked object is modified by another
303/// thread while the `Mutex` is unlocked.
304///
305/// The data protected by the mutex can be accessed through this guard via its
306/// [`Deref`] and [`DerefMut`] implementations.
307///
308/// This structure is created by the [`map`] and [`filter_map`] methods on
309/// [`MutexGuard`].
310///
311/// [`map`]: MutexGuard::map
312/// [`filter_map`]: MutexGuard::filter_map
313/// [`Condvar`]: crate::sync::Condvar
314#[must_use = "if unused the Mutex will immediately unlock"]
315#[must_not_suspend = "holding a MappedMutexGuard across suspend \
316 points can cause deadlocks, delays, \
317 and cause Futures to not implement `Send`"]
318#[unstable(feature = "mapped_lock_guards", issue = "117108")]
319#[clippy::has_significant_drop]
320pub struct MappedMutexGuard<'a, T: ?Sized + 'a> {
321 // NB: we use a pointer instead of `&'a mut T` to avoid `noalias` violations, because a
322 // `MappedMutexGuard` argument doesn't hold uniqueness for its whole scope, only until it drops.
323 // `NonNull` is covariant over `T`, so we add a `PhantomData<&'a mut T>` field
324 // below for the correct variance over `T` (invariance).
325 data: NonNull<T>,
326 inner: &'a sys::Mutex,
327 poison_flag: &'a poison::Flag,
328 poison: poison::Guard,
329 _variance: PhantomData<&'a mut T>,
330}
331
332#[unstable(feature = "mapped_lock_guards", issue = "117108")]
333impl<T: ?Sized> !Send for MappedMutexGuard<'_, T> {}
334#[unstable(feature = "mapped_lock_guards", issue = "117108")]
335unsafe impl<T: ?Sized + Sync> Sync for MappedMutexGuard<'_, T> {}
336
337impl<T> Mutex<T> {
338 /// Creates a new mutex in an unlocked state ready for use.
339 ///
340 /// # Examples
341 ///
342 /// ```
343 /// use std::sync::Mutex;
344 ///
345 /// let mutex = Mutex::new(0);
346 /// ```
347 #[stable(feature = "rust1", since = "1.0.0")]
348 #[rustc_const_stable(feature = "const_locks", since = "1.63.0")]
349 #[inline]
350 pub const fn new(t: T) -> Mutex<T> {
351 Mutex { inner: sys::Mutex::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) }
352 }
353
354 /// Returns the contained value by cloning it.
355 ///
356 /// # Errors
357 ///
358 /// If another user of this mutex panicked while holding the mutex, then
359 /// this call will return an error instead.
360 ///
361 /// # Examples
362 ///
363 /// ```
364 /// #![feature(lock_value_accessors)]
365 ///
366 /// use std::sync::Mutex;
367 ///
368 /// let mut mutex = Mutex::new(7);
369 ///
370 /// assert_eq!(mutex.get_cloned().unwrap(), 7);
371 /// ```
372 #[unstable(feature = "lock_value_accessors", issue = "133407")]
373 pub fn get_cloned(&self) -> Result<T, PoisonError<()>>
374 where
375 T: Clone,
376 {
377 match self.lock() {
378 Ok(guard) => Ok((*guard).clone()),
379 Err(_) => Err(PoisonError::new(())),
380 }
381 }
382
383 /// Sets the contained value.
384 ///
385 /// # Errors
386 ///
387 /// If another user of this mutex panicked while holding the mutex, then
388 /// this call will return an error containing the provided `value` instead.
389 ///
390 /// # Examples
391 ///
392 /// ```
393 /// #![feature(lock_value_accessors)]
394 ///
395 /// use std::sync::Mutex;
396 ///
397 /// let mut mutex = Mutex::new(7);
398 ///
399 /// assert_eq!(mutex.get_cloned().unwrap(), 7);
400 /// mutex.set(11).unwrap();
401 /// assert_eq!(mutex.get_cloned().unwrap(), 11);
402 /// ```
403 #[unstable(feature = "lock_value_accessors", issue = "133407")]
404 #[rustc_should_not_be_called_on_const_items]
405 pub fn set(&self, value: T) -> Result<(), PoisonError<T>> {
406 if mem::needs_drop::<T>() {
407 // If the contained value has non-trivial destructor, we
408 // call that destructor after the lock being released.
409 self.replace(value).map(drop)
410 } else {
411 match self.lock() {
412 Ok(mut guard) => {
413 *guard = value;
414
415 Ok(())
416 }
417 Err(_) => Err(PoisonError::new(value)),
418 }
419 }
420 }
421
422 /// Replaces the contained value with `value`, and returns the old contained value.
423 ///
424 /// # Errors
425 ///
426 /// If another user of this mutex panicked while holding the mutex, then
427 /// this call will return an error containing the provided `value` instead.
428 ///
429 /// # Examples
430 ///
431 /// ```
432 /// #![feature(lock_value_accessors)]
433 ///
434 /// use std::sync::Mutex;
435 ///
436 /// let mut mutex = Mutex::new(7);
437 ///
438 /// assert_eq!(mutex.replace(11).unwrap(), 7);
439 /// assert_eq!(mutex.get_cloned().unwrap(), 11);
440 /// ```
441 #[unstable(feature = "lock_value_accessors", issue = "133407")]
442 #[rustc_should_not_be_called_on_const_items]
443 pub fn replace(&self, value: T) -> LockResult<T> {
444 match self.lock() {
445 Ok(mut guard) => Ok(mem::replace(&mut *guard, value)),
446 Err(_) => Err(PoisonError::new(value)),
447 }
448 }
449}
450
451impl<T: ?Sized> Mutex<T> {
452 /// Acquires a mutex, blocking the current thread until it is able to do so.
453 ///
454 /// This function will block the local thread until it is available to acquire
455 /// the mutex. Upon returning, the thread is the only thread with the lock
456 /// held. An RAII guard is returned to allow scoped unlock of the lock. When
457 /// the guard goes out of scope, the mutex will be unlocked.
458 ///
459 /// The exact behavior on locking a mutex in the thread which already holds
460 /// the lock is left unspecified. However, this function will not return on
461 /// the second call (it might panic or deadlock, for example).
462 ///
463 /// # Errors
464 ///
465 /// If another user of this mutex panicked while holding the mutex, then
466 /// this call will return an error once the mutex is acquired. The acquired
467 /// mutex guard will be contained in the returned error.
468 ///
469 /// # Panics
470 ///
471 /// This function might panic when called if the lock is already held by
472 /// the current thread.
473 ///
474 /// # Examples
475 ///
476 /// ```
477 /// use std::sync::{Arc, Mutex};
478 /// use std::thread;
479 ///
480 /// let mutex = Arc::new(Mutex::new(0));
481 /// let c_mutex = Arc::clone(&mutex);
482 ///
483 /// thread::spawn(move || {
484 /// *c_mutex.lock().unwrap() = 10;
485 /// }).join().expect("thread::spawn failed");
486 /// assert_eq!(*mutex.lock().unwrap(), 10);
487 /// ```
488 #[stable(feature = "rust1", since = "1.0.0")]
489 #[rustc_should_not_be_called_on_const_items]
490 pub fn lock(&self) -> LockResult<MutexGuard<'_, T>> {
491 unsafe {
492 self.inner.lock();
493 MutexGuard::new(self)
494 }
495 }
496
497 /// Attempts to acquire this lock.
498 ///
499 /// If the lock could not be acquired at this time, then [`Err`] is returned.
500 /// Otherwise, an RAII guard is returned. The lock will be unlocked when the
501 /// guard is dropped.
502 ///
503 /// This function does not block.
504 ///
505 /// # Errors
506 ///
507 /// If another user of this mutex panicked while holding the mutex, then
508 /// this call will return the [`Poisoned`] error if the mutex would
509 /// otherwise be acquired. An acquired lock guard will be contained
510 /// in the returned error.
511 ///
512 /// If the mutex could not be acquired because it is already locked, then
513 /// this call will return the [`WouldBlock`] error.
514 ///
515 /// [`Poisoned`]: TryLockError::Poisoned
516 /// [`WouldBlock`]: TryLockError::WouldBlock
517 ///
518 /// # Examples
519 ///
520 /// ```
521 /// use std::sync::{Arc, Mutex};
522 /// use std::thread;
523 ///
524 /// let mutex = Arc::new(Mutex::new(0));
525 /// let c_mutex = Arc::clone(&mutex);
526 ///
527 /// thread::spawn(move || {
528 /// let mut lock = c_mutex.try_lock();
529 /// if let Ok(ref mut mutex) = lock {
530 /// **mutex = 10;
531 /// } else {
532 /// println!("try_lock failed");
533 /// }
534 /// }).join().expect("thread::spawn failed");
535 /// assert_eq!(*mutex.lock().unwrap(), 10);
536 /// ```
537 #[stable(feature = "rust1", since = "1.0.0")]
538 #[rustc_should_not_be_called_on_const_items]
539 pub fn try_lock(&self) -> TryLockResult<MutexGuard<'_, T>> {
540 unsafe {
541 if self.inner.try_lock() {
542 Ok(MutexGuard::new(self)?)
543 } else {
544 Err(TryLockError::WouldBlock)
545 }
546 }
547 }
548
549 /// Determines whether the mutex is poisoned.
550 ///
551 /// If another thread is active, the mutex can still become poisoned at any
552 /// time. You should not trust a `false` value for program correctness
553 /// without additional synchronization.
554 ///
555 /// # Examples
556 ///
557 /// ```
558 /// use std::sync::{Arc, Mutex};
559 /// use std::thread;
560 ///
561 /// let mutex = Arc::new(Mutex::new(0));
562 /// let c_mutex = Arc::clone(&mutex);
563 ///
564 /// let _ = thread::spawn(move || {
565 /// let _lock = c_mutex.lock().unwrap();
566 /// panic!(); // the mutex gets poisoned
567 /// }).join();
568 /// assert_eq!(mutex.is_poisoned(), true);
569 /// ```
570 #[inline]
571 #[stable(feature = "sync_poison", since = "1.2.0")]
572 pub fn is_poisoned(&self) -> bool {
573 self.poison.get()
574 }
575
576 /// Clear the poisoned state from a mutex.
577 ///
578 /// If the mutex is poisoned, it will remain poisoned until this function is called. This
579 /// allows recovering from a poisoned state and marking that it has recovered. For example, if
580 /// the value is overwritten by a known-good value, then the mutex can be marked as
581 /// un-poisoned. Or possibly, the value could be inspected to determine if it is in a
582 /// consistent state, and if so the poison is removed.
583 ///
584 /// # Examples
585 ///
586 /// ```
587 /// use std::sync::{Arc, Mutex};
588 /// use std::thread;
589 ///
590 /// let mutex = Arc::new(Mutex::new(0));
591 /// let c_mutex = Arc::clone(&mutex);
592 ///
593 /// let _ = thread::spawn(move || {
594 /// let _lock = c_mutex.lock().unwrap();
595 /// panic!(); // the mutex gets poisoned
596 /// }).join();
597 ///
598 /// assert_eq!(mutex.is_poisoned(), true);
599 /// let x = mutex.lock().unwrap_or_else(|mut e| {
600 /// **e.get_mut() = 1;
601 /// mutex.clear_poison();
602 /// e.into_inner()
603 /// });
604 /// assert_eq!(mutex.is_poisoned(), false);
605 /// assert_eq!(*x, 1);
606 /// ```
607 #[inline]
608 #[stable(feature = "mutex_unpoison", since = "1.77.0")]
609 #[rustc_should_not_be_called_on_const_items]
610 pub fn clear_poison(&self) {
611 self.poison.clear();
612 }
613
614 /// Consumes this mutex, returning the underlying data.
615 ///
616 /// # Errors
617 ///
618 /// If another user of this mutex panicked while holding the mutex, then
619 /// this call will return an error containing the underlying data
620 /// instead.
621 ///
622 /// # Examples
623 ///
624 /// ```
625 /// use std::sync::Mutex;
626 ///
627 /// let mutex = Mutex::new(0);
628 /// assert_eq!(mutex.into_inner().unwrap(), 0);
629 /// ```
630 #[stable(feature = "mutex_into_inner", since = "1.6.0")]
631 pub fn into_inner(self) -> LockResult<T>
632 where
633 T: Sized,
634 {
635 let data = self.data.into_inner();
636 poison::map_result(self.poison.borrow(), |()| data)
637 }
638
639 /// Returns a mutable reference to the underlying data.
640 ///
641 /// Since this call borrows the `Mutex` mutably, no actual locking needs to
642 /// take place -- the mutable borrow statically guarantees no new locks can be acquired
643 /// while this reference exists. Note that this method does not clear any previous abandoned locks
644 /// (e.g., via [`forget()`] on a [`MutexGuard`]).
645 ///
646 /// # Errors
647 ///
648 /// If another user of this mutex panicked while holding the mutex, then
649 /// this call will return an error containing a mutable reference to the
650 /// underlying data instead.
651 ///
652 /// # Examples
653 ///
654 /// ```
655 /// use std::sync::Mutex;
656 ///
657 /// let mut mutex = Mutex::new(0);
658 /// *mutex.get_mut().unwrap() = 10;
659 /// assert_eq!(*mutex.lock().unwrap(), 10);
660 /// ```
661 ///
662 /// [`forget()`]: mem::forget
663 #[stable(feature = "mutex_get_mut", since = "1.6.0")]
664 pub fn get_mut(&mut self) -> LockResult<&mut T> {
665 let data = self.data.get_mut();
666 poison::map_result(self.poison.borrow(), |()| data)
667 }
668
669 /// Returns a raw pointer to the underlying data.
670 ///
671 /// The returned pointer is always non-null and properly aligned, but it is
672 /// the user's responsibility to ensure that any reads and writes through it
673 /// are properly synchronized to avoid data races, and that it is not read
674 /// or written through after the mutex is dropped.
675 #[unstable(feature = "mutex_data_ptr", issue = "140368")]
676 pub const fn data_ptr(&self) -> *mut T {
677 self.data.get()
678 }
679}
680
681#[stable(feature = "mutex_from", since = "1.24.0")]
682impl<T> From<T> for Mutex<T> {
683 /// Creates a new mutex in an unlocked state ready for use.
684 /// This is equivalent to [`Mutex::new`].
685 fn from(t: T) -> Self {
686 Mutex::new(t)
687 }
688}
689
690#[stable(feature = "mutex_default", since = "1.10.0")]
691impl<T: Default> Default for Mutex<T> {
692 /// Creates a `Mutex<T>`, with the `Default` value for T.
693 fn default() -> Mutex<T> {
694 Mutex::new(Default::default())
695 }
696}
697
698#[stable(feature = "rust1", since = "1.0.0")]
699impl<T: ?Sized + fmt::Debug> fmt::Debug for Mutex<T> {
700 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
701 let mut d = f.debug_struct("Mutex");
702 match self.try_lock() {
703 Ok(guard) => {
704 d.field("data", &&*guard);
705 }
706 Err(TryLockError::Poisoned(err: PoisonError<{unknown}>)) => {
707 d.field("data", &&**err.get_ref());
708 }
709 Err(TryLockError::WouldBlock) => {
710 d.field("data", &"<locked>");
711 }
712 }
713 d.field("poisoned", &self.poison.get());
714 d.finish_non_exhaustive()
715 }
716}
717
718impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> {
719 unsafe fn new(lock: &'mutex Mutex<T>) -> LockResult<MutexGuard<'mutex, T>> {
720 poison::map_result(result:lock.poison.guard(), |guard: Guard| MutexGuard { lock, poison: guard })
721 }
722}
723
724#[stable(feature = "rust1", since = "1.0.0")]
725impl<T: ?Sized> Deref for MutexGuard<'_, T> {
726 type Target = T;
727
728 fn deref(&self) -> &T {
729 unsafe { &*self.lock.data.get() }
730 }
731}
732
733#[stable(feature = "rust1", since = "1.0.0")]
734impl<T: ?Sized> DerefMut for MutexGuard<'_, T> {
735 fn deref_mut(&mut self) -> &mut T {
736 unsafe { &mut *self.lock.data.get() }
737 }
738}
739
740#[stable(feature = "rust1", since = "1.0.0")]
741impl<T: ?Sized> Drop for MutexGuard<'_, T> {
742 #[inline]
743 fn drop(&mut self) {
744 unsafe {
745 self.lock.poison.done(&self.poison);
746 self.lock.inner.unlock();
747 }
748 }
749}
750
751#[stable(feature = "std_debug", since = "1.16.0")]
752impl<T: ?Sized + fmt::Debug> fmt::Debug for MutexGuard<'_, T> {
753 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
754 fmt::Debug::fmt(&**self, f)
755 }
756}
757
758#[stable(feature = "std_guard_impls", since = "1.20.0")]
759impl<T: ?Sized + fmt::Display> fmt::Display for MutexGuard<'_, T> {
760 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
761 (**self).fmt(f)
762 }
763}
764
765/// For use in [`nonpoison::condvar`](super::condvar).
766pub(super) fn guard_lock<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a sys::Mutex {
767 &guard.lock.inner
768}
769
770/// For use in [`nonpoison::condvar`](super::condvar).
771pub(super) fn guard_poison<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a poison::Flag {
772 &guard.lock.poison
773}
774
775impl<'a, T: ?Sized> MutexGuard<'a, T> {
776 /// Makes a [`MappedMutexGuard`] for a component of the borrowed data, e.g.
777 /// an enum variant.
778 ///
779 /// The `Mutex` is already locked, so this cannot fail.
780 ///
781 /// This is an associated function that needs to be used as
782 /// `MutexGuard::map(...)`. A method would interfere with methods of the
783 /// same name on the contents of the `MutexGuard` used through `Deref`.
784 #[unstable(feature = "mapped_lock_guards", issue = "117108")]
785 pub fn map<U, F>(orig: Self, f: F) -> MappedMutexGuard<'a, U>
786 where
787 F: FnOnce(&mut T) -> &mut U,
788 U: ?Sized,
789 {
790 // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard
791 // was created, and have been upheld throughout `map` and/or `filter_map`.
792 // The signature of the closure guarantees that it will not "leak" the lifetime of the reference
793 // passed to it. If the closure panics, the guard will be dropped.
794 let data = NonNull::from(f(unsafe { &mut *orig.lock.data.get() }));
795 let orig = ManuallyDrop::new(orig);
796 MappedMutexGuard {
797 data,
798 inner: &orig.lock.inner,
799 poison_flag: &orig.lock.poison,
800 poison: orig.poison.clone(),
801 _variance: PhantomData,
802 }
803 }
804
805 /// Makes a [`MappedMutexGuard`] for a component of the borrowed data. The
806 /// original guard is returned as an `Err(...)` if the closure returns
807 /// `None`.
808 ///
809 /// The `Mutex` is already locked, so this cannot fail.
810 ///
811 /// This is an associated function that needs to be used as
812 /// `MutexGuard::filter_map(...)`. A method would interfere with methods of the
813 /// same name on the contents of the `MutexGuard` used through `Deref`.
814 #[unstable(feature = "mapped_lock_guards", issue = "117108")]
815 pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedMutexGuard<'a, U>, Self>
816 where
817 F: FnOnce(&mut T) -> Option<&mut U>,
818 U: ?Sized,
819 {
820 // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard
821 // was created, and have been upheld throughout `map` and/or `filter_map`.
822 // The signature of the closure guarantees that it will not "leak" the lifetime of the reference
823 // passed to it. If the closure panics, the guard will be dropped.
824 match f(unsafe { &mut *orig.lock.data.get() }) {
825 Some(data) => {
826 let data = NonNull::from(data);
827 let orig = ManuallyDrop::new(orig);
828 Ok(MappedMutexGuard {
829 data,
830 inner: &orig.lock.inner,
831 poison_flag: &orig.lock.poison,
832 poison: orig.poison.clone(),
833 _variance: PhantomData,
834 })
835 }
836 None => Err(orig),
837 }
838 }
839}
840
841#[unstable(feature = "mapped_lock_guards", issue = "117108")]
842impl<T: ?Sized> Deref for MappedMutexGuard<'_, T> {
843 type Target = T;
844
845 fn deref(&self) -> &T {
846 unsafe { self.data.as_ref() }
847 }
848}
849
850#[unstable(feature = "mapped_lock_guards", issue = "117108")]
851impl<T: ?Sized> DerefMut for MappedMutexGuard<'_, T> {
852 fn deref_mut(&mut self) -> &mut T {
853 unsafe { self.data.as_mut() }
854 }
855}
856
857#[unstable(feature = "mapped_lock_guards", issue = "117108")]
858impl<T: ?Sized> Drop for MappedMutexGuard<'_, T> {
859 #[inline]
860 fn drop(&mut self) {
861 unsafe {
862 self.poison_flag.done(&self.poison);
863 self.inner.unlock();
864 }
865 }
866}
867
868#[unstable(feature = "mapped_lock_guards", issue = "117108")]
869impl<T: ?Sized + fmt::Debug> fmt::Debug for MappedMutexGuard<'_, T> {
870 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
871 fmt::Debug::fmt(&**self, f)
872 }
873}
874
875#[unstable(feature = "mapped_lock_guards", issue = "117108")]
876impl<T: ?Sized + fmt::Display> fmt::Display for MappedMutexGuard<'_, T> {
877 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
878 (**self).fmt(f)
879 }
880}
881
882impl<'a, T: ?Sized> MappedMutexGuard<'a, T> {
883 /// Makes a [`MappedMutexGuard`] for a component of the borrowed data, e.g.
884 /// an enum variant.
885 ///
886 /// The `Mutex` is already locked, so this cannot fail.
887 ///
888 /// This is an associated function that needs to be used as
889 /// `MappedMutexGuard::map(...)`. A method would interfere with methods of the
890 /// same name on the contents of the `MutexGuard` used through `Deref`.
891 #[unstable(feature = "mapped_lock_guards", issue = "117108")]
892 pub fn map<U, F>(mut orig: Self, f: F) -> MappedMutexGuard<'a, U>
893 where
894 F: FnOnce(&mut T) -> &mut U,
895 U: ?Sized,
896 {
897 // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard
898 // was created, and have been upheld throughout `map` and/or `filter_map`.
899 // The signature of the closure guarantees that it will not "leak" the lifetime of the reference
900 // passed to it. If the closure panics, the guard will be dropped.
901 let data = NonNull::from(f(unsafe { orig.data.as_mut() }));
902 let orig = ManuallyDrop::new(orig);
903 MappedMutexGuard {
904 data,
905 inner: orig.inner,
906 poison_flag: orig.poison_flag,
907 poison: orig.poison.clone(),
908 _variance: PhantomData,
909 }
910 }
911
912 /// Makes a [`MappedMutexGuard`] for a component of the borrowed data. The
913 /// original guard is returned as an `Err(...)` if the closure returns
914 /// `None`.
915 ///
916 /// The `Mutex` is already locked, so this cannot fail.
917 ///
918 /// This is an associated function that needs to be used as
919 /// `MappedMutexGuard::filter_map(...)`. A method would interfere with methods of the
920 /// same name on the contents of the `MutexGuard` used through `Deref`.
921 #[unstable(feature = "mapped_lock_guards", issue = "117108")]
922 pub fn filter_map<U, F>(mut orig: Self, f: F) -> Result<MappedMutexGuard<'a, U>, Self>
923 where
924 F: FnOnce(&mut T) -> Option<&mut U>,
925 U: ?Sized,
926 {
927 // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard
928 // was created, and have been upheld throughout `map` and/or `filter_map`.
929 // The signature of the closure guarantees that it will not "leak" the lifetime of the reference
930 // passed to it. If the closure panics, the guard will be dropped.
931 match f(unsafe { orig.data.as_mut() }) {
932 Some(data) => {
933 let data = NonNull::from(data);
934 let orig = ManuallyDrop::new(orig);
935 Ok(MappedMutexGuard {
936 data,
937 inner: orig.inner,
938 poison_flag: orig.poison_flag,
939 poison: orig.poison.clone(),
940 _variance: PhantomData,
941 })
942 }
943 None => Err(orig),
944 }
945 }
946}
947