envzn
0.8 · beta · not released

Errors

The error classes the kernel throws.

Generated by bin/build_library_doc.py from the kernel sources. Do not edit by hand: change the generator, or the doc comments in kernel/src/, and re-run it.

Errors

CLASS Error

Abstract base class for the kernel error hierarchy.

Every kernel error class extends Error (directly or transitively). User-defined error classes in consumer modules also extend Error to participate in RECOVER dispatch. The base class carries a single message field; subclasses add their own fields as needed (see ErrorTypes.ev for the kernel-shipped concrete classes).

────────────────────────────────────────────────────────────────── PANIC / RECOVER semantics ──────────────────────────────────────────────────────────────────

Every Error instance can be raised in a PANIC. RECOVER clauses match by class type (and any subclass of the matched type — covariant). The base class will recover from any panic:

TRY {
    doWork()
} RECOVER (FileError fe) {
    logError(fe->message())
} RECOVER (Error e) {
    // any error not handled above
    logError("unhandled: $1")->format(e->message())
}

The matching order is top-to-bottom; subclass clauses must precede their superclasses to be reachable.

────────────────────────────────────────────────────────────────── C++ INTEROP ──────────────────────────────────────────────────────────────────

At the C++ layer, Error extends std::exception so kernel errors propagate cleanly through any C++ stack frame the runtime traverses (FOREIGN-call-raising, runtime panics, etc.).

kernel/src/Error.ev:49

Fields

  • int32 code
  • int32 line_number

Constructors

INIT()
INIT(char32[] message)
INIT(REFERENCE String message)

Bridge from a String arg — copy the source's code points into this .msg. The per-subclass INIT(String message) pattern uses SUPER(message) which routes here.

INIT(REFERENCE String message, REFERENCE String cause)

Chaining INIT — set both the message and the triggering error's message as the cause. Errors are chained by passing a triggering error's message as the cause of a new one (I.M.ii). A subclass that wants to expose chaining declares its own INIT(String, String) and routes here with SUPER(message, cause).

INIT(REFERENCE String message, REFERENCE String cause, int32 code)

Chaining INIT with an explicit numeric code.

Methods

METHOD hasCause() RETURNS boolean

Whether a triggering cause is attached (I.M.ii).

METHOD getErrorCode() RETURNS int32

The numeric error code; 0 means "no code" (I.M.ii).

METHOD message() RETURNS String

What went wrong, as the PANIC site's INIT set it.

METHOD cause() RETURNS String

The triggering error's message, or empty when there is none (I.M.ii).

METHOD filename() RETURNS String

The source file of the PANIC site, injected by the compiler.

METHOD threadName() RETURNS String

The raising thread's name, or empty for an unnamed context.

CLASS CompileError

EXTENDS Error

Kernel error class. Raised by tooling that performs compilation at runtime (the self-hosted Envzn compiler, opaque-evaluation helpers). Not expected to be raised by ordinary application code, but reserved as a kernel type so compiler-using modules don't have to invent their own.

Subclass of Error; adds no new fields.

kernel/src/CompileError.ev:23

Constructors

INIT(REFERENCE String message)

CLASS FileError

EXTENDS Error

Kernel error class. Thrown by File / Path methods on I/O failure. Examples: file not found, permission denied, disk full, directory creation failed, recursive remove encountered an undeletable entry.

Subclass of Error; adds no new fields — the type name itself is the discriminant for RECOVER dispatch.

kernel/src/FileError.ev:19

Constructors

INIT(REFERENCE String message)

CLASS IndexOutOfBoundsError

EXTENDS Error

Kernel error class. Raised by every collection's bounds check (Array.at / Array.setAt / Array.insertAt / Array.remove, LinkedList.insertAt, removeAt, etc.). The message field typically encodes the offending index and the collection's length at PANIC time; format follows the pattern "index $1 out of bounds for length $2".

Subclass of Error; adds no new fields.

kernel/src/IndexOutOfBoundsError.ev:24

Constructors

INIT(REFERENCE String message)

CLASS MathError

EXTENDS Error

Kernel error class. Thrown by Math singleton methods on domain errors and by the checked-arithmetic helpers (Math.checkedAdd, etc.) on overflow. Examples: square root of a negative real, log of a non-positive value, integer-overflow on a checked op.

Subclass of Error; adds no new fields.

kernel/src/MathError.ev:19

Constructors

INIT(REFERENCE String message)

CLASS NetworkError

EXTENDS Error

Historical kernel-side placeholder. The production NetworkError class lives in the Networking module (Networking/NetworkError.ev) where it belongs alongside the rest of the network-protocol error surface. This kernel-side declaration exists for C++ ABI symmetry with ENVZN.hpp.

Subclass of Error; adds no new fields.

kernel/src/NetworkError.ev:19

Constructors

INIT(REFERENCE String message)

CLASS EmptyHandleError

EXTENDS Error

Raised when a handle is used while it holds nothing.

Two places raise it. The _UnsafeHandle<T>::operator->() and get() safety wrapper raises it (no message) when an UNSAFE.* handle is dereferenced while null. Kernel code raises it (with a message) from a guard that refuses to read a value it knows was moved out — CollisionNode's valid flag. Recover from the PANIC in user code via TRY { ... } RECOVER (EmptyHandleError e) { ... }, like any kernel Error.

Subclass of Error; adds no new fields. The probe at kernel_probe/unsafe_safety_wrapper/ validated that the raised PANIC unwinds across the FFI boundary and Envzn TRY/RECOVER recovers by class identity.

kernel/src/EmptyHandleError.ev:25

Constructors

INIT()
INIT(REFERENCE String message)

With a message naming the handle that was empty.

CLASS RandomError

EXTENDS Error

Kernel error class for the Random surface. Thrown by SecureRandom when OS entropy is unavailable, and by the generators on a non-positive bound (nextInt(bound <= 0)).

Subclass of Error; adds no new fields.

kernel/src/RandomError.ev:17

Constructors

INIT(REFERENCE String message)

CLASS OutOfMemoryError

EXTENDS ResourceExhaustedError

Kernel error class. Raised when the runtime allocator cannot get a block; the message is "out of memory allocating bytes". Use RECOVER on the LLVM backend; on the C++ backend the same report is printed and the program aborts.

Subclass of ResourceExhaustedError; adds no new fields.

kernel/src/OutOfMemoryError.ev:24

Constructors

INIT(REFERENCE String message)

CLASS ResourceExhaustedError

EXTENDS Error

Kernel error class. The parent of every error that means the program ran out of a finite resource (memory, the stack) rather than did something wrong. RECOVER (ResourceExhaustedError e) handles all of them.

Subclass of Error; adds no new fields.

kernel/src/ResourceExhaustedError.ev:20

Constructors

INIT(REFERENCE String message)

CLASS CloneError

EXTENDS Error

Raised when clone() is asked to copy a value that has no copy.

One place raises it today: clone() of an opaque that carries a C handle (a FOREIGN_TYPE pointer such as a sqlite3_stmt*). A C object has one owner, and copying the pointer would make two, one of which frees it under the other (I.D.v (c)). Keep one owner and lend it with REFERENCE. Raised from the kernel's opaque runtime, which is where the box knows what it carries; caught like any kernel Error, with TRY { ... } RECOVER (CloneError e) { ... }.

kernel/src/CloneError.ev:21

Constructors

INIT(REFERENCE String message)

CLASS LensMismatchError

EXTENDS Error

Kernel error class. Raised when a checked narrowing (:= or =@ from a parent or interface type to a narrower one) finds the object's class is not the one named. The message names both types.

Subclass of Error; adds no new fields.

kernel/src/LensMismatchError.ev:19

Constructors

INIT(REFERENCE String message)

ENUM Severity

Per the ENVZN module convention, this single file holds the constitution's reserved enums. They're small (2–3 cases each) so grouping them in one file matches the pattern used for STRUCTs and INTERFACEs.

Each enum is referenced by name from the constitution and/or standard library: - DeliveryMode — used by CHANNEL[T]->send_message() to specify how a message reaches subscribers. - Severity — used by logging APIs and the constitution's Compiler-Error-Strategy spec to grade diagnostic levels. - Build — used by WHEN_BUILD conditional compilation to switch on debug-vs-release at compile time. Severity — diagnostic and logging level. Ordered (informally) from least to most serious. Consumers can compare ordinally via the implicit enum order.

  • INFO — routine operational message.
  • WARNING — something unexpected but recoverable.
  • ERROR — operation failed; caller should handle.
  • FATAL — unrecoverable; typical follow-up is exit() or PANIC.

Spec reference: §17 mentions ENVZN::Severity.WARNING for compiler-driven diagnostics; user-side logging follows the same enum.

kernel/src/enums.ev:39

Case Description
? —
? —
? —
? —