ADR-0004: Compile exceptions as error values returned to the caller¶
Status¶
Accepted
Date¶
2026-11-05
Context¶
Python reports errors with exceptions: raise, try, except, else and
finally. ADR-0002 requires TyPy to keep them with CPython's meaning. The
specification pack had banned exceptions (its ERR-004) in favour of a
Result type and a ? operator, to keep the runtime small. The ?
operator is not Python, so that option is closed.
The runtime has a budget of 48 KB, and 32 KB without its large-integer and cycle-collection parts (NFR-02). An exception that is not raised shall cost no more than a compare and branch at each call that may raise (EXC-03). An exception shall not cross into C (EXC-05).
Swift's error handling rationale compares three ways to compile exceptions,
and LLVM supports Swift's choice directly with the swifterror attribute
(research section 6).
Options considered¶
- Table-based unwinding, as in C++. No work is done on the normal path. But raising is slow, because every frame on the way up needs a table lookup, every binary carries an unwinder and its tables, and the tables limit some optimisations.
setjmpandlongjmp. Raising is cheap. But every frame with cleanup work pays on the normal path, and reference counts held in registers are hard to release correctly on the way out.- Error values returned to the caller. A function that may raise returns an error indicator next to its result, and the caller checks it after the call. The normal path costs one compare and branch per call that may raise, and no unwinder is needed.
Decision¶
TyPy uses option 3.
- The compiler sees the whole program, so it works out which functions may raise. A function that cannot raise has no error indicator, and calls to it are not checked.
- A function that may raise returns an error indicator with its result. The
caller checks it after each call. If set, the caller runs its cleanup
(
finallyblocks,__exit__calls and reference releases), then either handles the exception in a matchingexceptclause or returns it to its own caller. - The exception object is an ordinary heap object under ADR-0001. As it passes up through each frame, it records that frame's location for the traceback, so the cost of building a traceback falls only on the error path.
- The machine-level form, a register pair or LLVM's
swifterror, is chosen per target in the detailed design. It is internal and may change between releases. - A function exported to C (FFI-05) catches any exception at its boundary, prints it, and aborts the program (EXC-05).
- An uncaught exception in the main module prints the exception, ends with the same last line of standard error as CPython, and exits with status 1 (STD-05).
Consequences¶
- No unwinder and no unwind tables go into the runtime or the binary, which keeps NFR-01 and NFR-02 within reach.
- Raising and catching are cheap, so code that uses exceptions for control
flow, as Python code often does with
KeyErrororStopIteration, stays fast. - Each call to a function that may raise costs a compare and branch, and adds code size. The may-raise analysis keeps that to the calls that need it.
- The calling convention for functions that may raise differs from the C convention. Exported functions need a wrapper, which EXC-05 requires anyway.
- Every cleanup path is generated by the compiler, so the reference count
stage and the exception stage must agree on what is live at each call.
The
--emit=tyir-memoutput (CLI-04) shows both for testing. - A foreign function called through
ctypescannot raise a Python exception, so calls to it need no check.
Related requirements¶
EXC-01 to EXC-05, STD-05, CST-04, CST-05, FFI-05, CLI-04, NFR-01, NFR-02, NFR-03.