Author:         David Cuthbert <dacut@kanga.org>
Author:         Kevin Kenny <kennykb@acm.org>
State:          Final
Type:           Project
Vote:           Done
Created:        23-Mar-2001
Post-History:   
Discussions-To: news:comp.lang.tcl
Keywords:       trace,Tcl_Obj
Tcl-Version:    8.4a4

Abstract

This document proposes to add Tcl_Obj support for trace procedures written in C.

Rationale

The Tcl_Obj system was introduced in version 8.0, making computations (potentially) much more efficient by eliminating many type conversions to and from strings. However, the trace API continues to require character strings in both command and variable traces.

In addition, the Tcl_CreateTrace function interacts rather badly with the bytecode compiler, since it forbids inlining of functions. Since many trace applications ignore the built-in functions that would have been inlined, this restriction is not needed by many applications. This TIP proposes to make it optional in the revised API.

The trace mechanism in the Tcl library has been underused for some time, partly because it is awkward. While the profiler, tracer and debugger from TclX and the debugger from Expect have seen some limited success, they are certainly not familiar to the majority of Tcl users.

The second author of this TIP has experimented with using the trace mechanism to build a profiler for Tcl that does not depend on source code instrumentation. His experience was that:

It is very difficult to write useful trace procedures without resorting to tclInt.h -- in particular, the fact that only the command name and not the Tcl_Command token is passed meant that Tcl_FindCommand is needed to do virtually anything useful.
The profiler often perturbs the run-time behavior of the program, often violently. The reason is twofold. First, the string representation of all of a traced command's arguments must be constructed, even though the trace procedure has no need for them. Second, the presence of the trace procedure defeats the bytecode compiler. Since the user of a profiler is unlikely to care about each individual built-in command (the common usage is to profile the time spent in procedures), turning off inline compilation of commands is neither needed nor wanted.
The profiler traces returns from commands by subsituting the command procedure with one that is internal to the profiler itself, and restoring the command procedure upon exit. Doing so requires many needless lookups of the command name, because only the name is presented to the trace procedure, and the name is the only way to access Tcl_GetCommandInfo and Tcl_SetCommandInfo. This overhead can be avoided only by including tclInt.h and casting the Tcl_Command object to a Command object -- in other words, by accessing the interpreter's internal data structures from the extension.

This TIP is an effort to rationalize the trace interface to avoid these difficulties.

Specification

The following functions shall be added to the Tcl core:

Tcl_CreateObjTrace
```
 Tcl_Trace Tcl_CreateObjTrace ( Tcl_Interp*          interp,
                                int                  level, 
                                int                  flags,
                                Tcl_CmdObjTraceProc* objProc,
                                ClientData           clientData );
```
The Tcl_CreateObjTrace function adds a trace to the Tcl evaluator. The interp argument is the Tcl interpreter for which tracing is being requested. The level argument is the maximum depth of recursive calls; when the execution depth of the interpreter exceeds this number, the trace callback does not execute. The objProc argument is the callback procedure to execute each time a Tcl command is evaluated; it is expected to have arguments and result type that match Tcl_CmdObjTraceProc below. The clientData argument is client data to pass to the objProc callback. Finally, the flags argument gives flags that control the tracing. Initially, the only flag supported will be TCL_ALLOW_INLINE_COMPILE. If this flag is set, the bytecode compiler is permitted to compile in-line code for the Tcl built-in commands; any command that has been compiled in-line will not be traced.

The Tcl_CreateObjTrace function returns a trace token -- an object of opaque type that may be passed to Tcl_DeleteTrace to delete the trace.

The Tcl_CmdObjTraceProc will have the following type signature.
```
    typedef int Tcl_CmdObjTraceProc( ClientData     clientData,
                                     Tcl_Interp*    interp,
                                     int            level,
                                     CONST char*    command,
                                     Tcl_Command    commandInfo,
                                     int            objc,
                                     Tcl_Obj *CONST objv[] );
```
The clientData parameter is the client data that was passed to Tcl_CreateObjTrace. The interp parameter designates a Tcl interpreter. The level parameter specifies the execution level. The command parameter gives the raw UTF-8 text of the command being evaluated, before any substitutions have been performed. The commandInfo parameter is an opaque Tcl_Command object that gives information about the command. The objc and objv parameters are the command name and parameter vector after substitution.

The trace procedure is expected to return a standard Tcl status return. If it returns TCL_OK, the command is evaluated normally. If it returns TCL_ERROR, evaluation of the command does not take place. The interpreter result is expected to contain an error message. If it returns any other status, such as TCL_BREAK, TCL_CONTINUE or TCL_RETURN, it is treated as if the command had done so.
Tcl_GetCommandInfoFromToken and Tcl_SetCommandInfoFromToken
```
 int
 Tcl_GetCommandInfoFromToken( Tcl_Command  token,
                          Tcl_CmdInfo* infoPtr );

 int
 Tcl_SetCommandInfoFromToken( Tcl_Command        token,
                          CONST Tcl_CmdInfo* infoPtr );
```
The Tcl_GetCommandInfoFromToken and Tcl_SetCommandInfoFromToken functions are precisely parallel to today's Tcl_GetCommandInfo and Tcl_SetCommandInfo procedures, except that they accept an opaque Tcl_Command object instead of a command name. They are provided so that trace procedures (and other extensions that have such an object) can adjust command information without having to go through two extra lookups in the command hash by applying Tcl_GetCommandInfo to the result of Tcl_GetCommandName.

Change History

10 February 2002 - Moved to Final Status with slight revisions in the names and arguments of Tcl_GetCommandInfoFromToken and Tcl_SetCommandInfoFromToken.

3 November 2001 - Reworked the entire TIP. Changed the object trace handling to work with Tcl_Command objects instead of command names. Removed the object-based variable trace procedures. Since Tcl variable names really are character strings and not Tcl objects, object-based variable trace procedures would be slower than the string-based ones.

30 March 2001 - Changed return value of objProc to a Tcl_Obj * instead of int (and using the interpreter result to indicate an error). This is more consistent with the current behavior (but without the bug). -dac

TIP 32: Add Tcl<em>Obj-enabled counterpart to Tcl</em>CreateTrace

Abstract

Rationale

Specification

Change History

Copyright