20 /// Basic operations for a mutex.
22 /// Types implementing this trait can be used by `Mutex` to form a safe and
23 /// fully-functioning mutex type.
27 /// Implementations of this trait must ensure that the mutex is actually
28 /// exclusive: a lock can't be acquired while the mutex is already locked.
30     /// Initial value for an unlocked mutex.
40     /// Acquires this mutex, blocking the current thread until it is able to do so.
43     /// Attempts to acquire this mutex without blocking. Returns `true`
47     /// Unlocks this mutex.
51     /// This method may only be called if the mutex is held in the current context, i.e. it must
60     /// Checks whether the mutex is currently locked.
81     /// Unlocks this mutex using a fair unlock protocol.
85     /// This method may only be called if the mutex is held in the current context, see
91     /// Temporarily yields the mutex to a waiting thread if there is one.
99     /// This method may only be called if the mutex is held in the current context, see
129 /// This mutex will block threads waiting for the lock to become available. The
130 /// mutex can also be statically initialized or created via a `new`
131 /// constructor. Each mutex has a type parameter which represents the data that
134 /// ever accessed when the mutex is locked.
135 pub struct Mutex<R, T: ?Sized> {  struct
140 unsafe impl<R: RawMutex + Send, T: ?Sized + Send> Send for Mutex<R, T> {}  argument
141 unsafe impl<R: RawMutex + Sync, T: ?Sized + Send> Sync for Mutex<R, T> {}  implementation
143 impl<R: RawMutex, T> Mutex<R, T> {  implementation
144     /// Creates a new mutex in an unlocked state ready for use.
147     pub const fn new(val: T) -> Mutex<R, T> {  in new()
148         Mutex {  in new()
154     /// Creates a new mutex in an unlocked state ready for use.
157     pub fn new(val: T) -> Mutex<R, T> {  in new()
158         Mutex {  in new()
164     /// Consumes this mutex, returning the underlying data.
171 impl<R, T> Mutex<R, T> {  impl
172     /// Creates a new mutex based on a pre-existing raw mutex.
174     /// This allows creating a mutex in a constant context on stable Rust.
176     pub const fn const_new(raw_mutex: R, val: T) -> Mutex<R, T> {  in const_new()
177         Mutex {  in const_new()
184 impl<R: RawMutex, T: ?Sized> Mutex<R, T> {  impl
191             mutex: self,  in guard()
196     /// Acquires a mutex, blocking the current thread until it is able to do so.
199     /// the mutex. Upon returning, the thread is the only thread with the mutex
201     /// the guard goes out of scope, the mutex will be unlocked.
203     /// Attempts to lock a mutex in the thread which already holds the lock will
231     /// Since this call borrows the `Mutex` mutably, no actual locking needs to
238     /// Checks whether the mutex is currently locked.
244     /// Forcibly unlocks the mutex.
254     /// Behavior is undefined if a mutex is unlocked when not locked.
260     /// Returns the underlying raw mutex object.
263     /// `lock_api` to be able to call functions on the raw mutex.
267     /// This method is unsafe because it allows unlocking a mutex while
291 impl<R: RawMutexFair, T: ?Sized> Mutex<R, T> {  implementation
292     /// Forcibly unlocks the mutex using a fair unlock procotol.
302     /// Behavior is undefined if a mutex is unlocked when not locked.
309 impl<R: RawMutexTimed, T: ?Sized> Mutex<R, T> {  impl
341 impl<R: RawMutex, T: ?Sized + Default> Default for Mutex<R, T> {  implementation
343     fn default() -> Mutex<R, T> {  in default()
344         Mutex::new(Default::default())  in default()
348 impl<R: RawMutex, T> From<T> for Mutex<R, T> {  implementation
350     fn from(t: T) -> Mutex<R, T> {  in from()
351         Mutex::new(t)  in from()
355 impl<R: RawMutex, T: ?Sized + fmt::Debug> fmt::Debug for Mutex<R, T> {  implementation
358             Some(guard) => f.debug_struct("Mutex").field("data", &&*guard).finish(),  in fmt()
367                 f.debug_struct("Mutex")  in fmt()
377 impl<R, T> Serialize for Mutex<R, T>  implementation
391 impl<'de, R, T> Deserialize<'de> for Mutex<R, T>  implementation
400         Deserialize::deserialize(deserializer).map(Mutex::new)  in deserialize()
404 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
407 /// The data protected by the mutex can be accessed through this guard via its
409 #[must_use = "if unused the Mutex will immediately unlock"]
411     mutex: &'a Mutex<R, T>,  field
418     /// Returns a reference to the original `Mutex` object.
419     pub fn mutex(s: &Self) -> &'a Mutex<R, T> {  in mutex()  method
420         s.mutex  in mutex()
426     /// in already locked the mutex.
436         let raw = &s.mutex.raw;  in map()
437         let data = f(unsafe { &mut *s.mutex.data.get() });  in map()
450     /// in already locked the mutex.
460         let raw = &s.mutex.raw;  in try_map()
461         let data = match f(unsafe { &mut *s.mutex.data.get() }) {  in try_map()
473     /// Temporarily unlocks the mutex to execute the given function.
476     /// references to the data protected by the mutex.
484             s.mutex.raw.unlock();  in unlocked()
486         defer!(s.mutex.raw.lock());  in unlocked()
492     /// Unlocks the mutex using a fair unlock protocol.
495     /// the mutex before another has the chance to acquire the lock, even if
496     /// that thread has been blocked on the mutex for a long time. This is the
498     /// context switch on every mutex unlock. This can result in one thread
499     /// acquiring a mutex many more times than other threads.
508             s.mutex.raw.unlock_fair();  in unlock_fair()
513     /// Temporarily unlocks the mutex to execute the given function.
515     /// The mutex is unlocked using a fair unlock protocol.
518     /// references to the data protected by the mutex.
526             s.mutex.raw.unlock_fair();  in unlocked_fair()
528         defer!(s.mutex.raw.lock());  in unlocked_fair()
532     /// Temporarily yields the mutex to a waiting thread if there is one.
541             s.mutex.raw.bump();  in bump()
550         unsafe { &*self.mutex.data.get() }  in deref()
557         unsafe { &mut *self.mutex.data.get() }  in deref_mut()
566             self.mutex.raw.unlock();  in drop()
586 /// An RAII mutex guard returned by `MutexGuard::map`, which can point to a
593 #[must_use = "if unused the Mutex will immediately unlock"]
613     /// in already locked the mutex.
637     /// in already locked the mutex.
662     /// Unlocks the mutex using a fair unlock protocol.
665     /// the mutex before another has the chance to acquire the lock, even if
666     /// that thread has been blocked on the mutex for a long time. This is the
668     /// context switch on every mutex unlock. This can result in one thread
669     /// acquiring a mutex many more times than other threads.