Function

Summary

Invokes the trace facilities when an instance of a class is accessed.

Package

clos

Signature

trace-on-access instance &key read write slot-names break when process trace-output entrycond eval-before before backtrace => t

Arguments

instance

A CLOS instance.

read

A generalized boolean.

write

A generalized boolean.

slot-names

A list of symbols, or t.

break

A generalized boolean.

when

A form.

process

A form.

trace-output

A form.

entrycond

A form.

eval-before

A list of forms.

before

A list of forms.

backtrace

A keyword, t or nil.

Values

Returns t.

Description

A useful debugging function which causes access to instance to invoke the trace facilities. Accesses include calls to slot-value and accessor functions defined by the class of instance.

The keyword arguments control which type of access are traced, and provide preconditions for tracing, code to run before access, and how to print any trace output. They are similar to those supported by the trace macro (but note that these CLOS symbols are functions, so the keyword values are evaluated immediately, unlike in trace).

read controls whether reading slots is traced. The default is t.

write controls whether writing slots is traced. The default is t.

slot-names controls which slots to trace access for. It can be a list of symbols which are the slot-names. The default value, t, means trace access to all slots.

break controls whether the debugger is entered when a traced slot in instance is accessed. When nil, the debugger is not invoked and messages are printed to *trace-output*. The default value is nil.

when is evaluated during slot access to determine whether any tracing should occur. The default value is t.

process is evaluated during slot access to determine whether any tracing should occur in the current process. The form should evaluate to either nil (meaning trace in all processes), a string naming the process in which tracing should occur (see process-name, find-process-from-name), or a list of strings naming the processes in which tracing should occur. The default value is nil.

trace-output is evaluated during slot access to determine the stream on which to print tracing messages. If this is nil then the value of *trace-output* is used. The default value is nil.

entrycond is evaluated during slot access to determine whether the default tracing messages should be printed.

eval-before is a list of forms which are evaluated during slot access.

before is a list of forms which are evaluated during slot access. The first value returned by each form is printed.

backtrace controls what kind of backtrace to print. If this is nil then no backtrace is printed, and this is the default value. Otherwise it can be any of the following values:

:quick

Like the :bq debugger command.

t

Like the :b debugger command.

:verbose

Like the :b :verbose debugger command.

:bug-form

Like the :bug-form debugger command.

Other instances of the same class are unaffected and you can remove the trace by calling untrace-on-access.

The variable *traced-arglist* is bound to a list of arguments for the slot access during evaluation of the options above, that is (instance slot-name) when reading a slot and (new-value instance slot-name) when writing a slot.

A common use of this function is to find where a slot is being changed in a complex program.

This function, when called with :break t, replaces the deprecated function break-on-access.

See also

untrace-on-access
trace-new-instances-on-access
break-on-access