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.
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.
15 use ops
::{Deref, DerefMut}
;
17 use sys_common
::poison
::{self, LockResult, TryLockError, TryLockResult}
;
18 use sys_common
::rwlock
as sys
;
20 /// A reader-writer lock
22 /// This type of lock allows a number of readers or at most one writer at any
23 /// point in time. The write portion of this lock typically allows modification
24 /// of the underlying data (exclusive access) and the read portion of this lock
25 /// typically allows for read-only access (shared access).
27 /// The priority policy of the lock is dependent on the underlying operating
28 /// system's implementation, and this type does not guarantee that any
29 /// particular policy will be used.
31 /// The type parameter `T` represents the data that this lock protects. It is
32 /// required that `T` satisfies `Send` to be shared across threads and `Sync` to
33 /// allow concurrent access through readers. The RAII guards returned from the
34 /// locking methods implement `Deref` (and `DerefMut` for the `write` methods)
35 /// to allow access to the contained of the lock.
39 /// An `RwLock`, like `Mutex`, will become poisoned on a panic. Note, however,
40 /// that an `RwLock` may only be poisoned if a panic occurs while it is locked
41 /// exclusively (write mode). If a panic occurs in any reader, then the lock
42 /// will not be poisoned.
47 /// use std::sync::RwLock;
49 /// let lock = RwLock::new(5);
51 /// // many reader locks can be held at once
53 /// let r1 = lock.read().unwrap();
54 /// let r2 = lock.read().unwrap();
55 /// assert_eq!(*r1, 5);
56 /// assert_eq!(*r2, 5);
57 /// } // read locks are dropped at this point
59 /// // only one write lock may be held, however
61 /// let mut w = lock.write().unwrap();
63 /// assert_eq!(*w, 6);
64 /// } // write lock is dropped here
66 #[stable(feature = "rust1", since = "1.0.0")]
67 pub struct RwLock
<T
: ?Sized
> {
68 inner
: Box
<sys
::RWLock
>,
73 #[stable(feature = "rust1", since = "1.0.0")]
74 unsafe impl<T
: ?Sized
+ Send
+ Sync
> Send
for RwLock
<T
> {}
75 #[stable(feature = "rust1", since = "1.0.0")]
76 unsafe impl<T
: ?Sized
+ Send
+ Sync
> Sync
for RwLock
<T
> {}
78 /// RAII structure used to release the shared read access of a lock when
81 /// This structure is created by the [`read()`] and [`try_read()`] methods on
84 /// [`read()`]: struct.RwLock.html#method.read
85 /// [`try_read()`]: struct.RwLock.html#method.try_read
86 /// [`RwLock`]: struct.RwLock.html
88 #[stable(feature = "rust1", since = "1.0.0")]
89 pub struct RwLockReadGuard
<'a
, T
: ?Sized
+ 'a
> {
90 __lock
: &'a RwLock
<T
>,
93 #[stable(feature = "rust1", since = "1.0.0")]
94 impl<'a
, T
: ?Sized
> !marker
::Send
for RwLockReadGuard
<'a
, T
> {}
96 /// RAII structure used to release the exclusive write access of a lock when
99 /// This structure is created by the [`write()`] and [`try_write()`] methods
102 /// [`write()`]: struct.RwLock.html#method.write
103 /// [`try_write()`]: struct.RwLock.html#method.try_write
104 /// [`RwLock`]: struct.RwLock.html
106 #[stable(feature = "rust1", since = "1.0.0")]
107 pub struct RwLockWriteGuard
<'a
, T
: ?Sized
+ 'a
> {
108 __lock
: &'a RwLock
<T
>,
109 __poison
: poison
::Guard
,
112 #[stable(feature = "rust1", since = "1.0.0")]
113 impl<'a
, T
: ?Sized
> !marker
::Send
for RwLockWriteGuard
<'a
, T
> {}
116 /// Creates a new instance of an `RwLock<T>` which is unlocked.
121 /// use std::sync::RwLock;
123 /// let lock = RwLock::new(5);
125 #[stable(feature = "rust1", since = "1.0.0")]
126 pub fn new(t
: T
) -> RwLock
<T
> {
128 inner
: box sys
::RWLock
::new(),
129 poison
: poison
::Flag
::new(),
130 data
: UnsafeCell
::new(t
),
135 impl<T
: ?Sized
> RwLock
<T
> {
136 /// Locks this rwlock with shared read access, blocking the current thread
137 /// until it can be acquired.
139 /// The calling thread will be blocked until there are no more writers which
140 /// hold the lock. There may be other readers currently inside the lock when
141 /// this method returns. This method does not provide any guarantees with
142 /// respect to the ordering of whether contentious readers or writers will
143 /// acquire the lock first.
145 /// Returns an RAII guard which will release this thread's shared access
146 /// once it is dropped.
150 /// This function will return an error if the RwLock is poisoned. An RwLock
151 /// is poisoned whenever a writer panics while holding an exclusive lock.
152 /// The failure will occur immediately after the lock has been acquired.
156 /// This function might panic when called if the lock is already held by the current thread.
158 #[stable(feature = "rust1", since = "1.0.0")]
159 pub fn read(&self) -> LockResult
<RwLockReadGuard
<T
>> {
162 RwLockReadGuard
::new(self)
166 /// Attempts to acquire this rwlock with shared read access.
168 /// If the access could not be granted at this time, then `Err` is returned.
169 /// Otherwise, an RAII guard is returned which will release the shared access
170 /// when it is dropped.
172 /// This function does not block.
174 /// This function does not provide any guarantees with respect to the ordering
175 /// of whether contentious readers or writers will acquire the lock first.
179 /// This function will return an error if the RwLock is poisoned. An RwLock
180 /// is poisoned whenever a writer panics while holding an exclusive lock. An
181 /// error will only be returned if the lock would have otherwise been
184 #[stable(feature = "rust1", since = "1.0.0")]
185 pub fn try_read(&self) -> TryLockResult
<RwLockReadGuard
<T
>> {
187 if self.inner
.try_read() {
188 Ok(RwLockReadGuard
::new(self)?
)
190 Err(TryLockError
::WouldBlock
)
195 /// Locks this rwlock with exclusive write access, blocking the current
196 /// thread until it can be acquired.
198 /// This function will not return while other writers or other readers
199 /// currently have access to the lock.
201 /// Returns an RAII guard which will drop the write access of this rwlock
206 /// This function will return an error if the RwLock is poisoned. An RwLock
207 /// is poisoned whenever a writer panics while holding an exclusive lock.
208 /// An error will be returned when the lock is acquired.
212 /// This function might panic when called if the lock is already held by the current thread.
214 #[stable(feature = "rust1", since = "1.0.0")]
215 pub fn write(&self) -> LockResult
<RwLockWriteGuard
<T
>> {
218 RwLockWriteGuard
::new(self)
222 /// Attempts to lock this rwlock with exclusive write access.
224 /// If the lock could not be acquired at this time, then `Err` is returned.
225 /// Otherwise, an RAII guard is returned which will release the lock when
228 /// This function does not block.
230 /// This function does not provide any guarantees with respect to the ordering
231 /// of whether contentious readers or writers will acquire the lock first.
235 /// This function will return an error if the RwLock is poisoned. An RwLock
236 /// is poisoned whenever a writer panics while holding an exclusive lock. An
237 /// error will only be returned if the lock would have otherwise been
240 #[stable(feature = "rust1", since = "1.0.0")]
241 pub fn try_write(&self) -> TryLockResult
<RwLockWriteGuard
<T
>> {
243 if self.inner
.try_write() {
244 Ok(RwLockWriteGuard
::new(self)?
)
246 Err(TryLockError
::WouldBlock
)
251 /// Determines whether the lock is poisoned.
253 /// If another thread is active, the lock can still become poisoned at any
254 /// time. You should not trust a `false` value for program correctness
255 /// without additional synchronization.
257 #[stable(feature = "sync_poison", since = "1.2.0")]
258 pub fn is_poisoned(&self) -> bool
{
262 /// Consumes this `RwLock`, returning the underlying data.
266 /// This function will return an error if the RwLock is poisoned. An RwLock
267 /// is poisoned whenever a writer panics while holding an exclusive lock. An
268 /// error will only be returned if the lock would have otherwise been
270 #[stable(feature = "rwlock_into_inner", since = "1.6.0")]
271 pub fn into_inner(self) -> LockResult
<T
> where T
: Sized
{
272 // We know statically that there are no outstanding references to
273 // `self` so there's no need to lock the inner lock.
275 // To get the inner value, we'd like to call `data.into_inner()`,
276 // but because `RwLock` impl-s `Drop`, we can't move out of it, so
277 // we'll have to destructure it manually instead.
279 // Like `let RwLock { inner, poison, data } = self`.
280 let (inner
, poison
, data
) = {
281 let RwLock { ref inner, ref poison, ref data }
= self;
282 (ptr
::read(inner
), ptr
::read(poison
), ptr
::read(data
))
285 inner
.destroy(); // Keep in sync with the `Drop` impl.
288 poison
::map_result(poison
.borrow(), |_
| data
.into_inner())
292 /// Returns a mutable reference to the underlying data.
294 /// Since this call borrows the `RwLock` mutably, no actual locking needs to
295 /// take place---the mutable borrow statically guarantees no locks exist.
299 /// This function will return an error if the RwLock is poisoned. An RwLock
300 /// is poisoned whenever a writer panics while holding an exclusive lock. An
301 /// error will only be returned if the lock would have otherwise been
303 #[stable(feature = "rwlock_get_mut", since = "1.6.0")]
304 pub fn get_mut(&mut self) -> LockResult
<&mut T
> {
305 // We know statically that there are no other references to `self`, so
306 // there's no need to lock the inner lock.
307 let data
= unsafe { &mut *self.data.get() }
;
308 poison
::map_result(self.poison
.borrow(), |_
| data
)
312 #[stable(feature = "rust1", since = "1.0.0")]
313 impl<T
: ?Sized
> Drop
for RwLock
<T
> {
314 #[unsafe_destructor_blind_to_params]
316 // IMPORTANT: This code needs to be kept in sync with `RwLock::into_inner`.
317 unsafe { self.inner.destroy() }
321 #[stable(feature = "rust1", since = "1.0.0")]
322 impl<T
: ?Sized
+ fmt
::Debug
> fmt
::Debug
for RwLock
<T
> {
323 fn fmt(&self, f
: &mut fmt
::Formatter
) -> fmt
::Result
{
324 match self.try_read() {
325 Ok(guard
) => write
!(f
, "RwLock {{ data: {:?} }}", &*guard
),
326 Err(TryLockError
::Poisoned(err
)) => {
327 write
!(f
, "RwLock {{ data: Poisoned({:?}) }}", &**err
.get_ref())
329 Err(TryLockError
::WouldBlock
) => write
!(f
, "RwLock {{ <locked> }}")
334 #[stable(feature = "rw_lock_default", since = "1.9.0")]
335 impl<T
: Default
> Default
for RwLock
<T
> {
336 /// Creates a new `RwLock<T>`, with the `Default` value for T.
337 fn default() -> RwLock
<T
> {
338 RwLock
::new(Default
::default())
342 impl<'rwlock
, T
: ?Sized
> RwLockReadGuard
<'rwlock
, T
> {
343 unsafe fn new(lock
: &'rwlock RwLock
<T
>)
344 -> LockResult
<RwLockReadGuard
<'rwlock
, T
>> {
345 poison
::map_result(lock
.poison
.borrow(), |_
| {
353 impl<'rwlock
, T
: ?Sized
> RwLockWriteGuard
<'rwlock
, T
> {
354 unsafe fn new(lock
: &'rwlock RwLock
<T
>)
355 -> LockResult
<RwLockWriteGuard
<'rwlock
, T
>> {
356 poison
::map_result(lock
.poison
.borrow(), |guard
| {
365 #[stable(feature = "rust1", since = "1.0.0")]
366 impl<'rwlock
, T
: ?Sized
> Deref
for RwLockReadGuard
<'rwlock
, T
> {
369 fn deref(&self) -> &T
{
370 unsafe { &*self.__lock.data.get() }
374 #[stable(feature = "rust1", since = "1.0.0")]
375 impl<'rwlock
, T
: ?Sized
> Deref
for RwLockWriteGuard
<'rwlock
, T
> {
378 fn deref(&self) -> &T
{
379 unsafe { &*self.__lock.data.get() }
383 #[stable(feature = "rust1", since = "1.0.0")]
384 impl<'rwlock
, T
: ?Sized
> DerefMut
for RwLockWriteGuard
<'rwlock
, T
> {
385 fn deref_mut(&mut self) -> &mut T
{
386 unsafe { &mut *self.__lock.data.get() }
390 #[stable(feature = "rust1", since = "1.0.0")]
391 impl<'a
, T
: ?Sized
> Drop
for RwLockReadGuard
<'a
, T
> {
393 unsafe { self.__lock.inner.read_unlock(); }
397 #[stable(feature = "rust1", since = "1.0.0")]
398 impl<'a
, T
: ?Sized
> Drop
for RwLockWriteGuard
<'a
, T
> {
400 self.__lock
.poison
.done(&self.__poison
);
401 unsafe { self.__lock.inner.write_unlock(); }
405 #[cfg(all(test, not(target_os = "emscripten")))]
407 #![allow(deprecated)] // rand
409 use rand
::{self, Rng}
;
410 use sync
::mpsc
::channel
;
412 use sync
::{Arc, RwLock, TryLockError}
;
413 use sync
::atomic
::{AtomicUsize, Ordering}
;
415 #[derive(Eq, PartialEq, Debug)]
420 let l
= RwLock
::new(());
421 drop(l
.read().unwrap());
422 drop(l
.write().unwrap());
423 drop((l
.read().unwrap(), l
.read().unwrap()));
424 drop(l
.write().unwrap());
430 const M
: usize = 1000;
432 let r
= Arc
::new(RwLock
::new(()));
434 let (tx
, rx
) = channel
::<()>();
438 thread
::spawn(move || {
439 let mut rng
= rand
::thread_rng();
441 if rng
.gen_weighted_bool(N
) {
442 drop(r
.write().unwrap());
444 drop(r
.read().unwrap());
455 fn test_rw_arc_poison_wr() {
456 let arc
= Arc
::new(RwLock
::new(1));
457 let arc2
= arc
.clone();
458 let _
: Result
<(), _
> = thread
::spawn(move|| {
459 let _lock
= arc2
.write().unwrap();
462 assert
!(arc
.read().is_err());
466 fn test_rw_arc_poison_ww() {
467 let arc
= Arc
::new(RwLock
::new(1));
468 assert
!(!arc
.is_poisoned());
469 let arc2
= arc
.clone();
470 let _
: Result
<(), _
> = thread
::spawn(move|| {
471 let _lock
= arc2
.write().unwrap();
474 assert
!(arc
.write().is_err());
475 assert
!(arc
.is_poisoned());
479 fn test_rw_arc_no_poison_rr() {
480 let arc
= Arc
::new(RwLock
::new(1));
481 let arc2
= arc
.clone();
482 let _
: Result
<(), _
> = thread
::spawn(move|| {
483 let _lock
= arc2
.read().unwrap();
486 let lock
= arc
.read().unwrap();
487 assert_eq
!(*lock
, 1);
490 fn test_rw_arc_no_poison_rw() {
491 let arc
= Arc
::new(RwLock
::new(1));
492 let arc2
= arc
.clone();
493 let _
: Result
<(), _
> = thread
::spawn(move|| {
494 let _lock
= arc2
.read().unwrap();
497 let lock
= arc
.write().unwrap();
498 assert_eq
!(*lock
, 1);
503 let arc
= Arc
::new(RwLock
::new(0));
504 let arc2
= arc
.clone();
505 let (tx
, rx
) = channel();
507 thread
::spawn(move|| {
508 let mut lock
= arc2
.write().unwrap();
515 tx
.send(()).unwrap();
518 // Readers try to catch the writer in the act
519 let mut children
= Vec
::new();
521 let arc3
= arc
.clone();
522 children
.push(thread
::spawn(move|| {
523 let lock
= arc3
.read().unwrap();
528 // Wait for children to pass their asserts
530 assert
!(r
.join().is_ok());
533 // Wait for writer to finish
535 let lock
= arc
.read().unwrap();
536 assert_eq
!(*lock
, 10);
540 fn test_rw_arc_access_in_unwind() {
541 let arc
= Arc
::new(RwLock
::new(1));
542 let arc2
= arc
.clone();
543 let _
= thread
::spawn(move|| -> () {
545 i
: Arc
<RwLock
<isize>>,
547 impl Drop
for Unwinder
{
549 let mut lock
= self.i
.write().unwrap();
553 let _u
= Unwinder { i: arc2 }
;
556 let lock
= arc
.read().unwrap();
557 assert_eq
!(*lock
, 2);
561 fn test_rwlock_unsized() {
562 let rw
: &RwLock
<[i32]> = &RwLock
::new([1, 2, 3]);
564 let b
= &mut *rw
.write().unwrap();
568 let comp
: &[i32] = &[4, 2, 5];
569 assert_eq
!(&*rw
.read().unwrap(), comp
);
573 fn test_rwlock_try_write() {
574 let lock
= RwLock
::new(0isize
);
575 let read_guard
= lock
.read().unwrap();
577 let write_result
= lock
.try_write();
579 Err(TryLockError
::WouldBlock
) => (),
580 Ok(_
) => assert
!(false, "try_write should not succeed while read_guard is in scope"),
581 Err(_
) => assert
!(false, "unexpected error"),
588 fn test_into_inner() {
589 let m
= RwLock
::new(NonCopy(10));
590 assert_eq
!(m
.into_inner().unwrap(), NonCopy(10));
594 fn test_into_inner_drop() {
595 struct Foo(Arc
<AtomicUsize
>);
598 self.0.fetch_add
(1, Ordering
::SeqCst
);
601 let num_drops
= Arc
::new(AtomicUsize
::new(0));
602 let m
= RwLock
::new(Foo(num_drops
.clone()));
603 assert_eq
!(num_drops
.load(Ordering
::SeqCst
), 0);
605 let _inner
= m
.into_inner().unwrap();
606 assert_eq
!(num_drops
.load(Ordering
::SeqCst
), 0);
608 assert_eq
!(num_drops
.load(Ordering
::SeqCst
), 1);
612 fn test_into_inner_poison() {
613 let m
= Arc
::new(RwLock
::new(NonCopy(10)));
615 let _
= thread
::spawn(move || {
616 let _lock
= m2
.write().unwrap();
617 panic
!("test panic in inner thread to poison RwLock");
620 assert
!(m
.is_poisoned());
621 match Arc
::try_unwrap(m
).unwrap().into_inner() {
622 Err(e
) => assert_eq
!(e
.into_inner(), NonCopy(10)),
623 Ok(x
) => panic
!("into_inner of poisoned RwLock is Ok: {:?}", x
),
629 let mut m
= RwLock
::new(NonCopy(10));
630 *m
.get_mut().unwrap() = NonCopy(20);
631 assert_eq
!(m
.into_inner().unwrap(), NonCopy(20));
635 fn test_get_mut_poison() {
636 let m
= Arc
::new(RwLock
::new(NonCopy(10)));
638 let _
= thread
::spawn(move || {
639 let _lock
= m2
.write().unwrap();
640 panic
!("test panic in inner thread to poison RwLock");
643 assert
!(m
.is_poisoned());
644 match Arc
::try_unwrap(m
).unwrap().get_mut() {
645 Err(e
) => assert_eq
!(*e
.into_inner(), NonCopy(10)),
646 Ok(x
) => panic
!("get_mut of poisoned RwLock is Ok: {:?}", x
),