# TIP 79: Add Deletion Callback to Tcl_CreateObjTrace
Author: Kevin Kenny <[email protected]>
State: Final
Type: Project
Vote: Done
Created: 03-Jan-2002
Post-History:
Discussions-To: news:comp.lang.tcl
Keywords: trace,Tcl_Obj
Tcl-Version: 8.4
-----
# Abstract
This document is a correction to the _Tcl\_CreateObjTrace_ API from
[[32]](32.md). It addresses a deficiency that the API provides no deletion
callback for its client data.
# Rationale
In developing a reference implementation for the changes described in
[[32]](32.md), 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.
# Specification
The _Tcl\_CreateObjTrace_ function proposed in [[32]](32.md) shall be changed
to the following:
Tcl_Trace Tcl_CreateObjTrace ( Tcl_Interp* interp,
int level,
int flags,
Tcl_CmdObjTraceProc* objProc,
ClientData clientData,
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,
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.
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
Copyright © 2002 by Kevin B. Kenny. Distribution in whole or part,
with or without annotations, is unlimited.