sync_poison_mod
)std
only.Expand description
Synchronization objects that employ poisoning.
§Poisoning
All synchronization objects in this module implement a strategy called “poisoning” where if a thread panics while holding the exclusive access granted by the primitive, the state of the primitive is set to “poisoned”. 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 depend on the primitive. See [#Overview] bellow.
For the alternative implementations that do not employ poisoning,
see std::sys::nonpoisoning
.
§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 aLockResult
, just likepoison::Mutex::lock()
does. -
Mutex
: Mutual Exclusion mechanism, which ensures that at most one thread at a time is able to access some data.Mutex::lock()
returns aLockResult
, providing a way to deal with the poisoned state. SeeMutex
’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 poisoned if the piece of code passed toOnce::call_once()
orOnce::call_once_force()
panics. When in poisoned state, subsequent calls toOnce::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
, will become poisoned on a panic. Note, however, that anRwLock
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.
Structs§
- Condvar
Experimental A Condition Variable - Mapped
Mutex Guard Experimental An RAII mutex guard returned byMutexGuard::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. - Mapped
RwLock Read Guard Experimental RAII structure used to release the shared read access of a lock when dropped, which can point to a subfield of the protected data. - Mapped
RwLock Write Guard Experimental RAII structure used to release the exclusive write access of a lock when dropped, which can point to a subfield of the protected data. - Mutex
Experimental A mutual exclusion primitive useful for protecting shared data - Mutex
Guard Experimental An RAII implementation of a “scoped lock” of a mutex. When this structure is dropped (falls out of scope), the lock will be unlocked. - Once
Experimental A low-level synchronization primitive for one-time global execution. - Once
State Experimental State yielded toOnce::call_once_force()
’s closure parameter. The state can be used to query the poison status of theOnce
. - Poison
Error Experimental A type of error which can be returned whenever a lock is acquired. - RwLock
Experimental A reader-writer lock - RwLock
Read Guard Experimental RAII structure used to release the shared read access of a lock when dropped. - RwLock
Write Guard Experimental RAII structure used to release the exclusive write access of a lock when dropped. - Wait
Timeout Result Experimental A type indicating whether a timed wait on a condition variable returned due to a time out or not.
Enums§
- TryLock
Error Experimental
Constants§
Type Aliases§
- Lock
Result Experimental A type alias for the result of a lock method which can be poisoned. - TryLock
Result Experimental A type alias for the result of a nonblocking locking method.