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:206

x2c_error_catch_close

void x2c_error_catch_close(ErrorHandler handle)

Closes and invalidates a transferring-catch handle. The handle releases its plans, captures, and retained error records. A still-registered handle also leaves the handler stack and truncates records above its registration watermark; a detached one leaves the chain of running arms instead. Handles must close in stack order on whichever chain holds them; violating that order reaches the raw error floor. A null handle does nothing.

Source: lib/error.x:243

x2c_error_catch_detach

void x2c_error_catch_detach(ErrorHandler handle)

Unregisters the top transferring catch before its arm runs. The handler stack then holds only registrations that can still be selected, so the arm may raise outward without matching itself and may close handlers the try was nested inside. The handle moves to the thread’s chain of running arms, which owns the retained Error and captures the arm still reads until x2c_error_catch_close; Error shutdown walks that chain, so an exit() from inside an arm still reclaims them. Repeated detach and a null handle do nothing. Detaching out of stack order reaches the raw error floor.

Source: lib/error.x:224

x2c_error_catch_push

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

Registers one transferring catch from patterns supplied per call. A hand-written caller that has no static site uses this form; arm_count List pattern Vars follow in source order, and one plan per arm is prepared for this registration alone. Results and failures follow x2c_error_catch_site_push.

Source: lib/error.x:174

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:198

x2c_error_catch_site_pending

int x2c_error_catch_site_pending(ErrorCatchSite *site)

Reports whether one catch site still needs its patterns at registration. A bound static site answers 0, so its caller can skip constructing them.

Source: lib/error.x:74

x2c_error_catch_site_push

ErrorHandler x2c_error_catch_site_push( void *target, ErrorCatchSite *site, Var *patterns)

Registers one compiler-generated transferring catch through its site. target names the ExceptionFrame that the caller pushes immediately afterward and site is the static site of this try, whose patterns are read in source order. A pending site reads patterns; a bound static site ignores them, so a caller may pass anything once x2c_error_catch_site_pending answers 0. The site borrows every referenced List graph, and those values and the target frame must outlive it. A null target or site, a zero arm count, or an 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:133

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:267

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:291

Error

Error.bound

int Error.bound(void)

Returns the maximum number of errors that may remain accumulated.

Source: lib/error.x:947

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:955

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:677

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:672

Error.handler_depth

int Error.handler_depth(void)

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

Source: lib/error.x:306

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:316

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:376

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:682

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:276

Error.policy_adopt

void Error.policy_adopt(void *capture)

Adopts a policy capture on the calling thread and releases it. Each captured code takes its captured disposition; codes the capture does not name keep the disposition this thread already has. A NULL capture, or one adopted while Error is unavailable, is released without effect. Failure to update Error-owned storage reaches the non-reentrant error floor.

Source: lib/error.x:924

Error.policy_capture

void *Error.policy_capture(void)

Captures the calling thread’s Error policy for another thread to adopt. Policy is per-thread state, so a worker starts with only the shared non-returning causes locked to <abort>; a capture carries the starting thread’s dispositions across. Error.policy_adopt consumes the capture and Error.policy_release discards one that no thread adopted. An unavailable Error runtime captures nothing and answers NULL.

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

Source: lib/error.x:900

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:851

Error.policy_release

void Error.policy_release(void *capture)

Releases a policy capture that no thread adopted. A NULL capture is accepted and does nothing.

Source: lib/error.x:944

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:830

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:1069

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:973

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:1303

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:1315

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:362

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:335

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:396

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:807

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:734

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:349

Error.unwind_head

void *Error.unwind_head(void)

Returns the handler head retained for the current Error transfer. During handler dispatch this is the head saved by the outermost dispatch, even though the running callbacks are temporarily hidden from nested raises. Exception frames store the opaque result as their landing watermark.

Source: lib/error.x:324

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:1105

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:1087

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:773

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:750

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:28

ErrorCatchSite

typedef struct ErrorCatchSite { MatchCaptureSite *arms; int default_arm, arm_count, state, fenced_arm; } ErrorCatchSite

Holds the process-lifetime plans of one compiler-generated filtered catch. arms is a zero-initialized static array of arm_count Match sites and default_arm is the first unpatterned arm, or -1. state and fenced_arm belong to Error; a site must be static storage that the first registration binds to its patterns.

Source: lib/error.x:53

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:35

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:45

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.