src/libstd/sync/rwlock.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 mem;
  17 use ops::{Deref, DerefMut};
  18 use ptr;
  19 use sys_common::poison::{self, LockResult, TryLockError, TryLockResult};
  20 use sys_common::rwlock as sys;
  21
  22 /// A reader-writer lock
  23 ///
  24 /// This type of lock allows a number of readers or at most one writer at any
  25 /// point in time. The write portion of this lock typically allows modification
  26 /// of the underlying data (exclusive access) and the read portion of this lock
  27 /// typically allows for read-only access (shared access).
  28 ///
  29 /// The priority policy of the lock is dependent on the underlying operating
  30 /// system's implementation, and this type does not guarantee that any
  31 /// particular policy will be used.
  32 ///
  33 /// The type parameter `T` represents the data that this lock protects. It is
  34 /// required that `T` satisfies `Send` to be shared across threads and `Sync` to
  35 /// allow concurrent access through readers. The RAII guards returned from the
  36 /// locking methods implement `Deref` (and `DerefMut` for the `write` methods)
  37 /// to allow access to the contained of the lock.
  38 ///
  39 /// # Poisoning
  40 ///
  41 /// An `RwLock`, like `Mutex`, will become poisoned on a panic. Note, however,
  42 /// that an `RwLock` may only be poisoned if a panic occurs while it is locked
  43 /// exclusively (write mode). If a panic occurs in any reader, then the lock
  44 /// will not be poisoned.
  45 ///
  46 /// # Examples
  47 ///
  48 /// ```
  49 /// use std::sync::RwLock;
  50 ///
  51 /// let lock = RwLock::new(5);
  52 ///
  53 /// // many reader locks can be held at once
  54 /// {
  55 ///     let r1 = lock.read().unwrap();
  56 ///     let r2 = lock.read().unwrap();
  57 ///     assert_eq!(*r1, 5);
  58 ///     assert_eq!(*r2, 5);
  59 /// } // read locks are dropped at this point
  60 ///
  61 /// // only one write lock may be held, however
  62 /// {
  63 ///     let mut w = lock.write().unwrap();
  64 ///     *w += 1;
  65 ///     assert_eq!(*w, 6);
  66 /// } // write lock is dropped here
  67 /// ```
  68 #[stable(feature = "rust1", since = "1.0.0")]
  69 pub struct RwLock<T: ?Sized> {
  70     inner: Box<sys::RWLock>,
  71     poison: poison::Flag,
  72     data: UnsafeCell<T>,
  73 }
  74
  75 #[stable(feature = "rust1", since = "1.0.0")]
  76 unsafe impl<T: ?Sized + Send + Sync> Send for RwLock<T> {}
  77 #[stable(feature = "rust1", since = "1.0.0")]
  78 unsafe impl<T: ?Sized + Send + Sync> Sync for RwLock<T> {}
  79
  80 /// RAII structure used to release the shared read access of a lock when
  81 /// dropped.
  82 #[must_use]
  83 #[stable(feature = "rust1", since = "1.0.0")]
  84 pub struct RwLockReadGuard<'a, T: ?Sized + 'a> {
  85     __lock: &'a RwLock<T>,
  86 }
  87
  88 #[stable(feature = "rust1", since = "1.0.0")]
  89 impl<'a, T: ?Sized> !marker::Send for RwLockReadGuard<'a, T> {}
  90
  91 /// RAII structure used to release the exclusive write access of a lock when
  92 /// dropped.
  93 #[must_use]
  94 #[stable(feature = "rust1", since = "1.0.0")]
  95 pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> {
  96     __lock: &'a RwLock<T>,
  97     __poison: poison::Guard,
  98 }
  99
 100 #[stable(feature = "rust1", since = "1.0.0")]
 101 impl<'a, T: ?Sized> !marker::Send for RwLockWriteGuard<'a, T> {}
 102
 103 impl<T> RwLock<T> {
 104     /// Creates a new instance of an `RwLock<T>` which is unlocked.
 105     ///
 106     /// # Examples
 107     ///
 108     /// ```
 109     /// use std::sync::RwLock;
 110     ///
 111     /// let lock = RwLock::new(5);
 112     /// ```
 113     #[stable(feature = "rust1", since = "1.0.0")]
 114     pub fn new(t: T) -> RwLock<T> {
 115         RwLock {
 116             inner: box sys::RWLock::new(),
 117             poison: poison::Flag::new(),
 118             data: UnsafeCell::new(t),
 119         }
 120     }
 121 }
 122
 123 impl<T: ?Sized> RwLock<T> {
 124     /// Locks this rwlock with shared read access, blocking the current thread
 125     /// until it can be acquired.
 126     ///
 127     /// The calling thread will be blocked until there are no more writers which
 128     /// hold the lock. There may be other readers currently inside the lock when
 129     /// this method returns. This method does not provide any guarantees with
 130     /// respect to the ordering of whether contentious readers or writers will
 131     /// acquire the lock first.
 132     ///
 133     /// Returns an RAII guard which will release this thread's shared access
 134     /// once it is dropped.
 135     ///
 136     /// # Errors
 137     ///
 138     /// This function will return an error if the RwLock is poisoned. An RwLock
 139     /// is poisoned whenever a writer panics while holding an exclusive lock.
 140     /// The failure will occur immediately after the lock has been acquired.
 141     #[inline]
 142     #[stable(feature = "rust1", since = "1.0.0")]
 143     pub fn read(&self) -> LockResult<RwLockReadGuard<T>> {
 144         unsafe {
 145             self.inner.read();
 146             RwLockReadGuard::new(self)
 147         }
 148     }
 149
 150     /// Attempts to acquire this rwlock with shared read access.
 151     ///
 152     /// If the access could not be granted at this time, then `Err` is returned.
 153     /// Otherwise, an RAII guard is returned which will release the shared access
 154     /// when it is dropped.
 155     ///
 156     /// This function does not block.
 157     ///
 158     /// This function does not provide any guarantees with respect to the ordering
 159     /// of whether contentious readers or writers will acquire the lock first.
 160     ///
 161     /// # Errors
 162     ///
 163     /// This function will return an error if the RwLock is poisoned. An RwLock
 164     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 165     /// error will only be returned if the lock would have otherwise been
 166     /// acquired.
 167     #[inline]
 168     #[stable(feature = "rust1", since = "1.0.0")]
 169     pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<T>> {
 170         unsafe {
 171             if self.inner.try_read() {
 172                 Ok(RwLockReadGuard::new(self)?)
 173             } else {
 174                 Err(TryLockError::WouldBlock)
 175             }
 176         }
 177     }
 178
 179     /// Locks this rwlock with exclusive write access, blocking the current
 180     /// thread until it can be acquired.
 181     ///
 182     /// This function will not return while other writers or other readers
 183     /// currently have access to the lock.
 184     ///
 185     /// Returns an RAII guard which will drop the write access of this rwlock
 186     /// when dropped.
 187     ///
 188     /// # Errors
 189     ///
 190     /// This function will return an error if the RwLock is poisoned. An RwLock
 191     /// is poisoned whenever a writer panics while holding an exclusive lock.
 192     /// An error will be returned when the lock is acquired.
 193     #[inline]
 194     #[stable(feature = "rust1", since = "1.0.0")]
 195     pub fn write(&self) -> LockResult<RwLockWriteGuard<T>> {
 196         unsafe {
 197             self.inner.write();
 198             RwLockWriteGuard::new(self)
 199         }
 200     }
 201
 202     /// Attempts to lock this rwlock with exclusive write access.
 203     ///
 204     /// If the lock could not be acquired at this time, then `Err` is returned.
 205     /// Otherwise, an RAII guard is returned which will release the lock when
 206     /// it is dropped.
 207     ///
 208     /// This function does not block.
 209     ///
 210     /// This function does not provide any guarantees with respect to the ordering
 211     /// of whether contentious readers or writers will acquire the lock first.
 212     ///
 213     /// # Errors
 214     ///
 215     /// This function will return an error if the RwLock is poisoned. An RwLock
 216     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 217     /// error will only be returned if the lock would have otherwise been
 218     /// acquired.
 219     #[inline]
 220     #[stable(feature = "rust1", since = "1.0.0")]
 221     pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<T>> {
 222         unsafe {
 223             if self.inner.try_write() {
 224                 Ok(RwLockWriteGuard::new(self)?)
 225             } else {
 226                 Err(TryLockError::WouldBlock)
 227             }
 228         }
 229     }
 230
 231     /// Determines whether the lock is poisoned.
 232     ///
 233     /// If another thread is active, the lock can still become poisoned at any
 234     /// time.  You should not trust a `false` value for program correctness
 235     /// without additional synchronization.
 236     #[inline]
 237     #[stable(feature = "sync_poison", since = "1.2.0")]
 238     pub fn is_poisoned(&self) -> bool {
 239         self.poison.get()
 240     }
 241
 242     /// Consumes this `RwLock`, returning the underlying data.
 243     ///
 244     /// # Errors
 245     ///
 246     /// This function will return an error if the RwLock is poisoned. An RwLock
 247     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 248     /// error will only be returned if the lock would have otherwise been
 249     /// acquired.
 250     #[stable(feature = "rwlock_into_inner", since = "1.6.0")]
 251     pub fn into_inner(self) -> LockResult<T> where T: Sized {
 252         // We know statically that there are no outstanding references to
 253         // `self` so there's no need to lock the inner lock.
 254         //
 255         // To get the inner value, we'd like to call `data.into_inner()`,
 256         // but because `RwLock` impl-s `Drop`, we can't move out of it, so
 257         // we'll have to destructure it manually instead.
 258         unsafe {
 259             // Like `let RwLock { inner, poison, data } = self`.
 260             let (inner, poison, data) = {
 261                 let RwLock { ref inner, ref poison, ref data } = self;
 262                 (ptr::read(inner), ptr::read(poison), ptr::read(data))
 263             };
 264             mem::forget(self);
 265             inner.destroy();  // Keep in sync with the `Drop` impl.
 266             drop(inner);
 267
 268             poison::map_result(poison.borrow(), |_| data.into_inner())
 269         }
 270     }
 271
 272     /// Returns a mutable reference to the underlying data.
 273     ///
 274     /// Since this call borrows the `RwLock` mutably, no actual locking needs to
 275     /// take place---the mutable borrow statically guarantees no locks exist.
 276     ///
 277     /// # Errors
 278     ///
 279     /// This function will return an error if the RwLock is poisoned. An RwLock
 280     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 281     /// error will only be returned if the lock would have otherwise been
 282     /// acquired.
 283     #[stable(feature = "rwlock_get_mut", since = "1.6.0")]
 284     pub fn get_mut(&mut self) -> LockResult<&mut T> {
 285         // We know statically that there are no other references to `self`, so
 286         // there's no need to lock the inner lock.
 287         let data = unsafe { &mut *self.data.get() };
 288         poison::map_result(self.poison.borrow(), |_| data)
 289     }
 290 }
 291
 292 #[stable(feature = "rust1", since = "1.0.0")]
 293 impl<T: ?Sized> Drop for RwLock<T> {
 294     #[unsafe_destructor_blind_to_params]
 295     fn drop(&mut self) {
 296         // IMPORTANT: This code needs to be kept in sync with `RwLock::into_inner`.
 297         unsafe { self.inner.destroy() }
 298     }
 299 }
 300
 301 #[stable(feature = "rust1", since = "1.0.0")]
 302 impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
 303     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 304         match self.try_read() {
 305             Ok(guard) => write!(f, "RwLock {{ data: {:?} }}", &*guard),
 306             Err(TryLockError::Poisoned(err)) => {
 307                 write!(f, "RwLock {{ data: Poisoned({:?}) }}", &**err.get_ref())
 308             },
 309             Err(TryLockError::WouldBlock) => write!(f, "RwLock {{ <locked> }}")
 310         }
 311     }
 312 }
 313
 314 #[stable(feature = "rw_lock_default", since = "1.9.0")]
 315 impl<T: Default> Default for RwLock<T> {
 316     fn default() -> RwLock<T> {
 317         RwLock::new(Default::default())
 318     }
 319 }
 320
 321 impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
 322     unsafe fn new(lock: &'rwlock RwLock<T>)
 323                   -> LockResult<RwLockReadGuard<'rwlock, T>> {
 324         poison::map_result(lock.poison.borrow(), |_| {
 325             RwLockReadGuard {
 326                 __lock: lock,
 327             }
 328         })
 329     }
 330 }
 331
 332 impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
 333     unsafe fn new(lock: &'rwlock RwLock<T>)
 334                   -> LockResult<RwLockWriteGuard<'rwlock, T>> {
 335         poison::map_result(lock.poison.borrow(), |guard| {
 336             RwLockWriteGuard {
 337                 __lock: lock,
 338                 __poison: guard,
 339             }
 340         })
 341     }
 342 }
 343
 344 #[stable(feature = "rust1", since = "1.0.0")]
 345 impl<'rwlock, T: ?Sized> Deref for RwLockReadGuard<'rwlock, T> {
 346     type Target = T;
 347
 348     fn deref(&self) -> &T {
 349         unsafe { &*self.__lock.data.get() }
 350     }
 351 }
 352
 353 #[stable(feature = "rust1", since = "1.0.0")]
 354 impl<'rwlock, T: ?Sized> Deref for RwLockWriteGuard<'rwlock, T> {
 355     type Target = T;
 356
 357     fn deref(&self) -> &T {
 358         unsafe { &*self.__lock.data.get() }
 359     }
 360 }
 361
 362 #[stable(feature = "rust1", since = "1.0.0")]
 363 impl<'rwlock, T: ?Sized> DerefMut for RwLockWriteGuard<'rwlock, T> {
 364     fn deref_mut(&mut self) -> &mut T {
 365         unsafe { &mut *self.__lock.data.get() }
 366     }
 367 }
 368
 369 #[stable(feature = "rust1", since = "1.0.0")]
 370 impl<'a, T: ?Sized> Drop for RwLockReadGuard<'a, T> {
 371     fn drop(&mut self) {
 372         unsafe { self.__lock.inner.read_unlock(); }
 373     }
 374 }
 375
 376 #[stable(feature = "rust1", since = "1.0.0")]
 377 impl<'a, T: ?Sized> Drop for RwLockWriteGuard<'a, T> {
 378     fn drop(&mut self) {
 379         self.__lock.poison.done(&self.__poison);
 380         unsafe { self.__lock.inner.write_unlock(); }
 381     }
 382 }
 383
 384 #[cfg(test)]
 385 mod tests {
 386     #![allow(deprecated)] // rand
 387
 388     use prelude::v1::*;
 389
 390     use rand::{self, Rng};
 391     use sync::mpsc::channel;
 392     use thread;
 393     use sync::{Arc, RwLock, TryLockError};
 394     use sync::atomic::{AtomicUsize, Ordering};
 395
 396     #[derive(Eq, PartialEq, Debug)]
 397     struct NonCopy(i32);
 398
 399     #[test]
 400     fn smoke() {
 401         let l = RwLock::new(());
 402         drop(l.read().unwrap());
 403         drop(l.write().unwrap());
 404         drop((l.read().unwrap(), l.read().unwrap()));
 405         drop(l.write().unwrap());
 406     }
 407
 408     #[test]
 409     fn frob() {
 410         const N: usize = 10;
 411         const M: usize = 1000;
 412
 413         let r = Arc::new(RwLock::new(()));
 414
 415         let (tx, rx) = channel::<()>();
 416         for _ in 0..N {
 417             let tx = tx.clone();
 418             let r = r.clone();
 419             thread::spawn(move || {
 420                 let mut rng = rand::thread_rng();
 421                 for _ in 0..M {
 422                     if rng.gen_weighted_bool(N) {
 423                         drop(r.write().unwrap());
 424                     } else {
 425                         drop(r.read().unwrap());
 426                     }
 427                 }
 428                 drop(tx);
 429             });
 430         }
 431         drop(tx);
 432         let _ = rx.recv();
 433     }
 434
 435     #[test]
 436     fn test_rw_arc_poison_wr() {
 437         let arc = Arc::new(RwLock::new(1));
 438         let arc2 = arc.clone();
 439         let _: Result<(), _> = thread::spawn(move|| {
 440             let _lock = arc2.write().unwrap();
 441             panic!();
 442         }).join();
 443         assert!(arc.read().is_err());
 444     }
 445
 446     #[test]
 447     fn test_rw_arc_poison_ww() {
 448         let arc = Arc::new(RwLock::new(1));
 449         assert!(!arc.is_poisoned());
 450         let arc2 = arc.clone();
 451         let _: Result<(), _> = thread::spawn(move|| {
 452             let _lock = arc2.write().unwrap();
 453             panic!();
 454         }).join();
 455         assert!(arc.write().is_err());
 456         assert!(arc.is_poisoned());
 457     }
 458
 459     #[test]
 460     fn test_rw_arc_no_poison_rr() {
 461         let arc = Arc::new(RwLock::new(1));
 462         let arc2 = arc.clone();
 463         let _: Result<(), _> = thread::spawn(move|| {
 464             let _lock = arc2.read().unwrap();
 465             panic!();
 466         }).join();
 467         let lock = arc.read().unwrap();
 468         assert_eq!(*lock, 1);
 469     }
 470     #[test]
 471     fn test_rw_arc_no_poison_rw() {
 472         let arc = Arc::new(RwLock::new(1));
 473         let arc2 = arc.clone();
 474         let _: Result<(), _> = thread::spawn(move|| {
 475             let _lock = arc2.read().unwrap();
 476             panic!()
 477         }).join();
 478         let lock = arc.write().unwrap();
 479         assert_eq!(*lock, 1);
 480     }
 481
 482     #[test]
 483     fn test_rw_arc() {
 484         let arc = Arc::new(RwLock::new(0));
 485         let arc2 = arc.clone();
 486         let (tx, rx) = channel();
 487
 488         thread::spawn(move|| {
 489             let mut lock = arc2.write().unwrap();
 490             for _ in 0..10 {
 491                 let tmp = *lock;
 492                 *lock = -1;
 493                 thread::yield_now();
 494                 *lock = tmp + 1;
 495             }
 496             tx.send(()).unwrap();
 497         });
 498
 499         // Readers try to catch the writer in the act
 500         let mut children = Vec::new();
 501         for _ in 0..5 {
 502             let arc3 = arc.clone();
 503             children.push(thread::spawn(move|| {
 504                 let lock = arc3.read().unwrap();
 505                 assert!(*lock >= 0);
 506             }));
 507         }
 508
 509         // Wait for children to pass their asserts
 510         for r in children {
 511             assert!(r.join().is_ok());
 512         }
 513
 514         // Wait for writer to finish
 515         rx.recv().unwrap();
 516         let lock = arc.read().unwrap();
 517         assert_eq!(*lock, 10);
 518     }
 519
 520     #[test]
 521     fn test_rw_arc_access_in_unwind() {
 522         let arc = Arc::new(RwLock::new(1));
 523         let arc2 = arc.clone();
 524         let _ = thread::spawn(move|| -> () {
 525             struct Unwinder {
 526                 i: Arc<RwLock<isize>>,
 527             }
 528             impl Drop for Unwinder {
 529                 fn drop(&mut self) {
 530                     let mut lock = self.i.write().unwrap();
 531                     *lock += 1;
 532                 }
 533             }
 534             let _u = Unwinder { i: arc2 };
 535             panic!();
 536         }).join();
 537         let lock = arc.read().unwrap();
 538         assert_eq!(*lock, 2);
 539     }
 540
 541     #[test]
 542     fn test_rwlock_unsized() {
 543         let rw: &RwLock<[i32]> = &RwLock::new([1, 2, 3]);
 544         {
 545             let b = &mut *rw.write().unwrap();
 546             b[0] = 4;
 547             b[2] = 5;
 548         }
 549         let comp: &[i32] = &[4, 2, 5];
 550         assert_eq!(&*rw.read().unwrap(), comp);
 551     }
 552
 553     #[test]
 554     fn test_rwlock_try_write() {
 555         use mem::drop;
 556
 557         let lock = RwLock::new(0isize);
 558         let read_guard = lock.read().unwrap();
 559
 560         let write_result = lock.try_write();
 561         match write_result {
 562             Err(TryLockError::WouldBlock) => (),
 563             Ok(_) => assert!(false, "try_write should not succeed while read_guard is in scope"),
 564             Err(_) => assert!(false, "unexpected error"),
 565         }
 566
 567         drop(read_guard);
 568     }
 569
 570     #[test]
 571     fn test_into_inner() {
 572         let m = RwLock::new(NonCopy(10));
 573         assert_eq!(m.into_inner().unwrap(), NonCopy(10));
 574     }
 575
 576     #[test]
 577     fn test_into_inner_drop() {
 578         struct Foo(Arc<AtomicUsize>);
 579         impl Drop for Foo {
 580             fn drop(&mut self) {
 581                 self.0.fetch_add(1, Ordering::SeqCst);
 582             }
 583         }
 584         let num_drops = Arc::new(AtomicUsize::new(0));
 585         let m = RwLock::new(Foo(num_drops.clone()));
 586         assert_eq!(num_drops.load(Ordering::SeqCst), 0);
 587         {
 588             let _inner = m.into_inner().unwrap();
 589             assert_eq!(num_drops.load(Ordering::SeqCst), 0);
 590         }
 591         assert_eq!(num_drops.load(Ordering::SeqCst), 1);
 592     }
 593
 594     #[test]
 595     fn test_into_inner_poison() {
 596         let m = Arc::new(RwLock::new(NonCopy(10)));
 597         let m2 = m.clone();
 598         let _ = thread::spawn(move || {
 599             let _lock = m2.write().unwrap();
 600             panic!("test panic in inner thread to poison RwLock");
 601         }).join();
 602
 603         assert!(m.is_poisoned());
 604         match Arc::try_unwrap(m).unwrap().into_inner() {
 605             Err(e) => assert_eq!(e.into_inner(), NonCopy(10)),
 606             Ok(x) => panic!("into_inner of poisoned RwLock is Ok: {:?}", x),
 607         }
 608     }
 609
 610     #[test]
 611     fn test_get_mut() {
 612         let mut m = RwLock::new(NonCopy(10));
 613         *m.get_mut().unwrap() = NonCopy(20);
 614         assert_eq!(m.into_inner().unwrap(), NonCopy(20));
 615     }
 616
 617     #[test]
 618     fn test_get_mut_poison() {
 619         let m = Arc::new(RwLock::new(NonCopy(10)));
 620         let m2 = m.clone();
 621         let _ = thread::spawn(move || {
 622             let _lock = m2.write().unwrap();
 623             panic!("test panic in inner thread to poison RwLock");
 624         }).join();
 625
 626         assert!(m.is_poisoned());
 627         match Arc::try_unwrap(m).unwrap().get_mut() {
 628             Err(e) => assert_eq!(*e.into_inner(), NonCopy(10)),
 629             Ok(x) => panic!("get_mut of poisoned RwLock is Ok: {:?}", x),
 630         }
 631     }
 632 }