Docs/Language/Errors & Effects
Errors & Effects
Result and the ? operator for errors; effect annotations and handlers for everything a function does to the outside world.
~3 min read
On this page
Result and ?
Fid has no exceptions. A fallible function returns Result<T, E>, and ? returns early with the error:
fn parse_age(s: str) -> Result<i64, str> {
val n = String::from(s).parse_int();
if n < 0 { return Result::Err("negative age"); }
return Result::Ok(n);
}
fn next_year(s: str) -> Result<i64, str> {
val age = parse_age(s)?; // returns early on Err
return Result::Ok(age + 1);
}
fn main() -> i64 {
match next_year("41") {
Result::Ok(n) => { println(f"Got {n}"); }
Result::Err(e) => { println(f"Error: {e}"); }
}
match next_year("-3") {
Result::Ok(n) => { println(f"Got {n}"); }
Result::Err(e) => { println(f"Error: {e}"); }
}
val fallback = next_year("-3").unwrap_or(0);
println(fallback);
return 0;
}Output: Got 42, Error: negative age, 0. ? does not convert between error types; the error types must match.
Effect annotations
Effects list what a function does to the outside world: !IO, !Net, !Spawn, !Alloc, several as !{IO, Net}, or !{} for pure.
fn log(msg: str) !IO {
println(msg);
}
fn greet() !{IO, Net} { // over-declaring is allowed
log("hello");
}
fn add(a: i64, b: i64) -> i64 !{} { // pure
return a + b;
}
fn main() -> i64 !IO {
greet();
println(add(2, 3));
return 0;
}Output: hello, 5. The compiler infers every function’s effects across the call graph; calls to the runtime’s file, socket, process and clock functions count as IO or Net. A function without an annotation is not checked; one whose annotation leaves out an inferred effect is a compile error (example). Effect names in an annotation are not validated. A function that takes a function value gets, at each call, the effects of the function passed, so apply(pure_fn, x) can be called from a !{} function (example).
Effect handlers
Inside a handle block, do Effect.op(args); performs an effect and pauses the block. The matching arm in with runs, and resume(cont, value) continues the block after the do:
fn main() {
handle {
val x = 10;
do Log.write(x); // perform the effect; the block pauses
println(x + 1); // runs after the handler resumes
} with {
Log.write(v) => {
println(f"handler got {v}");
resume(cont, 0); // continue after the `do`
}
}
}Output: handler got 10, 11.
A handler that does not call resume drops the rest of the block, which gives cooperative cancellation:
fn main() {
handle {
do Cancel.stop();
println("never printed");
} with {
Cancel.stop() => { println("stopped"); } // no resume
}
}Output: stopped.
Several do statements in one block run in order, and nested handle blocks send each effect to the nearest handler that has an arm for it:
fn main() {
handle {
handle {
do Inner.x(1);
do Outer.y(2); // not handled here: goes to the outer handler
println("inner block done");
} with {
Inner.x(v) => { println(f"inner {v}"); resume(cont, 0); }
}
} with {
Outer.y(v) => { println(f"outer {v}"); resume(cont, 0); }
}
}Output: inner 1, outer 2, inner block done. do is a statement; it does not return the resumed value.