1275 lines
48 KiB
Rust
1275 lines
48 KiB
Rust
use crate::cell::UnsafeCell;
|
|
use crate::fmt;
|
|
use crate::marker::PhantomData;
|
|
use crate::mem::{self, ManuallyDrop, forget};
|
|
use crate::ops::{Deref, DerefMut};
|
|
use crate::ptr::NonNull;
|
|
use crate::sync::{LockResult, PoisonError, TryLockError, TryLockResult, poison};
|
|
use crate::sys::sync as sys;
|
|
|
|
/// A reader-writer lock
|
|
///
|
|
/// This type of lock allows a number of readers or at most one writer at any
|
|
/// point in time. The write portion of this lock typically allows modification
|
|
/// of the underlying data (exclusive access) and the read portion of this lock
|
|
/// typically allows for read-only access (shared access).
|
|
///
|
|
/// In comparison, a [`Mutex`] does not distinguish between readers or writers
|
|
/// that acquire the lock, therefore blocking any threads waiting for the lock to
|
|
/// become available. An `RwLock` will allow any number of readers to acquire the
|
|
/// lock as long as a writer is not holding the lock.
|
|
///
|
|
/// The priority policy of the lock is dependent on the underlying operating
|
|
/// system's implementation, and this type does not guarantee that any
|
|
/// particular policy will be used. In particular, a writer which is waiting to
|
|
/// acquire the lock in `write` might or might not block concurrent calls to
|
|
/// `read`, e.g.:
|
|
///
|
|
/// <details><summary>Potential deadlock example</summary>
|
|
///
|
|
/// ```text
|
|
/// // Thread 1 | // Thread 2
|
|
/// let _rg1 = lock.read(); |
|
|
/// | // will block
|
|
/// | let _wg = lock.write();
|
|
/// // may deadlock |
|
|
/// let _rg2 = lock.read(); |
|
|
/// ```
|
|
///
|
|
/// </details>
|
|
///
|
|
/// The type parameter `T` represents the data that this lock protects. It is
|
|
/// required that `T` satisfies [`Send`] to be shared across threads and
|
|
/// [`Sync`] to allow concurrent access through readers. The RAII guards
|
|
/// returned from the locking methods implement [`Deref`] (and [`DerefMut`]
|
|
/// for the `write` methods) to allow access to the content of the lock.
|
|
///
|
|
/// # Poisoning
|
|
///
|
|
/// An `RwLock`, like [`Mutex`], will [usually] become poisoned on a panic. Note,
|
|
/// however, that an `RwLock` may only be poisoned if a panic occurs while it is
|
|
/// locked exclusively (write mode). If a panic occurs in any reader, then the
|
|
/// lock will not be poisoned.
|
|
///
|
|
/// [usually]: super::Mutex#poisoning
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::{Arc, RwLock};
|
|
/// use std::thread;
|
|
/// use std::time::Duration;
|
|
///
|
|
/// let data = Arc::new(RwLock::new(5));
|
|
///
|
|
/// // Multiple readers can access in parallel.
|
|
/// for i in 0..3 {
|
|
/// let lock_clone = Arc::clone(&data);
|
|
///
|
|
/// thread::spawn(move || {
|
|
/// let value = lock_clone.read().unwrap();
|
|
///
|
|
/// println!("Reader {}: Read value {}, now holding lock...", i, *value);
|
|
///
|
|
/// // Simulating a long read operation
|
|
/// thread::sleep(Duration::from_secs(1));
|
|
///
|
|
/// println!("Reader {}: Dropping lock.", i);
|
|
/// // Read lock unlocked when going out of scope.
|
|
/// });
|
|
/// }
|
|
///
|
|
/// thread::sleep(Duration::from_millis(100)); // Wait for readers to start
|
|
///
|
|
/// // While all readers can proceed, a call to .write() has to wait for
|
|
// // current active reader locks.
|
|
/// let mut writable_data = data.write().unwrap();
|
|
/// println!("Writer proceeds...");
|
|
/// *writable_data += 1;
|
|
/// ```
|
|
///
|
|
/// [`Mutex`]: super::Mutex
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[cfg_attr(not(test), rustc_diagnostic_item = "RwLock")]
|
|
pub struct RwLock<T: ?Sized> {
|
|
/// The inner [`sys::RwLock`] that synchronizes thread access to the protected data.
|
|
inner: sys::RwLock,
|
|
/// A flag denoting if this `RwLock` has been poisoned.
|
|
poison: poison::Flag,
|
|
/// The lock-protected data.
|
|
data: UnsafeCell<T>,
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
unsafe impl<T: ?Sized + Send> Send for RwLock<T> {}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
unsafe impl<T: ?Sized + Send + Sync> Sync for RwLock<T> {}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
// Guards
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
/// RAII structure used to release the shared read access of a lock when
|
|
/// dropped.
|
|
///
|
|
/// This structure is created by the [`read`] and [`try_read`] methods on
|
|
/// [`RwLock`].
|
|
///
|
|
/// [`read`]: RwLock::read
|
|
/// [`try_read`]: RwLock::try_read
|
|
#[must_use = "if unused the RwLock will immediately unlock"]
|
|
#[must_not_suspend = "holding a RwLockReadGuard across suspend \
|
|
points can cause deadlocks, delays, \
|
|
and cause Futures to not implement `Send`"]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[clippy::has_significant_drop]
|
|
#[cfg_attr(not(test), rustc_diagnostic_item = "RwLockReadGuard")]
|
|
pub struct RwLockReadGuard<'rwlock, T: ?Sized + 'rwlock> {
|
|
/// A pointer to the data protected by the `RwLock`. Note that we use a pointer here instead of
|
|
/// `&'rwlock T` to avoid `noalias` violations, because a `RwLockReadGuard` instance only holds
|
|
/// immutability until it drops, not for its whole scope.
|
|
/// `NonNull` is preferable over `*const T` to allow for niche optimizations. `NonNull` is also
|
|
/// covariant over `T`, just like we would have with `&T`.
|
|
data: NonNull<T>,
|
|
/// A reference to the internal [`sys::RwLock`] that we have read-locked.
|
|
inner_lock: &'rwlock sys::RwLock,
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> !Send for RwLockReadGuard<'_, T> {}
|
|
|
|
#[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
|
|
unsafe impl<T: ?Sized + Sync> Sync for RwLockReadGuard<'_, T> {}
|
|
|
|
/// RAII structure used to release the exclusive write access of a lock when
|
|
/// dropped.
|
|
///
|
|
/// This structure is created by the [`write`] and [`try_write`] methods
|
|
/// on [`RwLock`].
|
|
///
|
|
/// [`write`]: RwLock::write
|
|
/// [`try_write`]: RwLock::try_write
|
|
#[must_use = "if unused the RwLock will immediately unlock"]
|
|
#[must_not_suspend = "holding a RwLockWriteGuard across suspend \
|
|
points can cause deadlocks, delays, \
|
|
and cause Future's to not implement `Send`"]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[clippy::has_significant_drop]
|
|
#[cfg_attr(not(test), rustc_diagnostic_item = "RwLockWriteGuard")]
|
|
pub struct RwLockWriteGuard<'rwlock, T: ?Sized + 'rwlock> {
|
|
/// A reference to the [`RwLock`] that we have write-locked.
|
|
lock: &'rwlock RwLock<T>,
|
|
/// The poison guard. See the [`poison`] module for more information.
|
|
poison: poison::Guard,
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> !Send for RwLockWriteGuard<'_, T> {}
|
|
|
|
#[stable(feature = "rwlock_guard_sync", since = "1.23.0")]
|
|
unsafe impl<T: ?Sized + Sync> Sync for RwLockWriteGuard<'_, T> {}
|
|
|
|
/// RAII structure used to release the shared read access of a lock when
|
|
/// dropped, which can point to a subfield of the protected data.
|
|
///
|
|
/// This structure is created by the [`map`] and [`filter_map`] methods
|
|
/// on [`RwLockReadGuard`].
|
|
///
|
|
/// [`map`]: RwLockReadGuard::map
|
|
/// [`filter_map`]: RwLockReadGuard::filter_map
|
|
#[must_use = "if unused the RwLock will immediately unlock"]
|
|
#[must_not_suspend = "holding a MappedRwLockReadGuard across suspend \
|
|
points can cause deadlocks, delays, \
|
|
and cause Futures to not implement `Send`"]
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
#[clippy::has_significant_drop]
|
|
pub struct MappedRwLockReadGuard<'rwlock, T: ?Sized + 'rwlock> {
|
|
/// A pointer to the data protected by the `RwLock`. Note that we use a pointer here instead of
|
|
/// `&'rwlock T` to avoid `noalias` violations, because a `MappedRwLockReadGuard` instance only
|
|
/// holds immutability until it drops, not for its whole scope.
|
|
/// `NonNull` is preferable over `*const T` to allow for niche optimizations. `NonNull` is also
|
|
/// covariant over `T`, just like we would have with `&T`.
|
|
data: NonNull<T>,
|
|
/// A reference to the internal [`sys::RwLock`] that we have read-locked.
|
|
inner_lock: &'rwlock sys::RwLock,
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> !Send for MappedRwLockReadGuard<'_, T> {}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
unsafe impl<T: ?Sized + Sync> Sync for MappedRwLockReadGuard<'_, T> {}
|
|
|
|
/// RAII structure used to release the exclusive write access of a lock when
|
|
/// dropped, which can point to a subfield of the protected data.
|
|
///
|
|
/// This structure is created by the [`map`] and [`filter_map`] methods
|
|
/// on [`RwLockWriteGuard`].
|
|
///
|
|
/// [`map`]: RwLockWriteGuard::map
|
|
/// [`filter_map`]: RwLockWriteGuard::filter_map
|
|
#[must_use = "if unused the RwLock will immediately unlock"]
|
|
#[must_not_suspend = "holding a MappedRwLockWriteGuard across suspend \
|
|
points can cause deadlocks, delays, \
|
|
and cause Future's to not implement `Send`"]
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
#[clippy::has_significant_drop]
|
|
pub struct MappedRwLockWriteGuard<'rwlock, T: ?Sized + 'rwlock> {
|
|
/// A pointer to the data protected by the `RwLock`. Note that we use a pointer here instead of
|
|
/// `&'rwlock T` to avoid `noalias` violations, because a `MappedRwLockWriteGuard` instance only
|
|
/// holds uniquneness until it drops, not for its whole scope.
|
|
/// `NonNull` is preferable over `*const T` to allow for niche optimizations.
|
|
data: NonNull<T>,
|
|
/// `NonNull` is covariant over `T`, so we add a `PhantomData<&'rwlock mut T>` field here to
|
|
/// enforce the correct invariance over `T`.
|
|
_variance: PhantomData<&'rwlock mut T>,
|
|
/// A reference to the internal [`sys::RwLock`] that we have write-locked.
|
|
inner_lock: &'rwlock sys::RwLock,
|
|
/// A reference to the original `RwLock`'s poison state.
|
|
poison_flag: &'rwlock poison::Flag,
|
|
/// The poison guard. See the [`poison`] module for more information.
|
|
poison_guard: poison::Guard,
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> !Send for MappedRwLockWriteGuard<'_, T> {}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
unsafe impl<T: ?Sized + Sync> Sync for MappedRwLockWriteGuard<'_, T> {}
|
|
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
// Implementations
|
|
////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
|
|
impl<T> RwLock<T> {
|
|
/// Creates a new instance of an `RwLock<T>` which is unlocked.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let lock = RwLock::new(5);
|
|
/// ```
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[rustc_const_stable(feature = "const_locks", since = "1.63.0")]
|
|
#[inline]
|
|
pub const fn new(t: T) -> RwLock<T> {
|
|
RwLock { inner: sys::RwLock::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) }
|
|
}
|
|
|
|
/// Returns the contained value by cloning it.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error if the `RwLock` is poisoned. An
|
|
/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
|
|
/// lock.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// #![feature(lock_value_accessors)]
|
|
///
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let mut lock = RwLock::new(7);
|
|
///
|
|
/// assert_eq!(lock.get_cloned().unwrap(), 7);
|
|
/// ```
|
|
#[unstable(feature = "lock_value_accessors", issue = "133407")]
|
|
pub fn get_cloned(&self) -> Result<T, PoisonError<()>>
|
|
where
|
|
T: Clone,
|
|
{
|
|
match self.read() {
|
|
Ok(guard) => Ok((*guard).clone()),
|
|
Err(_) => Err(PoisonError::new(())),
|
|
}
|
|
}
|
|
|
|
/// Sets the contained value.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error containing the provided `value` if
|
|
/// the `RwLock` is poisoned. An `RwLock` is poisoned whenever a writer
|
|
/// panics while holding an exclusive lock.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// #![feature(lock_value_accessors)]
|
|
///
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let mut lock = RwLock::new(7);
|
|
///
|
|
/// assert_eq!(lock.get_cloned().unwrap(), 7);
|
|
/// lock.set(11).unwrap();
|
|
/// assert_eq!(lock.get_cloned().unwrap(), 11);
|
|
/// ```
|
|
#[unstable(feature = "lock_value_accessors", issue = "133407")]
|
|
#[rustc_should_not_be_called_on_const_items]
|
|
pub fn set(&self, value: T) -> Result<(), PoisonError<T>> {
|
|
if mem::needs_drop::<T>() {
|
|
// If the contained value has non-trivial destructor, we
|
|
// call that destructor after the lock being released.
|
|
self.replace(value).map(drop)
|
|
} else {
|
|
match self.write() {
|
|
Ok(mut guard) => {
|
|
*guard = value;
|
|
|
|
Ok(())
|
|
}
|
|
Err(_) => Err(PoisonError::new(value)),
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Replaces the contained value with `value`, and returns the old contained value.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error containing the provided `value` if
|
|
/// the `RwLock` is poisoned. An `RwLock` is poisoned whenever a writer
|
|
/// panics while holding an exclusive lock.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// #![feature(lock_value_accessors)]
|
|
///
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let mut lock = RwLock::new(7);
|
|
///
|
|
/// assert_eq!(lock.replace(11).unwrap(), 7);
|
|
/// assert_eq!(lock.get_cloned().unwrap(), 11);
|
|
/// ```
|
|
#[unstable(feature = "lock_value_accessors", issue = "133407")]
|
|
#[rustc_should_not_be_called_on_const_items]
|
|
pub fn replace(&self, value: T) -> LockResult<T> {
|
|
match self.write() {
|
|
Ok(mut guard) => Ok(mem::replace(&mut *guard, value)),
|
|
Err(_) => Err(PoisonError::new(value)),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<T: ?Sized> RwLock<T> {
|
|
/// Locks this `RwLock` with shared read access, blocking the current thread
|
|
/// until it can be acquired.
|
|
///
|
|
/// The calling thread will be blocked until there are no more writers which
|
|
/// hold the lock. There may be other readers currently inside the lock when
|
|
/// this method returns. This method does not provide any guarantees with
|
|
/// respect to the ordering of whether contentious readers or writers will
|
|
/// acquire the lock first.
|
|
///
|
|
/// Returns an RAII guard which will release this thread's shared access
|
|
/// once it is dropped.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error if the `RwLock` is poisoned. An
|
|
/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
|
|
/// lock. The failure will occur immediately after the lock has been
|
|
/// acquired. The acquired lock guard will be contained in the returned
|
|
/// error.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// This function might panic when called if the lock is already held by the current thread
|
|
/// in read or write mode.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::{Arc, RwLock};
|
|
/// use std::thread;
|
|
///
|
|
/// let lock = Arc::new(RwLock::new(1));
|
|
/// let c_lock = Arc::clone(&lock);
|
|
///
|
|
/// let n = lock.read().unwrap();
|
|
/// assert_eq!(*n, 1);
|
|
///
|
|
/// thread::spawn(move || {
|
|
/// let r = c_lock.read();
|
|
/// assert!(r.is_ok());
|
|
/// }).join().unwrap();
|
|
/// ```
|
|
#[inline]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[rustc_should_not_be_called_on_const_items]
|
|
pub fn read(&self) -> LockResult<RwLockReadGuard<'_, T>> {
|
|
unsafe {
|
|
self.inner.read();
|
|
RwLockReadGuard::new(self)
|
|
}
|
|
}
|
|
|
|
/// Attempts to acquire this `RwLock` with shared read access.
|
|
///
|
|
/// If the access could not be granted at this time, then `Err` is returned.
|
|
/// Otherwise, an RAII guard is returned which will release the shared access
|
|
/// when it is dropped.
|
|
///
|
|
/// This function does not block.
|
|
///
|
|
/// This function does not provide any guarantees with respect to the ordering
|
|
/// of whether contentious readers or writers will acquire the lock first.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return the [`Poisoned`] error if the `RwLock` is
|
|
/// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
|
|
/// an exclusive lock. `Poisoned` will only be returned if the lock would
|
|
/// have otherwise been acquired. An acquired lock guard will be contained
|
|
/// in the returned error.
|
|
///
|
|
/// This function will return the [`WouldBlock`] error if the `RwLock` could
|
|
/// not be acquired because it was already locked exclusively.
|
|
///
|
|
/// [`Poisoned`]: TryLockError::Poisoned
|
|
/// [`WouldBlock`]: TryLockError::WouldBlock
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let lock = RwLock::new(1);
|
|
///
|
|
/// match lock.try_read() {
|
|
/// Ok(n) => assert_eq!(*n, 1),
|
|
/// Err(_) => unreachable!(),
|
|
/// };
|
|
/// ```
|
|
#[inline]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[rustc_should_not_be_called_on_const_items]
|
|
pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>> {
|
|
unsafe {
|
|
if self.inner.try_read() {
|
|
Ok(RwLockReadGuard::new(self)?)
|
|
} else {
|
|
Err(TryLockError::WouldBlock)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Locks this `RwLock` with exclusive write access, blocking the current
|
|
/// thread until it can be acquired.
|
|
///
|
|
/// This function will not return while other writers or other readers
|
|
/// currently have access to the lock.
|
|
///
|
|
/// Returns an RAII guard which will drop the write access of this `RwLock`
|
|
/// when dropped.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error if the `RwLock` is poisoned. An
|
|
/// `RwLock` is poisoned whenever a writer panics while holding an exclusive
|
|
/// lock. An error will be returned when the lock is acquired. The acquired
|
|
/// lock guard will be contained in the returned error.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// This function might panic when called if the lock is already held by the current thread
|
|
/// in read or write mode.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let lock = RwLock::new(1);
|
|
///
|
|
/// let mut n = lock.write().unwrap();
|
|
/// *n = 2;
|
|
///
|
|
/// assert!(lock.try_read().is_err());
|
|
/// ```
|
|
#[inline]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[rustc_should_not_be_called_on_const_items]
|
|
pub fn write(&self) -> LockResult<RwLockWriteGuard<'_, T>> {
|
|
unsafe {
|
|
self.inner.write();
|
|
RwLockWriteGuard::new(self)
|
|
}
|
|
}
|
|
|
|
/// Attempts to lock this `RwLock` with exclusive write access.
|
|
///
|
|
/// If the lock could not be acquired at this time, then `Err` is returned.
|
|
/// Otherwise, an RAII guard is returned which will release the lock when
|
|
/// it is dropped.
|
|
///
|
|
/// This function does not block.
|
|
///
|
|
/// This function does not provide any guarantees with respect to the ordering
|
|
/// of whether contentious readers or writers will acquire the lock first.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return the [`Poisoned`] error if the `RwLock` is
|
|
/// poisoned. An `RwLock` is poisoned whenever a writer panics while holding
|
|
/// an exclusive lock. `Poisoned` will only be returned if the lock would
|
|
/// have otherwise been acquired. An acquired lock guard will be contained
|
|
/// in the returned error.
|
|
///
|
|
/// This function will return the [`WouldBlock`] error if the `RwLock` could
|
|
/// not be acquired because it was already locked.
|
|
///
|
|
/// [`Poisoned`]: TryLockError::Poisoned
|
|
/// [`WouldBlock`]: TryLockError::WouldBlock
|
|
///
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let lock = RwLock::new(1);
|
|
///
|
|
/// let n = lock.read().unwrap();
|
|
/// assert_eq!(*n, 1);
|
|
///
|
|
/// assert!(lock.try_write().is_err());
|
|
/// ```
|
|
#[inline]
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
#[rustc_should_not_be_called_on_const_items]
|
|
pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>> {
|
|
unsafe {
|
|
if self.inner.try_write() {
|
|
Ok(RwLockWriteGuard::new(self)?)
|
|
} else {
|
|
Err(TryLockError::WouldBlock)
|
|
}
|
|
}
|
|
}
|
|
|
|
/// Determines whether the lock is poisoned.
|
|
///
|
|
/// If another thread is active, the lock can still become poisoned at any
|
|
/// time. You should not trust a `false` value for program correctness
|
|
/// without additional synchronization.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::{Arc, RwLock};
|
|
/// use std::thread;
|
|
///
|
|
/// let lock = Arc::new(RwLock::new(0));
|
|
/// let c_lock = Arc::clone(&lock);
|
|
///
|
|
/// let _ = thread::spawn(move || {
|
|
/// let _lock = c_lock.write().unwrap();
|
|
/// panic!(); // the lock gets poisoned
|
|
/// }).join();
|
|
/// assert_eq!(lock.is_poisoned(), true);
|
|
/// ```
|
|
#[inline]
|
|
#[stable(feature = "sync_poison", since = "1.2.0")]
|
|
pub fn is_poisoned(&self) -> bool {
|
|
self.poison.get()
|
|
}
|
|
|
|
/// Clear the poisoned state from a lock.
|
|
///
|
|
/// If the lock is poisoned, it will remain poisoned until this function is called. This allows
|
|
/// recovering from a poisoned state and marking that it has recovered. For example, if the
|
|
/// value is overwritten by a known-good value, then the lock can be marked as un-poisoned. Or
|
|
/// possibly, the value could be inspected to determine if it is in a consistent state, and if
|
|
/// so the poison is removed.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::{Arc, RwLock};
|
|
/// use std::thread;
|
|
///
|
|
/// let lock = Arc::new(RwLock::new(0));
|
|
/// let c_lock = Arc::clone(&lock);
|
|
///
|
|
/// let _ = thread::spawn(move || {
|
|
/// let _lock = c_lock.write().unwrap();
|
|
/// panic!(); // the lock gets poisoned
|
|
/// }).join();
|
|
///
|
|
/// assert_eq!(lock.is_poisoned(), true);
|
|
/// let guard = lock.write().unwrap_or_else(|mut e| {
|
|
/// **e.get_mut() = 1;
|
|
/// lock.clear_poison();
|
|
/// e.into_inner()
|
|
/// });
|
|
/// assert_eq!(lock.is_poisoned(), false);
|
|
/// assert_eq!(*guard, 1);
|
|
/// ```
|
|
#[inline]
|
|
#[stable(feature = "mutex_unpoison", since = "1.77.0")]
|
|
pub fn clear_poison(&self) {
|
|
self.poison.clear();
|
|
}
|
|
|
|
/// Consumes this `RwLock`, returning the underlying data.
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error containing the underlying data if
|
|
/// the `RwLock` is poisoned. An `RwLock` is poisoned whenever a writer
|
|
/// panics while holding an exclusive lock. An error will only be returned
|
|
/// if the lock would have otherwise been acquired.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let lock = RwLock::new(String::new());
|
|
/// {
|
|
/// let mut s = lock.write().unwrap();
|
|
/// *s = "modified".to_owned();
|
|
/// }
|
|
/// assert_eq!(lock.into_inner().unwrap(), "modified");
|
|
/// ```
|
|
#[stable(feature = "rwlock_into_inner", since = "1.6.0")]
|
|
pub fn into_inner(self) -> LockResult<T>
|
|
where
|
|
T: Sized,
|
|
{
|
|
let data = self.data.into_inner();
|
|
poison::map_result(self.poison.borrow(), |()| data)
|
|
}
|
|
|
|
/// Returns a mutable reference to the underlying data.
|
|
///
|
|
/// Since this call borrows the `RwLock` mutably, no actual locking needs to
|
|
/// take place -- the mutable borrow statically guarantees no new locks can be acquired
|
|
/// while this reference exists. Note that this method does not clear any previously abandoned
|
|
/// locks (e.g., via [`forget()`] on a [`RwLockReadGuard`] or [`RwLockWriteGuard`]).
|
|
///
|
|
/// # Errors
|
|
///
|
|
/// This function will return an error containing a mutable reference to
|
|
/// the underlying data if the `RwLock` is poisoned. An `RwLock` is
|
|
/// poisoned whenever a writer panics while holding an exclusive lock.
|
|
/// An error will only be returned if the lock would have otherwise been
|
|
/// acquired.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// ```
|
|
/// use std::sync::RwLock;
|
|
///
|
|
/// let mut lock = RwLock::new(0);
|
|
/// *lock.get_mut().unwrap() = 10;
|
|
/// assert_eq!(*lock.read().unwrap(), 10);
|
|
/// ```
|
|
#[stable(feature = "rwlock_get_mut", since = "1.6.0")]
|
|
pub fn get_mut(&mut self) -> LockResult<&mut T> {
|
|
let data = self.data.get_mut();
|
|
poison::map_result(self.poison.borrow(), |()| data)
|
|
}
|
|
|
|
/// Returns a raw pointer to the underlying data.
|
|
///
|
|
/// The returned pointer is always non-null and properly aligned, but it is
|
|
/// the user's responsibility to ensure that any reads and writes through it
|
|
/// are properly synchronized to avoid data races, and that it is not read
|
|
/// or written through after the lock is dropped.
|
|
#[unstable(feature = "rwlock_data_ptr", issue = "140368")]
|
|
pub const fn data_ptr(&self) -> *mut T {
|
|
self.data.get()
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLock<T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
let mut d = f.debug_struct("RwLock");
|
|
match self.try_read() {
|
|
Ok(guard) => {
|
|
d.field("data", &&*guard);
|
|
}
|
|
Err(TryLockError::Poisoned(err)) => {
|
|
d.field("data", &&**err.get_ref());
|
|
}
|
|
Err(TryLockError::WouldBlock) => {
|
|
d.field("data", &format_args!("<locked>"));
|
|
}
|
|
}
|
|
d.field("poisoned", &self.poison.get());
|
|
d.finish_non_exhaustive()
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rw_lock_default", since = "1.10.0")]
|
|
impl<T: Default> Default for RwLock<T> {
|
|
/// Creates a new `RwLock<T>`, with the `Default` value for T.
|
|
fn default() -> RwLock<T> {
|
|
RwLock::new(Default::default())
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rw_lock_from", since = "1.24.0")]
|
|
impl<T> From<T> for RwLock<T> {
|
|
/// Creates a new instance of an `RwLock<T>` which is unlocked.
|
|
/// This is equivalent to [`RwLock::new`].
|
|
fn from(t: T) -> Self {
|
|
RwLock::new(t)
|
|
}
|
|
}
|
|
|
|
impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
|
|
/// Creates a new instance of `RwLockReadGuard<T>` from a `RwLock<T>`.
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// This function is safe if and only if the same thread has successfully and safely called
|
|
/// `lock.inner.read()`, `lock.inner.try_read()`, or `lock.inner.downgrade()` before
|
|
/// instantiating this object.
|
|
unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockReadGuard<'rwlock, T>> {
|
|
poison::map_result(lock.poison.borrow(), |()| RwLockReadGuard {
|
|
data: unsafe { NonNull::new_unchecked(lock.data.get()) },
|
|
inner_lock: &lock.inner,
|
|
})
|
|
}
|
|
|
|
/// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data, e.g.
|
|
/// an enum variant.
|
|
///
|
|
/// The `RwLock` is already locked for reading, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `RwLockReadGuard::map(...)`. A method would interfere with methods of
|
|
/// the same name on the contents of the `RwLockReadGuard` used through
|
|
/// `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be
|
|
/// poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockReadGuard<'rwlock, U>
|
|
where
|
|
F: FnOnce(&T) -> &U,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
let data = NonNull::from(f(unsafe { orig.data.as_ref() }));
|
|
let orig = ManuallyDrop::new(orig);
|
|
MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock }
|
|
}
|
|
|
|
/// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data. The
|
|
/// original guard is returned as an `Err(...)` if the closure returns
|
|
/// `None`.
|
|
///
|
|
/// The `RwLock` is already locked for reading, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `RwLockReadGuard::filter_map(...)`. A method would interfere with methods
|
|
/// of the same name on the contents of the `RwLockReadGuard` used through
|
|
/// `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be
|
|
/// poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockReadGuard<'rwlock, U>, Self>
|
|
where
|
|
F: FnOnce(&T) -> Option<&U>,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
match f(unsafe { orig.data.as_ref() }) {
|
|
Some(data) => {
|
|
let data = NonNull::from(data);
|
|
let orig = ManuallyDrop::new(orig);
|
|
Ok(MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock })
|
|
}
|
|
None => Err(orig),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
|
|
/// Creates a new instance of `RwLockWriteGuard<T>` from a `RwLock<T>`.
|
|
///
|
|
/// # Safety
|
|
///
|
|
/// This function is safe if and only if the same thread has successfully and safely called
|
|
/// `lock.inner.write()`, `lock.inner.try_write()`, or `lock.inner.try_upgrade` before
|
|
/// instantiating this object.
|
|
unsafe fn new(lock: &'rwlock RwLock<T>) -> LockResult<RwLockWriteGuard<'rwlock, T>> {
|
|
poison::map_result(lock.poison.guard(), |guard| RwLockWriteGuard { lock, poison: guard })
|
|
}
|
|
|
|
/// Downgrades a write-locked `RwLockWriteGuard` into a read-locked [`RwLockReadGuard`].
|
|
///
|
|
/// Since we have the `RwLockWriteGuard`, the [`RwLock`] must already be locked for writing, so
|
|
/// this method cannot fail.
|
|
///
|
|
/// After downgrading, other readers will be allowed to read the protected data.
|
|
///
|
|
/// # Examples
|
|
///
|
|
/// `downgrade` takes ownership of the `RwLockWriteGuard` and returns a [`RwLockReadGuard`].
|
|
///
|
|
/// ```
|
|
/// use std::sync::{RwLock, RwLockWriteGuard};
|
|
///
|
|
/// let rw = RwLock::new(0);
|
|
///
|
|
/// let mut write_guard = rw.write().unwrap();
|
|
/// *write_guard = 42;
|
|
///
|
|
/// let read_guard = RwLockWriteGuard::downgrade(write_guard);
|
|
/// assert_eq!(42, *read_guard);
|
|
/// ```
|
|
///
|
|
/// `downgrade` will _atomically_ change the state of the [`RwLock`] from exclusive mode into
|
|
/// shared mode. This means that it is impossible for another writing thread to get in between a
|
|
/// thread calling `downgrade` and any reads it performs after downgrading.
|
|
///
|
|
/// ```
|
|
/// use std::sync::{Arc, RwLock, RwLockWriteGuard};
|
|
///
|
|
/// let rw = Arc::new(RwLock::new(1));
|
|
///
|
|
/// // Put the lock in write mode.
|
|
/// let mut main_write_guard = rw.write().unwrap();
|
|
///
|
|
/// let rw_clone = rw.clone();
|
|
/// let evil_handle = std::thread::spawn(move || {
|
|
/// // This will not return until the main thread drops the `main_read_guard`.
|
|
/// let mut evil_guard = rw_clone.write().unwrap();
|
|
///
|
|
/// assert_eq!(*evil_guard, 2);
|
|
/// *evil_guard = 3;
|
|
/// });
|
|
///
|
|
/// *main_write_guard = 2;
|
|
///
|
|
/// // Atomically downgrade the write guard into a read guard.
|
|
/// let main_read_guard = RwLockWriteGuard::downgrade(main_write_guard);
|
|
///
|
|
/// // Since `downgrade` is atomic, the writer thread cannot have changed the protected data.
|
|
/// assert_eq!(*main_read_guard, 2, "`downgrade` was not atomic");
|
|
/// #
|
|
/// # drop(main_read_guard);
|
|
/// # evil_handle.join().unwrap();
|
|
/// #
|
|
/// # let final_check = rw.read().unwrap();
|
|
/// # assert_eq!(*final_check, 3);
|
|
/// ```
|
|
#[stable(feature = "rwlock_downgrade", since = "1.92.0")]
|
|
pub fn downgrade(s: Self) -> RwLockReadGuard<'rwlock, T> {
|
|
let lock = s.lock;
|
|
|
|
// We don't want to call the destructor since that calls `write_unlock`.
|
|
forget(s);
|
|
|
|
// SAFETY: We take ownership of a write guard, so we must already have the `RwLock` in write
|
|
// mode, satisfying the `downgrade` contract.
|
|
unsafe { lock.inner.downgrade() };
|
|
|
|
// SAFETY: We have just successfully called `downgrade`, so we fulfill the safety contract.
|
|
unsafe { RwLockReadGuard::new(lock).unwrap_or_else(PoisonError::into_inner) }
|
|
}
|
|
|
|
/// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data, e.g.
|
|
/// an enum variant.
|
|
///
|
|
/// The `RwLock` is already locked for writing, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `RwLockWriteGuard::map(...)`. A method would interfere with methods of
|
|
/// the same name on the contents of the `RwLockWriteGuard` used through
|
|
/// `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockWriteGuard<'rwlock, U>
|
|
where
|
|
F: FnOnce(&mut T) -> &mut U,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
let data = NonNull::from(f(unsafe { &mut *orig.lock.data.get() }));
|
|
let orig = ManuallyDrop::new(orig);
|
|
MappedRwLockWriteGuard {
|
|
data,
|
|
inner_lock: &orig.lock.inner,
|
|
poison_flag: &orig.lock.poison,
|
|
poison_guard: orig.poison.clone(),
|
|
_variance: PhantomData,
|
|
}
|
|
}
|
|
|
|
/// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data. The
|
|
/// original guard is returned as an `Err(...)` if the closure returns
|
|
/// `None`.
|
|
///
|
|
/// The `RwLock` is already locked for writing, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `RwLockWriteGuard::filter_map(...)`. A method would interfere with methods
|
|
/// of the same name on the contents of the `RwLockWriteGuard` used through
|
|
/// `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockWriteGuard<'rwlock, U>, Self>
|
|
where
|
|
F: FnOnce(&mut T) -> Option<&mut U>,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
match f(unsafe { &mut *orig.lock.data.get() }) {
|
|
Some(data) => {
|
|
let data = NonNull::from(data);
|
|
let orig = ManuallyDrop::new(orig);
|
|
Ok(MappedRwLockWriteGuard {
|
|
data,
|
|
inner_lock: &orig.lock.inner,
|
|
poison_flag: &orig.lock.poison,
|
|
poison_guard: orig.poison.clone(),
|
|
_variance: PhantomData,
|
|
})
|
|
}
|
|
None => Err(orig),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<'rwlock, T: ?Sized> MappedRwLockReadGuard<'rwlock, T> {
|
|
/// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data,
|
|
/// e.g. an enum variant.
|
|
///
|
|
/// The `RwLock` is already locked for reading, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `MappedRwLockReadGuard::map(...)`. A method would interfere with
|
|
/// methods of the same name on the contents of the `MappedRwLockReadGuard`
|
|
/// used through `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be
|
|
/// poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockReadGuard<'rwlock, U>
|
|
where
|
|
F: FnOnce(&T) -> &U,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
let data = NonNull::from(f(unsafe { orig.data.as_ref() }));
|
|
let orig = ManuallyDrop::new(orig);
|
|
MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock }
|
|
}
|
|
|
|
/// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data.
|
|
/// The original guard is returned as an `Err(...)` if the closure returns
|
|
/// `None`.
|
|
///
|
|
/// The `RwLock` is already locked for reading, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `MappedRwLockReadGuard::filter_map(...)`. A method would interfere with
|
|
/// methods of the same name on the contents of the `MappedRwLockReadGuard`
|
|
/// used through `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be
|
|
/// poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockReadGuard<'rwlock, U>, Self>
|
|
where
|
|
F: FnOnce(&T) -> Option<&U>,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
match f(unsafe { orig.data.as_ref() }) {
|
|
Some(data) => {
|
|
let data = NonNull::from(data);
|
|
let orig = ManuallyDrop::new(orig);
|
|
Ok(MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock })
|
|
}
|
|
None => Err(orig),
|
|
}
|
|
}
|
|
}
|
|
|
|
impl<'rwlock, T: ?Sized> MappedRwLockWriteGuard<'rwlock, T> {
|
|
/// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data,
|
|
/// e.g. an enum variant.
|
|
///
|
|
/// The `RwLock` is already locked for writing, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `MappedRwLockWriteGuard::map(...)`. A method would interfere with
|
|
/// methods of the same name on the contents of the `MappedRwLockWriteGuard`
|
|
/// used through `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn map<U, F>(mut orig: Self, f: F) -> MappedRwLockWriteGuard<'rwlock, U>
|
|
where
|
|
F: FnOnce(&mut T) -> &mut U,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
let data = NonNull::from(f(unsafe { orig.data.as_mut() }));
|
|
let orig = ManuallyDrop::new(orig);
|
|
MappedRwLockWriteGuard {
|
|
data,
|
|
inner_lock: orig.inner_lock,
|
|
poison_flag: orig.poison_flag,
|
|
poison_guard: orig.poison_guard.clone(),
|
|
_variance: PhantomData,
|
|
}
|
|
}
|
|
|
|
/// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data.
|
|
/// The original guard is returned as an `Err(...)` if the closure returns
|
|
/// `None`.
|
|
///
|
|
/// The `RwLock` is already locked for writing, so this cannot fail.
|
|
///
|
|
/// This is an associated function that needs to be used as
|
|
/// `MappedRwLockWriteGuard::filter_map(...)`. A method would interfere with
|
|
/// methods of the same name on the contents of the `MappedRwLockWriteGuard`
|
|
/// used through `Deref`.
|
|
///
|
|
/// # Panics
|
|
///
|
|
/// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned.
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
pub fn filter_map<U, F>(
|
|
mut orig: Self,
|
|
f: F,
|
|
) -> Result<MappedRwLockWriteGuard<'rwlock, U>, Self>
|
|
where
|
|
F: FnOnce(&mut T) -> Option<&mut U>,
|
|
U: ?Sized,
|
|
{
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
// The signature of the closure guarantees that it will not "leak" the lifetime of the
|
|
// reference passed to it. If the closure panics, the guard will be dropped.
|
|
match f(unsafe { orig.data.as_mut() }) {
|
|
Some(data) => {
|
|
let data = NonNull::from(data);
|
|
let orig = ManuallyDrop::new(orig);
|
|
Ok(MappedRwLockWriteGuard {
|
|
data,
|
|
inner_lock: orig.inner_lock,
|
|
poison_flag: orig.poison_flag,
|
|
poison_guard: orig.poison_guard.clone(),
|
|
_variance: PhantomData,
|
|
})
|
|
}
|
|
None => Err(orig),
|
|
}
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> Drop for RwLockReadGuard<'_, T> {
|
|
fn drop(&mut self) {
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created.
|
|
unsafe {
|
|
self.inner_lock.read_unlock();
|
|
}
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> Drop for RwLockWriteGuard<'_, T> {
|
|
fn drop(&mut self) {
|
|
self.lock.poison.done(&self.poison);
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
|
|
unsafe {
|
|
self.lock.inner.write_unlock();
|
|
}
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> Drop for MappedRwLockReadGuard<'_, T> {
|
|
fn drop(&mut self) {
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
unsafe {
|
|
self.inner_lock.read_unlock();
|
|
}
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> Drop for MappedRwLockWriteGuard<'_, T> {
|
|
fn drop(&mut self) {
|
|
self.poison_flag.done(&self.poison_guard);
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
unsafe {
|
|
self.inner_lock.write_unlock();
|
|
}
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> Deref for RwLockReadGuard<'_, T> {
|
|
type Target = T;
|
|
|
|
fn deref(&self) -> &T {
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created.
|
|
unsafe { self.data.as_ref() }
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> Deref for RwLockWriteGuard<'_, T> {
|
|
type Target = T;
|
|
|
|
fn deref(&self) -> &T {
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
|
|
unsafe { &*self.lock.data.get() }
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
impl<T: ?Sized> DerefMut for RwLockWriteGuard<'_, T> {
|
|
fn deref_mut(&mut self) -> &mut T {
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created.
|
|
unsafe { &mut *self.lock.data.get() }
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> Deref for MappedRwLockReadGuard<'_, T> {
|
|
type Target = T;
|
|
|
|
fn deref(&self) -> &T {
|
|
// SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
unsafe { self.data.as_ref() }
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> Deref for MappedRwLockWriteGuard<'_, T> {
|
|
type Target = T;
|
|
|
|
fn deref(&self) -> &T {
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
unsafe { self.data.as_ref() }
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized> DerefMut for MappedRwLockWriteGuard<'_, T> {
|
|
fn deref_mut(&mut self) -> &mut T {
|
|
// SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard
|
|
// was created, and have been upheld throughout `map` and/or `filter_map`.
|
|
unsafe { self.data.as_mut() }
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "std_debug", since = "1.16.0")]
|
|
impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLockReadGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "std_guard_impls", since = "1.20.0")]
|
|
impl<T: ?Sized + fmt::Display> fmt::Display for RwLockReadGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "std_debug", since = "1.16.0")]
|
|
impl<T: ?Sized + fmt::Debug> fmt::Debug for RwLockWriteGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[stable(feature = "std_guard_impls", since = "1.20.0")]
|
|
impl<T: ?Sized + fmt::Display> fmt::Display for RwLockWriteGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized + fmt::Debug> fmt::Debug for MappedRwLockReadGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized + fmt::Display> fmt::Display for MappedRwLockReadGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized + fmt::Debug> fmt::Debug for MappedRwLockWriteGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|
|
|
|
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
|
|
impl<T: ?Sized + fmt::Display> fmt::Display for MappedRwLockWriteGuard<'_, T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
|
|
(**self).fmt(f)
|
|
}
|
|
}
|