Tracking Issue for `mapped_lock_guards` (`MappedMutexGuard`, `MappedRwLockReadGuard`, `MappedRwLockWriteGuard`)

[zachs18]

Feature gate: #![feature(mapped_lock_guards)]

This is a tracking issue for MappedMutexGuard, MappedRwLockReadGuard, and MappedRwLockWriteGuard.

This adds types analogous to lock_api::MappedMutexGuard, MappedRwLockReadGuard, MappedRwLockWriteGuard) to std::sync, and methods MutexGuard::map and MutexGuard::filter_map (same for `RwLock*Guard) to create them

Public API

// std::sync::mutex

pub struct MappedMutexGuard<'mutex, T: ?Sized>;

impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> {
    pub fn map<U, F>(orig: Self, f: F) -> MappedMutexGuard<'mutex, U>
      where 
        F: FnOnce(&mut T) -> &mut U,
        U: ?Sized;
    pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedMutexGuard<'mutex, U>, Self>
      where 
        F: FnOnce(&mut T) -> Option<&mut U>,
        U: ?Sized;
}

impl<'mutex, T: ?Sized> MappedMutexGuard<'mutex, T> {
    pub fn map<U, F>(orig: Self, f: F) -> MappedMutexGuard<'mutex, U>
      where 
        F: FnOnce(&mut T) -> &mut U,
        U: ?Sized;
    pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedMutexGuard<'mutex, U>, Self>
      where 
        F: FnOnce(&mut T) -> Option<&mut U>,
        U: ?Sized;
}

impl<T: ?Sized> Deref/DerefMut for MappedMutexGuard<'_, T>;
impl<T: ?Sized + Debug/Display> Debug/Display for MappedMutexGuard<'_, T>;

// std::sync::rwlock

pub struct MappedRwLockReadGuard<'rwlock, T: ?Sized>;
pub struct MappedRwLockWriteGuard<'rwlock, T: ?Sized>;

impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> {
    pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockReadGuard<'rwlock, U>
      where 
        F: FnOnce(&T) -> &U,
        U: ?Sized;
    pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockReadGuard<'rwlock, U>, Self>
      where 
        F: FnOnce(&T) -> Option<&U>,
        U: ?Sized;
}
impl<'rwlock, T: ?Sized> MappedRwLockReadGuard<'rwlock, T> {
    pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockReadGuard<'rwlock, U>
      where 
        F: FnOnce(&T) -> &U,
        U: ?Sized;
    pub fn filter_map<U, F>(orig: Self, f: F) -> Result<MappedRwLockReadGuard<'rwlock, U>, Self>
      where 
        F: FnOnce(&T) -> Option<&U>,
        U: ?Sized;
}

impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> {
    pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockWriteGuard<'rwlock, U>
      where 
        F: FnOnce(&mut T) -> &mut U,
        U: ?Sized;
    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;
}
impl<'rwlock, T: ?Sized> MappedRwLockWriteGuard<'rwlock, T> {
    pub fn map<U, F>(orig: Self, f: F) -> MappedRwLockWriteGuard<'rwlock, U>
      where 
        F: FnOnce(&mut T) -> &mut U,
        U: ?Sized;
    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;
}

impl<T: ?Sized> Deref for MappedRwLockReadGuard<'_, T>;
impl<T: ?Sized> Deref/DerefMut for MappedRwLockWriteGuard<'_, T>;
impl<T: ?Sized + Debug/Display> Debug/Display for MappedRwLockReadGuard<'_, T>;
impl<T: ?Sized + Debug/Display> Debug/Display for MappedRwLockWriteGuard<'_, T>;

Steps / History

• ACP: Include MappedRwLocKWriteGuard from lock_api or parking_lot libs-team#260
• Implementation: Implement MappedMutexGuard, MappedRwLockReadGuard, and MappedRwLockWriteGuard. #117107
• Rename try_map to filter_map: Rename *Guard::try_map to filter_map. #140536
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• None yet.

Footnotes

1. https://std-dev-guide.rust-lang.org/feature-lifecycle/stabilization.html ↩

[Fuuzetsu]

Is there anything needed to start FCP? Seems it's all implemented and just waiting around.

[Earthcomputer]

Is there anything needed to start FCP? Seems it's all implemented and just waiting around.

I think it's this, there has been activity on zulip about this since that comment.

[RaitoBezarius]

From the Zulip activity, it seems like this has nothing to do with mapped lock guards, or am I missing something?

[tgross35]

This feature adds three structs and we would get three more with the nonpoison module (#134645), plus one more for ReentrantLockGuard (#121440). What if instead we added a perma-unstable LockGuard trait and then replaced these Mapped*Guard types with a single struct Mapped<G: LockGuard> { /* ... */ }? This would save us from having the same user-facing API repeated in seven different locations.

[ultimaweapon]

With the above API how to use with a method that return a value instead of a reference? e.g.:

let mtx = Mutex::new(HashMap::new());
let lock = mtx.lock().unwrap();
let mapped = MutexGuard::try_map(lock, |v| match v.entry(0) {
    Entry::Occupied(e) => Some(e), // This line won't work.
    Entry::Vacant(_) => None,
});