Author: Kevin Kenny <[email protected]>
This document is a correction to the Tcl_CreateObjTrace API from . It addresses a deficiency that the API provides no deletion callback for its client data.
In developing a reference implementation for the changes described in , the author of this TIP discovered an anomaly in the proposed API for Tcl_CreateObjTrace. While the function accepts a ClientData parameter, it provides no deletion callback for the client data, making it difficult to clean up the client data if Tcl_DeleteTrace is called from a point in the code where the client data is not readily available. (The usual pattern in the Tcl library is to provide a deletion callback wherever client data is passed to the Tcl interpreter; Tcl_CreateObjCommand is an example.
The Tcl_CreateObjTrace function proposed in  shall be changed to the following:
Tcl_Trace Tcl_CreateObjTrace ( Tcl_Interp* interp,
Tcl_CmdObjTraceDeleteProc* deleteProc );
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. The deleteProc argument specifies a function to call when the trace is removed by a call to Tcl_DeleteTrace. This parameter may be a null pointer if no deletion callback is desired. 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 trace token returned from Tcl_CreateObjTrace may be passed as a parameter to Tcl_DeleteTrace, which arranges to cancel the tracing. If a non-empty deleteProc argument was supplied to Tcl_CreateObjTrace, it is called at this time. After Tcl_DeleteTrace returns, no further calls to the trace procedure will be made, and the trace token must not be used further in the calling program.
The Tcl_CmdObjTraceProc will have the following type signature.
typedef int Tcl_CmdObjTraceProc( ClientData clientData,
CONST char* command,
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.
The Tcl_CmdObjTraceDeleteProc will have the following type signature.
typedef void Tcl_CmdObjTraceDeleteProc( ClientData clientData );
The clientData parameter is the client data that was originally passed into Tcl_CreateObjTrace.
Copyright © 2002 by Kevin B. Kenny. Distribution in whole or part, with or without annotations, is unlimited.