subtalegames / cortex

Flexible crash-handling for Rust applications.

Cortex is a flexible crash-handling solution for applications written in Rust.

Example

use subtale_cortex::CrashHandler;

fn run_application() {
    // Your application logic...
}

fn crash_handler(output: std::process::Output) -> Result<(), Box<dyn std::error::Error>> {
    // Handle the output of the application process when it crashes
}

fn main() {
    let result = CrashHandler::with_process(run_application)
        .crash_handler(crash_handler)
        // Use `RUST_BACKTRACE` full in your application process
        .full_backtrace()
        .run();

    match result {
        // The application process finished successfully
        Ok(true) => ..,
        // The application process crashed, but the error was
        // handled successfully
        Ok(false) => ..,
        // An error was encountered spawning the application or
        // when crash handling
        Err(e) => ..,
    }
}

The examples directory has specific implementation examples, including using the native-dialog for cross-platform message boxes and running a Bevy game within the crash handler.

How it works

Cortex uses the crash handling approach described in this blog post by Mason Remaley (Anthropic Studios) from March 2021.

The crash handling implementation is simple and straightforward: when the application is launched, invoke the application again as a subprocess of itself and monitor the subprocess for non-successful exit codes.

To prevent the application from recursively invoking itself until infinity, a command argument (--cortex-child) is used to identify whether the process is the crash handler (and so a subprocess should be invoked) or a subprocess.

For example, the first time that the application is run, Cortex identifies that the --cortex-child argument is not present. The application is then self-spawned as a subprocess, this time with the --cortex-child argument included so the regular application logic (run_application() in the example above) can start.

License

Cortex is free and open source. Unless explicitly noted otherwise, all code in this repository is dual-licensed under the MIT License and Apache License, Version 2.0.

This licensing approach is the de facto standard within the Rust ecosystem.

Contributions

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.