wiki:Trace

Version 2 (modified by gz, 6 years ago) (diff)

Extensions

CCL's tracing facility is invoked by an extended version of the Common Lisp trace macro. Extensions allow tracing of methods, as well as finer control over tracing actions.

TRACE {keyword global-value}* {spec | (spec {keyword local-value}*)}* [Macro]

The trace macro encapsulates the functions named by specs, causing trace actions to take place on entry and exit from each function. The default actions print a message on function entry and exit, keyword/value options can be used to specify changes in the default behavior.

Invoking (trace) without arguments returns a list of functions being traced.

A spec is either a symbol that is the name of a function, or an expression of the form (setf symbol), or a specific method of a generic function in the form (:method gf-name {qualifier}* ( {specializer}* )), where a specializer can be the name of a class or an EQL specializer.

A spec can also be a string naming a package, or equivalently a list (:package package-name), in order to request that all traceable functions in the package to be traced.

By default, whenever a traced function is entered or exited, a short message is printed on *trace-output* showing the arguments on entry and values on exit. Options specified as key/value pairs can be used to modify this behavior. Options preceding the function specs apply to all the functions being traced. Options specified along with a spec apply to that spec only. The following options are supported:

:before action
specifies the action to be taken just before the traced function is entered. action is one of:

  • :print - The default, prints a short indented message showing the function name and the invocation arguments
  • :break - Equivalent to :before :print :break-before t
  • :backtrace - Equivalent to :before :print :backtrace-before t
  • function - Any other value is interpreted as a function to call on entry instead of printing the standard entry message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the arguments to the function being traced, and ccl:*trace-level* bound to the current nesting level of trace actions.
:after action
specifies the action to be taken just after the traced function exits. action is one of:
  • :print - The default, prints a short indented message showing the function name and the returned values
  • :break - Equivalent to :after :print :break-after t
  • :backtrace - Equivalent to :after :print :backtrace-after t
  • function - Any other value is interpreted as a function to call on exit instead of printing the standard exit message. It is called with its first argument being the name of the function being traced, the remaining arguments being all the values returned by the function being traced, and ccl:*trace-level* bound to the current nesting level of trace actions.
:backtrace {T | nil}
If true, requests that a stack backtrace (in brief format) be printed whenever the function is invoked. The value can be an integer, in which case it is the maximum number of frames to print. Otherwise, all frames are shown.
:methods {T | nil}
If true, and if applied to a spec naming a generic function, arranges to trace all the methods of the generic function in addition to the generic function itself.
:if form
:condition form
Evaluates form whenever the function being traced is about to be entered, and inhibits all trace actions if form returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. :condition is just a synonym for :if, though if both are specified, both must return non-nil.
:before-if form
Evaluates form whenever the function being traced is about to be entered, and inhibits the entry trace actions if form returns nil. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. If both :if and :before-if are specified, both must return non-nil in order for the before entry actions to happen.
:after-if form
Evaluates form whenever the function being traced has just exited, and inhibits the exit trace actions if form returns nil. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. If both :if and :after-if are specified, both must return non-nil in order for the after exit actions to happen.
:print-before form
Evaluates form whenever the function being traced is about to be entered, and prints the result before printing the standard entry message. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. To see multiple forms, use values: :print-before (values (one-thing) (another-thing)).
:print-after form
Evaluates form whenever the function being traced has just exited, and prints the result after printing the standard exit message. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. To see multiple forms, use values: :print-after (values (one-thing) (another-thing)).
:print form
Equivalent to :print-before form :print-after form.
:eval-before form
Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.
:eval-after form
Evaluates form whenever the function being has just exited. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.
:eval form
Equivalent to :eval-before form :eval-after form.
:break-before form
Evaluates form whenever the function being traced is about to be entered, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call.
:break-after form
Evaluates form whenever the function being traced has just exited, and if the result is non-nil, enters a debugger break loop. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call.
:break form
Equivalent to :break-before form :break-after form.
:backtrace-before form
:backtrace form
Evaluates form whenever the function being traced is about to be entered. The form may reference the lexical variable ccl::args, which is a list of the arguments in this call. The value returned by form is intepreted as follows:
  • nil - do nothing.
  • :detailed - prints a detailed backtrace to *trace-output*.
  • (:detailed integer) - prints the top integer frames of detailed backtrace to *trace-output*.
  • integer - prints top integer frames of a terse backtrace to *trace-output*.
  • anything else - prints a terse backtrace to *trace-output*.
Note that unlike with the other options, :backtrace is equivalent to :backtrace-before only, not both before and after, since it's usually not helpful to print the same backtrace both before and after the function call.
:backtrace-after form
Evaluates form whenever the function being traced has just exited. The form may reference the lexical variable ccl::vals, which is a list of values returned by this call. The value returned by form is intepreted as follows:
  • nil - do nothing.
  • :detailed - prints a detailed backtrace to *trace-output*.
  • (:detailed integer) - prints the top integer frames of detailed backtrace to *trace-output*.
  • integer - prints top integer frames of terse backtrace to *trace-output*.
  • anything else - prints a terse backtrace to *trace-output*.

CCL:*TRACE-LEVEL* [Variable]

Variable bound to the current nesting level of tracing while before and after trace actions are executed.

TRACE-FUNCTION spec &key {keyword value}* [Function]

This is a functional version of the TRACE macro. spec and keywords are as for TRACE, except that all arguments are evaluated.