TIP #32 Version 1.2: Add Tcl_Obj support to traces

This is not necessarily the current version of this TIP.

TIP:	32
Title:	Add Tcl_Obj support to traces
Version:	$Revision: 1.2 $
Author:	David Cuthbert <dacut at kanga dot org>
State:	Draft
Type:	Project
Tcl-Version:	8.4a2
Vote:	Pending
Created:	Friday, 23 March 2001
Discussions To:	news:comp.lang.tcl
Keywords:	trace, Tcl_Obj

Abstract

This document proposes to add Tcl_Obj support for trace procedures written in C.

Rationale

The Tcl_Obj system was introduced in version 8.0, making computations (potentially) much more efficient by eliminating many type conversions to and from strings. However, the trace API continues to require character strings in both command and variable traces.

Specification

Add the following functions to the Tcl core:

Tcl_Trace Tcl_CreateObjTrace(interp, level, objProc, clientData)

Tcl_CreateObjTrace behaves in the same manner as Tcl_CreateTrace, except the trace procedure (objProc) should have arguments and result that match type type Tcl_CmdObjTraceProc:
```
typedef void Tcl_CmdObjTraceProc(
    ClientData clientData,
    Tcl_Interp *interp,
    int level,
    char *command,
    Tcl_ObjCmdProc *cmdProc,
    ClientData cmdClientData,
    int objc,
    Tcl_Obj * CONST objv[] );
```
Trace tokens returned by Tcl_CreateObjTrace can be used in Tcl_DeleteTrace to remove the trace.
int Tcl_ObjTraceVar2(interp, part1Ptr, part2Ptr, flags, objProc, clientData)

Tcl_ObjTraceVar2 behaves in the same manner as Tcl_TraceVar2, except the variable name is passed as Tcl_Obj pointers (in the same manner as Tcl_ObjSetVar2, q.v.), and the trace procedure (objProc) should have arguments and result that match the type Tcl_VarObjTraceProc:
```
typedef Tcl_Obj *Tcl_VarObjTraceProc(
    ClientData clientData,
    Tcl_Interp *interp,
    Tcl_Obj *part1Ptr,
    Tcl_Obj *part2Ptr,
    int flags );
```
Under normal conditions, the trace procedure should return NULL, indicating successful completion. If objProc returns a value other than NULL it signifies that an error occurred. Upon return, the reference count of the Tcl_Obj should be at least one; ownership of this reference is transferred to the Tcl interpreter.
void Tcl_ObjUntraceVar2(interp, part1Ptr, part2Ptr, flags, objProc, clientData)

Tcl_ObjUntraceVar2 behaves in the same manner as Tcl_UntraceVar2, except it is used to remove trace procedures registered with Tcl_ObjTraceVar2.
ClientData Tcl_ObjVarTraceInfo2(interp, part1Ptr, part2Ptr, flags, objProc, prevClientData)

Tcl_ObjVarTraceInfo2 behaves in the same manner as Tcl_VarTraceInfo2, except it is used to iterate through trace procedures registered with Tcl_ObjTraceVar2.

Change History

30 March 2001 - Changed return value of objProc to a Tcl_Obj * instead of int (and using the interpreter result to indicate an error). This is more consistent with the current behavior (but without the bug). -dac

Copyright