#analysis #outcome #definitely

definitely

Codepaths that are statically unreachable according to the compiler's intraprocedural control flow analysis

1 stable release

Uses new Rust 2024

new 1.0.0 Apr 26, 2025

#1 in #outcome

MIT/Apache

10KB

definitely::unreachable!() is a macro for marking codepaths that are known to be statically unreachable by the compiler's intraprocedural control flow analysis, to ensure that they remain unreachable.

This complements the standard library's unsafe { core::hint::unreachable_unchecked() } function and core::unreachable!() macro.

safety runtime behavior binary size
core::hint::unreachable_unchecked unsafe undefined behavior if reached zero
core::unreachable safe panic if reached nonzero
definitely::unreachable safe impossible to reach zero

Example

This use case has some complicated control flow involving retrying an API call with a succession of different arguments in reaction to previous observed failures. While there is a loop in the code, we would like to be sure that every path through this loop body ends explicitly in a specific intentional return or break or continue or panic. It should not be possible for this to become an implicit infinite loop during the course of future refactorings.

let mut retry_with_a = false;
let mut retry_with_b = false;
loop {
    let mut arg = "...";
    if retry_with_a {
        arg = alternate(arg);
    }
    let thing = do_thing(arg, retry_with_b.then_some(b));
    match thing {
        Ok(outcome) => {
            return outcome;
        }
        Err(err) if !retry_with_a && err.kind() == ErrorKind::NotFound => {
            retry_with_a = true;
            continue;
        }
        Err(err) if !retry_with_b => {
            retry_with_b = true;
            continue;
        }
        Err(err) => {
            eprintln!("{}", err);
            return default_value();
        }
    }

    definitely::unreachable!();
}

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this crate by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

No runtime deps