# TIP 79: Add Deletion Callback to Tcl_CreateObjTrace
	Author:         Kevin Kenny <kennykb@acm.org>
	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.

