11 /// An asynchronous `Mutex`-like type.
13 /// This type acts similarly to [`std::sync::Mutex`], with two major
17 /// # Which kind of mutex should you use?
20 /// [`Mutex`][std] from the standard library in asynchronous code.
22 /// The feature that the async mutex offers over the blocking mutex is the
24 /// mutex more expensive than the blocking mutex, so the blocking mutex should
26 /// async mutex is to provide shared mutable access to IO resources such as a
27 /// database connection. If the value behind the mutex is just data, it's
28 /// usually appropriate to use a blocking mutex such as the one in the standard
31 /// Note that, although the compiler will not prevent the std `Mutex` from holding
36 /// A common pattern is to wrap the `Arc<Mutex<...>>` in a struct that provides
38 /// lock the mutex inside these methods. The [mini-redis] example provides an
45 /// [std]: std::sync::Mutex
52 /// use tokio::sync::Mutex;
57 ///     let data1 = Arc::new(Mutex::new(0));
72 /// use tokio::sync::Mutex;
77 ///     let count = Arc::new(Mutex::new(0));
99 /// 1. The mutex is wrapped in an [`Arc`] to allow it to be shared across
102 /// 3. Mutation of the data protected by the Mutex is done by de-referencing
105 /// Tokio's Mutex works in a simple FIFO (first in, first out) style where all
107 /// Mutex is "fair" and predictable in how it distributes the locks to inner
115 /// Note that in contrast to [`std::sync::Mutex`], this implementation does not
116 /// poison the mutex when a thread holding the [`MutexGuard`] panics. In such a
117 /// case, the mutex will be unlocked. If the panic is caught, this might leave
118 /// the data protected by the mutex in an inconsistent state.
120 /// [`Mutex`]: struct@Mutex
123 /// [`std::sync::Mutex`]: struct@std::sync::Mutex
125 /// [`lock`]: method@Mutex::lock
126 pub struct Mutex<T: ?Sized> {  struct
131 /// A handle to a held `Mutex`. The guard can be held across any `.await` point  argument
135 /// `T`. The guard internally borrows the `Mutex`, so the mutex will not be
141     lock: &'a Mutex<T>,
144 /// An owned handle to a held `Mutex`.
146 /// This guard is only available from a `Mutex` that is wrapped in an [`Arc`]. It
147 /// is identical to `MutexGuard`, except that rather than borrowing the `Mutex`,
153 /// `Mutex`, so even if the lock goes away, the guard remains valid.
160     lock: Arc<Mutex<T>>,
163 // As long as T: Send, it's fine to send and share Mutex<T> between threads.
164 // If T was not Send, sending and sharing a Mutex<T> would be bad, since you can
165 // access T through Mutex<T>.
166 unsafe impl<T> Send for Mutex<T> where T: ?Sized + Send {}  implementation
167 unsafe impl<T> Sync for Mutex<T> where T: ?Sized + Send {}  implementation
171 /// Error returned from the [`Mutex::try_lock`], [`RwLock::try_read`] and
174 /// `Mutex::try_lock` operation will only fail if the mutex is already locked.
182 /// [`Mutex::try_lock`]: Mutex::try_lock
209     check_unpin::<Mutex<u32>>();  in bounds()
210     check_send_sync::<Mutex<u32>>();  in bounds()
213     let mutex = Mutex::new(1);  in bounds()  localVariable
214     check_send_sync_val(mutex.lock());  in bounds()
215     let arc_mutex = Arc::new(Mutex::new(1));  in bounds()
220 impl<T: ?Sized> Mutex<T> {  implementation
226     /// use tokio::sync::Mutex;
228     /// let lock = Mutex::new(5);
245     /// use tokio::sync::Mutex;
247     /// static LOCK: Mutex<i32> = Mutex::const_new(5);
261     /// Locks this mutex, causing the current task
268     /// use tokio::sync::Mutex;
272     ///     let mutex = Mutex::new(1);
274     ///     let mut n = mutex.lock().await;
283     /// Locks this mutex, causing the current task to yield until the lock has
287     /// This method is identical to [`Mutex::lock`], except that the returned
288     /// guard references the `Mutex` with an [`Arc`] rather than by borrowing
289     /// it. Therefore, the `Mutex` must be wrapped in an `Arc` to call this
291     /// the `Mutex` alive by holding an `Arc`.
296     /// use tokio::sync::Mutex;
301     ///     let mutex = Arc::new(Mutex::new(1));
303     ///     let mut n = mutex.clone().lock_owned().await;
329     /// use tokio::sync::Mutex;
332     /// let mutex = Mutex::new(1);
334     /// let n = mutex.try_lock()?;
348     /// Since this call borrows the `Mutex` mutably, no actual locking needs to
354     /// use tokio::sync::Mutex;
357     ///     let mut mutex = Mutex::new(1);
359     ///     let n = mutex.get_mut();
373     /// This method is identical to [`Mutex::try_lock`], except that the
374     /// returned  guard references the `Mutex` with an [`Arc`] rather than by
375     /// borrowing it. Therefore, the `Mutex` must be wrapped in an `Arc` to call
377     /// keeps the `Mutex` alive by holding an `Arc`.
384     /// use tokio::sync::Mutex;
388     /// let mutex = Arc::new(Mutex::new(1));
390     /// let n = mutex.clone().try_lock_owned()?;
401     /// Consumes the mutex, returning the underlying data.
405     /// use tokio::sync::Mutex;
409     ///     let mutex = Mutex::new(1);
411     ///     let n = mutex.into_inner();
423 impl<T> From<T> for Mutex<T> {  implementation
429 impl<T> Default for Mutex<T>  implementation
438 impl<T> std::fmt::Debug for Mutex<T>  implementation
443         let mut d = f.debug_struct("Mutex");  in fmt()