Implement MappedMutexGuard.

Author: zachs18

library/std/src/sync/mutex.rs

@@ -3,7 +3,10 @@ mod tests;
 
 usecrate::cell::UnsafeCell;
 usecrate::fmt;
+usecrate::marker::PhantomData;
+usecrate::mem::ManuallyDrop;
 usecrate::ops::{Deref,DerefMut};
+usecrate::ptr::NonNull;
 usecrate::sync::{poison,LockResult,TryLockError,TryLockResult};
 usecrate::sys::locks as sys;
 
@@ -213,6 +216,43 @@ impl<T: ?Sized> !Send for MutexGuard<'_, T> {}
 #[stable(feature = "mutexguard", since = "1.19.0")]
 unsafeimpl<T: ?Sized + Sync>SyncforMutexGuard<'_,T>{}
 
+/// An RAII mutex guard returned by `MutexGuard::map`, which can point to a
+/// subfield of the protected data. When this structure is dropped (falls out
+/// of scope), the lock will be unlocked.
+///
+/// The main difference between `MappedMutexGuard` and [`MutexGuard`] is that the
+/// former cannot be used with [`CondVar`], since that
+/// could introduce soundness issues if the locked object is modified by another
+/// thread while the `Mutex` is unlocked.
+///
+/// The data protected by the mutex can be accessed through this guard via its
+/// [`Deref`] and [`DerefMut`] implementations.
+///
+/// This structure is created by the [`map`] and [`try_map`] methods on
+/// [`MutexGuard`].
+///
+/// [`map`]: MutexGuard::map
+/// [`try_map`]: MutexGuard::try_map
+/// [`CondVar`]: crate::sync::CondVar
+#[must_use = "if unused the Mutex will immediately unlock"]
+#[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")]
+#[clippy::has_significant_drop]
+pubstructMappedMutexGuard<'a,T: ?Sized + 'a>{
+data:NonNull<T>,
+inner:&'a sys::Mutex,
+poison_flag:&'a poison::Flag,
+poison: poison::Guard,
+_variance:PhantomData<&'amutT>,
+}
+
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+impl<T: ?Sized> !SendforMappedMutexGuard<'_,T>{}
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+unsafeimpl<T: ?Sized + Sync>SyncforMappedMutexGuard<'_,T>{}
+
 impl<T>Mutex<T>{
 /// Creates a new mutex in an unlocked state ready for use.
 ///
@@ -552,3 +592,156 @@ pub fn guard_lock<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a sys::Mutex {
 pubfnguard_poison<'a,T: ?Sized>(guard:&MutexGuard<'a,T>) -> &'a poison::Flag{
 &guard.lock.poison
 }
+
+impl<'a,T: ?Sized>MutexGuard<'a,T>{
+/// Makes a [`MappedMutexGuard`] for a component of the borrowed data, e.g.
+/// an enum variant.
+///
+/// The `Mutex` is already locked, so this cannot fail.
+///
+/// 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")]
+pubfnmap<U,F>(orig:Self,f:F) -> MappedMutexGuard<'a,U>
+where
+F:FnOnce(&mutT) -> &mutU,
+U: ?Sized,
+{
+letmut orig = ManuallyDrop::new(orig);
+let value = NonNull::from(f(&mut*orig));
+MappedMutexGuard{
+data: value,
+inner:&orig.lock.inner,
+poison_flag:&orig.lock.poison,
+poison: orig.poison.clone(),
+_variance:PhantomData,
+}
+}
+
+/// Makes a [`MappedMutexGuard`] for a component of the borrowed data. The
+/// original guard is returned as an `Err(...)` if the closure returns
+/// `None`.
+///
+/// The `Mutex` is already locked, so this cannot fail.
+///
+/// This is an associated function that needs to be used as
+/// `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")]
+pubfntry_map<U,F>(orig:Self,f:F) -> Result<MappedMutexGuard<'a,U>,Self>
+where
+F:FnOnce(&mutT) -> Option<&mutU>,
+U: ?Sized,
+{
+letmut orig = ManuallyDrop::new(orig);
+matchf(&mut*orig).map(NonNull::from){
+Some(value) => Ok(MappedMutexGuard{
+data: value,
+inner:&orig.lock.inner,
+poison_flag:&orig.lock.poison,
+poison: orig.poison.clone(),
+_variance:PhantomData,
+}),
+None => Err(ManuallyDrop::into_inner(orig)),
+}
+}
+}
+
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+impl<T: ?Sized>DerefforMappedMutexGuard<'_,T>{
+typeTarget = T;
+
+fnderef(&self) -> &T{
+unsafe{self.data.as_ref()}
+}
+}
+
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+impl<T: ?Sized>DerefMutforMappedMutexGuard<'_,T>{
+fnderef_mut(&mutself) -> &mutT{
+unsafe{self.data.as_mut()}
+}
+}
+
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+impl<T: ?Sized>DropforMappedMutexGuard<'_,T>{
+#[inline]
+fndrop(&mutself){
+unsafe{
+self.poison_flag.done(&self.poison);
+self.inner.unlock();
+}
+}
+}
+
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+impl<T: ?Sized + fmt::Debug> fmt::DebugforMappedMutexGuard<'_,T>{
+fnfmt(&self,f:&mut fmt::Formatter<'_>) -> fmt::Result{
+ fmt::Debug::fmt(&**self, f)
+}
+}
+
+#[unstable(feature = "mapped_lock_guards", issue = "none")]
+impl<T: ?Sized + fmt::Display> fmt::DisplayforMappedMutexGuard<'_,T>{
+fnfmt(&self,f:&mut fmt::Formatter<'_>) -> fmt::Result{
+(**self).fmt(f)
+}
+}
+
+impl<'a,T: ?Sized>MappedMutexGuard<'a,T>{
+/// Makes a [`MappedMutexGuard`] for a component of the borrowed data, e.g.
+/// an enum variant.
+///
+/// The `Mutex` is already locked, so this cannot fail.
+///
+/// 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")]
+pubfnmap<U,F>(orig:Self,f:F) -> MappedMutexGuard<'a,U>
+where
+F:FnOnce(&mutT) -> &mutU,
+U: ?Sized,
+{
+letmut orig = ManuallyDrop::new(orig);
+let value = NonNull::from(f(&mut*orig));
+MappedMutexGuard{
+data: value,
+inner: orig.inner,
+poison_flag: orig.poison_flag,
+poison: orig.poison.clone(),
+_variance:PhantomData,
+}
+}
+
+/// Makes a [`MappedMutexGuard`] for a component of the borrowed data. The
+/// original guard is returned as an `Err(...)` if the closure returns
+/// `None`.
+///
+/// The `Mutex` is already locked, so this cannot fail.
+///
+/// This is an associated function that needs to be used as
+/// `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")]
+pubfntry_map<U,F>(orig:Self,f:F) -> Result<MappedMutexGuard<'a,U>,Self>
+where
+F:FnOnce(&mutT) -> Option<&mutU>,
+U: ?Sized,
+{
+letmut orig = ManuallyDrop::new(orig);
+matchf(&mut*orig).map(NonNull::from){
+Some(value) => Ok(MappedMutexGuard{
+data: value,
+inner: orig.inner,
+poison_flag: orig.poison_flag,
+poison: orig.poison.clone(),
+_variance:PhantomData,
+}),
+None => Err(ManuallyDrop::into_inner(orig)),
+}
+}
+}