Tracking Issue for `sync_nonpoison` and `nonpoison_{condvar,mutex,rwlock}`

View all comments

Feature gates:

• #![feature(sync_nonpoison)]
• #![feature(nonpoison_condvar)]
• #![feature(nonpoison_mutex)]
• #![feature(nonpoison_rwlock)]

This is a tracking issue for versions of synchronization primitives that do not not need to worry about poison.

Public API

sync_nonpoison

The module itself and common types will be gated by this feature:

// std::sync

mod nonpoison {
    pub type TryLockResult<Guard> = Result<Guard, WouldBlock>;
    
    // Error type for failed locking
    pub struct WouldBlock;
}

nonpoison_condvar

// std::sync::nonpoison

pub struct Condvar { /* ... */ }

impl Condvar {
    pub const fn new() -> Self;
    pub fn wait<T>(&self, guard: &mut MutexGuard<'_, T>)
    pub fn notify_one(&self);
    pub fn notify_all(&self);

    pub fn wait_while<T, F>(&self, guard: &mut MutexGuard<'_, T>, mut condition: F)
    where
        F: FnMut(&mut T) -> bool;

    pub fn wait_timeout<T>(
        &self,
        guard: &mut MutexGuard<'_, T>,
        dur: Duration,
    ) -> WaitTimeoutResult;

    pub fn wait_timeout_while<T, F>(
        &self,
        guard: &mut MutexGuard<'_, T>,
        dur: Duration,
        mut condition: F,
    ) -> WaitTimeoutResult
    where
        F: FnMut(&mut T) -> bool;
}

/* trait implementations from `std::sync::poison::Condvar` */

nonpoison_mutex

// std::sync::nonpoison

pub struct Mutex<T: ?Sized> { /* ... */ }

impl<T> Mutex<T> {
    pub const fn new(t: T) -> Self;
}

impl<T: ?Sized> Mutex<T> {
    pub fn lock(&self) -> MutexGuard<'_, T>;
    pub fn try_lock(&self) -> TryLockResult<MutexGuard<'_, T>>;
    pub fn get_mut(&mut self) -> &mut T;
    pub fn into_inner(self) -> T
    where
        T: Sized;
}

/* trait implementations from `std::sync::poison::Mutex` */

pub struct MutexGuard<'a, T: ?Sized + 'a> { /* ... */ }

impl<'a, T: ?Sized> MutexGuard<'a, T> {
    // Unstable API from `mapped_lock_guards`
}

/* trait implementations from `std::sync::poison::MutexGuard` */

// Currently unstable under `mapped_lock_guards`, see that tracking issue for more
pub struct MappedMutexGuard<'a, T: ?Sized + 'a> { /* ... */ }

nonpoison_rwlock

// std::sync::nonpoison

pub struct RwLock<T: ?Sized> { /* ... */ }

impl<T> RwLock<T> {
    pub const fn new(t: T) -> Self;
}

impl<T: ?Sized> RwLock<T> {
    pub fn read(&self) -> RwLockReadGuard<'_, T>;
    pub fn try_read(&self) -> TryLockResult<RwLockReadGuard<'_, T>>;
    pub fn write(&self) -> RwLockWriteGuard<'_, T>;
    pub fn try_write(&self) -> TryLockResult<RwLockWriteGuard<'_, T>>;
    pub fn get_mut(&mut self) -> &mut T;
    pub fn into_inner(self) -> T
    where
        T: Sized;
}

/* trait implementations from `std::sync::poison::RwLock` */

pub struct RwLockReadGuard<'a, T: ?Sized + 'a> { /* private fields */ }

impl<'a, T: ?Sized> RwLockReadGuard<'a, T> {
    // Unstable API from `mapped_lock_guards`
}

/* trait implementations from `std::sync::poison::RwLockReadGuard` */

impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> {
    // Unstable API from `mapped_lock_guards`
}

/* trait implementations from `std::sync::poison::RwLockWriteGuard` */

// Currently unstable under `mapped_lock_guards`, see that tracking issue for more
pub struct MappedRwLockReadGuard<'a, T: ?Sized + 'a> { /* ... */ }
pub struct MappedRwLockReadGuard<'a, T: ?Sized + 'a> { /* ... */ }

Steps / History

• ACP: https://github.com/rust-lang/libs-team/issues/169
• Mutex implementation: https://github.com/rust-lang/rust/pull/144022
• RwLock implementation https://github.com/rust-lang/rust/pull/144648
• Condvar implementation https://github.com/rust-lang/rust/pull/144651
• Final comment period (FCP)^1
• Stabilization PR

Unresolved Questions

• Should existing types without poison be moved to this module? Barrier, LazyLock, OnceLock, ReentrantLock. (Answer: no, it only makes sense to move to the poison and nonpoison modules if there is a version for each)
• Should we use this as an opportunity to change the variance of RwLock to support try_upgrade? https://github.com/rust-lang/libs-team/issues/514 / https://github.com/rust-lang/rust/issues/138559#issuecomment-2816380452

Related

• Move all existing poisonable types to std::sync::poison and reexport them https://github.com/rust-lang/rust/issues/134646
• The unstable ReentrantLock currently does not support poisoning https://github.com/rust-lang/rust/issues/121440
• mapped_lock_guards adds API to the guard types https://github.com/rust-lang/rust/issues/117108
• Discussion for changing the defaults https://github.com/rust-lang/rust/issues/149359