3.10 Function 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.

 
• 3.10.1 Encapsulation Functions