Skip to content

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.

Report an issue