Lithium

Lightweight exceptions.

Lithium provides a custom exception mechanism as an alternative to Rust panics. Compared to Rust panics, this mechanism is allocation-free, avoids indirections and RTTI, and is hence faster, if less applicable.

On nightly, Lithium is more than 2x faster than Rust panics on common Result-like usecases. See the benchmark.

See documentation for usage and installation instructions.

lib.rs:

Lightweight exceptions.

Lithium provides a custom exception mechanism as an alternative to Rust panics. Compared to Rust panics, this mechanism is allocation-free, avoids indirections and RTTI, and is hence faster, if less applicable.

On nightly, Lithium is more than 2x faster than Rust panics on common Result-like usecases. See the benchmark.

Usage

Throw an exception with throw, catch it with catch or the more low-level intercept. Unlike with Rust panics, non-Send and non-'static types can be used soundly.

Using the panic = "abort" strategy breaks Lithium; avoid doing that.

For interop, all crates that depend on Lithium need to use the same version:

[dependencies]
lithium = "1"

If you break either of these two requirements, cargo will scream at you.

Platform support

On stable Rust, Lithium uses the built-in panic mechanism, tweaking it to increase performance just a little bit.

On nightly Rust, Lithium uses a custom mechanism on the following targets:

Lithium strives to support all targets that Rust panics support. If Lithium does not work correctly on such a target, please open an issue.

no_std support can be enabled by using default-features = false (only on nightly). This requires an Itanium EH unwinder to be linked in on targets that use it as the implementation.

Safety

Exceptions lack dynamic typing information. For soundness, the thrown and caught types must match exactly. Note that the functions are generic, and if the type is inferred wrong, UB will happen. Use turbofish to avoid this pitfall.

The matching types requirement only applies to exceptions that aren't caught inside the catch/intercept callback. For example, this is sound:

use lithium::{catch, throw};

struct A;
struct B;

unsafe {
    let _ = catch::<_, A>(|| {
        let _ = catch::<_, B>(|| throw(B));
        throw(A);
    });
}

The responsibility of upholding this safety requirement is split between the throwing and the catching functions. All throwing functions must be unsafe, listing "only caught by type E" as a safety requirement. All catching functions that take a user-supplied callback must be unsafe too, listing "callback only throws type E" as a safety requirement.

Although seemingly redundant, this enables safe abstractions over exceptions when both the throwing and the catching functions are provided by one crate. As long as the exception types used by the crate match, all safe user-supplied callbacks are sound to call, because safe callbacks can only interact with exceptions in an isolated manner.