Condition Handling (MIT/GNU Scheme 11.0.90)

Next: Restarts, Previous: Error Messages, Up: Error System [Contents][Index]

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

Next: Restarts, Previous: Error Messages, Up: Error System [Contents][Index]