Next: Encapsulation Functions
Up: The Debugger
Previous: Breakpoint Example
  Contents
  Index
Function Tracing
tracing
tracing
The tracer causes selected functions to print their arguments and
their results whenever they are called. Options allow conditional
printing of the trace information and conditional breakpoints on
function entry or exit.
[Macro]
trace

option global-value 
name 
option
value
trace is a debugging tool that prints information when
specified functions are called. In its simplest form:
(trace name-1 name-2 ...)
trace causes a printout on **trace-output each time
that one of the named functions is entered or returns (the
names are not evaluated.) Trace output is indented according
to the number of pending traced calls, and this trace depth is
printed at the beginning of each line of output. Printing verbosity
of arguments and return values is controlled by
**debug-print-level and **debug-print-length.
If no names or options are are given, trace
returns the list of all currently traced functions,
*traced-function-list*.
Trace options can cause the normal printout to be suppressed, or
cause extra information to be printed. Each option is a pair of an
option keyword and a value form. Options may be interspersed with
function names. Options only affect tracing of the function whose
name they appear immediately after. Global options are specified
before the first name, and affect all functions traced by a given
use of trace. If an already traced function is traced again,
any new options replace the old options. The following options are
defined:
- :condition form, :condition-after form,
:condition-all form
- If :condition is specified,
then trace does nothing unless form evaluates to true
at the time of the call. :condition-after is similar, but
suppresses the initial printout, and is tested when the function
returns. :condition-all tries both before and after.
- :wherein names
- If specified, names is a
function name or list of names. trace does nothing unless
a call to one of those functions encloses the call to this
function (i.e. it would appear in a backtrace.) Anonymous
functions have string names like "DEFUN FOO".
- :break form, :break-after form,
:break-all form
- If specified, and form evaluates
to true, then the debugger is invoked at the start of the
function, at the end of the function, or both, according to the
respective option.
- :print form, :print-after form,
:print-all form
- In addition to the usual printout, the
result of evaluating form is printed at the start of the
function, at the end of the function, or both, according to the
respective option. Multiple print options cause multiple values
to be printed.
- :function function-form
- This is a not really an
option, but rather another way of specifying what function to
trace. The function-form is evaluated immediately, and the
resulting function is traced.
- :encapsulate

:default | t | nil
- In CMU Common Lisp,
tracing can be done either by temporarily redefining the function
name (encapsulation), or using breakpoints. When breakpoints are
used, the function object itself is destructively modified to
cause the tracing action. The advantage of using breakpoints is
that tracing works even when the function is anonymously called
via funcall.
When :encapsulate is true, tracing is done via encapsulation.
:default is the default, and means to use encapsulation for
interpreted functions and funcallable instances, breakpoints
otherwise. When encapsulation is used, forms are not
evaluated in the function's lexical environment, but
debug:arg can still be used.
:condition, :break and :print forms are evaluated in
the lexical environment of the called function; debug:var and
debug:arg can be used. The -after and -all
forms are evaluated in the null environment.
[Macro]
untrace
&rest function-names
This macro turns off tracing for the specified functions, and
removes their names from *traced-function-list*. If no
function-names are given, then all currently traced functions
are untraced.
[Variable]
*extensions:*
traced-function-list
A list of function names maintained and used by trace,
untrace, and untrace-all. This list should contain
the names of all functions currently being traced.
[Variable]
*extensions:*
max-trace-indentation
The maximum number of spaces which should be used to indent trace
printout. This variable is initially set to 40.
Subsections
Next: Encapsulation Functions
Up: The Debugger
Previous: Breakpoint Example
  Contents
  Index
Peter Van Eynde
2000-02-08