The first portion of this chapter explains how programs
can handle errors, by means of condition handlers. It also explains how
a program can signal an error if it detects something it doesn't like.
The second explains how users can handle errors, by means of an interactive debugger;
that is, it explains how to recover if you do something wrong.
A new user of the Lisp Machine, or someone who just wants to know how
to deal with errors and not how to cause them, should ignore the first
sections and skip ahead to
The remaining sections describe some other debugging facilities.
Anyone who is going to be writing programs for the Lisp Machine should
familiarize himself with these.
The trace facility provides the ability to perform certain
actions at the time a function is called or at the time it returns. The
actions may be simple typeout, or more sophisticated debugging functions.
The advise facility is a somewhat similar facility for modifying
the behavior of a function.
The breakon facility allows you to cause the debugger to be
entered when a certain function is called. You can then use the debugger's
stepping commands to step to the next function call or return.
The step facility allows the evaluation of a form to be
intercepted at every step so that the user may examine just what is happening
throughout the execution of the form. Stepping works only on interpreted code.
The MAR facility provides the ability to cause a trap
on any memory reference to a word (or a set of words) in memory. If
something is getting clobbered by agents unknown, this can help track
down the source of the clobberage.
Programmers often want to control what action is taken by their programs
when errors or other exceptional situations occur. Usually different situations
are handled in different ways, and in order to express what kind of handling
each situation should have, each situation must have an associated name. In
Zetalisp, noteworthy events are represented by objects called condition instances.
When an event occurs, a condition instance is created; it is then signaled, and a
handler for that condition may be invoked.
When a condition is signaled, the system (essentially) searches
up the stack of nested function invocations looking for a handler
established to handle that condition. The handler is a function that
gets called to deal with the condition. The condition mechanism itself
is just a convenient way for finding an appropriate handler function
for a particular exceptional situation.
When a condition is signaled, a condition instance is created to represent the
event and hold information about it. This information includes condition
names then classify the condition and any other data that is likely to be of
interest to condition handlers. A condition instance is immutable once it has
been created. Some conditions are errors, which means that the debugger is
invoked if they are signaled and not handled.
Condition instances are flavor instances. The flavor condition is the
base flavor from which all flavors of condition are built. Several
operations that are defined on condition instances are described below.
The flavor error, which is built on condition, is the base flavor for all kinds of
conditions which are errors.
A condition name is a symbol then is used to identify a category of conditions.
Each condition instance possesses one or more condition names. Each condition
handler specifies one or more condition names that it should apply to. A
handler applies to a condition if they have any condition names in common.
This is the sole purpose of condition names: to match condition instances with
their handlers. The meaning of every condition name signaled by the system is
described in this manual. The condition name index is a directory for them.
Conditions that are errors possess the condition name error.
In PL/I, CLU, ADA and most other systems that provide named conditions, each
condition has only one name. That is to say, the categories identified by
condition names are disjoint. In Zetalisp, each condition instance can have
multiple condition names, which means that the categories identified by
condition names can overlap and be subdivided.
For example, among the condition names defined by the system are condition,
error, sys:arithmetic-error, sys:floating-exponent-underflow and sys:divide-by-zero.
condition is a condition name that all condition instances possess. error
identifies the category of conditions that are considered errors.
sys:arithmetic-error identifies the category of errors that pertain to arithmetic
operations. sys:floating-exponent-underflow and sys:divide-by-zero are the most specific level
of categorization. So, the condition signaled when you evaluate (* 1s-30 1s-30 1s-30 1s-30)
possesses condition names sys:floating-exponent-underflow, sys:arithmetic-error, error and
condition, while the one signaled if you evaluate (// 1 0) possesses condition
names sys:divide-by-zero, sys:arithmetic-error, error and condition. In this
example, the categories fall into a strict hierarchy, but this does not need to be
the case.
Condition names are documented throughout the manual, with definitions like this:
(sys:arithmetic-error error)
The condition name sys:divide-by-zero is always accompanied by
sys:arithmetic-error and error (that is, it categorizes a subset of those categories).
The presence of error implies that all sys:divide-by-zero conditions are errors.
The condition instance also records additional information about the
event. For example, the condition instance signaled by dividing by
zero handles the :function operation by returning the function
that did the division (it might be truncate, floor,
ceiling or round, as well as //). In general, for each
condition name there are conventions saying what additional
information is provided and what operations to use to obtain it.
The flavor of the condition instance is always one of the condition names, and so
are its component flavors (with a few exceptions; si:vanilla-flavor and some
other flavor components are omitted, since they are not useful categories for
condition handlers to specify). In our example, the flavor of the condition is
sys:arithmetic-error, and its components include error and condition.
Condition names require new flavors only when they require significantly
different handling by the error system; you will understand in detail after
finishing this section.
condition-instance condition-name
Returns t if condition-instance possesses condition name condition-name.
condition-name can also be a combination of condition names using and, or
and not; then the condition tested for is a boolean combination of the
presence or absence of various condition names. Example:
(condition-typep error 'fs:file-not-found)
(condition-typep error
'(or fs:file-not-found fs:directory-not-found))
object
Returns t if object is a condition instance and its flavor incorporates error.
This is normally equivalent to (typep object 'error). Some functions such as
open optionally return the condition instance rather than signaling it, if an error
occurs. errorp is useful in testing the value returned.
Returns a list of all the condition names possesses by this condition instance.
A condition handler is a function that is associated with certain
condition names (categories of conditions). The variable
eh:condition-handlers contains a list of the handlers that are current;
handlers are established using macros which bind this variable. When a condition is
signaled, this list is scanned and all the handlers which apply are called,
one by one, until one of the handlers either throws or returns non-nil.
Since each new handler is pushed onto the front of eh:condition-handlers, the
innermost-established handler gets the first chance to handle the condition.
When the handler is run, eh:condition-handlers is bound so that the running
handler (and all the ones that were established farther in) are not in effect. This
avoids the danger of infinite recursion due to an error in a handler invoking the
same handler.
One thing a handler can do is throw to a tag. Often the catch for this
tag is right next to the place where the handler is established, but this
does not have to be so. A simple handler that applies to all errors and just
throws to a tag is established using ignore-errors.
body...
An error within the execution of body causes control to return
from the ignore-errors form. In this case, the values are
nil, t. If there is no error inside body, the first value
is that of the last form in the body and the second is nil.
Errors whose condition instances return true for the :dangerous-condition-p operation
are not handled. These include such things as running out of virtual memory.
A handler can also signal another condition. For example, signaling sys:abort
has the effect of pretending that the user typed the Abort key. The following
function creates a handler which signals sys:abort.
form
Evaluates form with a condition handler for many common error conditions such as
:wrong-type-argument, :unbound-variable and :unclaimed-message.
The handler asks the user whether to allow the debugger to be entered.
If the user says `no', the handler signals the sys:abort condition. If the user
says `yes', the handler does not handle the condition, allowing the debugger
to do so.
In some cases the handler attempts to determine whether the incorrect variable,
operation, or argument appeared in form; if it did not, the debugger is always
allowed to run. The assumption is that form was typed in by the user, and
the intention is to distinguish trivial mistakes from program bugs.
The handler can also ask to proceed from the condition. This is done by
returning a non-nil value. See the section on proceeding,
The handler can also decline to handle the condition, by returning nil.
Then the next applicable handler is called, and so on until either some
handler does handle the condition or there are no more handlers.
The handler function is called in the environment where the condition
was signaled, and in the same stack group. All special variables have the
values they had at the place where the signaling was done, and all catch
tags that were available at the point of signaling may be thrown to.
The handler receives the condition instance as its first argument. When
establishing the handler, you can also provide additional arguments to
pass to the handler when it is called. This allows the same function to
be used in varying circumstances.
The fundamental means of establishing a condition handler is the macro
condition-bind.
(handlers...) body...
(handlers...) body...
A condition-bind form looks like this:
(condition-bind ((conditions handler-form additional-arg-forms...)
(conditions handler-form additional-arg-forms...))
body...)
The purpose is to execute body with one or more condition handlers
established.
Each list of conditions and handler-form establishes one handler.
conditions is a condition name or a list of condition names to which the
handler should apply. It is not evaluated. handler-form is evaluated to
produce the function that is the actual handler. The
additional-arg-forms are evaluated, on entry to the condition-bind, to
produce additional arguments that are passed to the handler
function when it is called. The arguments to the handler function are
the condition instance being signaled, followed by the values of any
additional-arg-forms.
conditions can be nil; then the handler applies to all conditions that
are signaled. In this case it is up to the handler function to decide whether to
do anything. It is important for the handler to refrain from handling
certain conditions that are used for debugging, such as break and
eh:call-trap. The :debugging-condition-p operation on condition
instances returns non-nil for these conditions. Certain other
conditions such as sys:virtual-memory-overflow should be handled only
with great care. The :dangerous-condition-p operation returns non-nil
for these conditions. Example:
(condition-bind ((nil 'myhandler "it happened here" 45))
(catch 'x
...))
(defun myhandler (condition string value)
(unless (or (condition-typep condition 'fs:file-error)
(send condition :dangerous-condition-p)
(send condition :debugging-condition-p))
(format error-output "~&~A:~%~A~%" string condition)
(throw 'x value)))
myhandler declines to handle file errors, and all debugging conditions and
dangerous errors. For all other conditions, it prints the string specified
in the condition bind and throws to the tag x the value specified there (45).
condition-bind-default is like condition-bind but establishes a default handler
instead of an ordinary handler. Default handlers work like ordinary handlers, but
they are tried in a different order: first all the applicable ordinary handlers are
given a chance to handle the condition, and then the default handlers get their
chance. A more flexible way of doing things like this is described under
signal-condition (Condition handlers that simply throw to the function that established
them are very common, so there are special constructs provided for
defining them.
(variables...) body-form clauses...
(condition-case (variable)
body-form
(condition-names forms...)
(condition-names forms...)
...)
body-form is executed with a condition handler established that will
throw back to the condition-case if any of the specified condition names
is signaled.
Each list starting with some condition names is a clause, and specifies
what to do if one of those condition names is signaled. condition-names
is either a condition name or a list of condition names; it is not
evaluated.
Once the handler per se has done the throw, the clauses are tested in
order until one is found that applies. This is almost like a selectq,
except that the signaled condition can have several condition names, so
the first clause that matches any of them gets to run. The forms in the
clause are executed with variable bound to the condition instance that
was signaled. The values of the last form in the clause are returned
from the condition-case form.
If none of the specified conditions is signaled during the execution of
body-form (or if other handlers, established within body-form, handle
them) then the values of body-form are returned from the
condition-case form.
variable may be omitted if it is not used.
It is also possible to have a clause starting with :no-error in place of a
condition name. This clause is executed if body-form finishes normally.
Instead of just one variable there can be several variables; during the
execution of the :no-error clause, these are bound to the values returned
by body-form. The values of the last form in the clause become the
values of the condition-case form.
Here is an example:
(condition-case ()
(print foo)
(error (format t " <<Error in printing>>")))
(variables...) body-form clauses...
condition-call is an extension of condition-case that allows you to
give each clause an arbitrary conditional expression instead of just a list
of condition names. It looks like this:
(condition-call (variables...)
body-form
(test forms...)
(test forms...)
...)
The difference between this and condition-case is the test in
each clause. The clauses in a condition-call resemble the clauses of a
cond rather than those of a selectq.
When a condition is signaled, each test is executed while still within the
environment of the signaling (that is, within the actual handler function). The
condition instance can be found in the first variable. If any test returns
non-nil, then the handler throws to the condition-call and the corresponding
clause's forms are executed. If every test returns nil, the condition is not
handled by this handler.
In fact, each test is computed a second time after the throw has
occurred in order to decide which clause to execute. The code for the
test is copied in two different places, once into the handler
function to decide whether to throw, and once in a cond which follows
the catch.
The last clause can be a :no-error clause just as in condition-case.
It is executed if the body returns without error.
The values returned by the body are stored in the variables.
The values of the last form in the :no-error clause are returned by the
condition-call.
Only the first of variables is used if there is no :no-error clause.
The variables may be omitted entirely in the unlikely event that none is used.
Example:
(condition-call (instance)
(do-it)
((condition-typep instance
'(and fs:file-error (not fs:no-more-room)))
(compute-what-to-return)))
The condition name fs:no-more-room is a subcategory of
fs:file-error; therefore, this handles all file errors except for
fs:no-more-room.
Each of the four condition handler establishing constructs has a
conditional version that decides at run time whether to establish the
handlers.
cond-form (handlers...) body...
(condition-bind-if cond-form
((conditions handler-form additional-arg-forms...)
(conditions handler-form additional-arg-forms...))
body...)
begins by executing cond-form. If it returns non-nil, then all proceeds
as for a regular condition-bind. If cond-form returns nil, then the body
is still executed but without the condition handler.
cond-form (variables...) body-form clauses...
(condition-case-if cond-form (variables...)
body-form
(condition-names forms...)
(condition-names forms...)
...)
begins by executing cond-form. If it returns non-nil, then all proceeds
as for a regular condition-case. If cond-form returns nil, then the
body-form is still executed but without the condition handler.
body-form's values are returned, or, if there is a :no-error clause, it is
executed and its values returned.
cond-form ([variable]) body-form clauses...
(condition-call-if cond-form (variables...)
body-form
(test forms...)
(test forms...)
...)
begins by executing cond-form. If it returns non-nil, then everything proceeds
as for a regular condition-call. If cond-form returns nil, then the
body-form is still executed but without the condition handler.
In that case, body-form's values are returned, or, if there is a :no-error clause, it is
executed and its values returned.
cond-form (handlers...) body...
This is used just like condition-bind-if, but establishes a default handler
instead of an ordinary handler.
This is the list of established condition handlers. Each element looks
like this:
(condition-names function additional-arg-values...)
condition-names is a condition name or a list of condition names, or nil
which means all conditions.
function is the actual handler function.
additional-arg-values are additional arguments to be passed to the
function when it is called. function's first argument is always the
condition instance.
Both the links of the value of eh:condition-handlers and the elements
are usually created with with-stack-list, so copy them if you want to
save them for any period of time.
This is the list of established default condition handlers. The data
format is the same as that of eh:condition-handlers.
The flavor condition is the base flavor of all conditions, and provides default
definitions for all the operations described in this chapter.
condition incorporates si:property-list-mixin, which defines operations
:get and :plist. Each property name on the property list is also an operation
name, so that sending the :foo message is equivalent to
(send instance :get :foo). In addition, (send instance :set :foo value) is equivalent
to (send instance :set :get :foo value).
condition also provides two instance variables, eh:format-string and eh:format-args.
condition's method for the the :report operation passes these to format to print
the error message.
The flavor error makes a condition an error condition. errorp returns t for such
conditions, and the debugger is entered if they are signaled and not otherwise
handled.
This mixin provides a definition of the proceed type :no-action.
This mixin provides a definition of the proceed type :new-value.
This flavor is a mixture of error, sys:no-action-mixin and
sys:proceed-with-value-mixin. It is the flavor used by default by the functions
ferror and cerror, and is often convenient for users to instantiate.
This flavor is a mixture of sys:no-action-mixin and condition.
This mixin provides a definition of the proceed type :new-array.
Every condition instance can be asked to print an error message which describes
the circumstances that led to the signaling of the condition. The easiest way
to print one is to print the condition instance without escaping (princ, or
format operation ~A). This actually uses the :report operation, which
implements the printing of an error message. When a condition instance is
printed with escaping, it uses the #⊂ syntax so that it can be read back in.
This is done using si:print-readably-mixin,
stream
Prints on stream the condition's error message, a description of the circumstances
for which the condition instance was signaled. The output should neither start
nor end with a carriage return.
If you are defining a new flavor of condition and wish to change the way the
error message is printed, this is the operation to redefine. All others use this
one.
Returns a string containing the text that the :report operation would
print.
Operations provided specifically for condition handlers to use:
Returns t if the condition instance is one of those that indicate events
that are considered extremely dangerous, such as running out of memory.
Handlers that normally handle all conditions might want to
make an exception for these.
Returns t if the condition instance is one of those that are signaled as
part of debugging, such as break, which is signaled when you type
Meta-Break. Although these conditions normally enter the debugger,
they are not errors; this serves to prevent most condition
handlers from handling them. But any condition handler which is
written to handle all conditions should probably make a specific
exception for these.
See also the operations :proceed-types and :proceed-type-p, which have to do
with proceeding (
Some operations are intended for the debugger to use. They are documented
because some flavors of condition redefine them so as to cause the debugger to
behave differently. This section is of interest only to advanced users.
stack-group brief-flag stream
This operation is used by the debugger to print a complete error message. This
is done primarily using the :report operation.
Certain flavors of condition define a :after :print-error-message method which,
when brief-flag is nil, prints additional helpful information which is not part of
the error message per se. Often this requires access to the stack group in
addition to the data in the condition instance. The method can assume that if
brief-flag is nil then stack-group is not the one which is executing.
For example, the :print-error-message method of the condition signaled when you call
an undefined function checks for the case of calling a function such as bind
that is meaningful only in compiled code; if that is what happened, it searches
the stack to look for the name of the function in which the call appears. This is
information that is not considered crucial to the error itself, and is therefore
not recorded in the condition instance.
stream
This operation is used on entry to the debugger to discard input.
Certain condition flavors, used by stepping redefine this operation to do nothing,
so that input is not discarded.
The value returned by this operation is used to determine what address to mail
bug reports to, when the debugger Control-M command is used.
By default, it returns "LISPM". The value is passed to the function bug.
stream &optional numeric-arg
This operation is used by the Control-M command to print on stream the
information that should go in the bug report. numeric-arg is the numeric
argument, if any, that the user gave to the Control-M command.
stack-group
Returns the stack indices of the stack frames that the debugger should operate
on.
The first value is the frame ``at which the error occurred.'' This is not the
innermost stack frame; it is outside the calls to such functions as ferror and
signal-condition which were used to signal the error.
The second value is the initial value for the debugger command loop's current
frame.
The third value is the innermost frame that the debugger should be willing to let the
user see. By default this is the innermost active frame, but it is safe to use
an open but not active frame within it.
The fourth value, if non-nil, tells the debugger to consider the innermost frame
to be ``interesting''. Normally, frames that are part of the interpreter (calls to
si:eval1, si:apply-lambda, prog, cond, etc.) are considered uninteresting.
This is a flavor operation so that certain flavors of condition can redefine it.
stack-group &optional error-object
Enters the debugger command loop. The initial error message and backtrace have
already been printed. This message is sent in an error handler stack group;
stack-group is the stack group in which the condition was signaled. error-object
is the condition object which was signaled; it defaults to the one the message is
sent to.
This operation uses :or method combination (see Signaling a condition has two steps, creating a condition instance and signaling
the instance. There are convenience interface functions that combine the two
steps. You can also do them separately. If you just want to signal an error and
do not want to worry much about condition handling, the function ferror is all
you need to know.
&rest make-condition-arguments
Creates a condition instance using make-condition and then signals it
with signal-condition, specifying no local proceed types, and with t as the
use-debugger argument so the debugger is always entered if the condition is not
otherwise handled.
The first argument to ferror is always a signal name (often nil). The second
argument is usually a format string and the remaining arguments are additional
arguments for format; but this is under the control of the definition of the
signal name. Example:
(ferror 'math:singular-matrix
"The matrix ~S cannot be inverted." matrix)
For compatibility with the Symbolics system, if the first argument to ferror is a
string, then a signal name of nil is assumed. The arguments to ferror are passed
on to make-condition with an additional nil preceding them.
If you prefer, you can use the formatted output functions
(Other functions that can be used to test for invalid values include
ecase and ccase (
test-form [(places...) [string args...]]
Signals an error if test-form evaluates to nil. The rest of the assert form is
relevant only if the error happens.
First of all, the places are forms that can be stored into with setf, and which are used
(presumably) in test-form. The reason that the places are specified again
in the assert is so that the expanded code can arrange for the user to
be able to specify a new value to be stored into any one of them when
he proceeds from the error. When the error is signaled, one proceed-type
is provided for each place that is given. The condition object has flavor
eh:failed-assertion.
If the user does proceed with a new value in that fashion, the test-form is
evaluated again, and the error repeats until the test-form comes out non-nil.
The string and args are used to print the error message. If they are omitted,
"Failed assertion" is used. They are evaluated only when an error is signaled,
and are evaluated again each time an error is signaled. setf'ing the places may
also involve evaluation, which happens each time the user proceeds and sets one.
Example: (assert (neq (car a) (car b)) ((car a) (car b))
"The CARS of A and B are EQ: ~S and ~S"
(car a) (car b))
The places here are (car a) and (car b). The args happen to be the same
two forms, by not-exactly-coincidence; the current values of the places are
often useful in the error message.
The remaining signaling functions are provided for compatibility only.
&rest make-condition-arguments
error exists for compatibility with Maclisp and the Symbolics version of Zetalisp.
It takes arguments in three patterns:
(error string object [interrupt])
which is used in Maclisp, and
(error condition-instance)
(error flavor-name init-options...)
which are used by Symbolics. (In fact, the arguments to error are simply passed
along to make-condition if they do not appear to fit the Maclisp pattern).
If the Maclisp argument pattern is not used then there is no difference between
error and ferror.
format-string &rest args
The Common Lisp version of error
signals an uncorrectable error whose error message is printed by passing
format-string and args to format.
format-string &rest format-args
This function is for Symbolics compatibility only, and is equivalent to
(cerror :no-action nil nil format-string format-args...)
signal-name &rest remaining-make-condition-arguments
The signal-name and remaining-make-condition-arguments are passed to
make-condition, and the result is signaled with signal-condition.
If the remaining-make-condition-arguments are keyword arguments and
:proceed-types is one of the keywords, the associated value is used as the list of
proceed types. In particular, if signal-name is actually a condition instance, so
that the remaining arguments will be ignored by make-condition, it works to
specify the proceed types this way.
If the proceed types are not specified, a list of all the proceed types that the
condition instance knows how to prompt the user about is used by default.
form [flag]
Catches errors during the evaluation of form. If an error occurs, the usual
error message is printed unless flag is nil. Then control is thrown and the
errset-form returns nil. flag is evaluated first and is optional, defaulting to t. If
no error occurs, the value of the errset-form is a list of one element, the value
of form.
errset is an old, Maclisp construct, implemented much like condition-case.
Many uses of errset or errset-like constructs really ought to be checking for
more specific conditions instead.
form [flag]
catch-error is a variant of errset. This construct catches errors during the
evaluation of form and returns two values. If form returns normally, the first value is
form's first value and the second value is nil. If an error occurs, the usual error message
is printed unless flag is nil, and then control is thrown out of the catch-error
form, which returns two values, first nil and second a non-nil value that
indicates the occurrence of an error. flag is evaluated before form and is optional,
defaulting to t.
If this variable is non-nil, errset forms are not allowed to trap errors.
The debugger is entered just as if there were no errset. This is intended mainly
for debugging. The initial value of errset is nil.
This is for Maclisp compatibility only and should not be used.
(err) is a dumb way to cause an error. If executed inside an errset,
that errset returns nil, and no message is printed.
Otherwise an error is signaled with error message just "ERROR>>".
(err form) evaluates form and causes the containing errset
to return the result. If executed when not inside an errset, an error
is signaled with form's value printed as the error message.
(err form flag), which exists in Maclisp, is not supported.
You can create a condition instance quite satisfactorily with make-instance if
you know which instance variables to initialize. For example,
(make-instance 'ferror :condition-names '(foo)
:format-string "~S loses."
:format-args losing-object)
creates an instance of ferror just like the one that would be signaled if you do
(ferror 'foo "~S loses." losing-object)
Note that the flavor name and its components' names are added in automatically
to whatever you specify for the :condition-names keyword.
Direct use of make-instance is cumbersome, however, and it is usually handier
to define a signal name with defsignal or defsignal-explicit and then create the
instance with make-condition.
A signal name is a sort of abbreviation for all the things that are always the same
for a certain sort of condition: the flavor to use, the condition names, and what
arguments are expected. In addition, it allows you to use a positional syntax for
the arguments, which is usually more convenient than a keyword syntax in
simple use.
Here is a typical defsignal:
(defsignal series-not-convergent sys:arithmetic-error (series)
"Signaled by limit extractor when SERIES does not converge.")
This defines a signal name series-not-convergent, together with the name of the
flavor to use (sys:arithmetic-error, whose meaning is being stretched a little),
an interpretation for the arguments (series, which is explained below),
and a documentation string. The documentation string is not used in printing
the error message; it is documentation for the signal name. It becomes accessible
via (documentation 'series-not-convergent 'signal).
series-not-convergent could then be used to signal an error, or just to create a
condition instance:
(ferror 'series-not-convergent
"The series ~S went to infinity." myseries)
(make-condition 'series-not-convergent
"The series ~S went to infinity." myseries)
The list (series) in the defsignal is a list of implicit instance variable
names. They are matched against arguments to make-condition following the
format string, and each implicit instance variable name becomes an operation
defined on the condition instance to return the corresponding argument. (You
can imagine that :gettable-instance-variables is in effect for all the implicit
instance variables.) In this example, sending a :series message to the condition
instance returns the value specified via myseries when the condition was
signaled. The implicit instance variables are actually implemented using the
condition instance's property list.
Thus, defsignal spares you the need to create a new flavor merely in
order to remember a particular datum about the condition.
signal-name (flavor condition-names...) implicit-instance-variables documentation extra-init-keyword-forms
Defines signal-name to create an instance of flavor with condition names
condition-names, and implicit instance variable whose names are taken from the list
implicit-instance-variables and whose values are taken from the make-condition arguments
following the format string.
Instead of a list (flavor condition-names...) there may appear just a flavor name.
This is equivalent to using signal-name as the sole condition name.
The extra-init-keyword-forms are forms to be evaluated to produce additional
keyword arguments to pass to make-instance. These can be used to initialize
other instance variables that particular flavors may have. These expressions can
refer to the implicit-instance-variables.
documentation is a string which is recorded so that it can be accessed via
the function documentation, as in (documentation signal-name 'signal).
signal-name (flavor condition-names...) signal-arglist documentation init-keyword-forms...
Like defsignal, defsignal-explicit defines a signal name. This signal name is
used the same way, but the way it goes about creating the condition instance is
different.
First of all, there is no list of implicit instance variables. Instead, signal-arglist is
a lambda list which is matched up against all the arguments to make-condition
except for the signal-name itself. The variables bound by the lambda list can
be used in the init-keyword-forms, which are evaluated to get arguments to pass
to make-instance. For example:
(defsignal-explicit mysignal-3
(my-error-flavor mysignal-3 my-signals-category)
(format-string losing-object &rest format-args)
"The third kind of thing I like to signal."
:format-string format-string
:format-args (cons losing-object (copylist format-args))
:losing-object-name (send losing-object :name))
Since implicit instance variables are really just properties on the property list of
the instance, you can create them by using init keyword :property-list. The
contents of the property list determines what implicit instance variables exist
and their values.
signal-name &rest arguments
make-condition is the fundamental way that condition instances are created.
The signal-name says how to interpret the arguments and come up with a flavor
and values for its instance variables. The handling of the arguments is
entirely determined by the signal-name.
If signal-name is a condition instance, make-condition returns it.
It is not useful to call make-condition this way explicitly, but this allows
condition instances to be passed to the convenience functions error and signal
which call make-condition.
If the signal-name was defined with defsignal or defsignal-explicit, then that
definition specifies exactly how to interpret the arguments and create the
instance. In general, if the signal-name has an eh:make-condition-function
property (which is what defsignal defines), this property is a function to which
the signal-name and arguments are passed, and it does the work.
Alternatively, the signal-name can be the name of a flavor. Then the arguments
are passed to make-instance, which interprets them as init keywords and values.
This mode is not really recommended and exists for compatibility with
Symbolics software.
If the signal-name has no eh:make-condition-function property and is not a
flavor name, then a trivial defsignal is assumed as a default. It looks like this:
(defsignal signal-name ferror ())
So the value is an instance of ferror, with the signal-name as a condition name,
and the arguments are interpreted as a format string and args for it.
The signal-name nil actually has a definition of this form. nil is frequently used
as a signal name in the function ferror when there is no desire to use any
condition name in particular.
Once you have a condition instance, you are ready to invoke the condition
handling mechanism by signaling it. A condition instance can be signaled any number
of times, in any stack groups.
condition-instance &optional proceed-types invoke-debugger ucode-error-status inhibit-resume-handlers
Invoke the condition handling mechanism on condition-instance.
The list of proceed-types says which proceed types (among those conventionally
defined for the type of condition you have signaled) you are prepared to
implement, should a condition handler return one (see ``proceeding'').
These are in addition to any proceed types implemented nonlocally by
condition-resume forms.
ucode-error-status is used for internal purposes in signaling errors detected by
the microcode.
signal-condition tries various possible handlers for the
condition. First eh:condition-handlers is scanned for handlers
that are applicable (according to the condition names they specify) to
this condition instance. After this list is exhausted,
eh:condition-default-handlers is scanned the same way. Each
handler that is tried can terminate the act of signaling by throwing
out of signal-condition, or it can specify a way to proceed from
the signal. The handler can also return nil to decline to handle the condition;
then the next possible handler is offered a chance.
If all handlers decline to handle the condition and
invoke-debugger is non-nil, the debugger is the handler of
last resort. With the debugger, the user can ask to throw or to
proceed. The default value of invoke-debugger is non-nil if
the condition-instance is an error.
If all handlers decline to act and invoke-debugger is nil,
signal-condition proceeds using the first proceed type on the list
of available ones, provided it is a nonlocal proceed type. If it is a
local proceed type, or if there are no proceed types,
signal-condition just returns nil. (It would be slightly
simpler to proceed using the first proceed type whether it is local or
not. But in the case of a local proceed type, this would just mean
returning the proceed type instead of nil. It is considered
slightly more useful to return nil, allowing the signaler to
distinguish the case of a condition not handled. The signaler knows
which proceed types it specified, and can if it wishes consider nil as
equivalent to the first of them.)
Otherwise, by this stage, a proceed type has been chosen from the available list.
If the proceed type was among those specified by the caller of signal-condition,
then proceeding consists simply of returning to that caller. The chosen proceed
type is the first value, and arguments (returned by the handler along with the
proceed type) may follow it. If the proceed type was implemented nonlocally
with condition-resume (see
If inhibit-resume-handlers is non-nil, resume handlers are not invoked. If a
handler returns a nonlocal proceed type, signal-condition just returns to its caller
as if the proceed type were local. If the condition is not handled,
signal-condition returns nil.
The purpose of condition-bind-default is so that you can define a
handler that is allowed to handle a signal only if none of the callers' handlers handle it.
A more flexible technique for doing this sort of thing is to make an ordinary
handler signal the same condition instance recursively by calling
signal-condition, like this:
(multiple-value-list
(signal-condition condition-instance
eh:condition-proceed-types nil nil t))
This passes along the same list of proceed types specified by the original
signaler, prevents the debugger from being called, and prevents resume handlers
from being run. If the first value signal-condition returns is non-nil, one of
the outer handlers has handled the condition; your handler's simplest option is to
return those same values so that the other handler has its way (but it could
also examine them and return modified values). Otherwise, you go on to handle
the condition in your default manner.
This variable may be set to a list of condition names to be
traced. Whenever a condition possessing a traced condition name
is signaled, an error is signaled to report the fact. (Tracing of
conditions is turned off while this error is signaled and handled).
Proceeding with proceed type :no-action causes the signaling of
the original condition to continue.
If eh:trace-conditions is t, all conditions are traced.
Both condition handlers and the user (through the debugger) have the
option of proceeding certain conditions.
Each condition name can define, as a convention, certain proceed types, which are
keywords that signify a certain conceptual way to proceed. For example,
condition name sys:wrong-type-argument defines the proceed type
:argument-value which means, ``Here is a new value to use as the argument.''
Each signaler may or may not implement all the proceed types which are
meaningful in general for the condition names being signaled. For example, it is
futile to proceed from a sys:wrong-type-argument error with :argument-value
unless the signaler knows how to take the associated value and store it into the
argument, or do something else that fits the conceptual specifications of
:argument-value. For some signalers, it may not make sense to do this at all.
Therefore, one of the arguments to signal-condition is a list of the proceed
types that this particular signaler knows how to handle.
In addition to the proceed types specified by the individual signaler, other
proceed types can be provided nonlocally; they are implemented by a resume
handler which is in effect through a dynamic scope. See below,
A condition handler can use the operations :proceed-types and :proceed-type-p
on the condition instance to find out which proceed types are available. It can
request to proceed by returning one of the available proceed types as a value.
This value is returned from signal-condition, and the condition's signaler can
take action as appropriate.
If the handler returns more than one value, the remaining values are
considered arguments of the proceed type. The meaning of the
arguments to a proceed type, and what sort of arguments are expected,
are part of the conventions associated with the condition name that
gives the proceed type its meaning. For example, the :argument-value
proceed type for sys:wrong-type-argument errors conventionally takes
one argument, which is the new value to use. All the values returned by
the handler are returned by signal-condition to the signaler.
Here is an example of a condition handler that proceeds from
sys:wrong-type-argument errors. It makes any atom effectively equivalent to
nil when used in car or any other function that expects a list. The handler uses
the :description operation, which on sys:wrong-type-argument condition
instances returns a keyword describing the data type that was desired.
(condition-bind
((sys:wrong-type-argument
#'(lambda (condition)
(if (eq (send condition :description) 'cons)
(values :argument-value nil)))))
body...)
Here the argument to the :argument-value proceed type is nil.
Returns a list of the proceed types available for this condition instance.
This operation should be used only within the signaling of the condition
instance, as it refers to the special variable in which signal-condition
stores its second argument.
proceed-type
t if proceed-type is one of the proceed types available for this condition instance.
This operation should be used only within the signaling of the condition
instance, as it refers to the special variable in which signal-condition
stores its second argument.
If the condition invokes the debugger, then the user has the
opportunity to proceed. When the
debugger is entered, the available proceed types are assigned
command characters starting with Super-A. Each character becomes a
command to proceed using the corresponding proceed type.
Three additional facilities are required to make it convenient for the
user to proceed using the debugger. Each is provided by methods
defined on condition flavors. When you define a new condition flavor,
you must provide methods to implement these facilities.
| Documentation: | It must be possible to tell the user what each proceed type is for.
|
| Prompting for arguments: | The user must be asked for the arguments for the proceed type.
Each proceed type may have different arguments to ask for.
|
| Not always the same proceed types: | Usually the user can choose among the same set of proceed types that a
handler can, but sometimes it is useful to provide the user with a
few extra ones, or to suppress some of them for him.
|
These three facilities are provided by methods defined on condition
flavors. Each proceed type that is provided by signalers should be
accompanied by suitable methods. This means that you must normally
define a new flavor if you wish to use a new proceed type.
The :document-proceed-type operation is supposed to print
documentation of what a proceed type is for. For example, when sent to
a condition instance describing an unbound variable error, if the
proceed type specified is :new-value, the text printed is something
like ``Proceed, reading a value to use instead.''
proceed-type stream
Prints on stream a description of the purpose of proceed type proceed-type. This
operation uses :case method combination (see The :proceed-asking-user operation is supposed to ask for suitable
arguments to pass with the proceed type. Sending :proceed-asking-user
to an instance of sys:unbound-variable with argument :new-value would
read and evaluate one expression, prompting appropriately.
proceed-type continuation read-object-fn
The method for :proceed-asking-user embodies the knowledge of how to
prompt for and read the additional arguments that go with proceed-type.
:case method combination is used (see Here is how sys:proceed-with-value-mixin provides for the proceed type
:new-value. Note the documentation string, which is automatically
use by :document-proceed-type since no :case method for that operation
is provided.
(defmethod (proceed-with-value-mixin
:case :proceed-asking-user :new-value)
(continuation read-object-function)
"Return a value; the value of an expression you type."
(funcall continuation :new-value
(funcall read-object-function
:eval-read
"~&Form whose value to use instead: ")))
The :user-proceed-types operation is given the list of proceed types
actually available and is supposed to return the list of proceed types to
offer to the user. By default, this operation returns its argument: all
proceed types are available to the user through the debugger.
For example, the condition name sys:unbound-variable conventionally
defines the proceed types :new-value and :no-action. The first
specifies a new value; the second attempts to use the variable's current
value and gets another error if the variable is still unbound. These are
clean operations for handlers to use. But it is more convenient for the
user to be offered only one choice, which will use the variable's new
value if it is bound now, but otherwise ask for a new value. This is
implemented with a :user-proceed-types method that replaces the two
proceed types with a single one.
Or, you might wish to offer the user two different proceed types
that differ only in how they ask the user for additional information.
For handlers, there would be only one proceed type.
Finally, there may be proceed types intended only for the debugger
which do not actually proceed; these should be inserted into the list
by the :user-proceed-types method.
proceed-types
Assuming that proceed-types is the list of proceed types available for
condition handlers to return, this operation returns the list of
proceed types that the debugger should offer to the user.
Only the proceed types offered to the user need to be handled
by :document-proceed-type and :proceed-asking-user.
The flavor condition itself defines this to return its argument.
Other condition flavors may redefine this to filter the argument
in some appropriate fashion.
:pass-on method combination is used (see Here is an example of nontrivial use of :user-proceed-types:
(defflavor my-error () (error))
(defmethod (my-error :user-proceed-types) (proceed-types)
(if (memq :foo proceed-types)
(cons :foo-two-args proceed-types)
proceed-types))
(defmethod (my-error :case :proceed-asking-user :foo)
(cont read-object-fn)
"Proceeds, reading a value to foo with."
(funcall cont :foo
(funcall read-object-fn :eval-read
"Value to foo with: ")))
(defmethod (my-error :case :proceed-asking-user :foo-two-args)
(cont read-object-fn)
"Proceeds, reading two values to foo with."
(funcall cont :foo
(funcall read-object-fn :eval-read
"Value to foo with: ")
(funcall read-object-fn :eval-read
"Value to foo some more with: ")))
In this example, if the signaler provides the proceed type :foo, then it is
described for the user as ``proceeds, reading a value to foo with''; and if
the user specifies that proceed type, he is asked for a single value,
which is used as the argument when proceeding. In addition, the
user is offered the proceed type :foo-two-args, which has its own
documentation and which reads two values. But for condition handlers
there is really only one proceed type, :foo. :foo-two-args is just an
alternate interface for the user to proceed type :foo, and this is why the
:user-proceed-types method offers :foo-two-args only if the signaler
is willing to accept :foo.
Each condition name defines a conceptual meaning for certain
proceed types, but this does not mean that all of those proceed types
may be used every time the condition is signaled. The signaler must
specifically implement the proceed types in order to make them do what
they are conventionally supposed to do. For some signalers it may be
difficult to do, or may not even make sense. For example, it is no use
having a proceed type :store-new-value if the signaler does not have a
suitable place to store, permanently, the argument the handler supplies.
Therefore, we require each signaler to specify just which proceed types
it implements. Unless the signaler explicitly specifies proceed types
one way or another, no proceed types are allowed (except for nonlocal ones,
described in the following section).
One way to specify the proceed types allowed is to call signal-condition and
pass the list of proceed types as the second argument.
Another way that is less general but more convenient is
signal-proceed-case.
((variables...) make-condition-arguments...) clauses...
Signals a condition, providing proceed types and code to implement them. Each
clause specifies a proceed type to provide, and also contains code to be run if a
handler should proceed with that proceed type.
(signal-proceed-case ((argument-vars...)
signal-name signal-name-arguments...)
(proceed-type forms...)
(proceed-type forms...)
...)
A condition-object is created with make-condition using the
signal-name and signal-name-arguments; then it is signaled giving a list
of the proceed types from all the clauses as the list of proceed types
allowed.
The variables argument-vars are bound to the values
returned by signal-condition, except for the first value, which is tested
against the proceed-type from each clause, using a selectq. The clause that
matches is executed.
Example: (defsignal my-wrong-type-arg
(eh:wrong-type-argument-error sys:wrong-type-argument)
(old-value arg-name description)
"Wrong type argument from my own code.")
(signal-proceed-case
((newarg)
'my-wrong-type-arg
"The argument ~A was ~S, which is not a cons."
'foo foo 'cons)
(:argument-value (car newarg)))
The signal name my-wrong-type-arg creates errors with condition name
sys:wrong-type-argument. The signal-proceed-case shown signals such an
error, and handles the proceed type :argument-value. If a handler proceeds
using that proceed type, the handler's value is put in newarg, and then its car is
returned from the signal-proceed-case.
When the caller of signal-condition specifies proceed types, these are called
local proceed types. They are implemented at the point of signaling. There are
also nonlocal proceed types, which are in effect for all conditions (with appropriate
condition names) signaled during the execution of the body of the establishing
macro. We say that the macro establishes a resume handler for the proceed type.
The most general construct for establishing a resume handler is condition-resume.
For example, in
(condition-resume
'(fs:file-error :retry-open t
("Proceeds, opening the file again.")
(lambda (ignore) (throw 'tag nil)))
(do-forever
(catch 'tag (return (open pathname)))))
the proceed type :retry-open is available for all fs:file-error conditions signaled
within the call to open.
handler-form &body body
cond-form handler-form &body body
Both execute body with a resume handler in effect for a nonlocal proceed type according to
the value of handler-form. For condition-resume-if, the resume handler is in
effect only if cond-form's value is non-nil.
The value of the handler-form should be a list with at least five elements: (condition-names proceed-type predicate format-string-and-args
handler-function additional-args...)
condition-names is a condition name or a list of them. The resume handler
applies to these conditions only.
proceed-type is the proceed type implemented by this resume handler.
predicate is either t or a function that is applied to a condition instance and
determines whether the resume handler is in effect for that condition instance.
format-string-and-args is a list of a string and additional arguments that can be
passed to format to print a description of what this proceed type is for.
These are needed only for anonymous proceed types.
handler-function is the function called to do the work of proceeding, once this
proceed type has been returned by a condition handler or the debugger.
catch-error-restart-explicit-if makes it easy to establish a particular
simple kind of resume handler.
cond-form (condition-names proceed-type format-string format-args...) body...
Executes body with (if cond-form produces a non-nil value) a resume handler for
proceed type proceed-type and condition(s) condition-names. condition-names
should be a symbol or a list of symbols; it is not evaluated. proceed-type should be
a symbol.
If proceeding is done using this resume handler, control returns from the
catch-error-restart-explicit-if form. The first value is nil and the second is
non-nil.
format-string and the format-args, all of which are evaluated, are used by the
:document-proceed-type operation to describe the proceed type, if it is
anonymous.
For condition handlers there is no distinction between local and nonlocal
proceed types. They are both included in the list of available proceed types
returned by the :proceed-types operation (all the local proceed types come
first), and the condition handler selects one by returning the proceed type and
any conventionally associated arguments. The debugger's :user-proceed-types,
:document-proceed-type and :proceed-asking-user operations are also make
no distinction.
The difference comes after the handler or the debugger returns
to signal-condition. If the proceed type is a local one (one of those in the
second argument to signal-condition), signal-condition simply returns.
If the proceed type is not among those the caller handles, signal-condition looks for
a resume handler
associated with the proceed type, and calls its handler function. The arguments to the handler
function are the condition instance, the additional-args specified in the resume
handler, and any arguments returned by the condition handler in addition to
the proceed type. The handler function is supposed to do a throw. If it returns
to signal-condition, an error is signaled.
You are allowed to use ``anonymous'' nonlocal proceed types, which have no
conventional meaning and are not specially known to the
:document-proceed-type and :proceed-asking-user operations. The anonymous
proceed type may be any Lisp object. The default definition of
:proceed-asking-user handles an anonymous proceed type by simply calling the
continuation passed to it, reading no arguments. The default definition of
:document-proceed-type handles anonymous proceed types by passing format
the format-string-and-args list found in the resume handler (this is what that list
is for).
Anonymous proceed types are often lists. Such proceed types are usually made by some variant
of error-restart, and they are treated a little bit specially. For one
thing, they are all put at the end of the list returned by the :proceed-types
operation. For another, the debugger command Control-C or Resume never uses
a proceed type which is a list. If no atomic proceed type is available, Resume or
Control-C is not allowed.
(condition-names format-string format-args...) body...
cond-form (condition-names format-string format-args...) body...
All execute body with an anonymous resume handler for condition-names.
The proceed type for this resume handler is a list, so the Resume key will not use it.
condition-names is either a single condition name or a list of them, or nil
meaning all conditions; it is not evaluated.
format-string and the format-args, all of which are evaluated, are used by the
:document-proceed-type operation to describe the anonymous proceed type.
If the resume handler made by error-restart is invoked by proceeding from a
signal, the automatically generated resume handler function does a throw back to
the error-restart and the body is executed again from the beginning. If body
returns, the values of the last form in it are returned from the error-restart
form.
error-restart-loop is like error-restart except that it loops to the beginning of
body even if body completes normally. It is like enclosing an error-restart in an
iteration.
catch-error-restart is like error-restart except that it never loops back to the
beginning. If the anonymous proceed type is used for proceeding, the
catch-error-restart form returns with nil as the first value and a non-nil second
value.
catch-error-restart-if is like catch-error-restart except that the resume
handler is only in effect if the value of the cond-form is non-nil.
All of these variants of error-restart can be written in terms of
condition-resume-if.
These forms are typically used by any sort of command loop, so that aborting
within the command loop returns to it and reads another command.
error-restart-loop is often right for simple command loops. catch-error-restart
is useful when aborting should terminate execution rather than retry, or with an
explicit conditional to test whether a throw was done.
error-restart forms often specify (error sys:abort) as the condition-names.
The presence of error causes them to be listed (and assigned command
characters) by the debugger, for all errors, and the presence of sys:abort causes
the Abort key to use them. If you would like a procede type to be offered as an option
by the debugger, but do not want the Abort key to use it, specify just error.
condition-instance proceed-type &rest args
Invokes the innermost applicable resume handler for proceed-type.
Applicability of a resume handler is determined by matching its condition names
against those possessed by condition-instance and by applying its predicate, if not
t, to condition-instance.
If proceed-type is nil, the innermost applicable resume handler is invoked
regardless of its proceed type. However, in this case, the scan stops if t is
encountered as an element of eh:condition-resume-handlers.
The current list of resume handlers for nonlocal proceed types.
condition-resume works by binding this variable. Elements are usually lists
that have the format described above under condition-resume. The symbol t
is also meaningful as an element of this list. It terminates the scan for a resume
handler when it is made by signal-condition for a condition that was not
handled. t is pushed onto the list by break loops and the debugger to shield the
evaluation of your type-in from automatic invocation of resume handlers
established outside the break loop or the error.
The links of this list, and its elements, are often created using with-stack-list.
so be careful if you try to save the value outside the context in which you
examine it.
(condition)
This condition is signaled by the Abort key; it is how that key is implemented.
Most command loops use some version of error-restart to set up a resume
handler for sys:abort so that it will return to the innermost command loop if (as
is usually the case) no handler handles it. These resume handlers usually apply
to error as well as sys:abort, so that the debugger will offer a specific command
to return to the command loop even if it is not the innermost one.