src/libstd/sync/mutex.rs

   1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 use prelude::v1::*;
  12
  13 use cell::UnsafeCell;
  14 use fmt;
  15 use marker;
  16 use ops::{Deref, DerefMut};
  17 use sys_common::mutex as sys;
  18 use sys_common::poison::{self, TryLockError, TryLockResult, LockResult};
  19
  20 /// A mutual exclusion primitive useful for protecting shared data
  21 ///
  22 /// This mutex will block threads waiting for the lock to become available. The
  23 /// mutex can also be statically initialized or created via a `new`
  24 /// constructor. Each mutex has a type parameter which represents the data that
  25 /// it is protecting. The data can only be accessed through the RAII guards
  26 /// returned from `lock` and `try_lock`, which guarantees that the data is only
  27 /// ever accessed when the mutex is locked.
  28 ///
  29 /// # Poisoning
  30 ///
  31 /// The mutexes in this module implement a strategy called "poisoning" where a
  32 /// mutex is considered poisoned whenever a thread panics while holding the
  33 /// lock. Once a mutex is poisoned, all other threads are unable to access the
  34 /// data by default as it is likely tainted (some invariant is not being
  35 /// upheld).
  36 ///
  37 /// For a mutex, this means that the `lock` and `try_lock` methods return a
  38 /// `Result` which indicates whether a mutex has been poisoned or not. Most
  39 /// usage of a mutex will simply `unwrap()` these results, propagating panics
  40 /// among threads to ensure that a possibly invalid invariant is not witnessed.
  41 ///
  42 /// A poisoned mutex, however, does not prevent all access to the underlying
  43 /// data. The `PoisonError` type has an `into_inner` method which will return
  44 /// the guard that would have otherwise been returned on a successful lock. This
  45 /// allows access to the data, despite the lock being poisoned.
  46 ///
  47 /// # Examples
  48 ///
  49 /// ```
  50 /// use std::sync::{Arc, Mutex};
  51 /// use std::thread;
  52 /// use std::sync::mpsc::channel;
  53 ///
  54 /// const N: usize = 10;
  55 ///
  56 /// // Spawn a few threads to increment a shared variable (non-atomically), and
  57 /// // let the main thread know once all increments are done.
  58 /// //
  59 /// // Here we're using an Arc to share memory among threads, and the data inside
  60 /// // the Arc is protected with a mutex.
  61 /// let data = Arc::new(Mutex::new(0));
  62 ///
  63 /// let (tx, rx) = channel();
  64 /// for _ in 0..10 {
  65 ///     let (data, tx) = (data.clone(), tx.clone());
  66 ///     thread::spawn(move || {
  67 ///         // The shared static can only be accessed once the lock is held.
  68 ///         // Our non-atomic increment is safe because we're the only thread
  69 ///         // which can access the shared state when the lock is held.
  70 ///         //
  71 ///         // We unwrap() the return value to assert that we are not expecting
  72 ///         // threads to ever fail while holding the lock.
  73 ///         let mut data = data.lock().unwrap();
  74 ///         *data += 1;
  75 ///         if *data == N {
  76 ///             tx.send(()).unwrap();
  77 ///         }
  78 ///         // the lock is unlocked here when `data` goes out of scope.
  79 ///     });
  80 /// }
  81 ///
  82 /// rx.recv().unwrap();
  83 /// ```
  84 ///
  85 /// To recover from a poisoned mutex:
  86 ///
  87 /// ```
  88 /// use std::sync::{Arc, Mutex};
  89 /// use std::thread;
  90 ///
  91 /// let lock = Arc::new(Mutex::new(0_u32));
  92 /// let lock2 = lock.clone();
  93 ///
  94 /// let _ = thread::spawn(move || -> () {
  95 ///     // This thread will acquire the mutex first, unwrapping the result of
  96 ///     // `lock` because the lock has not been poisoned.
  97 ///     let _lock = lock2.lock().unwrap();
  98 ///
  99 ///     // This panic while holding the lock (`_guard` is in scope) will poison
 100 ///     // the mutex.
 101 ///     panic!();
 102 /// }).join();
 103 ///
 104 /// // The lock is poisoned by this point, but the returned result can be
 105 /// // pattern matched on to return the underlying guard on both branches.
 106 /// let mut guard = match lock.lock() {
 107 ///     Ok(guard) => guard,
 108 ///     Err(poisoned) => poisoned.into_inner(),
 109 /// };
 110 ///
 111 /// *guard += 1;
 112 /// ```
 113 #[stable(feature = "rust1", since = "1.0.0")]
 114 pub struct Mutex<T: ?Sized> {
 115     // Note that this static mutex is in a *box*, not inlined into the struct
 116     // itself. Once a native mutex has been used once, its address can never
 117     // change (it can't be moved). This mutex type can be safely moved at any
 118     // time, so to ensure that the native mutex is used correctly we box the
 119     // inner lock to give it a constant address.
 120     inner: Box<StaticMutex>,
 121     data: UnsafeCell<T>,
 122 }
 123
 124 // these are the only places where `T: Send` matters; all other
 125 // functionality works fine on a single thread.
 126 unsafe impl<T: ?Sized + Send> Send for Mutex<T> { }
 127
 128 unsafe impl<T: ?Sized + Send> Sync for Mutex<T> { }
 129
 130 /// The static mutex type is provided to allow for static allocation of mutexes.
 131 ///
 132 /// Note that this is a separate type because using a Mutex correctly means that
 133 /// it needs to have a destructor run. In Rust, statics are not allowed to have
 134 /// destructors. As a result, a `StaticMutex` has one extra method when compared
 135 /// to a `Mutex`, a `destroy` method. This method is unsafe to call, and
 136 /// documentation can be found directly on the method.
 137 ///
 138 /// # Examples
 139 ///
 140 /// ```
 141 /// #![feature(static_mutex)]
 142 ///
 143 /// use std::sync::{StaticMutex, MUTEX_INIT};
 144 ///
 145 /// static LOCK: StaticMutex = MUTEX_INIT;
 146 ///
 147 /// {
 148 ///     let _g = LOCK.lock().unwrap();
 149 ///     // do some productive work
 150 /// }
 151 /// // lock is unlocked here.
 152 /// ```
 153 #[unstable(feature = "static_mutex",
 154            reason = "may be merged with Mutex in the future",
 155            issue = "27717")]
 156 pub struct StaticMutex {
 157     lock: sys::Mutex,
 158     poison: poison::Flag,
 159 }
 160
 161 /// An RAII implementation of a "scoped lock" of a mutex. When this structure is
 162 /// dropped (falls out of scope), the lock will be unlocked.
 163 ///
 164 /// The data protected by the mutex can be access through this guard via its
 165 /// `Deref` and `DerefMut` implementations
 166 #[must_use]
 167 #[stable(feature = "rust1", since = "1.0.0")]
 168 pub struct MutexGuard<'a, T: ?Sized + 'a> {
 169     // funny underscores due to how Deref/DerefMut currently work (they
 170     // disregard field privacy).
 171     __lock: &'a StaticMutex,
 172     __data: &'a UnsafeCell<T>,
 173     __poison: poison::Guard,
 174 }
 175
 176 impl<'a, T: ?Sized> !marker::Send for MutexGuard<'a, T> {}
 177
 178 /// Static initialization of a mutex. This constant can be used to initialize
 179 /// other mutex constants.
 180 #[unstable(feature = "static_mutex",
 181            reason = "may be merged with Mutex in the future",
 182            issue = "27717")]
 183 pub const MUTEX_INIT: StaticMutex = StaticMutex::new();
 184
 185 impl<T> Mutex<T> {
 186     /// Creates a new mutex in an unlocked state ready for use.
 187     #[stable(feature = "rust1", since = "1.0.0")]
 188     pub fn new(t: T) -> Mutex<T> {
 189         Mutex {
 190             inner: box StaticMutex::new(),
 191             data: UnsafeCell::new(t),
 192         }
 193     }
 194 }
 195
 196 impl<T: ?Sized> Mutex<T> {
 197     /// Acquires a mutex, blocking the current thread until it is able to do so.
 198     ///
 199     /// This function will block the local thread until it is available to acquire
 200     /// the mutex. Upon returning, the thread is the only thread with the mutex
 201     /// held. An RAII guard is returned to allow scoped unlock of the lock. When
 202     /// the guard goes out of scope, the mutex will be unlocked.
 203     ///
 204     /// # Failure
 205     ///
 206     /// If another user of this mutex panicked while holding the mutex, then
 207     /// this call will return an error once the mutex is acquired.
 208     #[stable(feature = "rust1", since = "1.0.0")]
 209     pub fn lock(&self) -> LockResult<MutexGuard<T>> {
 210         unsafe { self.inner.lock.lock() }
 211         MutexGuard::new(&*self.inner, &self.data)
 212     }
 213
 214     /// Attempts to acquire this lock.
 215     ///
 216     /// If the lock could not be acquired at this time, then `Err` is returned.
 217     /// Otherwise, an RAII guard is returned. The lock will be unlocked when the
 218     /// guard is dropped.
 219     ///
 220     /// This function does not block.
 221     ///
 222     /// # Failure
 223     ///
 224     /// If another user of this mutex panicked while holding the mutex, then
 225     /// this call will return failure if the mutex would otherwise be
 226     /// acquired.
 227     #[stable(feature = "rust1", since = "1.0.0")]
 228     pub fn try_lock(&self) -> TryLockResult<MutexGuard<T>> {
 229         if unsafe { self.inner.lock.try_lock() } {
 230             Ok(try!(MutexGuard::new(&*self.inner, &self.data)))
 231         } else {
 232             Err(TryLockError::WouldBlock)
 233         }
 234     }
 235
 236     /// Determines whether the lock is poisoned.
 237     ///
 238     /// If another thread is active, the lock can still become poisoned at any
 239     /// time.  You should not trust a `false` value for program correctness
 240     /// without additional synchronization.
 241     #[inline]
 242     #[stable(feature = "sync_poison", since = "1.2.0")]
 243     pub fn is_poisoned(&self) -> bool {
 244         self.inner.poison.get()
 245     }
 246 }
 247
 248 #[stable(feature = "rust1", since = "1.0.0")]
 249 impl<T: ?Sized> Drop for Mutex<T> {
 250     fn drop(&mut self) {
 251         // This is actually safe b/c we know that there is no further usage of
 252         // this mutex (it's up to the user to arrange for a mutex to get
 253         // dropped, that's not our job)
 254         unsafe { self.inner.lock.destroy() }
 255     }
 256 }
 257
 258 #[stable(feature = "rust1", since = "1.0.0")]
 259 impl<T: ?Sized + fmt::Debug + 'static> fmt::Debug for Mutex<T> {
 260     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 261         match self.try_lock() {
 262             Ok(guard) => write!(f, "Mutex {{ data: {:?} }}", &*guard),
 263             Err(TryLockError::Poisoned(err)) => {
 264                 write!(f, "Mutex {{ data: Poisoned({:?}) }}", &**err.get_ref())
 265             },
 266             Err(TryLockError::WouldBlock) => write!(f, "Mutex {{ <locked> }}")
 267         }
 268     }
 269 }
 270
 271 struct Dummy(UnsafeCell<()>);
 272 unsafe impl Sync for Dummy {}
 273 static DUMMY: Dummy = Dummy(UnsafeCell::new(()));
 274
 275 #[unstable(feature = "static_mutex",
 276            reason = "may be merged with Mutex in the future",
 277            issue = "27717")]
 278 impl StaticMutex {
 279     /// Creates a new mutex in an unlocked state ready for use.
 280     pub const fn new() -> StaticMutex {
 281         StaticMutex {
 282             lock: sys::Mutex::new(),
 283             poison: poison::Flag::new(),
 284         }
 285     }
 286
 287     /// Acquires this lock, see `Mutex::lock`
 288     #[inline]
 289     pub fn lock(&'static self) -> LockResult<MutexGuard<()>> {
 290         unsafe { self.lock.lock() }
 291         MutexGuard::new(self, &DUMMY.0)
 292     }
 293
 294     /// Attempts to grab this lock, see `Mutex::try_lock`
 295     #[inline]
 296     pub fn try_lock(&'static self) -> TryLockResult<MutexGuard<()>> {
 297         if unsafe { self.lock.try_lock() } {
 298             Ok(try!(MutexGuard::new(self, &DUMMY.0)))
 299         } else {
 300             Err(TryLockError::WouldBlock)
 301         }
 302     }
 303
 304     /// Deallocates resources associated with this static mutex.
 305     ///
 306     /// This method is unsafe because it provides no guarantees that there are
 307     /// no active users of this mutex, and safety is not guaranteed if there are
 308     /// active users of this mutex.
 309     ///
 310     /// This method is required to ensure that there are no memory leaks on
 311     /// *all* platforms. It may be the case that some platforms do not leak
 312     /// memory if this method is not called, but this is not guaranteed to be
 313     /// true on all platforms.
 314     pub unsafe fn destroy(&'static self) {
 315         self.lock.destroy()
 316     }
 317 }
 318
 319 impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> {
 320
 321     fn new(lock: &'mutex StaticMutex, data: &'mutex UnsafeCell<T>)
 322            -> LockResult<MutexGuard<'mutex, T>> {
 323         poison::map_result(lock.poison.borrow(), |guard| {
 324             MutexGuard {
 325                 __lock: lock,
 326                 __data: data,
 327                 __poison: guard,
 328             }
 329         })
 330     }
 331 }
 332
 333 #[stable(feature = "rust1", since = "1.0.0")]
 334 impl<'mutex, T: ?Sized> Deref for MutexGuard<'mutex, T> {
 335     type Target = T;
 336
 337     fn deref(&self) -> &T {
 338         unsafe { &*self.__data.get() }
 339     }
 340 }
 341
 342 #[stable(feature = "rust1", since = "1.0.0")]
 343 impl<'mutex, T: ?Sized> DerefMut for MutexGuard<'mutex, T> {
 344     fn deref_mut(&mut self) -> &mut T {
 345         unsafe { &mut *self.__data.get() }
 346     }
 347 }
 348
 349 #[stable(feature = "rust1", since = "1.0.0")]
 350 impl<'a, T: ?Sized> Drop for MutexGuard<'a, T> {
 351     #[inline]
 352     fn drop(&mut self) {
 353         unsafe {
 354             self.__lock.poison.done(&self.__poison);
 355             self.__lock.lock.unlock();
 356         }
 357     }
 358 }
 359
 360 pub fn guard_lock<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a sys::Mutex {
 361     &guard.__lock.lock
 362 }
 363
 364 pub fn guard_poison<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a poison::Flag {
 365     &guard.__lock.poison
 366 }
 367
 368 #[cfg(test)]
 369 mod tests {
 370     use prelude::v1::*;
 371
 372     use sync::mpsc::channel;
 373     use sync::{Arc, Mutex, StaticMutex, Condvar};
 374     use thread;
 375
 376     struct Packet<T>(Arc<(Mutex<T>, Condvar)>);
 377
 378     unsafe impl<T: Send> Send for Packet<T> {}
 379     unsafe impl<T> Sync for Packet<T> {}
 380
 381     #[test]
 382     fn smoke() {
 383         let m = Mutex::new(());
 384         drop(m.lock().unwrap());
 385         drop(m.lock().unwrap());
 386     }
 387
 388     #[test]
 389     fn smoke_static() {
 390         static M: StaticMutex = StaticMutex::new();
 391         unsafe {
 392             drop(M.lock().unwrap());
 393             drop(M.lock().unwrap());
 394             M.destroy();
 395         }
 396     }
 397
 398     #[test]
 399     fn lots_and_lots() {
 400         static M: StaticMutex = StaticMutex::new();
 401         static mut CNT: u32 = 0;
 402         const J: u32 = 1000;
 403         const K: u32 = 3;
 404
 405         fn inc() {
 406             for _ in 0..J {
 407                 unsafe {
 408                     let _g = M.lock().unwrap();
 409                     CNT += 1;
 410                 }
 411             }
 412         }
 413
 414         let (tx, rx) = channel();
 415         for _ in 0..K {
 416             let tx2 = tx.clone();
 417             thread::spawn(move|| { inc(); tx2.send(()).unwrap(); });
 418             let tx2 = tx.clone();
 419             thread::spawn(move|| { inc(); tx2.send(()).unwrap(); });
 420         }
 421
 422         drop(tx);
 423         for _ in 0..2 * K {
 424             rx.recv().unwrap();
 425         }
 426         assert_eq!(unsafe {CNT}, J * K * 2);
 427         unsafe {
 428             M.destroy();
 429         }
 430     }
 431
 432     #[test]
 433     fn try_lock() {
 434         let m = Mutex::new(());
 435         *m.try_lock().unwrap() = ();
 436     }
 437
 438     #[test]
 439     fn test_mutex_arc_condvar() {
 440         let packet = Packet(Arc::new((Mutex::new(false), Condvar::new())));
 441         let packet2 = Packet(packet.0.clone());
 442         let (tx, rx) = channel();
 443         let _t = thread::spawn(move|| {
 444             // wait until parent gets in
 445             rx.recv().unwrap();
 446             let &(ref lock, ref cvar) = &*packet2.0;
 447             let mut lock = lock.lock().unwrap();
 448             *lock = true;
 449             cvar.notify_one();
 450         });
 451
 452         let &(ref lock, ref cvar) = &*packet.0;
 453         let mut lock = lock.lock().unwrap();
 454         tx.send(()).unwrap();
 455         assert!(!*lock);
 456         while !*lock {
 457             lock = cvar.wait(lock).unwrap();
 458         }
 459     }
 460
 461     #[test]
 462     fn test_arc_condvar_poison() {
 463         let packet = Packet(Arc::new((Mutex::new(1), Condvar::new())));
 464         let packet2 = Packet(packet.0.clone());
 465         let (tx, rx) = channel();
 466
 467         let _t = thread::spawn(move || -> () {
 468             rx.recv().unwrap();
 469             let &(ref lock, ref cvar) = &*packet2.0;
 470             let _g = lock.lock().unwrap();
 471             cvar.notify_one();
 472             // Parent should fail when it wakes up.
 473             panic!();
 474         });
 475
 476         let &(ref lock, ref cvar) = &*packet.0;
 477         let mut lock = lock.lock().unwrap();
 478         tx.send(()).unwrap();
 479         while *lock == 1 {
 480             match cvar.wait(lock) {
 481                 Ok(l) => {
 482                     lock = l;
 483                     assert_eq!(*lock, 1);
 484                 }
 485                 Err(..) => break,
 486             }
 487         }
 488     }
 489
 490     #[test]
 491     fn test_mutex_arc_poison() {
 492         let arc = Arc::new(Mutex::new(1));
 493         assert!(!arc.is_poisoned());
 494         let arc2 = arc.clone();
 495         let _ = thread::spawn(move|| {
 496             let lock = arc2.lock().unwrap();
 497             assert_eq!(*lock, 2);
 498         }).join();
 499         assert!(arc.lock().is_err());
 500         assert!(arc.is_poisoned());
 501     }
 502
 503     #[test]
 504     fn test_mutex_arc_nested() {
 505         // Tests nested mutexes and access
 506         // to underlying data.
 507         let arc = Arc::new(Mutex::new(1));
 508         let arc2 = Arc::new(Mutex::new(arc));
 509         let (tx, rx) = channel();
 510         let _t = thread::spawn(move|| {
 511             let lock = arc2.lock().unwrap();
 512             let lock2 = lock.lock().unwrap();
 513             assert_eq!(*lock2, 1);
 514             tx.send(()).unwrap();
 515         });
 516         rx.recv().unwrap();
 517     }
 518
 519     #[test]
 520     fn test_mutex_arc_access_in_unwind() {
 521         let arc = Arc::new(Mutex::new(1));
 522         let arc2 = arc.clone();
 523         let _ = thread::spawn(move|| -> () {
 524             struct Unwinder {
 525                 i: Arc<Mutex<i32>>,
 526             }
 527             impl Drop for Unwinder {
 528                 fn drop(&mut self) {
 529                     *self.i.lock().unwrap() += 1;
 530                 }
 531             }
 532             let _u = Unwinder { i: arc2 };
 533             panic!();
 534         }).join();
 535         let lock = arc.lock().unwrap();
 536         assert_eq!(*lock, 2);
 537     }
 538
 539     #[test]
 540     fn test_mutex_unsized() {
 541         let mutex: &Mutex<[i32]> = &Mutex::new([1, 2, 3]);
 542         {
 543             let b = &mut *mutex.lock().unwrap();
 544             b[0] = 4;
 545             b[2] = 5;
 546         }
 547         let comp: &[i32] = &[4, 2, 5];
 548         assert_eq!(&*mutex.lock().unwrap(), comp);
 549     }
 550 }