Kevin Kenny$Revision: 1.7 $trace Tcl_Obj

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: IFRjbF9UcmFjZSBUY2xfQ3JlYXRlT2JqVHJhY2UgKCBUY2xfSW50ZXJwKiAgICAgICAgICAgICAgICBpbnRlcnAsICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBpbnQgICAgICAgICAgICAgICAgICAgICAgICBsZXZlbCwgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBpbnQgICAgICAgICAgICAgICAgICAgICAgICBmbGFncyw=ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBUY2xfQ21kT2JqVHJhY2VQcm9jKiAgICAgICBvYmpQcm9jLA==ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBDbGllbnREYXRhICAgICAgICAgICAgICAgICBjbGllbnREYXRhLA==ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICBUY2xfQ21kT2JqVHJhY2VEZWxldGVQcm9jKiBkZWxldGVQcm9jICk7 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. ICAgIHR5cGVkZWYgaW50IFRjbF9DbWRPYmpUcmFjZVByb2MoIENsaWVudERhdGEgICAgIGNsaWVudERhdGEsICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFRjbF9JbnRlcnAqICAgIGludGVycCw=ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGludCAgICAgICAgICAgIGxldmVsLA==ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIENPTlNUIGNoYXIqICAgIGNvbW1hbmQsICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFRjbF9Db21tYW5kICAgIGNvbW1hbmRJbmZvLA==ICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIGludCAgICAgICAgICAgIG9iamMsICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgICAgIFRjbF9PYmogKkNPTlNUIG9ianZbXSApOw== 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. ICAgIHR5cGVkZWYgdm9pZCBUY2xfQ21kT2JqVHJhY2VEZWxldGVQcm9jKCBDbGllbnREYXRhIGNsaWVudERhdGEgKTs= 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.