Struct Context

pub struct Context<P> { /* private fields */ }

The launch pad for a thread checked for the expected panic type.

The generic type Context serves as the type system’s anchor for the expected type of the panic value, which is given as the type parameter. It can be constructed from an std::thread::Builder providing a customized thread configuration.

The method spawn() is used to spawn a new thread, similarly to how the function std::thread::spawn() works. See the documentation of the spawn() method for detailed description and examples.

Examples

The example below demonstrates how to construct a Context from a configured std::thread::Builder using the implementation of the standard trait From.

use panic_control::Context;
use std::thread;

#[derive(Debug, PartialEq, Eq)]
struct ExpectedToken;

let thread_builder = thread::Builder::new()
                     .name("My panicky thread".into())
                     .stack_size(65 * 1024);
let ctx = Context::<ExpectedToken>::from(thread_builder);
let h = ctx.spawn(|| {
    // ...
});
h.join().unwrap();

Implementations

impl<P: Any> Context<P>

pub fn new() -> Context<P>

Constructs a context with the default thread configuration.

The type parameter can be specified explicitly:

let ctx = Context::<Expected>::new();

pub fn spawn<T, F>(self, f: F) -> CheckedJoinHandle<T, P>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Spawns a new thread taking ownership of the Context, and returns the CheckedJoinHandle for the thread. Other than the return value, and panicking on an OS failure to create a thread, this method behaves exactly like the spawn() method of std::thread::Builder does, and if the Context was constructed from a std::thread::Builder, its thread configuration will be applied.

Panics

Panics if the underlying call to std::thread::Builder::spawn() returns an Err value. Any panics that function can cause apply as well.

Examples

The example below uses some kludges to work around a compiler quirk:

let ctx = Context::<Expected>::new();

#[allow(unreachable_code)]
let h = ctx.spawn(|| {
    panic!(Expected(42));
    ()
});

let outcome = h.join().unwrap();
assert_eq!(outcome, Outcome::Panicked(Expected(42)));

Note that unless the unreachable return expression is present, the compiler would have no information to infer the unspecified first type parameter of Outcome, so it would settle on a default type that is going to be changed to ! in Rust 1.26. In previous versions of the compiler, code that invokes this behavior is denied by a lint, so the following example does not compile:

let ctx = Context::<Expected>::new();
let h = ctx.spawn(|| {
    panic!(Expected(42));
});
let outcome = h.join().unwrap();
assert_eq!(outcome, Outcome::Panicked(Expected(42)));

A way to avoid the future incompatibility without resorting to warning overrides is to match the Outcome value without touching the sensitive parts:

let ctx = Context::<Expected>::new();
let h = ctx.spawn(|| {
    panic!(Expected(42));
});
let outcome = h.join().unwrap();
match outcome {
    Outcome::Panicked(Expected(n)) => assert_eq!(n, 42),
    _ => panic!("join() returned an unexpected Outcome value")
}

pub fn spawn_quiet<T, F>(self, f: F) -> CheckedJoinHandle<T, P>

where F: FnOnce() -> T + Send + 'static, T: Send + 'static,

Like spawn(), but disables the panic hook if the spawned thread panics.

The process-global panic hook, either installed with std::panic::set_hook() or the standard library default, gets augmented with a filter that disables invocation of the hook closure if the spawned thread panics.

This function can be used in any order together with other functions and methods of this crate that modify the panic hook.

Caveats

Note that the suppression can apply to the default panic hook that is normally used to report assertion failures and other unexpected panics on the standard error stream. The only remaining way to observe the panic is by checking the result of join() for the spawned thread.

Other code within the program that modifies the panic hook, concurrently to, or after, a call to this function, may cause the suppression not to work as intended. See the documentation on the function disable_hook_in_current_thread() for possible pitfalls.

Examples

let ctx = Context::<Expected>::new();
let h = ctx.spawn_quiet(|| {
    assert!(false, "I'm panicking, \
        but you can only learn about it through join()");
});
let res = h.join();
assert!(res.is_err());

Trait Implementations

impl<P> Debug for Context<P>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<P: Any> Default for Context<P>

fn default() -> Context<P>

Returns the “default value” for a type.

impl<P: Any> From<Builder> for Context<P>

fn from(builder: Builder) -> Context<P>

Converts to this type from the input type.