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

[tgross35]

Feature gates:

• #![feature(sync_nonpoison)]
• #![feature(nonpoison_condvar)]
• #![feature(nonpoison_mutex)]
• #![feature(nonpoison_once)]
• #![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<'a, T>(&self, guard: MutexGuard<'a, T>) -> MutexGuard<'a, T>;
    pub fn notify_one(&self);
    pub fn notify_all(&self);

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

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

    pub fn wait_timeout_while<'a, T, F>(
        &self,
        guard: MutexGuard<'a, T>,
        dur: Duration,
        condition: F,
    ) -> (MutexGuard<'a, T>, 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_once

// std::sync::nonpoison

pub struct Once { /* ... */ }

impl Once {
    pub const fn new() -> Self;
    pub fn call_once<F: FnOnce()>(&self, f: F);
    pub fn call_once_force<F: FnOnce(&OnceState)>(&self, f: F)
    pub fn is_completed(&self) -> bool
   
    // Currently unstable from `once_wait`
    pub fn wait(&self);
    pub fn wait_force(&self);
}

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

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: Adding locks disregarding poison libs-team#169
• Implementation: #...
• Final comment period (FCP)¹
• Stabilization PR

Unresolved Questions

• Should existing types without poison be moved to this module? Barrier, LazyLock, OnceLock, ReentrantLock

Related

• Move all existing poisonable types to std::sync::poison and reexport them Tracking Issue for sync_poison #134646
• The unstable ReentrantLock currently does not support poisoning Tracking Issue for ReentrantLock #121440
• mapped_lock_guards adds API to the guard types Tracking Issue for mapped_lock_guards (MappedMutexGuard, MappedRwLockReadGuard, MappedRwLockWriteGuard) #117108

Footnotes

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

[GrigorenkoPV]

Should Barrier, LazyLock, and OnceLock (all of which ignore poison) be moved to std::sync::nonpoison as well (and then unconditionally reexported in std::sync)?

[tgross35]

I am not sure - for types where we are unlikely to have both versions, it doesn't gain too much. This is also applicable for something like the unstable ReentrantLock (cc @joboet) which is currently nonpoison-only.

Maybe just leave it as-is for now, I'll add this as an unresolved question.