Function Tracing (CMUCL User’s Manual)

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.

Local functions defined by flet and labels can be traced using the syntax (flet f f1 f2 ...) or (labels f f1 f2 ...) where f is the flet or labels function we want to trace and f1, f2, are the functions containing the local function f. Invidiual methods can also be traced using the syntax (method name qualifiers specializers). See sec-method-tracing for more information.

If no names or options are are given, trace returns the list of all currently traced functions, See *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". Individual methods can also be traced. See sec-method-tracing.

:wherein-only names

If specified, this is just like :wherein, but trace produces output only if the immediate caller of the traced function is one of the functions listed in names.

: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 CMUCL, 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.

Note that if you trace using :encapsulate, you will only get a trace or breakpoint at the outermost call to the traced function, not on recursive calls.

In the case of functions where the known return convention is used to optimize, encapsulation may be necessary in order to make tracing work at all. The symptom of this occurring is an error stating

    Error in function foo: :FUNCTION-END breakpoints are
    currently unsupported for the known return convention.

in such cases we recommend using (trace foo :encapsulate t)

: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 See *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.

Variable: debug:*trace-encapsulate-package-names* ¶: A list of package names. Functions from these packages are traced using encapsulation instead of function-end breakpoints. This list should at least include those packages containing functions used directly or indirectly in the implementation of trace.