16.4.3 Finding and Invoking General Restart Code

Restarts are a general mechanism for establishing a protocol between condition-signalling and condition-handling code. The Scheme error system provides “packaging” for a number of common protocols. It also provides lower-level hooks that are intended for implementing customized protocols. The mechanism used by signalling code (with-restart and with-simple-restart) is used for both purposes.

Four additional operations are provided for the use of condition-handling code. Two operations (bound-restarts and find-restart) allow condition-handling code to locate active restarts. The other two operations (invoke-restart and invoke-restart-interactively) allow restart effectors to be invoked once the restart object has been located.

In addition, there is a data abstraction that provides access to the information encapsulated in restart objects.

procedure: bound-restarts

Returns a list of all currently active restart objects, most recently installed first. bound-restarts should be used with caution by condition-handling code, since it reveals all restarts that are active at the time it is called, rather than at the time the condition was signalled. It is useful, however, for collecting the list of restarts for inclusion in newly generated condition objects or for inspecting the current state of the system.

procedure: find-restart name [restarts]

Returns the first restart object named name in the list of restarts (permissible values for restarts are described above in Restarts). When used in a condition handler, find-restart is usually passed the name of a particular restart and the condition object that has been signalled. In this way the handler finds only restarts that were available when the condition was created (usually the same as when it was signalled). If restarts is omitted, the currently active restarts would be used, and these often include restarts added after the condition ocurred.

procedure: invoke-restart restart argument …

Calls the restart effector encapsulated in restart, passing the specified arguments to it. invoke-restart is intended for use by condition-handling code that understands the protocol implemented by restart, and can therefore calculate and pass an appropriate set of arguments.

If a condition handler needs to interact with a user to gather the arguments for an effector (e.g. if it does not understand the protocol implemented by restart) invoke-restart-interactively should be used instead of invoke-restart.

procedure: invoke-restart-interactively restart

First calls the interactor encapsulated in restart to interactively gather the arguments needed for restart’s effector. It then calls the effector, passing these arguments to it.

invoke-restart-interactively is intended for calling interactive restarts (those for which restart/interactor is not #f). For convenience, invoke-restart-interactively will call the restart’s effector with no arguments if the restart has no interactor; this behavior may change in the future.