16.4 Restarts

The Scheme error system provides a mechanism, known as restarts, that helps coordinate condition-signalling code with condition-handling code. A module of code that detects and signals conditions can provide procedures (using with-simple-restart or with-restart) to be invoked by handlers that wish to continue, abort, or restart the computation. These procedures, called restart effectors, are encapsulated in restart objects.

When a condition object is created, it contains a set of restart objects, each of which contains a restart effector. Condition handlers can inspect the condition they are handling (using find-restart to find restarts by name, or condition/restarts to see the entire set), and they can invoke the associated effectors (using invoke-restart or invoke-restart-interactively). Effectors can take arguments, and these may be computed directly by the condition-handling code or by gathering them interactively from the user.

The names of restarts can be chosen arbitrarily, but the choice of name is significant. These names are used to coordinate between the signalling code (which supplies names for restarts) and the handling code (which typically chooses a restart effector by the name of its restart). Thus, the names specify the restart protocol implemented by the signalling code and invoked by the handling code. The protocol indicates the number of arguments required by the effector code as well as the semantics of the arguments.

Scheme provides a conventional set of names (hence, protocols) for common use. By choosing the names of restarts from this set, signalling code can indicate that it is able to perform a small set of fairly common actions (abort, continue, muffle-warning, retry, store-value, use-value). In turn, simple condition-handling code can look for the kind of action it wishes to perform and simply invoke it by name. All of Scheme’s conventional names are symbols, although in general restart names are not restricted to any particular data type. In addition, the object #f is reserved to indicate the “not for automated use” protocol: these restarts should be activated only under human control.

Restarts themselves are first-class objects. They encapsulate their name, a procedure (known as the effector) to be executed if they are invoked, and a thunk (known as the reporter) that can be invoked to display a description of the restart (used, for example, by the interactive debugger). Invoking a restart is an indication that a handler has chosen to accept control for a condition; as a consequence, the effector of the restart should not return, since this would indicate that the handler declined to handle the condition. Thus, the effector should call a continuation captured before the condition-signalling process began. The most common pattern of usage by signalling code is encapsulated in with-simple-restart.

Within this chapter, a parameter named restarts will accept any of the following values:

• A list of restart objects.
• A condition. The procedure condition/restarts is called on the condition, and the resulting list of restarts is used in place of the condition.
• The symbol bound-restarts. The procedure bound-restarts is called (with no arguments), and the resulting list of restarts is used in place of the symbol.
• If the restarts parameter is optional and is not supplied, it is equivalent to having specified the symbol bound-restarts.