rust-lang/rust
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Add comment about Mapped(Mutex|RwLockWrite)Guard variance.

Browse Source
This commit is contained in:
Zachary S
2023-10-23 16:36:13 -05:00
parent ea97c1f2dc
commit 04f8630442
2 changed files with 43 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
library/std/src/sync/mutex.rs
View File

@@ -238,9 +238,13 @@ unsafe impl<T: ?Sized + Sync> Sync for MutexGuard<'_, T> {}
#[must_not_suspend = "holding a MappedMutexGuard across suspend \
points can cause deadlocks, delays, \
and cause Futures to not implement `Send`"]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
#[clippy::has_significant_drop]
pub struct MappedMutexGuard<'a, T: ?Sized + 'a> {
// NB: we use a pointer instead of `&'a mut T` to avoid `noalias` violations, because a
// `MappedMutexGuard` argument doesn't hold uniqueness for its whole scope, only until it drops.
// `NonNull` is covariant over `T`, so we add a `PhantomData<&'a mut T>` field
// below for the correct variance over `T` (invariance).
data: NonNull<T>,
inner: &'a sys::Mutex,
poison_flag: &'a poison::Flag,
@@ -248,9 +252,9 @@ pub struct MappedMutexGuard<'a, T: ?Sized + 'a> {
_variance: PhantomData<&'a mut T>,
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> !Send for MappedMutexGuard<'_, T> {}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
unsafe impl<T: ?Sized + Sync> Sync for MappedMutexGuard<'_, T> {}
impl<T> Mutex<T> {
@@ -602,7 +606,7 @@ impl<'a, T: ?Sized> MutexGuard<'a, T> {
/// This is an associated function that needs to be used as
/// `MutexGuard::map(...)`. A method would interfere with methods of the
/// same name on the contents of the `MutexGuard` used through `Deref`.
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn map<U, F>(orig: Self, f: F) -> MappedMutexGuard<'a, U>
where
F: FnOnce(&mut T) -> &mut U,
@@ -629,7 +633,7 @@ impl<'a, T: ?Sized> MutexGuard<'a, T> {
/// `MutexGuard::try_map(...)`. A method would interfere with methods of the
/// same name on the contents of the `MutexGuard` used through `Deref`.
#[doc(alias = "filter_map")]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn try_map<U, F>(orig: Self, f: F) -> Result<MappedMutexGuard<'a, U>, Self>
where
F: FnOnce(&mut T) -> Option<&mut U>,
@@ -649,7 +653,7 @@ impl<'a, T: ?Sized> MutexGuard<'a, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> Deref for MappedMutexGuard<'_, T> {
type Target = T;
@@ -658,14 +662,14 @@ impl<T: ?Sized> Deref for MappedMutexGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> DerefMut for MappedMutexGuard<'_, T> {
fn deref_mut(&mut self) -> &mut T {
unsafe { self.data.as_mut() }
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> Drop for MappedMutexGuard<'_, T> {
#[inline]
fn drop(&mut self) {
@@ -676,14 +680,14 @@ impl<T: ?Sized> Drop for MappedMutexGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized + fmt::Debug> fmt::Debug for MappedMutexGuard<'_, T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
fmt::Debug::fmt(&**self, f)
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized + fmt::Display> fmt::Display for MappedMutexGuard<'_, T> {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
(**self).fmt(f)
@@ -699,7 +703,7 @@ impl<'a, T: ?Sized> MappedMutexGuard<'a, T> {
/// This is an associated function that needs to be used as
/// `MutexGuard::map(...)`. A method would interfere with methods of the
/// same name on the contents of the `MutexGuard` used through `Deref`.
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn map<U, F>(orig: Self, f: F) -> MappedMutexGuard<'a, U>
where
F: FnOnce(&mut T) -> &mut U,
@@ -726,7 +730,7 @@ impl<'a, T: ?Sized> MappedMutexGuard<'a, T> {
/// `MutexGuard::try_map(...)`. A method would interfere with methods of the
/// same name on the contents of the `MutexGuard` used through `Deref`.
#[doc(alias = "filter_map")]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn try_map<U, F>(orig: Self, f: F) -> Result<MappedMutexGuard<'a, U>, Self>
where
F: FnOnce(&mut T) -> Option<&mut U>,

50
library/std/src/sync/rwlock.rs
View File

@@ -158,7 +158,7 @@ unsafe impl<T: ?Sized + Sync> Sync for RwLockWriteGuard<'_, T> {}
#[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 = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
#[clippy::has_significant_drop]
pub struct MappedRwLockReadGuard<'a, T: ?Sized + 'a> {
// NB: we use a pointer instead of `&'a T` to avoid `noalias` violations, because a
@@ -169,10 +169,10 @@ pub struct MappedRwLockReadGuard<'a, T: ?Sized + 'a> {
inner_lock: &'a sys::RwLock,
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> !Send for MappedRwLockReadGuard<'_, T> {}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[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
@@ -187,9 +187,13 @@ unsafe impl<T: ?Sized + Sync> Sync for MappedRwLockReadGuard<'_, T> {}
#[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 = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
#[clippy::has_significant_drop]
pub struct MappedRwLockWriteGuard<'a, T: ?Sized + 'a> {
// NB: we use a pointer instead of `&'a mut T` to avoid `noalias` violations, because a
// `MappedRwLockWriteGuard` argument doesn't hold uniqueness for its whole scope, only until it drops.
// `NonNull` is covariant over `T`, so we add a `PhantomData<&'a mut T>` field
// below for the correct variance over `T` (invariance).
data: NonNull<T>,
inner_lock: &'a sys::RwLock,
poison_flag: &'a poison::Flag,
@@ -197,10 +201,10 @@ pub struct MappedRwLockWriteGuard<'a, T: ?Sized + 'a> {
_variance: PhantomData<&'a mut T>,
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> !Send for MappedRwLockWriteGuard<'_, T> {}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
unsafe impl<T: ?Sized + Sync> Sync for MappedRwLockWriteGuard<'_, T> {}
impl<T> RwLock<T> {
@@ -621,28 +625,28 @@ impl<T: ?Sized + fmt::Display> fmt::Display for RwLockWriteGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[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 = "none")]
#[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 = "none")]
#[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 = "none")]
#[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)
@@ -677,7 +681,7 @@ impl<T: ?Sized> DerefMut for RwLockWriteGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> Deref for MappedRwLockReadGuard<'_, T> {
type Target = T;
@@ -688,7 +692,7 @@ impl<T: ?Sized> Deref for MappedRwLockReadGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> Deref for MappedRwLockWriteGuard<'_, T> {
type Target = T;
@@ -699,7 +703,7 @@ impl<T: ?Sized> Deref for MappedRwLockWriteGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[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
@@ -729,7 +733,7 @@ impl<T: ?Sized> Drop for RwLockWriteGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[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
@@ -740,7 +744,7 @@ impl<T: ?Sized> Drop for MappedRwLockReadGuard<'_, T> {
}
}
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
impl<T: ?Sized> Drop for MappedRwLockWriteGuard<'_, T> {
fn drop(&mut self) {
self.poison_flag.done(&self.poison);
@@ -762,7 +766,7 @@ impl<'a, T: ?Sized> RwLockReadGuard<'a, T> {
/// `RwLockReadGuard::map(...)`. A method would interfere with methods of
/// the same name on the contents of the `RwLockReadGuard` used through
/// `Deref`.
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockReadGuard<'a, U>
where
F: FnOnce(&T) -> &U,
@@ -784,7 +788,7 @@ impl<'a, T: ?Sized> RwLockReadGuard<'a, T> {
/// of the same name on the contents of the `RwLockReadGuard` used through
/// `Deref`.
#[doc(alias = "filter_map")]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn try_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockReadGuard<'a, U>, Self>
where
F: FnOnce(&T) -> Option<&U>,
@@ -808,7 +812,7 @@ impl<'a, T: ?Sized> MappedRwLockReadGuard<'a, T> {
/// `MappedRwLockReadGuard::map(...)`. A method would interfere with
/// methods of the same name on the contents of the `MappedRwLockReadGuard`
/// used through `Deref`.
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockReadGuard<'a, U>
where
F: FnOnce(&T) -> &U,
@@ -830,7 +834,7 @@ impl<'a, T: ?Sized> MappedRwLockReadGuard<'a, T> {
/// methods of the same name on the contents of the `MappedRwLockReadGuard`
/// used through `Deref`.
#[doc(alias = "filter_map")]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn try_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockReadGuard<'a, U>, Self>
where
F: FnOnce(&T) -> Option<&U>,
@@ -854,7 +858,7 @@ impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> {
/// `RwLockWriteGuard::map(...)`. A method would interfere with methods of
/// the same name on the contents of the `RwLockWriteGuard` used through
/// `Deref`.
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockWriteGuard<'a, U>
where
F: FnOnce(&mut T) -> &mut U,
@@ -882,7 +886,7 @@ impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> {
/// of the same name on the contents of the `RwLockWriteGuard` used through
/// `Deref`.
#[doc(alias = "filter_map")]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn try_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockWriteGuard<'a, U>, Self>
where
F: FnOnce(&mut T) -> Option<&mut U>,
@@ -912,7 +916,7 @@ impl<'a, T: ?Sized> MappedRwLockWriteGuard<'a, T> {
/// `MappedRwLockWriteGuard::map(...)`. A method would interfere with
/// methods of the same name on the contents of the `MappedRwLockWriteGuard`
/// used through `Deref`.
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockWriteGuard<'a, U>
where
F: FnOnce(&mut T) -> &mut U,
@@ -940,7 +944,7 @@ impl<'a, T: ?Sized> MappedRwLockWriteGuard<'a, T> {
/// methods of the same name on the contents of the `MappedRwLockWriteGuard`
/// used through `Deref`.
#[doc(alias = "filter_map")]
#[unstable(feature = "mapped_lock_guards", issue = "none")]
#[unstable(feature = "mapped_lock_guards", issue = "117108")]
pub fn try_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockWriteGuard<'a, U>, Self>
where
F: FnOnce(&mut T) -> Option<&mut U>,