Finding and Invoking General Restart Code - MIT/GNU Scheme 7.7.90+
Description: MIT/GNU Scheme 7.7.90+

Next: The Named Restart Abstraction, Previous: Invoking Standard Restart Code, Up: Restarts

#### 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.