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.

[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,
});

[zachs18]

These APIs can only be used with functions that return references. There are for two main reasons that I can think of for this design:

1. A *Guard<'a, T> does not itself own a T; it has temporary exclusive¹ access to a T that is owned by a lock somewhere else. Changing this API to instead allow owning a T that itself borrows something owned by a lock (like HypotheticalGuard<OccupiedEntry<'a, K, V>> would in your Mutex<HashMap<K, V>> example) would be a nontrivial change².

2. The returned reference needs to be converted into a raw pointer to store³. There's no "raw" version of a std::collections::hash_map::OccupiedEntry (or other types in general) that could be used for this in general⁴.

For your specific example, if you only want to access the value in the hashmap (not the key or other OccupiedEntry functionality), you could use Some(e.into_mut()) instead of Some(e), or just replace the whole closure with |v| v.get_mut(&0).

Footnotes

1. or shared, in the case of (Mapped)RwLockReadGuard ↩

2. There's the issue that Rust doesn't (yet) have higher-ranked types other than dyn Trait IIUC, so writing the for<'a> OccupedEntry<'a, K, V> type or the for<'a> FnOnce(T<'a>) -> U<'a> bound generically might be impossible currently, or I think would at least require using a trait and a marker type. Also it would need to be ensured that T<'a> is not-contravariant in 'a. ↩ ↩²

3. IIUC this is for aliasing reasons. For one example: a MutexGuard<'a, T> cannot hold a &'a mut T, since it would become invalid after dropping the MutexGuard, and (most) references that are function parameters currently must be valid for the whole function call IIUC, making fn foo(x: &Mutex<T>, y: MutexGuard<'_, T>) { drop(y); let z = x.lock(); } possibly unsound if MutexGuard<'a, T> held a &'a mut T. ↩

4. well, maybe MaybeDangling/MaybeUninit? I think it would be sound for HypotheticalGuard<T> to hold a MaybeDangling<T> and just not access it after unlocking, but that's not the only issue: see the other footnote². ↩

[zachs18]

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.

I think this is a good idea if possible, like how std::num::NonZero is now generic. One possible problem I can think of is issues with variance if the Mapped type's API is implemented using associated types from trait LockGuard, as IIUC using an associated type projection from a type parameter as a struct field makes that parameter invariant (playground). This could maybe be bypassed by implementing LockGuard for marker types instead of the guards themselves, and having the lifetime and pointee as type parameters on Mapped, like struct Mapped<'a, GuardKind: LockGuardKind, T>. Though how to specify the variance of T there is still difficult, since *MutexGuard and *RwLockWriteGuard should be invariant, but *RwLockReadGuard should be covariant in T.