NAME¶
Tcl_CreateTrace, Tcl_CreateObjTrace, Tcl_DeleteTrace - arrange for command
execution to be traced
SYNOPSIS¶
#include <tcl.h>
Tcl_Trace
Tcl_CreateTrace(interp, level, proc, clientData)
Tcl_Trace
Tcl_CreateObjTrace(interp, level, flags, objProc, clientData, deleteProc)
Tcl_DeleteTrace(interp, trace)
ARGUMENTS¶
- Tcl_Interp *interp (in)
- Interpreter containing command to be traced or untraced.
- int level (in)
- Only commands at or below this nesting level will be traced unless 0 is
specified. 1 means top-level commands only, 2 means top-level commands or
those that are invoked as immediate consequences of executing top-level
commands (procedure bodies, bracketed commands, etc.) and so on. A value
of 0 means that commands at any level are traced.
- int flags (in)
- Flags governing the trace execution. See below for details.
- Tcl_CmdObjTraceProc *objProc (in)
- Procedure to call for each command that is executed. See below for details
of the calling sequence.
- Tcl_CmdTraceProc *proc (in)
- Procedure to call for each command that is executed. See below for details
on the calling sequence.
- ClientData clientData (in)
- Arbitrary one-word value to pass to objProc or proc.
- Tcl_CmdObjTraceDeleteProc *deleteProc (in)
- Procedure to call when the trace is deleted. See below for details of the
calling sequence. A NULL pointer is permissible and results in no callback
when the trace is deleted.
- Tcl_Trace trace (in)
- Token for trace to be removed (return value from previous call to
Tcl_CreateTrace).
DESCRIPTION¶
Tcl_CreateObjTrace arranges for command tracing. After it is called,
objProc will be invoked before the Tcl interpreter calls any command
procedure when evaluating commands in
interp. The return value from
Tcl_CreateObjTrace is a token for the trace, which may be passed to
Tcl_DeleteTrace to remove the trace. There may be many traces in effect
simultaneously for the same interpreter.
objProc should have arguments and result that match the type,
Tcl_CmdObjTraceProc:
typedef int Tcl_CmdObjTraceProc(
ClientData clientData,
Tcl_Interp* interp,
int level,
const char * command,
Tcl_Command commandToken,
int objc,
Tcl_Obj *const objv[] );
The
clientData and
interp parameters are copies of the
corresponding arguments given to
Tcl_CreateTrace.
ClientData
typically points to an application-specific data structure that describes what
to do when
objProc is invoked. The
level parameter gives the
nesting level of the command (1 for top-level commands passed to
Tcl_Eval by the application, 2 for the next-level commands passed to
Tcl_Eval as part of parsing or interpreting level-1 commands, and so
on). The
command parameter points to a string containing the text of
the command, before any argument substitution. The
commandToken
parameter is a Tcl command token that identifies the command to be invoked.
The token may be passed to
Tcl_GetCommandName,
Tcl_GetCommandInfoFromToken, or
Tcl_SetCommandInfoFromToken to
manipulate the definition of the command. The
objc and
objv
parameters designate the final parameter count and parameter vector that will
be passed to the command, and have had all substitutions performed.
The
objProc callback is expected to return a standard Tcl status return
code. If this code is
TCL_OK (the normal case), then the Tcl
interpreter will invoke the command. Any other return code is treated as if
the command returned that status, and the command is
not invoked.
The
objProc callback must not modify
objv in any way. It is,
however, permissible to change the command by calling
Tcl_SetCommandTokenInfo prior to returning. Any such change takes
effect immediately, and the command is invoked with the new information.
Tracing will only occur for commands at nesting level less than or equal to the
level parameter (i.e. the
level parameter to
objProc will
always be less than or equal to the
level parameter to
Tcl_CreateTrace).
Tracing has a significant effect on runtime performance because it causes the
bytecode compiler to refrain from generating in-line code for Tcl commands
such as
if and
while in order that they may be traced. If traces
for the built-in commands are not required, the
flags parameter may be
set to the constant value
TCL_ALLOW_INLINE_COMPILATION. In this case,
traces on built-in commands may or may not result in trace callbacks,
depending on the state of the interpreter, but run-time performance will be
improved significantly. (This functionality is desirable, for example, when
using
Tcl_CreateObjTrace to implement an execution time profiler.)
Calls to
objProc will be made by the Tcl parser immediately before it
calls the command procedure for the command (
cmdProc). This occurs
after argument parsing and substitution, so tracing for substituted commands
occurs before tracing of the commands containing the substitutions. If there
is a syntax error in a command, or if there is no command procedure associated
with a command name, then no tracing will occur for that command. If a string
passed to Tcl_Eval contains multiple commands (bracketed, or on different
lines) then multiple calls to
objProc will occur, one for each command.
Tcl_DeleteTrace removes a trace, so that no future calls will be made to
the procedure associated with the trace. After
Tcl_DeleteTrace returns,
the caller should never again use the
trace token.
When
Tcl_DeleteTrace is called, the interpreter invokes the
deleteProc that was passed as a parameter to
Tcl_CreateObjTrace.
The
deleteProc must match the type,
Tcl_CmdObjTraceDeleteProc:
typedef void Tcl_CmdObjTraceDeleteProc(
ClientData clientData);
The
clientData parameter will be the same as the
clientData
parameter that was originally passed to
Tcl_CreateObjTrace.
Tcl_CreateTrace is an alternative interface for command tracing,
not
recommended for new applications. It is provided for backward
compatibility with code that was developed for older versions of the Tcl
interpreter. It is similar to
Tcl_CreateObjTrace, except that its
proc parameter should have arguments and result that match the type
Tcl_CmdTraceProc:
typedef void Tcl_CmdTraceProc(
ClientData clientData,
Tcl_Interp * interp,
int level,
char * command,
Tcl_CmdProc * cmdProc,
ClientData cmdClientData,
int argc,
const char * argv[]);
The parameters to the
proc callback are similar to those of the
objProc callback above. The
commandToken is replaced with
cmdProc, a pointer to the (string-based) command procedure that will be
invoked; and
cmdClientData, the client data that will be passed to the
procedure. The
objc parameter is replaced with an
argv
parameter, that gives the arguments to the command as character strings.
Proc must not modify the
command or
argv strings.
If a trace created with
Tcl_CreateTrace is in effect, inline compilation
of Tcl commands such as
if and
while is always disabled. There
is no notification when a trace created with
Tcl_CreateTrace is
deleted. There is no way to be notified when the trace created by
Tcl_CreateTrace is deleted. There is no way for the
proc
associated with a call to
Tcl_CreateTrace to abort execution of
command.
KEYWORDS¶
command, create, delete, interpreter, trace