Next: Restarts, Previous: Error Messages, Up: Error System [Contents][Index]
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:
By returning from the handler in the usual manner.
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.
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.
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.
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.
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.
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.
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.
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.
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.)
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]