Home /Modules/impl/EXCEPTIONS.md

EXCEPTIONS.md

impl/EXCEPTIONS.md · 202 line(s) · markdown

VM Exception and Stack-Unwind Design

Status: runtime foundation and first source-level catch-all lowering implemented on work/vm-exception-compiler-stage1; typed catches and finally remain incomplete.

Why this work is required

The current compiler accepts Java-shaped try, catch, finally, and throw syntax, but the execution path is not exception-safe:

This is a semantic gap, not merely a missing Java library method. Java String null/bounds failures and many other JDK-compatible operations cannot be implemented faithfully until the VM can transfer control to a handler.

Required runtime model

1. Per-thread handler records

Exception state belongs to SLThread, never to the shared SLVM. Each handler record must capture at least:

The handler stack must be bounded consistently with the VM's fixed execution limits. Registration overflow is a normal VM diagnostic; it must not corrupt the operand or frame stacks.

2. Per-frame handler ownership

Each SLFrame records the handler-stack depth that existed when the frame was entered. Returning from a frame discards handlers installed by that frame. Unwinding across a frame restores the saved operand-stack height and removes that frame's handlers before continuing in its caller.

This prevents a handler in a returned method from remaining active and intercepting an unrelated later throw.

3. Throw and dispatch

A throw operation consumes one SLValue and searches the current thread's handler stack from newest to oldest. On a match it:

  1. preserves the thrown value as a GC-visible root;
  2. discards handlers newer than the selected handler;
  3. unwinds call frames to the handler's saved depth;
  4. restores the operand stack to the saved height;
  5. pushes the thrown value for the compiler-generated catch prologue; and
  6. transfers the instruction pointer to the catch entry.

If no handler matches, the value becomes the thread's uncaught-exception payload and execution terminates with a distinct uncaught-exception result or diagnostic. It must not be silently converted to a normal return.

A throw from a catch body must search only handlers still active outside that catch. A rethrow must preserve the original value and identity.

4. GC and lifetime rules

The active exception payload, any pending exception during cleanup, and exception values stored in handler records are VM roots. Root enumeration must include every live thread, including suspended worker threads, and the native-callback caller stack. A handler must never retain a raw object pointer; it stores the normal tagged SLValue handle.

The thrown value must remain rooted across stack truncation, frame unwinding, and any cleanup code that may allocate or trigger a GC safepoint.

5. Finally and abrupt completion

Finally is not equivalent to code appended after a try block. It must execute on normal completion, return, break/continue leaving the protected region, and exception propagation. If finally itself throws, returns, or otherwise completes abruptly, that completion replaces the pending completion according to Java-like rules.

Implement this as explicit pending-completion state (kind plus payload/target), not by duplicating unstructured finally bytecode at every exit. The initial exception milestone may deliberately ship catch/throw without finally only if the compiler rejects or clearly diagnoses finally in that mode; it must never silently skip a finally block on exceptional exit.

6. Catch typing and source compatibility

The first runtime milestone may support a single catch-all clause whose variable receives an arbitrary thrown SLValue. It must not pretend that different declared catch types are distinguished. Typed catches require runtime type identity / assignability metadata and ordered matching, including multi-catch rules.

The compiler must reject unsupported multi-catch or typed-catch constructs rather than routing every exception to the first clause. Null thrown values must remain distinguishable from "no pending exception" through an explicit pending-state flag.

Bytecode and artifact compatibility

A minimal opcode family is expected to provide handler registration, handler removal, and throw dispatch. Exact names and operands should be fixed only alongside the compiler lowering and artifact validator changes.

Runtime error boundary

Language exceptions and VM integrity failures are different:

Never convert every TERR into a catchable exception. That would allow source code to catch and continue after VM invariant violations.

Implementation sequence

  1. Add per-thread handler/pending-exception state and root enumeration.
  2. Add append-only handler push/pop/throw opcodes and artifact validation.
  3. Add compiler lowering for one catch-all clause and a catch variable.
  4. Add deterministic tests for nested handlers, cross-frame unwind, return cleanup, rethrow, uncaught values, stack restoration, and GC during unwind.
  5. Add explicit finally/pending-completion lowering for all abrupt exits.
  6. Add runtime type identity and typed catch matching.
  7. Convert selected Java-compatible language faults into catchable exception objects, then connect Java String and JDK facades to those types.

Acceptance criteria

No Java exception-compatibility claim is valid until tests prove all of the following: nested catch selection, cross-method propagation, correct operand and local restoration, rethrow identity, uncaught propagation, GC survival during unwind, finally execution on every abrupt exit, and typed catch ordering. A source parser accepting try/catch/throw is not evidence of runtime support.

Implemented runtime milestone

The current runtime branch now includes:

An opt-in C smoke test is available as make -C impl test-exceptions. It covers cross-frame catch dispatch and preservation of an uncaught false payload. A source-level integration smoke is available as `make -C impl test-exceptions-source`; it exercises nested catch selection, cross-method unwind, rethrow through an outer catch, preservation of a pre-existing local, and normal completion without entering the catch body. Both tests have been added but have not been run in this milestone.

Current limitation

The source compiler now lowers a single catch (Any name) clause to OP_TRY_PUSH, OP_TRY_POP, and a handler prologue that stores the thrown value in the catch local. Explicit throw expression; now emits OP_THROW. The compiler rejects multiple catch clauses, narrower declared catch types, catch-variable collisions with existing method locals, break/continue that would leave the protected try region, and any finally block. This is deliberately narrower than Java: matching is catch-all only, and the catch variable holds the original arbitrary tagged SLValue.

Typed exception classes and ordered matching, rethrow syntax/identity semantics, selected language-fault conversion, and finally/abrupt-completion lowering remain unimplemented. The compiler change and opt-in runtime smoke test have not been executed in this milestone; source-level Java exception compatibility is not claimed.

Implemented compiler milestone

On work/vm-exception-compiler-stage1, try { ... } catch (Any error) { ... } registers a catch-all handler, removes it on normal completion, and transfers the thrown value into error on exceptional completion. throw expression; now dispatches the evaluated value rather than discarding it. finally and all unsupported catch shapes fail compilation explicitly. This is a first source-to-bytecode integration step, not a claim of full Java exception semantics.