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 marker;
  15 use ops::{Deref, DerefMut};
  16 use sync::poison::{self, LockResult, TryLockError, TryLockResult};
  17 use sys_common::rwlock as sys;
  18
  19 /// A reader-writer lock
  20 ///
  21 /// This type of lock allows a number of readers or at most one writer at any
  22 /// point in time. The write portion of this lock typically allows modification
  23 /// of the underlying data (exclusive access) and the read portion of this lock
  24 /// typically allows for read-only access (shared access).
  25 ///
  26 /// The type parameter `T` represents the data that this lock protects. It is
  27 /// required that `T` satisfies `Send` to be shared across tasks and `Sync` to
  28 /// allow concurrent access through readers. The RAII guards returned from the
  29 /// locking methods implement `Deref` (and `DerefMut` for the `write` methods)
  30 /// to allow access to the contained of the lock.
  31 ///
  32 /// # Poisoning
  33 ///
  34 /// RwLocks, like Mutexes, will become poisoned on panics. Note, however, that
  35 /// an RwLock may only be poisoned if a panic occurs while it is locked
  36 /// exclusively (write mode). If a panic occurs in any reader, then the lock
  37 /// will not be poisoned.
  38 ///
  39 /// # Examples
  40 ///
  41 /// ```
  42 /// use std::sync::RwLock;
  43 ///
  44 /// let lock = RwLock::new(5i);
  45 ///
  46 /// // many reader locks can be held at once
  47 /// {
  48 ///     let r1 = lock.read().unwrap();
  49 ///     let r2 = lock.read().unwrap();
  50 ///     assert_eq!(*r1, 5);
  51 ///     assert_eq!(*r2, 5);
  52 /// } // read locks are dropped at this point
  53 ///
  54 /// // only one write lock may be held, however
  55 /// {
  56 ///     let mut w = lock.write().unwrap();
  57 ///     *w += 1;
  58 ///     assert_eq!(*w, 6);
  59 /// } // write lock is dropped here
  60 /// ```
  61 #[stable]
  62 pub struct RwLock<T> {
  63     inner: Box<StaticRwLock>,
  64     data: UnsafeCell<T>,
  65 }
  66
  67 unsafe impl<T:'static+Send> Send for RwLock<T> {}
  68 unsafe impl<T> Sync for RwLock<T> {}
  69
  70 /// Structure representing a statically allocated RwLock.
  71 ///
  72 /// This structure is intended to be used inside of a `static` and will provide
  73 /// automatic global access as well as lazy initialization. The internal
  74 /// resources of this RwLock, however, must be manually deallocated.
  75 ///
  76 /// # Example
  77 ///
  78 /// ```
  79 /// use std::sync::{StaticRwLock, RW_LOCK_INIT};
  80 ///
  81 /// static LOCK: StaticRwLock = RW_LOCK_INIT;
  82 ///
  83 /// {
  84 ///     let _g = LOCK.read().unwrap();
  85 ///     // ... shared read access
  86 /// }
  87 /// {
  88 ///     let _g = LOCK.write().unwrap();
  89 ///     // ... exclusive write access
  90 /// }
  91 /// unsafe { LOCK.destroy() } // free all resources
  92 /// ```
  93 #[unstable = "may be merged with RwLock in the future"]
  94 pub struct StaticRwLock {
  95     lock: sys::RWLock,
  96     poison: poison::Flag,
  97 }
  98
  99 unsafe impl Send for StaticRwLock {}
 100 unsafe impl Sync for StaticRwLock {}
 101
 102 /// Constant initialization for a statically-initialized rwlock.
 103 #[unstable = "may be merged with RwLock in the future"]
 104 pub const RW_LOCK_INIT: StaticRwLock = StaticRwLock {
 105     lock: sys::RWLOCK_INIT,
 106     poison: poison::FLAG_INIT,
 107 };
 108
 109 /// RAII structure used to release the shared read access of a lock when
 110 /// dropped.
 111 #[must_use]
 112 #[stable]
 113 pub struct RwLockReadGuard<'a, T: 'a> {
 114     __lock: &'a StaticRwLock,
 115     __data: &'a UnsafeCell<T>,
 116 }
 117
 118 impl<'a, T> !marker::Send for RwLockReadGuard<'a, T> {}
 119
 120 /// RAII structure used to release the exclusive write access of a lock when
 121 /// dropped.
 122 #[must_use]
 123 #[stable]
 124 pub struct RwLockWriteGuard<'a, T: 'a> {
 125     __lock: &'a StaticRwLock,
 126     __data: &'a UnsafeCell<T>,
 127     __poison: poison::Guard,
 128 }
 129
 130 impl<'a, T> !marker::Send for RwLockWriteGuard<'a, T> {}
 131
 132 impl<T: Send + Sync> RwLock<T> {
 133     /// Creates a new instance of an RwLock which is unlocked and read to go.
 134     #[stable]
 135     pub fn new(t: T) -> RwLock<T> {
 136         RwLock { inner: box RW_LOCK_INIT, data: UnsafeCell::new(t) }
 137     }
 138
 139     /// Locks this rwlock with shared read access, blocking the current thread
 140     /// until it can be acquired.
 141     ///
 142     /// The calling thread will be blocked until there are no more writers which
 143     /// hold the lock. There may be other readers currently inside the lock when
 144     /// this method returns. This method does not provide any guarantees with
 145     /// respect to the ordering of whether contentious readers or writers will
 146     /// acquire the lock first.
 147     ///
 148     /// Returns an RAII guard which will release this thread's shared access
 149     /// once it is dropped.
 150     ///
 151     /// # Failure
 152     ///
 153     /// This function will return an error if the RwLock is poisoned. An RwLock
 154     /// is poisoned whenever a writer panics while holding an exclusive lock.
 155     /// The failure will occur immediately after the lock has been acquired.
 156     #[inline]
 157     #[stable]
 158     pub fn read(&self) -> LockResult<RwLockReadGuard<T>> {
 159         unsafe { self.inner.lock.read() }
 160         RwLockReadGuard::new(&*self.inner, &self.data)
 161     }
 162
 163     /// Attempt to acquire this lock with shared read access.
 164     ///
 165     /// This function will never block and will return immediately if `read`
 166     /// would otherwise succeed. Returns `Some` of an RAII guard which will
 167     /// release the shared access of this thread when dropped, or `None` if the
 168     /// access could not be granted. This method does not provide any
 169     /// guarantees with respect to the ordering of whether contentious readers
 170     /// or writers will acquire the lock first.
 171     ///
 172     /// # Failure
 173     ///
 174     /// This function will return an error if the RwLock is poisoned. An RwLock
 175     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 176     /// error will only be returned if the lock would have otherwise been
 177     /// acquired.
 178     #[inline]
 179     #[stable]
 180     pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<T>> {
 181         if unsafe { self.inner.lock.try_read() } {
 182             Ok(try!(RwLockReadGuard::new(&*self.inner, &self.data)))
 183         } else {
 184             Err(TryLockError::WouldBlock)
 185         }
 186     }
 187
 188     /// Lock this rwlock with exclusive write access, blocking the current
 189     /// thread until it can be acquired.
 190     ///
 191     /// This function will not return while other writers or other readers
 192     /// currently have access to the lock.
 193     ///
 194     /// Returns an RAII guard which will drop the write access of this rwlock
 195     /// when dropped.
 196     ///
 197     /// # Failure
 198     ///
 199     /// This function will return an error if the RwLock is poisoned. An RwLock
 200     /// is poisoned whenever a writer panics while holding an exclusive lock.
 201     /// An error will be returned when the lock is acquired.
 202     #[inline]
 203     #[stable]
 204     pub fn write(&self) -> LockResult<RwLockWriteGuard<T>> {
 205         unsafe { self.inner.lock.write() }
 206         RwLockWriteGuard::new(&*self.inner, &self.data)
 207     }
 208
 209     /// Attempt to lock this rwlock with exclusive write access.
 210     ///
 211     /// This function does not ever block, and it will return `None` if a call
 212     /// to `write` would otherwise block. If successful, an RAII guard is
 213     /// returned.
 214     ///
 215     /// # Failure
 216     ///
 217     /// This function will return an error if the RwLock is poisoned. An RwLock
 218     /// is poisoned whenever a writer panics while holding an exclusive lock. An
 219     /// error will only be returned if the lock would have otherwise been
 220     /// acquired.
 221     #[inline]
 222     #[stable]
 223     pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<T>> {
 224         if unsafe { self.inner.lock.try_read() } {
 225             Ok(try!(RwLockWriteGuard::new(&*self.inner, &self.data)))
 226         } else {
 227             Err(TryLockError::WouldBlock)
 228         }
 229     }
 230 }
 231
 232 #[unsafe_destructor]
 233 #[stable]
 234 impl<T> Drop for RwLock<T> {
 235     fn drop(&mut self) {
 236         unsafe { self.inner.lock.destroy() }
 237     }
 238 }
 239
 240 struct Dummy(UnsafeCell<()>);
 241 unsafe impl Sync for Dummy {}
 242 static DUMMY: Dummy = Dummy(UnsafeCell { value: () });
 243
 244 impl StaticRwLock {
 245     /// Locks this rwlock with shared read access, blocking the current thread
 246     /// until it can be acquired.
 247     ///
 248     /// See `RwLock::read`.
 249     #[inline]
 250     #[unstable = "may be merged with RwLock in the future"]
 251     pub fn read(&'static self) -> LockResult<RwLockReadGuard<'static, ()>> {
 252         unsafe { self.lock.read() }
 253         RwLockReadGuard::new(self, &DUMMY.0)
 254     }
 255
 256     /// Attempt to acquire this lock with shared read access.
 257     ///
 258     /// See `RwLock::try_read`.
 259     #[inline]
 260     #[unstable = "may be merged with RwLock in the future"]
 261     pub fn try_read(&'static self)
 262                     -> TryLockResult<RwLockReadGuard<'static, ()>> {
 263         if unsafe { self.lock.try_read() } {
 264             Ok(try!(RwLockReadGuard::new(self, &DUMMY.0)))
 265         } else {
 266             Err(TryLockError::WouldBlock)
 267         }
 268     }
 269
 270     /// Lock this rwlock with exclusive write access, blocking the current
 271     /// thread until it can be acquired.
 272     ///
 273     /// See `RwLock::write`.
 274     #[inline]
 275     #[unstable = "may be merged with RwLock in the future"]
 276     pub fn write(&'static self) -> LockResult<RwLockWriteGuard<'static, ()>> {
 277         unsafe { self.lock.write() }
 278         RwLockWriteGuard::new(self, &DUMMY.0)
 279     }
 280
 281     /// Attempt to lock this rwlock with exclusive write access.
 282     ///
 283     /// See `RwLock::try_write`.
 284     #[inline]
 285     #[unstable = "may be merged with RwLock in the future"]
 286     pub fn try_write(&'static self)
 287                      -> TryLockResult<RwLockWriteGuard<'static, ()>> {
 288         if unsafe { self.lock.try_write() } {
 289             Ok(try!(RwLockWriteGuard::new(self, &DUMMY.0)))
 290         } else {
 291             Err(TryLockError::WouldBlock)
 292         }
 293     }
 294
 295     /// Deallocate all resources associated with this static lock.
 296     ///
 297     /// This method is unsafe to call as there is no guarantee that there are no
 298     /// active users of the lock, and this also doesn't prevent any future users
 299     /// of this lock. This method is required to be called to not leak memory on
 300     /// all platforms.
 301     #[unstable = "may be merged with RwLock in the future"]
 302     pub unsafe fn destroy(&'static self) {
 303         self.lock.destroy()
 304     }
 305 }
 306
 307 impl<'rwlock, T> RwLockReadGuard<'rwlock, T> {
 308
 309     fn new(lock: &'rwlock StaticRwLock, data: &'rwlock UnsafeCell<T>)
 310            -> LockResult<RwLockReadGuard<'rwlock, T>> {
 311         poison::map_result(lock.poison.borrow(), |_| {
 312             RwLockReadGuard {
 313                 __lock: lock,
 314                 __data: data,
 315             }
 316         })
 317     }
 318 }
 319 impl<'rwlock, T> RwLockWriteGuard<'rwlock, T> {
 320
 321     fn new(lock: &'rwlock StaticRwLock, data: &'rwlock UnsafeCell<T>)
 322            -> LockResult<RwLockWriteGuard<'rwlock, T>> {
 323         poison::map_result(lock.poison.borrow(), |guard| {
 324             RwLockWriteGuard {
 325                 __lock: lock,
 326                 __data: data,
 327                 __poison: guard,
 328             }
 329         })
 330     }
 331 }
 332
 333 #[stable]
 334 impl<'rwlock, T> Deref for RwLockReadGuard<'rwlock, T> {
 335     type Target = T;
 336
 337     fn deref(&self) -> &T { unsafe { &*self.__data.get() } }
 338 }
 339 #[stable]
 340 impl<'rwlock, T> Deref for RwLockWriteGuard<'rwlock, T> {
 341     type Target = T;
 342
 343     fn deref(&self) -> &T { unsafe { &*self.__data.get() } }
 344 }
 345 #[stable]
 346 impl<'rwlock, T> DerefMut for RwLockWriteGuard<'rwlock, T> {
 347     fn deref_mut(&mut self) -> &mut T {
 348         unsafe { &mut *self.__data.get() }
 349     }
 350 }
 351
 352 #[unsafe_destructor]
 353 #[stable]
 354 impl<'a, T> Drop for RwLockReadGuard<'a, T> {
 355     fn drop(&mut self) {
 356         unsafe { self.__lock.lock.read_unlock(); }
 357     }
 358 }
 359
 360 #[unsafe_destructor]
 361 #[stable]
 362 impl<'a, T> Drop for RwLockWriteGuard<'a, T> {
 363     fn drop(&mut self) {
 364         self.__lock.poison.done(&self.__poison);
 365         unsafe { self.__lock.lock.write_unlock(); }
 366     }
 367 }
 368
 369 #[cfg(test)]
 370 mod tests {
 371     use prelude::v1::*;
 372
 373     use rand::{self, Rng};
 374     use sync::mpsc::channel;
 375     use thread::Thread;
 376     use sync::{Arc, RwLock, StaticRwLock, RW_LOCK_INIT};
 377
 378     #[test]
 379     fn smoke() {
 380         let l = RwLock::new(());
 381         drop(l.read().unwrap());
 382         drop(l.write().unwrap());
 383         drop((l.read().unwrap(), l.read().unwrap()));
 384         drop(l.write().unwrap());
 385     }
 386
 387     #[test]
 388     fn static_smoke() {
 389         static R: StaticRwLock = RW_LOCK_INIT;
 390         drop(R.read().unwrap());
 391         drop(R.write().unwrap());
 392         drop((R.read().unwrap(), R.read().unwrap()));
 393         drop(R.write().unwrap());
 394         unsafe { R.destroy(); }
 395     }
 396
 397     #[test]
 398     fn frob() {
 399         static R: StaticRwLock = RW_LOCK_INIT;
 400         static N: uint = 10;
 401         static M: uint = 1000;
 402
 403         let (tx, rx) = channel::<()>();
 404         for _ in range(0, N) {
 405             let tx = tx.clone();
 406             Thread::spawn(move|| {
 407                 let mut rng = rand::thread_rng();
 408                 for _ in range(0, M) {
 409                     if rng.gen_weighted_bool(N) {
 410                         drop(R.write().unwrap());
 411                     } else {
 412                         drop(R.read().unwrap());
 413                     }
 414                 }
 415                 drop(tx);
 416             });
 417         }
 418         drop(tx);
 419         let _ = rx.recv();
 420         unsafe { R.destroy(); }
 421     }
 422
 423     #[test]
 424     fn test_rw_arc_poison_wr() {
 425         let arc = Arc::new(RwLock::new(1i));
 426         let arc2 = arc.clone();
 427         let _: Result<uint, _> = Thread::scoped(move|| {
 428             let _lock = arc2.write().unwrap();
 429             panic!();
 430         }).join();
 431         assert!(arc.read().is_err());
 432     }
 433
 434     #[test]
 435     fn test_rw_arc_poison_ww() {
 436         let arc = Arc::new(RwLock::new(1i));
 437         let arc2 = arc.clone();
 438         let _: Result<uint, _> = Thread::scoped(move|| {
 439             let _lock = arc2.write().unwrap();
 440             panic!();
 441         }).join();
 442         assert!(arc.write().is_err());
 443     }
 444
 445     #[test]
 446     fn test_rw_arc_no_poison_rr() {
 447         let arc = Arc::new(RwLock::new(1i));
 448         let arc2 = arc.clone();
 449         let _: Result<uint, _> = Thread::scoped(move|| {
 450             let _lock = arc2.read().unwrap();
 451             panic!();
 452         }).join();
 453         let lock = arc.read().unwrap();
 454         assert_eq!(*lock, 1);
 455     }
 456     #[test]
 457     fn test_rw_arc_no_poison_rw() {
 458         let arc = Arc::new(RwLock::new(1i));
 459         let arc2 = arc.clone();
 460         let _: Result<uint, _> = Thread::scoped(move|| {
 461             let _lock = arc2.read().unwrap();
 462             panic!()
 463         }).join();
 464         let lock = arc.write().unwrap();
 465         assert_eq!(*lock, 1);
 466     }
 467
 468     #[test]
 469     fn test_rw_arc() {
 470         let arc = Arc::new(RwLock::new(0i));
 471         let arc2 = arc.clone();
 472         let (tx, rx) = channel();
 473
 474         Thread::spawn(move|| {
 475             let mut lock = arc2.write().unwrap();
 476             for _ in range(0u, 10) {
 477                 let tmp = *lock;
 478                 *lock = -1;
 479                 Thread::yield_now();
 480                 *lock = tmp + 1;
 481             }
 482             tx.send(()).unwrap();
 483         });
 484
 485         // Readers try to catch the writer in the act
 486         let mut children = Vec::new();
 487         for _ in range(0u, 5) {
 488             let arc3 = arc.clone();
 489             children.push(Thread::scoped(move|| {
 490                 let lock = arc3.read().unwrap();
 491                 assert!(*lock >= 0);
 492             }));
 493         }
 494
 495         // Wait for children to pass their asserts
 496         for r in children.into_iter() {
 497             assert!(r.join().is_ok());
 498         }
 499
 500         // Wait for writer to finish
 501         rx.recv().unwrap();
 502         let lock = arc.read().unwrap();
 503         assert_eq!(*lock, 10);
 504     }
 505
 506     #[test]
 507     fn test_rw_arc_access_in_unwind() {
 508         let arc = Arc::new(RwLock::new(1i));
 509         let arc2 = arc.clone();
 510         let _ = Thread::scoped(move|| -> () {
 511             struct Unwinder {
 512                 i: Arc<RwLock<int>>,
 513             }
 514             impl Drop for Unwinder {
 515                 fn drop(&mut self) {
 516                     let mut lock = self.i.write().unwrap();
 517                     *lock += 1;
 518                 }
 519             }
 520             let _u = Unwinder { i: arc2 };
 521             panic!();
 522         }).join();
 523         let lock = arc.read().unwrap();
 524         assert_eq!(*lock, 2);
 525     }
 526 }