Errors & exceptions

When some­thing bad—that is, an error—happens while a program is running, an excep­tion is raised. “Raised” means the excep­tion prop­a­gates upward through the chain of calling func­tions. If the excep­tion isn’t caught by any of these func­tions, the program stops and the excep­tion is printed, like so:

Any kind of value can be used as an excep­tion. Usually it’s an instance of the special exn struc­ture, which carries infor­ma­tion about the nature of the error and where it happened. In this case, car is raising an excep­tion of type exn:fail:contract?.

Catching excep­tions

We wrap with-handlers around an expres­sion to catch excep­tions that might arise from the expres­sion. Below, the contract viola­tion in car still raises a exn:fail:contract? excep­tion. But this time it invokes a func­tion desig­nated to handle this excep­tion. The error is suppressed, and we get the result of the func­tion:

with-handlers is similar to cond. It contains a sequence of branches. On the left side of each branch is an excep­tion pred­i­cate; on the right is a func­tion that will handle the excep­tion. Following these branches is a body consisting of any other expres­sions. The body is eval­u­ated first. If an excep­tion is raised within the body, with-handlers tests it against each left-hand pred­i­cate. If a match is found, it passes the excep­tion to the handler on the right. If it doesn’t get a match, the excep­tion exits the current with-handlers expres­sion and continues prop­a­gating upward (where it might hit another with-handlers).

For conve­nience, Racket offers a set of built-in excep­tion types that are orga­nized as a hier­archy with inher­i­tance. exn is at the top, then every exn:fail excep­tion counts as an exn, then every exn:fail:contract excep­tion also counts as an exn and an exn:fail, etc. Each excep­tion type has a corre­sponding pred­i­cate (spelled with a ? suffix, e.g. exn?, exn:fail?).

It’s a virtuous habit to construct excep­tion pred­i­cates as narrowly as possible, to avoid false posi­tives. For instance, (car 42) raises an excep­tion of the type exn:fail:contract. We’re better off testing for that rather than the more generic exn:fail. Like cond, this lets us order our branches from partic­ular to general:

Raising excep­tions

The simplest way to raise an excep­tion is with raise. Note that any value can be raised as an excep­tion (and caught using with-handlers). It can, but does not have to be, one of Racket’s built-in excep­tion types (like exn:fail):

When possible, it’s prefer­able to use one of the more specific vari­ants of raise—like raise-argument-error, raise-result-error, or raise-syntax-error—because they auto­mat­i­cally raise the conven­tional excep­tion type for those errors, promoting better coop­er­a­tion with handlers in the calling chain. For instance, this div func­tion uses raise to emit its own special excep­tion when it gets 0 for denom:

The problem is that no func­tion in the calling chain is expecting this kind of excep­tion, so there’s no handler to catch it (hence the “uncaught excep­tion” message).

The better approach is to phrase the error in terms of raise-argument-error, which produces a stan­dard contract-viola­tion message:

It will also be caught by a stan­dard exn:fail:contract handler in the calling chain:

Making new excep­tion types

It’s wise to rely on Racket’s built-in excep­tion types when we can, so that our excep­tions coop­erate with handlers in the wild (meaning, in other modules, espe­cially ones we don’t control). For instance, if we were writing a math library, there would be no benefit to rein­venting the exn:fail:contract:divide-by-zero excep­tion type.

But other times, our error may not fit these generic types. Or it may be suffi­ciently special that we delib­er­ately want to keep it from being caught by existing handlers. In those cases, we can create a new excep­tion type with struct that inherits from an existing excep­tion type (either the apex exn type or a subtype):

We catch a custom excep­tion the same way as a built-in excep­tion:

Excep­tion hacking

Though excep­tions and handlers are typi­cally asso­ci­ated with catching errors, they don’t have to be used that way. They can also be used to send & receive other kinds of signals, and thereby create alter­na­tive control flows.

For instance, Racket has no return state­ment. Usually it’s not missed. But some­times it’s handy to be able to break out of a deeply nested chain of func­tions. We can use excep­tions to simu­late this control flow. A contrived example:

The func­tion a picks a random integer from 0–9 inclu­sive and passes it to b, which does the same and passes the two inte­gers to c, which does the same and ends up with a list of three random inte­gers. The for loop will call a repeat­edly until c has a list of three zeroes, at which point it will print the number of attempts it took, for instance:

We do this by creating a special exn:all-zero excep­tion that acts as a signal that we’ve found a list of three zeroes. We raise this excep­tion within c once we’ve found our target list. We catch this excep­tion within the loop (using with-handlers as usual) and then raise trial as a new excep­tion, which is the number of attempts we’ve made so far. Outside the loop, we catch this second excep­tion and print it as a result. This is a perverse way of accom­plishing this partic­ular task. But it shows how we can rewire program flow with excep­tions.  + Compare: an excep­tion lets us jump back through the chain of calling func­tions any distance. A return, by contrast, can only jump back to the imme­di­ately previous caller.

Within Racket, excep­tions are members of a broader class of things called contin­u­a­tions that can rewire program flow in more arbi­trary ways.

Further