Module poison

🔬This is a nightly-only experimental API. (sync_poison_mod #134646)

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.

For the alternative implementations that do not employ poisoning, see std::sync::nonpoison.

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.

• Once: A thread-safe way to run a piece of code only once. Mostly useful for implementing one-time global initialization.

  Once is reliably poisoned if the piece of code passed to Once::call_once() or Once::call_once_force() panics. When in poisoned state, subsequent calls to Once::call_once() will panic too. Once::call_once_force() can be used to clear the poisoned state.

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

Re-exports

pub use self::condvar::Condvar;

pub use self::condvar::WaitTimeoutResult;

pub use self::mutex::MappedMutexGuard;Experimental

pub use self::mutex::Mutex;

pub use self::mutex::MutexGuard;

pub use self::once::ONCE_INIT;Deprecated

pub use self::once::Once;

pub use self::once::OnceState;

pub use self::rwlock::MappedRwLockReadGuard;Experimental

pub use self::rwlock::MappedRwLockWriteGuard;Experimental

pub use self::rwlock::RwLock;

pub use self::rwlock::RwLockReadGuard;

pub use self::rwlock::RwLockWriteGuard;

Modules

condvar 🔒 Experimental

mutex 🔒 Experimental

once 🔒 Experimental

A “once initialization” primitive

rwlock 🔒 Experimental

Structs

Flag 🔒 Experimental

Guard 🔒 Experimental

PoisonErrorExperimental

A type of error which can be returned whenever a lock is acquired.

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.

Functions

map_result 🔒 Experimental

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.