TRACE Proposal (Version 1)

[kempf%hplabsz@hplabs.HP.COM]

As promised, here is an initial draft of a proposal for modifying the
TRACE macro (CLtL, pp. 440-441) to better support object-oriented
programming. The proposal is motivated by the expressed need of our
applications programmers. Sometimes, they would like to only trace
when a particular method is run, rather than tracing every method
when the generic function is invoked. Additionally, some constructs
in Common Lisp which are usually implemented as functions (macroexpansions,
SETF's) are currently not tracable through the TRACE function, but rather
require extra effort. There is obviously lots of room for implementation
dependency here, and some things which would be nice to do portably
(like tracing local function invocations) are difficult because Common
Lisp doesn't have the right constructs (like no first class environments).

The proposal is a combination of Moon's function spec idea, at the
programmer interface level, and Danny's generic function idea, at the
system level. I think most Common Lisp implementors probably include
some help for tracing methods already, if they implement an object-oriented
language.

---------------------------------------------------------------------------------

TRACE &REST {function-spec}*  		[Macro]

Invoking TRACE with one or more function specifications causes the
functions specified to be traced. Henceforth whenever a specified
function is invoked, information about the call, the arguments passed,
and the returned values, if any, will be printed to the stream that is
the value of *TRACE-OUTPUT*.

A function-spec is either a symbol naming a function (i.e. a symbol
whose global function cell is bound to a function definition object)
or a list whose first element is a function specification type, and 
whose tail indicates which particular function of that type should 
be traced. The complete set of function specification types will 
necessarily be implementation specific, but all implementations 
are required to provide the following:

<symbol>-Invocation of the function named by <symbol> via. <symbol>'s
global function cell are traced.

(:SETF <place> )-If the generalized variable reference indicated by
<place> is tracable, then invocations of the function implementing
the SETF operation will be traced.

(:METHOD <generic-function-name> <parameter-specializer-name-list>)-
If the method whose parameter specializer list and generic function
are indicated in the specification is tracable, then invocations 
through the generic function name will be traced.

(:MACRO-FUNCTION <symbol>)-If <symbol> has a global function definition
that is a macro definition, then invocations of the macro function through
<symbol> will be traced.

>>>>others? Some which I can think of that might be useful are:

(:LOCAL <symbol> <environment>)-Invocations of the function named
<symbol> when the current environment is <environment> are traced.

Problems: Environments are second-class in Common Lisp. Something similar
would be:

(:LOCAL <global-function-symbol> <local-function-symbol>)-Same, except
would get at the environment via. a global function name. This won't take
care of FLETS inside FLETS, nor of FLETS at the top level, however.

This could also be potentially handled via. the macro's environment
parameter.

(:FUNDEF <function definition object>)-Invocations of the function
definition object are traced, regardless of whether they are through
a global or local name symbol.

Problems: Wrapping the function to trace invocation may require modifying the
function definition object, which may not be possible in all
implementations of Common Lisp.

Slot initialization functions, and lambdas are other items which need
consideration.

Note: Another useful enhancement would be to support a :BREAK flag, like
this:

	(:METHOD <spec>  :BREAK)

indicating that a break loop should be entered before and after the
function executes. Most implementations support this, but it is not
in CLtL. This may be an issue for the cleanup committee, however.

<<<<<<<<<<

TRACE-EXECUTION object &OPTIONAL env		[Generic Function]

TRACE-EXECUTION discriminates on object to select an implementation
specific method that arranges for the executable entity associated
with object to be traced. The optional env environment parameter is for 
those implementations which require environmental information to
arrange for tracing to occur. Implementations are required to provide
TRACE-EXECUTION as the system level entry point for implementing trace
functionality.

The exact nature and number of methods associated with TRACE-EXECUTION
will differ, depending on what function specifications are supported
by TRACE, but every implementation needs to support the following:

SYMBOL-The function indicated by the symbol will be traced when invoked
in the environment. If the function is a macro, then tracing will occur
when the macro function is invoked. If the function definition is bound to
the symbol's global function definition cell, then invocations of
the function via. its global name will be traced. If the function is a 
local function, then only invocations when the environment parameter is 
the current environment will be traced, provided the implementation can
arrange for it.

METHOD-The method function is traced when invoked.

GENERIC-FUNCTION-The generic function is traced when the discriminator
code is invoked.

FUNCALLABLE-STANDARD-CLASS-???? need more information about what
this is.

>>>>>>>>>others? Some which I can think of are:

FUNCTION-Invocation of the function is traced, regardless
of whether invocation is through a named symbol. This will obviously
depend on whether modifications in fundefs are allowed to support
tracing.