16.3 Condition Handling

The occurrence of a condition is signalled using signal-condition. signal-condition attempts to locate and invoke a condition handler that is prepared to deal with the type of condition that has occurred. A condition handler is a procedure of one parameter, the condition that is being signalled. A procedure is installed as a condition handler by calling bind-condition-handler (to establish a handler that is in effect only while a particular thunk is executing) or bind-default-condition-handler (to establish a handler that is in effect permanently). As implied by the name, handlers created by bind-default-condition-handler are invoked only after all other applicable handlers have been invoked.

A handler may process a signal in any way it deems appropriate, but the common patterns are:

Ignore the condition.

By returning from the handler in the usual manner.

Handle the condition.

By doing some processing and then invoking a restart (or, less preferably, a continuation) that was established at some point prior to the call to signal-condition.

Resignal a condition.

By doing some processing and calling signal-condition with either the same condition or a newly created one. In order to support this, signal-condition runs handler in such a way that a subsequent call to signal-condition sees only the handlers that were established prior to this one.

As an aid to debugging condition handlers, Scheme maintains a set of condition types that will cause an interactive breakpoint to occur prior to normal condition signalling. That is, signal-condition creates a new REPL prior to its normal operation when its argument is a condition that is a specialization of any of these types. The procedure break-on-signals establishes this set of condition types.

procedure: ignore-errors thunk

Executes thunk with a condition handler that intercepts the signalling of any specialization of condition-type:error (including those produced by calls to error) and immediately terminates the execution of thunk and returns from the call to ignore-errors with the signalled condition as its value. If thunk returns normally, its value is returned from ignore-errors.

Notice that ignore-errors does not “turn off signalling” or condition handling. Condition handling takes place in the normal manner but conditions specialized from condition-type:error are trapped rather than propogated as they would be by default.

procedure: bind-condition-handler condition-types handler thunk

Invokes thunk after adding handler as a condition handler for the conditions specified by condition-types. Condition-types must be a list of condition types; signalling a condition whose type is a specialization of any of these types will cause the handler to be invoked. See signal-condition for a description of the mechanism used to invoke handlers.

By special extension, if condition-types is the empty list then the handler is called for all conditions.

procedure: bind-default-condition-handler condition-types handler

Installs handler as a (permanent) condition handler for the conditions specified by condition-types. Condition-types must be a list of condition types; signalling a condition whose type is a specialization of any of these types will cause the handler to be invoked. See signal-condition for a description of the mechanism used to invoke handlers.

By special extension, if condition-types is the empty list then the handler is called for all conditions.

procedure: break-on-signals condition-types

Arranges for signal-condition to create an interactive REPL before it signals a condition that is a specialization of any of the types in the list of condition-types. This can be extremely helpful when trying to debug code that uses custom condition handlers. In order to create a REPL when any condition type is signalled it is best to actually put a breakpoint on entry to signal-condition.

procedure: standard-error-handler condition

Called internally by error after it calls signal-condition. Normally creates a new REPL with the prompt "error>" (but see standard-error-hook). In order to simulate the effect of calling error, code may call signal-condition directly and then call standard-error-handler if signal-condition returns.

parameter: standard-error-hook

This parameter controls the behavior of the procedure standard-error-handler, and hence error. It is intended to be bound with parameterize and is normally #f. It may be changed to a procedure of one argument and will then be invoked (with standard-error-hook rebound to #f) by standard-error-handler just prior to starting the error REPL. It is passed one argument, the condition being signalled.

procedure: standard-warning-handler condition

This is the procedure called internally by warn after it calls signal-condition. The normal behavior of standard-warning-handler is to print a message (but see standard-warning-hook). More precisely, the message is printed to the port returned by notification-output-port. The message is formed by first printing the string "Warning: " to this port, and then calling write-condition-report on condition and the port.

In order to simulate the effect of calling warn, code may call signal-condition directly and then call standard-warning-handler if signal-condition returns. (This is not sufficient to implement the muffle-warning protocol, however. For that purpose an explicit restart must be provided.)

parameter: standard-warning-hook

This parameter controls the behavior of the procedure standard-warning-handler, and hence warn. It is intended to be bound with parameterize and is normally #f. It may be changed to a procedure of one argument and will then be invoked (with standard-warning-hook rebound to #f) by standard-warning-handler in lieu of writing the warning message. It is passed one argument, the condition being signalled.