Axle v0.22.0

Exception dispatch

Axle’s throw / catch uses a polling model — not the strict LLVM exception-handling model (invoke / landingpad / resume). This page describes what the compiler emits and how catches dispatch.

What this page covers: why polling instead of LLVM EH · how a throw lowers · the check after a may-throw call · how a catch picks its handler · what finally runs on · every runtime symbol the model uses.

Why polling

Strict LLVM-EH requires invoke / landingpad / resume plus the MSVC SEH funclet primitives (catchpad / catchswitch / cleanuppad) on Windows. The codegen kernel opens no door onto the funclet primitives, and an Itanium-style personality function isn’t available on an MSVC linker — so LLVM-native EH cannot be emitted. A setjmp / longjmp scheme is also ruled out (setjmp needs SEH unwind metadata LLVM doesn’t emit, and the jump buffer must live in the caller’s own frame). Polling sidesteps all of that and is Windows MSVC-compatible out of the box.

How a throw flows

fn save() : void ! IOException {
    throw IOException("disk full");
}

The lowering depends on where the throw sits. Two questions decide it: is there an enclosing try in this function, and is this function one whose failure travels in its return value (see The check after a call)?

throw inside a try-scope             throw with no try-scope here
------------------------             -----------------------------
build the exception object           build the exception object
write (value, class_id) into         tagged function:
  the try-scope's value and            store (value, class_id) in the
  class slots                            failure record its caller owns,
branch to try.dispatch                   return a non-zero tag
                                     other shapes (main, a native callee,
                                       a coroutine, ...):
                                       __axle_throw(value, class_id),
                                       then return; the caller probes
                                       axle_has_exception()

In a try-scope the exception never leaves the function: control goes straight to the dispatch block. Outside one, the failure climbs one frame at a time, each caller testing the tag or the probe, until a try catches it or the chain reaches main. main terminates with axle_unhandled_exception() followed by unreachable, so an uncaught exception ends the process.

axle_native_throw(class_name, message) is the entry point for Rust-side native code, and also the path a throw of a stdlib exception class takes (such as IOException). It resolves the class id from the runtime’s name registry, so a native raise and a user throw of the same class agree even though the stdlib module and the user program number their types separately. In a tagged function the armed slot is then moved into the failure record the caller owns.

The check after a call

After every call to a function the compiler has proven may throw (through its declared ! error set or an uncaught throwing call it makes), the emitted IR carries one of two checks.

A function that can raise carries the failure in its own return: it takes one extra trailing parameter — the failure record its caller owns — and returns { i64 tag, T }, the tag alone when it answers nothing. tag == 0 means it returned a result:

%pair = call { i64, T } @f(args…, ptr %emplace)
%tag  = extractvalue { i64, T } %pair, 0
%v    = extractvalue { i64, T } %pair, 1
%fail = icmp ne i64 %tag, 0
br i1 %fail, label %dispatch.exc, label %normal.continue

The other shapes — a native or extern "C" callee, the entry point, a coroutine machine, a constructor, a function reached through a value — keep the plain signature and raise through a runtime slot, so their sites probe it:

%has_exc = call i1 @axle_has_exception()
br i1 %has_exc, label %dispatch.exc, label %normal.continue

Both questions open the same arm. If it fires, control jumps to the enclosing try-scope’s dispatch block (after reading the class id and taking the exception into SSA), or — with no try-scope active — runs the cleanup chain and propagates outward. Calls to fns proven non-throwing carry no check at all — zero hot-path cost for the common case.

The unwind edge is tagged with a cold branch weight (≈ 1 / 2000) so LLVM’s block layout pushes the propagation path off the hot path. axle_has_exception carries nounwind, which lets LLVM drop the unwind tables around the probe. The probe itself is one load + one branch on the hot path (predicted false forever when nothing throws); the tag test is one compare on a register the call just produced, which the optimiser folds away once the callee is inlined. It carries no memory(read) effect — which would let LLVM fold the load across consecutive call sites — because the runtime-function table names a signature and nothing else: axle_has_exception is declared with no memory-effect annotation.

Catch dispatch

try { stmts } catch e : X { handler } catch e : Y { handler } lowers to a value slot, a class slot, and a chain of i32 compares :

try.body:
  <stmts>
  br label %try.exit

try.dispatch:                        ; reached via in-scope throw or post-call poll
  %cls = load i32, ptr %class_slot
  %eq0 = icmp eq i32 %cls, <id in X's closure>
  ; … OR-chained against every id in X's subclass closure …
  br i1 %match0, label %catch.0, label %try.dispatch.next.0

try.dispatch.next.0:
  ; same shape for Y's closure
  br i1 %match1, label %catch.1, label %try.rethrow

The expected class ids for each catch arm come from a precomputed subclass-closure table — the transitive subclass set of every exception, built once by the compiler after type resolution. The dispatch reads that closure for each catch’s declared type and OR-chains an icmp eq against every id in it, so:

  • catch e : Exception matches Exception plus every transitive subclass.
  • catch e : IOException matches IOException and its subclasses (FileNotFoundException, EOFException, …).
  • A throw raised inside a nested function call is caught just the same — the polling model carries it up the call chain to the enclosing try, where the same class-id matching runs.

A multi-catch clause (catch e : X | Y) carries several types; the dispatch unions the subclass closure of every member into one id-set before building the compare chain, so the arm fires on any id in either closure.

Dispatch is entirely compile-time class-id comparison: there is no RTTI global, no landingpad, and no stack unwinding. Each id in each closure is a constant baked into the IR.

When sema proves that every exception able to reach a try is covered by one of its clauses, the try.rethrow block is not emitted: the last clause is entered without a compare, and a try with one such clause reads no class at all. The default, when there is no proof, keeps the full chain, because omitting a compare would run a handler on an exception of another class.

finally

try { B } catch … finally { F } runs F on every path out of the construct :

  • Normal completion — the try-body fall-through and each catch handler’s fall-through run F, then continue past the construct.
  • A matched catch — F runs after the handler body.
  • The uncaught rethrow tail — when no catch matches, F runs inline (the pending exception survives in the slots) before the exception propagates to the outer try-scope or aborts.
  • An escaping transfer — any return / break / continue / throw leaving the protected body runs the active finally bodies inline before the transfer.

A finally that itself exits abruptly supersedes the original transfer: once F returns / throws, the block is terminated and the pending transfer is dropped. A throw inside F is not covered by the same try’s catches (it runs outside the protected region), so an uncaught throw there is a compile error (E0005).

Runtime ABI symbols

Every symbol name below is a stable runtime ABI constant — the compiler never types them as inline string literals.

SymbolRole
__axle_throw(value_ptr, class_id) — stashes the payload + class id into the thread-local exception slots and returns normally. No abort, no print.
axle_native_throw(class_name_ptr, message_ptr) — called from Rust-side native code and from the stdlib-exception abort path. The runtime resolves class_name → class_id and hands off to __axle_throw.
axle_has_exceptioni1 probe of the runtime slot, emitted after a call whose callee raises through that slot rather than in its return.
axle_current_exception_class_idi32 — reads the pending exception’s class id without clearing the slot. The dispatch chain compares against it before committing to a handler.
axle_take_exceptionConsumes the thread-local slot ; returns the ptr payload and clears both slots so a call inside the handler (or a finally) doesn’t re-observe the same exception.
axle_unhandled_exceptiondiverging — prints axle: unhandled exception {class}: {message} to stderr (axle: unhandled exception (class_id=N): … when the class is unknown), frees the pending exception and the arena, and exits non-zero. Emitted on the no-catch path of main.
axle_register_exception_classes(table_ptr, count) — emitted once at main’s prologue, and only when the program holds at least one exception class. The table holds a (class_name_ptr, class_id) row per user-visible exception class and fills the name → id registry every native raise consults.

There is no axle_is_subclass runtime helper. Every class id is known at compile time and stamped into the IR directly ; the dispatch chain is a plain i32 == expected_id compare OR-chained over the subclass closure.


Limits / Uncabled

FeatureStateDetail / workaround
Exception cause chainNot supportedAn exception carries its message and nothing else, so a wrapper cannot point at the failure it wrapped. Copy the message into the wrapper.
Stack trace and unwindingNot supportedthrow stores a slot (or a failure record) and returns; there are no frames to walk.
Catch outside mainNot possibleAn uncaught exception ends the process at main with a diagnostic and a non-zero exit.
Jump-table dispatchNot builtEach catch arm is a linear chain of icmp eq over its subclass closure.
Exceptions across a C frameNot supportedKeep throw and catch on the Axle side of every foreign call.

See also

exceptionscodegenruntimeinternals