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 : ExceptionmatchesExceptionplus every transitive subclass.catch e : IOExceptionmatchesIOExceptionand 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 —
Fruns after the handler body. - The uncaught rethrow tail — when no catch matches,
Fruns 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/throwleaving the protected body runs the activefinallybodies 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.
| Symbol | Role |
|---|---|
__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_exception | i1 probe of the runtime slot, emitted after a call whose callee raises through that slot rather than in its return. |
axle_current_exception_class_id | i32 — reads the pending exception’s class id without clearing the slot. The dispatch chain compares against it before committing to a handler. |
axle_take_exception | Consumes 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_exception | diverging — 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
| Feature | State | Detail / workaround |
|---|---|---|
| Exception cause chain | Not supported | An 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 unwinding | Not supported | throw stores a slot (or a failure record) and returns; there are no frames to walk. |
Catch outside main | Not possible | An uncaught exception ends the process at main with a diagnostic and a non-zero exit. |
| Jump-table dispatch | Not built | Each catch arm is a linear chain of icmp eq over its subclass closure. |
| Exceptions across a C frame | Not supported | Keep throw and catch on the Axle side of every foreign call. |
See also
- Reading compiler errors — the user side of compile-time exception checking.
- Error handling — the patterns Axle programmers actually write.
- Compiler internals overview — index of all internals pages.
- Concept index — every exception concept on one page.