76e5ed655c
All of the current std::sync primitives have poisoning enable which means that when a task fails inside of a write-access lock then all future attempts to acquire the lock will fail. This strategy ensures that stale data whose invariants are possibly not upheld are never viewed by other tasks to help propagate unexpected panics (bugs in a program) among tasks. Currently there is no way to test whether a mutex or rwlock is poisoned. One method would be to duplicate all the methods with a sister foo_catch function, for example. This pattern is, however, against our [error guidelines][errors]. As a result, this commit exposes the fact that a task has failed internally through the return value of a `Result`. [errors]: https://github.com/rust-lang/rfcs/blob/master/text/0236-error-conventions.md#do-not-provide-both-result-and-fail-variants All methods now return a `LockResult<T>` or a `TryLockResult<T>` which communicates whether the lock was poisoned or not. In a `LockResult`, both the `Ok` and `Err` variants contains the `MutexGuard<T>` that is being returned in order to allow access to the data if poisoning is not desired. This also means that the lock is *always* held upon returning from `.lock()`. A new type, `PoisonError`, was added with one method `into_guard` which can consume the assertion that a lock is poisoned to gain access to the underlying data. This is a breaking change because the signatures of these methods have changed, often incompatible ways. One major difference is that the `wait` methods on a condition variable now consume the guard and return it in as a `LockResult` to indicate whether the lock was poisoned while waiting. Most code can be updated by calling `.unwrap()` on the return value of `.lock()`. [breaking-change]
127 lines
4 KiB
Rust
127 lines
4 KiB
Rust
// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
|
|
// file at the top-level directory of this distribution and at
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
use prelude::*;
|
|
|
|
use cell::UnsafeCell;
|
|
use error::FromError;
|
|
use fmt;
|
|
use thread::Thread;
|
|
|
|
pub struct Flag { failed: UnsafeCell<bool> }
|
|
pub const FLAG_INIT: Flag = Flag { failed: UnsafeCell { value: false } };
|
|
|
|
impl Flag {
|
|
#[inline]
|
|
pub fn borrow(&self) -> LockResult<Guard> {
|
|
let ret = Guard { panicking: Thread::panicking() };
|
|
if unsafe { *self.failed.get() } {
|
|
Err(new_poison_error(ret))
|
|
} else {
|
|
Ok(ret)
|
|
}
|
|
}
|
|
|
|
#[inline]
|
|
pub fn done(&self, guard: &Guard) {
|
|
if !guard.panicking && Thread::panicking() {
|
|
unsafe { *self.failed.get() = true; }
|
|
}
|
|
}
|
|
|
|
#[inline]
|
|
pub fn get(&self) -> bool {
|
|
unsafe { *self.failed.get() }
|
|
}
|
|
}
|
|
|
|
#[allow(missing_copy_implementations)]
|
|
pub struct Guard {
|
|
panicking: bool,
|
|
}
|
|
|
|
/// A type of error which can be returned whenever a lock is acquired.
|
|
///
|
|
/// Both Mutexes and RWLocks are poisoned whenever a task fails while the lock
|
|
/// is held. The precise semantics for when a lock is poisoned is documented on
|
|
/// each lock, but once a lock is poisoned then all future acquisitions will
|
|
/// return this error.
|
|
pub struct PoisonError<T> {
|
|
guard: T,
|
|
}
|
|
|
|
/// An enumeration of possible errors which can occur while calling the
|
|
/// `try_lock` method.
|
|
pub enum TryLockError<T> {
|
|
/// The lock could not be acquired because another task failed while holding
|
|
/// the lock.
|
|
Poisoned(PoisonError<T>),
|
|
/// The lock could not be acquired at this time because the operation would
|
|
/// otherwise block.
|
|
WouldBlock,
|
|
}
|
|
|
|
/// A type alias for the result of a lock method which can be poisoned.
|
|
///
|
|
/// The `Ok` variant of this result indicates that the primitive was not
|
|
/// poisoned, and the `Guard` is contained within. The `Err` variant indicates
|
|
/// that the primitive was poisoned. Note that the `Err` variant *also* carries
|
|
/// the associated guard, and it can be acquired through the `into_inner`
|
|
/// method.
|
|
pub type LockResult<Guard> = Result<Guard, PoisonError<Guard>>;
|
|
|
|
/// A type alias for the result of a nonblocking locking method.
|
|
///
|
|
/// For more information, see `LockResult`. A `TryLockResult` doesn't
|
|
/// necessarily hold the associated guard in the `Err` type as the lock may not
|
|
/// have been acquired for other reasons.
|
|
pub type TryLockResult<Guard> = Result<Guard, TryLockError<Guard>>;
|
|
|
|
impl<T> fmt::Show for PoisonError<T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
|
"poisoned lock: another task failed inside".fmt(f)
|
|
}
|
|
}
|
|
|
|
impl<T> PoisonError<T> {
|
|
/// Consumes this error indicating that a lock is poisoned, returning the
|
|
/// underlying guard to allow access regardless.
|
|
pub fn into_guard(self) -> T { self.guard }
|
|
}
|
|
|
|
impl<T> FromError<PoisonError<T>> for TryLockError<T> {
|
|
fn from_error(err: PoisonError<T>) -> TryLockError<T> {
|
|
TryLockError::Poisoned(err)
|
|
}
|
|
}
|
|
|
|
impl<T> fmt::Show for TryLockError<T> {
|
|
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
|
|
match *self {
|
|
TryLockError::Poisoned(ref p) => p.fmt(f),
|
|
TryLockError::WouldBlock => {
|
|
"try_lock failed because the operation would block".fmt(f)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
pub fn new_poison_error<T>(guard: T) -> PoisonError<T> {
|
|
PoisonError { guard: guard }
|
|
}
|
|
|
|
pub fn map_result<T, U, F>(result: LockResult<T>, f: F)
|
|
-> LockResult<U>
|
|
where F: FnOnce(T) -> U {
|
|
match result {
|
|
Ok(t) => Ok(f(t)),
|
|
Err(PoisonError { guard }) => Err(new_poison_error(f(guard)))
|
|
}
|
|
}
|