lib/error.x

Handler stack and accumulated errors.

Advanced and interop API

Functions

x2c_error_catch_capture

Var x2c_error_catch_capture(ErrorHandler handle, int index)

Returns one borrowed capture from a selected catch arm. An invalid index, a null or unselected handle, or an unbound alternative returns void. The value remains valid until the handle is closed; use Error.snapshot to keep it longer.

Source: lib/error.x:121

x2c_error_catch_close

void x2c_error_catch_close(ErrorHandler handle)

Closes and invalidates a transferring-catch handle. A detached handle releases its plans, captures, and retained error records. An attached handle additionally removes itself and truncates records above its registration watermark. Attached handles must close in stack order; violating that order reaches the raw error floor. A null handle does nothing.

Source: lib/error.x:150

x2c_error_catch_detach

void x2c_error_catch_detach(ErrorHandler handle)

Removes the top transferring catch while retaining its selected state. This lets the catch arm raise outward without matching itself. The caller must still close the handle; repeated detach and a null handle do nothing. Detaching out of stack order reaches the raw error floor.

Source: lib/error.x:134

x2c_error_catch_push

ErrorHandler x2c_error_catch_push(void *target, unsigned arm_count, ...)

Registers one compiler-generated transferring catch. target names the ExceptionFrame that the caller pushes immediately afterward; the following arm_count arguments are List patterns in source order. The registration copies pattern Vars into its table but borrows every referenced List graph and MatchPlan constant. Those values and the target frame must outlive the handle. A null target, zero arm count, or unavailable Error runtime reaches the raw error floor.

Raises: <alloc-fail> when registration or fence-detail storage cannot be allocated, or <size-limit> when an arm’s pattern crosses a Match lowering fence. A fenced arm can never be selected. The registration is reclaimed and the error reaches the enclosing handler; the caller’s own frame is not yet pushed, so it never sees its own failure.

Source: lib/error.x:68

x2c_error_catch_selected

int x2c_error_catch_selected(ErrorHandler handle)

Returns the selected zero-based catch arm, or -1 before selection or for a null handle.

Source: lib/error.x:113

x2c_error_raise

void x2c_error_raise(Symbol code, List detail)

Raises one compiler-generated error from a prepared detail List. The runtime copies admissible detail before synchronous handler dispatch. Resumable causes may return after handling or policy; shared non-returning causes may transfer to a filtered catch but never return here. Invalid detail or unavailable, reentrant, or failed Error machinery reaches the raw error floor.

Source: lib/error.x:169

x2c_error_raise_n

void x2c_error_raise_n( const X2CErrorSite *site, Symbol code, unsigned pair_count, ...)

Raises one compiler-generated error from native key-value arguments. pair_count controls the following alternating Var keys and values; site may be NULL. The runtime copies admissible values and preserves pair order. Resumable causes may return after handling or policy; shared non-returning causes may transfer to a filtered catch but never return here. Invalid detail or unavailable, reentrant, or failed Error machinery reaches the raw error floor.

Source: lib/error.x:193

Error

Error.bound

int Error.bound(void)

Returns the maximum number of errors that may remain accumulated.

Source: lib/error.x:764

Error.bound_set

void Error.bound_set(int bound)

Sets the accumulated-error bound when bound is positive. A zero or negative value leaves the current bound unchanged.

Source: lib/error.x:772

Error.count

int Error.count(void)

Returns the number of errors currently accumulated. Returns zero before Error initialization and after shutdown.

Source: lib/error.x:579

Error.depth

int Error.depth(void)

Returns the current nested error-dispatch depth. This is the nesting depth of error dispatch. Error.count returns the number of accumulated errors.

Source: lib/error.x:574

Error.handler_depth

int Error.handler_depth(void)

Returns the current thread’s number of registered Error handlers.

Source: lib/error.x:208

Error.handler_head

void *Error.handler_head(void)

Returns the current thread’s borrowed top Error-handler pointer. Exception frames use this opaque value as a restore watermark; it remains valid only while its registration remains live.

Source: lib/error.x:218

Error.initialize_raw

void Error.initialize_raw(void)

Initializes the current thread’s Error runtime without lifecycle insertion. Repeated calls after successful initialization and calls after shutdown do nothing. Initialization owns a private Scope, record stack, and policy Map; failure before the Error runtime becomes ready reaches the raw error floor.

Source: lib/error.x:277

Error.mark

int Error.mark(void)

Captures the current error-stack position. Pass the result to Error.since to inspect only later errors.

Source: lib/error.x:584

Error.note_rendered

void Error.note_rendered(void)

Marks the current nested error dispatch as already rendered by Logger. This suppresses only Error’s fallback report for a <log> policy. Calling outside dispatch has no effect.

Source: lib/error.x:178

Error.policy_get

Symbol Error.policy_get(Symbol code)

Returns the default disposition for code. Unknown codes and an unavailable Error runtime default to <abort>.

Source: lib/error.x:750

Error.policy_set

void Error.policy_set(Symbol code, Symbol disposition)

Sets the default disposition for code. Supported policy values are <abort>, <collect>, <log>, and <ignore>. Another value raises <bad-arg> and leaves the previous policy unchanged. Shared non-returning causes accept only <abort>; another disposition raises <bad-arg> and leaves their policy unchanged. The call is a no-op while Error is unavailable; failure to update Error-owned storage reaches the non-reentrant error floor.

Source: lib/error.x:729

Error.pop

void Error.pop(ErrorHandler handle)

Closes the most recently pushed observing handler. Closing truncates and reclaims every error above the handler’s registration watermark, then unregisters it. Errors below the watermark remain. Handles must be popped in stack order. An out-of-order pop reaches the non-reentrant error floor; a null handle does nothing.

Source: lib/error.x:865

Error.push

ErrorHandler Error.push(ErrorHandlerFn fn, Var data)

Pushes an observing handler and returns its removal handle. The handler sees a borrowed view of errors raised after this registration; the view is valid only during the callback. Use Error.snapshot for any value that must escape. Returning <handled> consumes that slice, <declined> leaves it for outer handlers, and <fatal> reaches the error floor. For a shared non-returning cause, <handled> also reaches the floor. A null callback or unavailable runtime returns NULL without registering. Raises <alloc-fail> if registration storage cannot be allocated. data is retained by value without copying its referent, so any referenced storage must outlive the registration.

Source: lib/error.x:790

Error.raise

Symbol Error.raise(Symbol code, List detail)

Raises one cause with optional structured detail. This functional entry records and dispatches like the raise statement but has no source-location record. A handled resumable error returns <handled>; a collected or policy-consumed resumable error returns <declined>. Shared non-returning causes may transfer to a matching filtered catch but never return from this call. Detail is recursively restricted to null/nil, numeric values, enums, Symbols/Atoms, Strings, and Lists of those values. An invalid dynamic detail, unhandled abort-policy error, unavailable runtime, or reentrant failure reaches the non-reentrant error floor.

Prefer the raise statement in source so generated location detail is retained.

Source: lib/error.x:1098

Error.ready

int Error.ready(void)

Reports whether the rich Error runtime can currently accept raises. This is per-thread state and is false before initialization and after shutdown.

Source: lib/error.x:1110

Error.restore

void Error.restore(int handler_depth, int stack_height)

Discards handler and record growth after one cleanup callback. Registrations and records created by that callback are reclaimed toward the saved heights before the interrupted unwind continues. State the callback itself removed is not reconstructed.

Source: lib/error.x:263

Error.restore_landing

void Error.restore_landing(void *saved_head, int saved_depth)

Restores Error state after an exception frame lands. saved_head is a prior handler watermark and saved_depth is the dispatch depth captured when the frame was pushed. The saved head is restored only when the current handler head is still a suffix of its chain; dispatch bookkeeping is cleared.

Source: lib/error.x:236

Error.shutdown_raw

void Error.shutdown_raw(void)

Releases the current thread’s Error storage without lifecycle insertion. The call reclaims all registrations, records, policies, and private storage and makes Error.ready false. Repeated calls do nothing; later raises reach the raw error floor.

Source: lib/error.x:297

Error.since

List Error.since(int mark)

Returns the accumulated errors at and after mark, oldest first. Each entry has code, detail, and location fields. An invalid mark or an unavailable Error runtime returns nil. The snapshot enters the caller’s outermost Scope and canonical pools and remains live until those owners are released. Failure to materialize it reaches the non-reentrant error floor.

Source: lib/error.x:706

Error.snapshot

Var Error.snapshot(Var value)

Copies one admissible error value into the caller’s ordinary owners. Handler slices and filtered-catch bindings are borrowed. Snapshot a value that must outlive its callback or selected arm; Strings and Lists enter the caller’s outermost canonical pools and wide scalar boxes enter its outermost Scope, so nested caller brackets may be released safely. Invalid or identity-bearing values and failures while copying reach the raw error floor; they never re-enter handler dispatch.

Source: lib/error.x:629

Error.trim

void Error.trim(void *saved_head, int stack_height)

Trims Error state while an exception frame leaves. Handlers newer than saved_head are reclaimed. Records at and above stack_height are also reclaimed; pass the current height on normal frame exit to preserve collected errors.

Source: lib/error.x:250

Error.unwind_head

void *Error.unwind_head(void)

Returns the handler head retained for the current Error transfer. During handler dispatch this is the saved pre-dispatch head, even though the active callback is temporarily hidden from nested raises. Exception frames store the opaque result as their landing watermark.

Source: lib/error.x:225

Runtime-internal callables

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

Error

Error.context_close

void Error.context_close(void *token, int preserve_records)

Closes one Context Error overlay. An exception unwinding out of the Context keeps its records for the outer handler; an ordinary close discards records accumulated inside it. In both cases handlers pushed inside the Context are reclaimed. Tokens must close in nesting order; an out-of-order close reaches the raw error floor. A null token does nothing and a closed token is invalid.

Source: lib/error.x:903

Error.context_open

void *Error.context_open(void)

Opens the Error state owned by one Context. Policy and bound changes become local overlays; handlers and accumulated records are restored by Error.context_close. The returned opaque token is allocated in the current Scope, which must remain live through the matching close. An unavailable Error runtime returns NULL.

Raises: <alloc-fail> when the overlay cannot be allocated.

Source: lib/error.x:883

Error.since_in

List Error.since_in(int mark, Scope *values, Pool pool)

Copies errors at and after mark into explicit owners, oldest first. Strings and Lists are canonicalized through pool’s chain and remain live until their actual owning pool is released. Wide scalar boxes enter *values, whose possibly updated Scope head is written back, and remain live until that Scope is destroyed. An unavailable runtime or negative mark returns nil. Null owners or failures while copying reach the raw floor.

Source: lib/error.x:668

Error.snapshot_in

Var Error.snapshot_in(Var value, Scope *values, Pool pool)

Copies one admissible error value into explicit runtime owners. Strings and Lists are canonicalized through pool’s chain and remain live until their actual owning pool is released. Wide scalar boxes enter *values, whose possibly updated Scope head is written back, and remain live until that Scope is destroyed. Null owners, invalid or identity-bearing values, and failures while copying reach the raw floor.

Source: lib/error.x:645

Public types

Error

typedef struct Error *Error

Names the structured-error runtime and its static operations. Programs do not construct Error values; automatic runtime initialization owns the per-thread handler, record, policy, and dispatch state.

Source: lib/error.x:27

ErrorHandler

typedef struct ErrorHandler *ErrorHandler

Identifies one Error-owned handler registration. An observing handle remains valid until Error.pop; a transferring-catch handle remains valid until x2c_error_catch_close. Enclosing frame or Context cleanup and Error shutdown may reclaim a registration first.

Source: lib/error.x:34

ErrorHandlerFn

typedef Symbol (*ErrorHandlerFn)(List errors, Var data)

Handles a borrowed oldest-first List of errors raised since registration. Error invokes callbacks synchronously from innermost registration outward. Return <handled>, <declined>, or <fatal>; <unwind> is reserved for compiler-generated catches. Any other result behaves as <declined> and continues outward or to policy. The List and its contents expire on return.

Source: lib/error.x:44

Design notes

Raising an error records it and calls registered handlers, innermost first. Each handler sees the errors raised since it was registered and decides how to respond. The caller sets the policy for errors no handler accepts.

Each accumulated record owns an independent Scope and canonical List and String pools. A handler watermark bounds those regions, so closing the handler reclaims its complete slice without touching application pools. Raising while the error path is itself failing uses the error floor, which allocates nothing.