Error Handling

Errors in Graphix are represented by the Error<'a> type. A new instance of which can be created with the error function. e.g.

〉error(`Foo)
-: Error<'a: `Foo>
error:"Foo"

Catch and ?

While errors are normal values, and can be matched in select, they can also be thrown and handled like exceptions. A catch(e) expr statement installs an error handler covering the REST of its enclosing scope — every statement after it, and everything called from those statements. The ? operator throws errors generated by the expression on it’s left to the nearest installed catch in dynamic scope. for example,

〉let a = [1, 2, 3, 4]
〉catch(e) println(e)
〉a[15]?
-: i64
error:[["cause", null], ["error", ["ArrayIndexError", "array index out of bounds"]], ["ori", [["parent", null], ["source", "Unspecified"], ["text", "a[15]?"]]], ["pos", [["column", i32:2], ["line", i32:1]]]]

Catches the array index error and prints it’s full context to stdout.

Catching errors is NOT control flow: the catch statement is an installation, its type is bottom (it never produces a value), and an error being raised does not stop the execution of any node. The handler is an ordinary reactive expression that runs when an error value arrives — the natural idiom is to connect it to state your program reads,

let error_display: [null, string] = null;
let x = {
    catch(e) error_display <- "[e]";
    calc(in0)
};
widget([x, text(error_display)])

The catch here covers calc(in0) — and only that block: a catch installed inside a block covers the rest of THAT block, nothing outside it. A second catch in the same block shadows the first for the statements below it; a handler may rethrow with ?, which resolves to the previous catch (or the next one out). Every error raised with ? is wrapped in an ErrChain struct, the full definition of which is,

type Pos = {
    line: i32,
    column: i32
};

type Source = [
    `File(string),
    `Netidx(string),
    `Internal(string),
    `Unspecified
];

type Ori = {
    parent: [Ori, null],
    source: Source,
    text: string
};

type ErrChain<'a> = {
    cause: [ErrChain<'a>, null],
    error: 'a,
    ori: Ori,
    pos: Pos
}

This gives the full context of where the error happened, and whether it was previously caught and reraised, giving the full history back to the first time it was ever raised.

The scope is dynamic, not lexical, mirroring exception systems that unwind the stack,

〉let div0 = { catch(e) println(e ~ "never triggered"); |x| (x /? 0)? }
〉catch(e) println(e)
〉div0(0)
-: i64
error:[["cause", null], ["error", ["ArithError", "attempt to divide by zero"]], ["ori", [["parent", null], ["source", "Unspecified"], ["text", "let div0 = { catch(e) println(e ~ \"never triggered\"); |x| (x /? 0)? }"]]], ["pos", [["column", i32:26], ["line", i32:1]]]]

The catch surrounding the function call site, not the definition site, is the one triggered. Note the use of the checked division operator /? combined with ? to propagate the error – unchecked / would simply return bottom on division by zero rather than throwing.

Constraining the error type

The binder may carry a type annotation, catch(e: T) expr, which the compiler checks against the union of every error type the covered region can throw — a contract on what the handler must be prepared to receive.

Checked Errors

Graphix function types are annotated by the type of error they might raise. In most cases this is automatic, but for some higher order functions it may be necessary to specify it explicitly. For example array map has type fn(a: Array<'a>, f: fn(x: 'a) -> 'b throws 'e) -> Array<'b> throws 'e indicating that while the map function itself does not throw any errors, it will throw any errors the function passed to it throws. This is all in the service of being able to statically check the type of thrown errors, for example,

let a = [0, 1, 2, 3];
catch(e) select (e.0).error {
    `ArithError(s) => println("arithmetic operation error [s]"),
    `ArrayIndexError(s) => println("array index error [s]")
};
(a[0]? +? a[1]?)?

There are two types of errors that can happen in this example: the array indexing can produce an ArrayIndexError, and the checked addition +? can produce an ArithError. The compiler knows both, and if you were to omit one of them, then the example would not compile. Suppose we remove the pattern for ArrayIndexError, we would get,

Error: in file "test.gx"

Caused by:
    0: at: line: 3, column: 13, in: select (e.0).error {`ArithError(s) => ..
    1: missing match cases type mismatch `ArithError('_1897: string) does not contain '_1895: [`ArithError(string), `ArrayIndexError(string)]

You’ll recognize that this is just the normal select exhaustiveness checking at work. Since errors are just normal types, the important point is the compiler knows the type of every error at compile time, everything else flows from there.

Unhandled Errors

By default when evaluating a file, the compiler will print a warning whenever an error raised by ? is not covered by an installed catch. Using -W flags you can change the compilers behavior in this respect.

The $ Operator, aka Or Never

The $ operator goes in the same position as ?, and is best described as “or never”. If the expression on it’s left is a non error, then $ doesn’t do anything, otherwise it logs the error at the warn! log level and returns nothing. This is a concise way of writing,

select might_fail(1, 2, 3) {
  error as _ => never(),
  v => v
}

can instead be written as,

might_fail(1, 2, 3)$

The $ operator logs errors rather than silently discarding them, making it easier to debug issues while still allowing execution to continue.

One caveat: the log message is produced by the interpreter. When the expression is compiled by the JIT (fusion is on by default), the error is dropped without a diagnostic — the resulting value is the same, but nothing is logged. If you’re debugging a swallowed error, run with --no-fusion to see the logged diagnostics.