std::sync::poison - Rust
Description: Synchronization objects that employ poisoning.

## Module poison

Source
🔬This is a nightly-only experimental API. (`sync_poison_mod` #134646)
Expand description

Synchronization objects that employ poisoning.

## §Poisoning

All synchronization objects in this module implement a strategy called “poisoning” where a primitive becomes poisoned if it recognizes that some thread has panicked while holding the exclusive access granted by the primitive. This information is then propagated to all other threads to signify that the data protected by this primitive is likely tainted (some invariant is not being upheld).

The specifics of how this “poisoned” state affects other threads and whether the panics are recognized reliably or on a best-effort basis depend on the primitive. See Overview below.

The synchronization objects in this module have alternative implementations that do not employ poisoning in the `std::sync::nonpoison` module.

## §Overview

Below is a list of synchronization objects provided by this module with a high-level overview for each object and a description of how it employs “poisoning”.

- `Condvar`: Condition Variable, providing the ability to block a thread while waiting for an event to occur.

  Condition variables are typically associated with a boolean predicate (a condition) and a mutex. This implementation is associated with `poison::Mutex`, which employs poisoning. For this reason, `Condvar::wait()` will return a `LockResult`, just like `poison::Mutex::lock()` does.

- `Mutex`: Mutual Exclusion mechanism, which ensures that at most one thread at a time is able to access some data.

  Panicking while holding the lock typically poisons the mutex, but it is not guaranteed to detect this condition in all circumstances. `Mutex::lock()` returns a `LockResult`, providing a way to deal with the poisoned state. See `Mutex`’s documentation for more.

- `RwLock`: Provides a mutual exclusion mechanism which allows multiple readers at the same time, while allowing only one writer at a time. In some cases, this can be more efficient than a mutex.

  This implementation, like `Mutex`, usually becomes poisoned on a panic. Note, however, that an `RwLock` may only be poisoned if a panic occurs while it is locked exclusively (write mode). If a panic occurs in any reader, then the lock will not be poisoned.

Note that the `Once` type also employs poisoning, but since it has non-poisoning `force` methods available on it, there is no separate `nonpoison` and `poison` version.

## Structs§

CondvarExperimental
  A Condition Variable
MappedMutexGuardExperimental
  An RAII mutex guard returned by `MutexGuard::map`, which can point to a subfield of the protected data. When this structure is dropped (falls out of scope), the lock will be unlocked.
MappedRwLockReadGuardExperimental
  RAII structure used to release the shared read access of a lock when dropped, which can point to a subfield of the protected data.
MappedRwLockWriteGuardExperimental
  RAII structure used to release the exclusive write access of a lock when dropped, which can point to a subfield of the protected data.
MutexExperimental
  A mutual exclusion primitive useful for protecting shared data
MutexGuardExperimental
  An RAII implementation of a “scoped lock” of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked.
PoisonErrorExperimental
  A type of error which can be returned whenever a lock is acquired.
RwLockExperimental
  A reader-writer lock
RwLockReadGuardExperimental
  RAII structure used to release the shared read access of a lock when dropped.
RwLockWriteGuardExperimental
  RAII structure used to release the exclusive write access of a lock when dropped.

## Enums§

TryLockErrorExperimental
  An enumeration of possible errors associated with a `TryLockResult` which can occur while trying to acquire a lock, from the `try_lock` method on a `Mutex` or the `try_read` and `try_write` methods on an `RwLock`.

## Type Aliases§

LockResultExperimental
  A type alias for the result of a lock method which can be poisoned.
TryLockResultExperimental
  A type alias for the result of a nonblocking locking method.