Issue: TRACE-FUNCTION-ONLY

[Masinter.pa@Xerox.COM]

I took the liberty of renaming this issue since the "problem" is broader
than CLOS, but this is otherwise as submitted.

     ----- Begin Forwarded Messages -----

Return-Path: <kempf%hplabsz@hplabs.HP.COM>
Received: from hplabs.HP.COM ([15.255.16.7]) by Xerox.COM ; 21 OCT 87
10:00:05 PDT
Received: from hplms2 by hplabs.HP.COM with SMTP ; Wed, 21 Oct 87
09:59:19 PDT
Received: from hplabsz.hpl.hp.com by hplms2; Wed, 21 Oct 87 09:58:43 pdt
Return-Path: <kempf@hplabsz>
Received: from hplabsz by hplabsz; Wed, 21 Oct 87 10:58:12 pdt
To: Masinter.pa
Cc: Common-Lisp-Object-System@sail.stanford.edu
Subject: TRACE Proposal
X-Mailer: mh6.5
Date: Wed, 21 Oct 87 09:58:09 PDT
Message-Id: <24566.561833889@hplabsz>
 From: kempf%hplabsz@hplabs.HP.COM


Larry:

	Here is a copy of the proposed modifications to TRACE, which
were discussed at the September CLOS committee meeting. I have not
included the TRACE-EXECUTION proposal, since it is a generic function,
similar to PRINT-OBJECT, and its disposition was not clear at the
meeting.

	I hope this gets to you in time for the November meeting. If
not, apologies: OOPSLA and recovery took longer than expected.

		Jim Kempf


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


Issue:         TRACE-CLOS

References:    trace macro pp. 440-441

Category:      MODIFICATION

Edit history:  Version 1, 21-Oct-87 Kempf

Problem description:

With the addition of the Common Lisp Object System, there is no
command language level way to trace individual method execution.
The TRACE macro, as currently specified in Common Lisp, allows
only tracing of globally defined functions through their names.
Since a generic function name may have several executable methods,
users need some way to specify that they would like invocation of
particular
methods to be traced, rather than invocation of the entire generic
function.

In addition, the current specification of TRACE does not allow tracing
of functions associated with SETF "methods", of macro functions, 
nor of lexically defined functions or functions invoked via. their
function definition objects.  While this proposal does not attempt 
to address the latter problems, since identification and/or tracing of
these
is likely to be implementation dependent, it does leave 
open the option for those implementations which can arrange it. Finally,
some implementations of Common Lisp have extended TRACE to take an
option 
which puts the system into a break loop after the trace information has
been
printed. This proposal adds that capability to the standard.

Proposal (TRACE-CLOS::TRACE-FUNCTION-SPECIFICATION)

(Font Note: UPPERCASE indicates bold, _this_ indicates italic)

TRACE _function-spec_ &KEY (:BREAK NIL) _[Macro]_

TRACE

UNTRACE _function-spec_	_[Macro]_

UNTRACE

Invoking TRACE with a function specification causes the function
specified
to be traced. Henceforth, whenever the 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*. If the keyword argument :BREAK is T, then the BREAK
function will be called after the trace information is printed. 
UNTRACE undoes any tracing. Calling TRACE without any arguments
prints a list of currently traced executable entities, calling
UNTRACE without any arguments causes tracing to be undone for
all currently traced entities.

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 to which the application of MACRO-FUNCTION will return
a function definition object) or a list whose first element indicates
what kind of funcallable object is to be traced and whose tail indicates
which particular function should be traced. The complete set of
function specifications will necessarily be implementation dependent;
however,
every implementation is required to support the following:

	_symbol_-Invocations of the function or macrofunction named by
	         _symbol_ via. _symbol_ as a global name are traced.

	(METHOD _generic-function-name-specification_
                _{method-qualifiers}_* 
	        _parameter-specializer-name-list_
        )
	If the method whose parameter specializer list, generic function
	name specification, and method qualifiers are listed is tracable,
	then invocations through the generic function name specification 
	will be traced.

	(SETF _symbol_)-If the SETF function having the name specification
	is tracable, it will be traced (see proposal SETF-CLOS for
	more information on SETF name specifications).

Implementations are encouraged to provide for tracing of as many
funcallable objects as possible.

Rationale:

Adoption of the Common Lisp Object System will require the availability
of debugging information on individual methods. 

Current practice:

Some Common Lisp implementations have extended TRACE syntax to
allow specification of breaks. Currently, the TRACE macro is
specified to take any number of symbols.

Adoption Cost:

The syntax of the TRACE macro will take only one function specification
in order to accomodate the :BREAK key. But, since TRACE tends to
be used interactively at the command langauge level, the impact
on existing code should be slight.

Cost of non-adoption:

Without this, implementation dependent ways of specifying the
:BREAK option would continue to be used. In addition, most
implementors would probably add their own syntax for allowing
programmers to obtain information on individual method invocation.

Benefits:

Allow programmers to obtain information on individual method
invocations.

Conversion Cost:

Minor re-write of the TRACE and UNTRACE macros.



     ----- End Forwarded Messages -----