lib/exception.x

Transfer frames for x2c Error unwinding and cleanup.

Advanced and interop API

Functions

x2c_cleanup_leave

void x2c_cleanup_leave(X2CCleanup *record)

Removes and runs the current compiler-generated cleanup record. Records must leave in last-in, first-out order. The record is unlinked before its callback runs, so a callback that transfers cannot run it again. A null or out-of-order record exits through the raw exception fatal path.

Source: lib/exception.x:79

x2c_cleanup_push

void x2c_cleanup_push(X2CCleanup *record)

Pushes one compiler-generated cleanup record. record and its fn must be nonnull, and the record and borrowed env must remain live until leave or Error transfer. Invalid registration exits through the raw exception fatal path.

Source: lib/exception.x:67

x2c_exception_claim

int x2c_exception_claim(ExceptionFrame *frame)

Claims a frame’s cleanup for the calling exit path, once per frame. Compiler-generated code tests this on every path that reaches a finalizer and runs the finalizer only when it reports the claim. Claiming also retires the frame’s landing: the frame has already landed, so a raise from the finalizer transfers to the enclosing frame instead of re-entering this landing and running the finalizer again; that transfer abandons this frame and replaces any Error it was already carrying. A null or already claimed frame reports zero.

Source: lib/exception.x:176

x2c_exception_is_error_target

int x2c_exception_is_error_target(ExceptionFrame *frame)

Reports whether frame is carrying an Error transfer targeted to itself. A null, inactive, handled, or intervening frame returns false.

Source: lib/exception.x:164

x2c_exception_landed

void x2c_exception_landed(ExceptionFrame *frame)

Restores Error handler and dispatch state after a frame landing. Compiler-generated code calls this only on the nonzero sigsetjmp path. A null frame does nothing.

Source: lib/exception.x:146

x2c_exception_leave

void x2c_exception_leave(ExceptionFrame *frame)

Removes an active exception frame and continues any pending Error transfer. The frame must be left in nesting order after its cleanup records have been removed. Normal leave preserves accumulated errors but reclaims handlers registered inside the frame. An intervening unwind instead restores the frame’s error-stack watermark and transfers to the next outer frame. A null or already left frame does nothing; cleanup imbalance exits through the raw fatal path.

Source: lib/exception.x:199

x2c_exception_mark_handled

void x2c_exception_mark_handled(ExceptionFrame *frame)

Marks a selected exception-frame Error transfer as handled. This prevents x2c_exception_leave from continuing the transfer outward. A null frame does nothing.

Source: lib/exception.x:186

x2c_exception_push

void x2c_exception_push(ExceptionFrame *e)

Initializes and pushes one compiler-generated exception frame. The frame records the current cleanup, handler, dispatch-depth, and error stack watermarks and must remain live until x2c_exception_leave. A null frame does nothing.

Source: lib/exception.x:92

ExceptionFrame

ExceptionFrame.unwind

void ExceptionFrame.unwind(void *target_ptr)

Transfers an Error toward the selected active exception frame. target_ptr must identify a landable frame in the current thread. The call selects the innermost frame that is not already running its own cleanup, abandons any frame it skips, marks the selected frame, drains newer cleanup records in last-in, first-out order, records the post-cleanup handler head, and jumps to that frame’s landing. It never returns normally. An invalid target exits through the raw exception fatal path. The transfer does not restore the process signal mask.

Source: lib/exception.x:124

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

Functions

x2c_exception_unwinding

int x2c_exception_unwinding(void)

Reports whether any active frame is carrying an Error transfer.

Source: lib/exception.x:154

Public types

ExceptionFrame

typedef struct ExceptionFrame { struct ExceptionFrame *prev; X2CCleanup *cleanup_watermark; sigjmp_buf env, volatile Symbol state; struct ExceptionFrame *volatile unwind_target, void *error_handler_head; void *volatile error_landing_head, int error_dispatch_depth; int error_stack_height, volatile int cleanup_active; } ExceptionFrame

Holds one caller-owned non-local Error transfer frame. Compiler-generated code keeps the frame on the C stack, pushes it before establishing its sigsetjmp landing, and leaves it in nesting order. Its fields capture cleanup and Error restore points and are runtime-managed while the frame is active.

Source: lib/exception.x:39

X2CCleanup

typedef struct X2CCleanup { struct X2CCleanup *prev, X2CCleanupFn fn, void *env; } X2CCleanup

Holds one caller-owned cleanup registration. The record and its callback environment storage must remain live from x2c_cleanup_push through x2c_cleanup_leave or Error transfer. The runtime owns the record’s links while registered. Cleanup records nest and run in last-in, first-out order.

Source: lib/exception.x:29

X2CCleanupFn

typedef void (*X2CCleanupFn)(void *env)

Performs one compiler-generated cleanup using its borrowed environment. Exception invokes the callback once after unlinking its record, on normal leave or Error transfer. The environment must remain live until then.

Source: lib/exception.x:21

Design notes

The emitter allocates ExceptionFrame objects on the C stack for filtered catches and finally clauses. Callable cleanup records cover defer-only regions without adding a setjmp landing. Error unwind drains those records before landing each intervening exception frame.