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::try_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 try_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 try_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 try_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 try_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 try_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 try_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
• 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.