wiki:Trace

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

--

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 {spec | (spec {option-key value}*)}*    [Macro]

The trace macro encapsulates the function named by spec, causing trace actions to take place on entry and exit from the function. The default actions print a message on function entry and exit.

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.

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. The following option-keys can be used to modify this behavior:

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

  • :print - The default, prints a short indented message showing the function name and the invocation arguments
  • :break - Enters the debugger after printing the standard function entry message
  • 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
specifies the action to be taken just after the traced function exits. The value is one of:
  • :print - The default, prints a short indented message showing the function name and the returned values
  • :break - Enters the debugger after printing the standard function exit message
  • 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
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.