Trait HandlePoisonResult

Source

pub trait HandlePoisonResult {
    type PoisonlessResult;

    // Required methods
    fn ignore_poison(self) -> Self::PoisonlessResult;
    fn panic_if_poison(self) -> Self::PoisonlessResult;
}

Expand description

Extension trait for Result which adds the ability to more conveniently handle the poison errors returned by this crate’s locks.

§About Poison

When another thread panics while it holds a poisonable lock, the lock becomes poisoned (which may be manually cleared). Attempts to acquire a poisoned lock (or otherwise access, via the lock, the data protected by the lock) return poison errors, which act as speed bumps for accessing data whose logical invariants are potentially broken. See std’s PoisonError for more.

As a poison error is only returned when some thread has already panicked, it is common to unconditionally panic in the current thread as well when poison is encountered, or to simply ignore such a circumstance.

As a notable example, parking_lot does not provide poison errors at all, and does not care whether a different thread panicked while holding a parking_lot mutex. This is roughly equivalent to (but more performant than) using HandlePoisonResult::ignore_poison everywhere.