Next: The Named Restart Abstraction, Previous: Invoking Standard Restart Code, Up: Restarts
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.
Returns a list of all currently active restart objects, most recently installed first.
bound-restartsshould 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.
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-restartis 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.
Calls the restart effector encapsulated in restart, passing the specified arguments to it.
invoke-restartis 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-interactivelyshould be used instead ofinvoke-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-interactivelyis intended for calling interactive restarts (those for whichrestart/interactoris not#f). For convenience,invoke-restart-interactivelywill call the restart's effector with no arguments if the restart has no interactor; this behavior may change in the future.