Fallible main
Every program so far ended with return 0; from func Main() -> int. That made plain try useless at the top level: Main could not throw, so an error had nowhere to go, and every step had to be caught by hand.
Main may also throw. Then plain try works at the top level too, and an error that reaches Main ends the program.
Main may throw
The installer in this lesson reserves disk space for two programs. Reserve throws a SpaceError when there is not enough room, and Main declares the same error:
func Main() throws SpaceError {
var free = 100;
PrintLine("Installing the editor (40 MB of {} MB free)", free);
free = try Reserve(40, free);
Main now has no return type, like the functions in Unit fallible, so it follows the same rules: falling off its end is success, and it has no return 0;. The second reservation asks for 90 MB with only 60 free, so its try passes the error out of Main and ends the program — the last PrintLine never runs.
How the program ends
The operating system receives a number when a program ends, its exit status. 0 means success; anything else means something went wrong.
Main is declared | and ends by | Exit status |
|---|---|---|
-> int | return n; | n |
throws E | reaching its end | 0 |
-> int throws E | return n; | n |
throws E or -> int throws E | a throw, or an error from try | 1 |
An error still runs the program's ordinary cleanup on the way out — every defer and destructor, just as a return would — unlike a panic, which stops at once.
An error prints nothing
The surprise is what an error does not do: it prints nothing. The SpaceError value is not shown anywhere, so a user only sees the program stop after the second line.
The exit status is for whoever started the program — a script, a build tool or a shell. In PowerShell, echo $LASTEXITCODE shows it right after the program ends; in a POSIX shell such as bash, it is echo $?. That 1 is the last line of the output below.
If a person should learn why the program stopped, print a message yourself before throwing. A catch arm can do both — print, then throw the same error on:
free = try Reserve(90, free) catch {
e => {
PrintLine("Not enough space: {} MB needed, {} MB free", e.needed, e.free);
throw e;
}
};
The arm e => ... binds the whole error, and its block ends by leaving, so it never has to produce a value.
The program
The whole lesson is one package in the Examples repository. Its comments explain every step.
// Every program so far ended with `return 0;` from `func Main() -> int`. `Main`
// may also throw, with or without an `int` result:
//
// func Main() throws SpaceError
// func Main() -> int throws SpaceError
//
// Now plain `try` works at the top level too: an error that reaches `Main`
// leaves it like any other error leaves a throwing function. Falling off the
// end of a `Main` with no result is success, and the program exits with
// status 0. An error — from a `throw` in `Main` or passed on by a `try` —
// ends the program with exit status 1, after every `defer` and destructor on
// the way out has run.
//
// The surprise is what an error does *not* do: it prints nothing. The error
// value is not shown anywhere, so a user only sees the program stop. If they
// should learn why, print a message yourself before throwing. The exit status
// is for whoever started the program: a script, a build tool or a shell. In
// PowerShell, `echo $LASTEXITCODE` shows it right after the program ends.
//
// This program fails on purpose: the second install does not fit.
import Io::PrintLine;
struct SpaceError {
needed: int;
free: int;
}
func Reserve(needed: int, free: int) -> int throws SpaceError {
if needed > free {
throw SpaceError { needed: needed, free: free };
}
return free - needed;
}
func Main() throws SpaceError {
var free = 100;
PrintLine("Installing the editor (40 MB of {} MB free)", free);
free = try Reserve(40, free);
PrintLine("Installing the compiler (90 MB of {} MB free)", free);
free = try Reserve(90, free);
// Never printed: the `try` above passed the error out of `Main`, which
// ended the program with status 1.
PrintLine("Everything is installed, {} MB left", free);
}
Run it
cd Examples/Errors/FallibleMain
rux run
echo $?
The program fails on purpose, so it stops after the second line, and echo $? prints its exit status, 1. In PowerShell, use echo $LASTEXITCODE instead.
Installing the editor (40 MB of 100 MB free)
Installing the compiler (90 MB of 60 MB free)
1
Common mistakes
Try it yourself
- Change the compiler's 90 MB to 50 and run again. What does
echo $LASTEXITCODEshow now? - Replace the second
trywith thecatchabove, so the user learns why the install stopped. - Declare
func Main() -> int throws SpaceError, end it withreturn 2;, and check the exit status when everything fits.
Learn more
- A throwing Main and The Main entry point in the Rux Reference
- Unit fallible — the rules a function with only
throws Efollows - Propagate — the plain
trythatMaincan now use - Panic — stopping a program that has hit a bug