#thread #panic #applications #gamedev

panik

Application-wide panic handling, whereby panics occurring in any thread are treated as a hard error and can be detected by other threads to trigger a graceful exit

3 unstable releases

0.2.0 Feb 9, 2021
0.1.1 Feb 9, 2021
0.1.0 Feb 6, 2021

#872 in Game dev

39 downloads per month

MIT license

25KB
289 lines

panik-rs

Build Status Documentation Version License

This crate enables application-wide panic handling, whereby panics occurring in any thread are captured and stored, and can later be queried to trigger an early application exit.

This goes against the standard panic behaviour where a panic is isolated to the thread that caused it. This library introduces the condition that any panic in any thread is an error and the application cannot continue or recover.

Use case

The main use case for this crate is when a thread spawns some threads to do work, and blocks on their completion. If a worker thread panics before the result is posted, the waiting thread might get stuck in a blocking call to recv, unless it specifically plans and checks for this error case (e.g. poisoned mutex, disconnected mpsc sender).

In a large application with thread pools and lots of types of work being posted to it all over the place (like a game engine), it can be hard to handle every panic case properly. Using this library allows the main thread to poll for panics in its core game loop and exit gracefully, rather than soldiering on without its audio/rendering/AI/worker threads.

An example that doesn't use panic detection and hangs forever:

let (tx, rx) = std::sync::mpsc::channel();
let worker = std::thread::spawn(move || {
    // hopefully do some work...
    // tx.send(5).unwrap();

    // ...or panic and hold up the main thread forever
    todo!()
});

let result: i32 = rx.recv().expect("recv failed"); // blocks forever
println!("result: {}", result);

The same example detecting and handling panics and exiting gracefully:

let application_result = panik::run_and_handle_panics(|| {
    let (tx, rx) = std::sync::mpsc::channel();
    let worker = std::thread::spawn(move || {
        // do some work...
        // tx.send(5).unwrap();

        // ...or panic and hold up the main thread forever
        todo!()
    });

    // periodically check if a panic has occurred
    let poll_freq = Duration::from_secs(5);
    while !panik::has_panicked() {
        if let Ok(res) = rx.recv_timeout(poll_freq) {
            return res;
        }
    }

    // return value is irrelevant here, the panic on the worker
    // thread will clobber this when `run_and_handle_panics`
    // returns None
    0
});

match application_result {
    None => {
        eprintln!("something went wrong: {:?}", panik::panics());
        std::process::exit(1);
    },
    Some(result) => {
        println!("result: {}", result);
        std::process::exit(0);
    }
}

This looks pretty heavyweight, but this intentional - this library is meant for large and heavyweight applications!

Features

  • use-stderr: log panics to stderr
  • use-log: log panics with the log crate
  • use-slog: log panics with the slog crate (see Builder::slogger)
  • use-parking-lot: use parking_lot::Mutex instead of std::sync::Mutex

Dependencies

~2.4–4MB
~75K SLoC