Skip to content

Commit

Permalink
Add comment about Mapped(Mutex|RwLockWrite)Guard variance.
Browse files Browse the repository at this point in the history
  • Loading branch information
@zachs18
zachs18 committed Dec 5, 2023
1 parent ea97c1f commit 04f8630
Show file tree
Hide file tree
Showing 2 changed files with 43 additions and 35 deletions.
28 changes: 16 additions & 12 deletions library/std/src/sync/mutex.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -238,19 +238,23 @@ 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,
poison: poison::Guard,
_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> {
Expand Down Expand Up @@ -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,
Expand All @@ -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>,
Expand All @@ -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;

Expand All @@ -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) {
Expand All @@ -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)
Expand All @@ -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,
Expand All @@ -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>,
Expand Down
50 changes: 27 additions & 23 deletions library/std/src/sync/rwlock.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -187,20 +187,24 @@ 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,
poison: poison::Guard,
_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> {
Expand Down Expand Up @@ -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)
Expand Down Expand Up @@ -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;

Expand All @@ -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;

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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);
Expand All @@ -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,
Expand All @@ -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>,
Expand All @@ -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,
Expand All @@ -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>,
Expand All @@ -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,
Expand Down Expand Up @@ -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>,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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>,
Expand Down

0 comments on commit 04f8630

Please sign in to comment.