184 lines
9.8 KiB
HTML
184 lines
9.8 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3O//DTD W3 HTML 2.0//EN">
|
|
<!Converted with LaTeX2HTML 0.6.5 (Tue Nov 15 1994) by Nikos Drakos (nikos@cbl.leeds.ac.uk), CBLU, University of Leeds >
|
|
<HEAD>
|
|
<TITLE>29.4.1. Signaling Conditions</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
<meta name="description" value=" Signaling Conditions">
|
|
<meta name="keywords" value="clm">
|
|
<meta name="resource-type" value="document">
|
|
<meta name="distribution" value="global">
|
|
<P>
|
|
<b>Common Lisp the Language, 2nd Edition</b>
|
|
<BR> <HR><A NAME=tex2html5884 HREF="node336.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html5882 HREF="node334.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html5876 HREF="node334.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html5886 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html5887 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
|
<B> Next:</B> <A NAME=tex2html5885 HREF="node336.html"> Assertions</A>
|
|
<B>Up:</B> <A NAME=tex2html5883 HREF="node334.html"> Program Interface to </A>
|
|
<B> Previous:</B> <A NAME=tex2html5877 HREF="node334.html"> Program Interface to </A>
|
|
<HR> <P>
|
|
<H2><A NAME=SECTION003341000000000000000>29.4.1. Signaling Conditions</A></H2>
|
|
<P>
|
|
<img align=bottom alt="change_begin" src="gif/change_begin.gif"><br>
|
|
<A NAME=SIGNALLINGCONDITIONS>The</A>
|
|
functions in this section provide various mechanisms
|
|
for signaling warnings, breaks, continuable errors, and fatal errors.
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>error <i>datum</i> &rest <i>arguments</i></tt><P>
|
|
[This supersedes the description of <tt>error</tt>
|
|
given in section <A HREF="node220.html#ERRORSIGNALLINGFUNCTIONS">24.1</A>.-GLS]
|
|
<P>
|
|
Invokes the signal facility on a condition. If the condition is not handled,
|
|
<tt>(invoke-debugger <i>condition</i>)</tt> is executed. As a consequence of calling
|
|
<tt>invoke-debugger</tt>, <tt>error</tt> never directly returns to its caller; the only exit from this
|
|
function can come by non-local transfer of control in a handler or by use of
|
|
an interactive debugging command.
|
|
<P>
|
|
If <i>datum</i> is a condition, then that condition is used directly.
|
|
In this case, it is an error for the list of <i>arguments</i> to be non-empty;
|
|
that is, <tt>error</tt> must have been called with exactly one argument, the condition.
|
|
<P>
|
|
If <i>datum</i> is a condition type (a class or class name), then the condition used is effectively the result
|
|
of <tt>(apply #'make-condition <i>datum</i> <i>arguments</i>)</tt>.
|
|
<P>
|
|
If <i>datum</i> is a string, then the condition used is effectively the result of
|
|
<P><pre>
|
|
(make-condition 'simple-error
|
|
:format-string <i>datum</i>
|
|
:format-arguments <i>arguments</i>)
|
|
</pre><P>
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>cerror <i>continue-format-string</i> <i>datum</i> &rest <em>arguments</em></tt><P> [This supersedes the description of <tt>cerror</tt>
|
|
given in section <A HREF="node220.html#ERRORSIGNALLINGFUNCTIONS">24.1</A>.-GLS]
|
|
<P>
|
|
The function <tt>cerror</tt>
|
|
invokes the error facility on a condition. If the condition is not handled,
|
|
<tt>(invoke-debugger <i>condition</i>)</tt> is executed. While signaling is going on,
|
|
and
|
|
while control is in the debugger (if it is reached), it is possible to continue
|
|
program execution (thereby returning from the call to <tt>cerror</tt>)
|
|
using the <tt>continue</tt> restart.
|
|
<P>
|
|
If <i>datum</i> is a condition, then that condition is used directly.
|
|
In this case, the list of <i>arguments</i> need not be empty,
|
|
but will be used only with the <i>continue-format-string</i>
|
|
and will not be used to initialize <i>datum</i>.
|
|
<P>
|
|
If <i>datum</i> is a condition type (a class or class name), then the condition used is effectively the result
|
|
of <tt>(apply #'make-condition <i>datum</i> <i>arguments</i>)</tt>.
|
|
<P>
|
|
If <i>datum</i> is a string, then the condition used is effectively the result of
|
|
<P><pre>
|
|
(make-condition 'simple-error
|
|
:format-string <i>datum</i>
|
|
:format-arguments <i>arguments</i>)
|
|
</pre><P>
|
|
<P>
|
|
The <i>continue-format-string</i> must be a string.
|
|
Note that if <i>datum</i> is not a
|
|
string, then the format arguments used by the <i>continue-format-string</i> will
|
|
still be the list of <i>arguments</i> (which is in keyword format if <i>datum</i> is a condition
|
|
type). In this case, some care may be necessary to set up the
|
|
<i>continue-format-string</i> correctly. The <tt>format</tt> directive <tt>~*</tt>,
|
|
which ignores and skips over <tt>format</tt> arguments,
|
|
may be particularly
|
|
useful in this situation.
|
|
<P>
|
|
The value returned by <tt>cerror</tt> is <tt>nil</tt>.
|
|
<P>
|
|
<BR><b>[Function]</b><BR>
|
|
<tt>signal <i>datum</i> &rest <em>arguments</em></tt><P> Invokes the signal facility on a condition. If the condition is not handled,
|
|
<tt>signal</tt> returns <tt>nil</tt>.
|
|
<P>
|
|
If <i>datum</i> is a condition, then that condition is used directly.
|
|
In this case, it is an error for the list of <i>arguments</i> to be non-empty;
|
|
that is, <tt>error</tt> must have been called with exactly one argument, the condition.
|
|
<P>
|
|
If <i>datum</i> is a condition type (a class or class name), then the condition used is effectively the result
|
|
of <tt>(apply #'make-condition <i>datum</i> <i>arguments</i>)</tt>.
|
|
<P>
|
|
If <i>datum</i> is a string, then the condition used is effectively the result of
|
|
<P><pre>
|
|
(make-condition 'simple-error
|
|
:format-string <i>datum</i>
|
|
:format-arguments <i>arguments</i>)
|
|
</pre><P>
|
|
<P>
|
|
Note that if <tt>(typep <i>condition</i> *break-on-signals*)</tt> is true, then the debugger
|
|
will be entered prior to beginning the process of signaling. The <tt>continue</tt>
|
|
restart function may be used to continue with the signaling process;
|
|
the restart is associated with the signaled condition as if by
|
|
use of <tt>with-condition-restarts</tt>.
|
|
This is true
|
|
also for all other functions and macros that signal conditions, such
|
|
as <tt>warn</tt>, <tt>error</tt>, <tt>cerror</tt>, <tt>assert</tt>, and <tt>check-type</tt>.
|
|
<P>
|
|
During the dynamic extent of a call to <tt>signal</tt> with a
|
|
particular condition, the effect of calling <tt>signal</tt> again on that
|
|
condition object for a distinct abstract event is not defined.
|
|
For example, although a handler <i>may</i> resignal a condition in order to
|
|
allow outer handlers first shot at handling the condition, two
|
|
distinct asynchronous keyboard events must not signal an the same (<tt>eq</tt>) condition
|
|
object at the same time.
|
|
<P>
|
|
For further details about signaling and handling, see the discussion of
|
|
condition handlers in section <A HREF="node332.html#CONDITIONHANDLERS">29.3.17</A>.
|
|
<P>
|
|
<BR><b>[Variable]</b><BR>
|
|
<tt>*break-on-signals*</tt><P> This variable is intended primarily for use when the user is debugging
|
|
programs that do signaling.
|
|
The value of <tt>*break-on-signals*</tt> should be suitable as a second argument to
|
|
<tt>typep</tt>, that is, a type or type specifier.
|
|
<P>
|
|
When <tt>(typep <i>condition</i> *break-on-signals*)</tt> is true, then calls to
|
|
<tt>signal</tt> (and to other advertised functions such as <tt>error</tt> that
|
|
implicitly call <tt>signal</tt>) will enter the debugger prior to signaling
|
|
that <i>condition</i>. The <tt>continue</tt> restart may be used to continue with
|
|
the normal signaling process;
|
|
the restart is associated with the signaled condition as if by
|
|
use of <tt>with-condition-restarts</tt>.
|
|
<P>
|
|
Note that <tt>nil</tt> is a valid type specifier. If the value of
|
|
<tt>*break-on-signals*</tt> is <tt>nil</tt>, then <tt>signal</tt> will never
|
|
enter the debugger in this implicit manner.
|
|
<P>
|
|
When setting this variable, the user is encouraged to choose the
|
|
most restrictive specification that suffices. Setting this flag
|
|
effectively violates the modular handling of condition signaling
|
|
that this chapter seeks to establish. Its complete effect may be
|
|
unpredictable in some cases, since the user may not be aware of the
|
|
variety or number of calls to <tt>signal</tt> that are used in programs
|
|
called only incidentally.
|
|
<P>
|
|
By default-and certainly in any ``production'' use-the value
|
|
of this variable should be <tt>nil</tt>, both for reasons of performance and
|
|
for reasons of modularity and abstraction.
|
|
<P>
|
|
X3J13 voted in March 1989
|
|
(BREAK-ON-WARNINGS-OBSOLETE) <A NAME=36771> </A>
|
|
to remove <tt>*break-on-warnings*</tt> from the language;
|
|
<tt>*break-on-signals*</tt> offers all the power of
|
|
<tt>*break-on-warnings*</tt> and more.
|
|
<P>
|
|
<hr>
|
|
<b>Compatibility note:</b> This variable is similar to the Zetalisp
|
|
variable <tt>trace-conditions</tt> except for the obvious difference that
|
|
<tt>zl:trace-conditions</tt> takes a type or list of types while
|
|
<tt>*break-on-signals*</tt> takes a single type specifier.
|
|
<P>
|
|
[There is no loss of generality in Common Lisp
|
|
because the <tt>or</tt> type specifier may be used to indicate that
|
|
any of a set of conditions should enter the debugger.-GLS]
|
|
<hr>
|
|
<br><img align=bottom alt="change_end" src="gif/change_end.gif">
|
|
<P>
|
|
<BR> <HR><A NAME=tex2html5884 HREF="node336.html"><IMG ALIGN=BOTTOM ALT="next" SRC="icons/next_motif.gif"></A> <A NAME=tex2html5882 HREF="node334.html"><IMG ALIGN=BOTTOM ALT="up" SRC="icons/up_motif.gif"></A> <A NAME=tex2html5876 HREF="node334.html"><IMG ALIGN=BOTTOM ALT="previous" SRC="icons/previous_motif.gif"></A> <A NAME=tex2html5886 HREF="node1.html"><IMG ALIGN=BOTTOM ALT="contents" SRC="icons/contents_motif.gif"></A> <A NAME=tex2html5887 HREF="index.html"><IMG ALIGN=BOTTOM ALT="index" SRC="icons/index_motif.gif"></A> <BR>
|
|
<B> Next:</B> <A NAME=tex2html5885 HREF="node336.html"> Assertions</A>
|
|
<B>Up:</B> <A NAME=tex2html5883 HREF="node334.html"> Program Interface to </A>
|
|
<B> Previous:</B> <A NAME=tex2html5877 HREF="node334.html"> Program Interface to </A>
|
|
<HR> <P>
|
|
<HR>
|
|
<P><ADDRESS>
|
|
AI.Repository@cs.cmu.edu
|
|
</ADDRESS>
|
|
</BODY>
|