INTERFACE
tcl.lang.VarTrace -- Interface for montoring the access on Tcl variables.
METHODS
abstract void traceProc(Interp interp, String name1, String name2, int flags)
ARGUMENTS
DESCRIPTION
ACCESSING VARIABLES DURING TRACES
ERROR RETURNS
TCL.TRACE_DESTROYED FLAG
TCL.INTERP_DESTROYED FLAG
EQUIVALENT C FUNCTIONS
SEE ALSO
KEYWORDS

INTERFACE

tcl.lang.VarTrace -- Interface for montoring the access on Tcl variables.

METHODS

abstract void traceProc(Interp interp, String name1, String name2, int flags)

ARGUMENTS

Interp interp ()
The interpreter accessing the variable.

String name1 ()
If the trace occurs on a scalar variable, name1 contains the name of the variable. If the trace occurs on an array element, or on a whole array, name1 contains the name of the array.

String name2 ()
If the trace occurs on an array element, name2 contains the index of the element. Otherwise name2 is null.

int flags ()
Specifies when action has be applied on the variable when the trace occurs. See below for details.

DESCRIPTION

The VarTrace interface is used for montoring the access on Tcl variables. A VarTrace instance can be registered for a Tcl variable using interp.traceVar. The flags parameter to interp.traceVar specifies which type(s) of access on the variable should cause the VarTrace instance to be activated. When the VarTrace instance is activated, its traceProc method is called. name1 and name2 give the name of the traced variable in the normal two-part form. flags is an OR-ed combination of bits providing several pieces of information. One of the bits TCL.TRACE_READS, TCL.TRACE_WRITES, or TCL.TRACE_UNSETS will be set in flags to indicate which operation is being performed on the variable. The bit TCL.GLOBAL_ONLY will be set whenever the variable being accessed is a global one not accessible from the current level of procedure call: traceProc will need to pass this flag back to variable-related procedures like interp.getVar if it attempts to access the variable. The bit TCL.TRACE_DESTROYED will be set in flags if the trace is about to be destroyed; this information may be useful to traceProc so that it can clean up its own internal data structures (see the section TCL.TRACE_DESTROYED below for more details). Lastly, the bit TCL.INTERP_DESTROYED will be set if the entire interpreter is being destroyed. When this bit is set, traceProc must be especially careful in the things it does (see the section TCL.INTERP_DESTROYED below).

ACCESSING VARIABLES DURING TRACES

During read and write traces, traceProc can read, write, or unset the traced variable using interp.getVar, interp.setVar, and other procedures. While traceProc is executing, traces are temporarily disabled for the variable, so that calls to interp.getVar and interp.setVar will not cause traceProc or other trace procedures to be invoked again. Disabling only occurs for the variable whose trace procedure is active; accesses to other variables will still be traced. However, if a variable is unset during a read or write trace then unset traces will be invoked. During unset traces the variable has already been completely expunged. It is possible for the trace procedure to read or write the variable, but this will be a new version of the variable. Traces are not disabled during unset traces as they are for read and write traces, but existing traces have been removed from the variable before any trace procedures are invoked. If new traces are set by unset trace pro- cedures, these traces will be invoked on accesses to the variable by the trace procedures.

ERROR RETURNS

If traceProc throws a TclException, it signifies that an error occurred, in which case no further traces are invoked for the access and the traced access aborts with the message given by the TclException. Trace procedures can use this facility to make variables read-only, for example (but note that the value of the variable will already have been modified before the trace procedure is called, so the trace procedure will have to restore the correct value). The TclException is used only during read and write tracing. During unset traces, the TclException is ignored and all relevant trace procedures will always be invoked.

TCL.TRACE_DESTROYED FLAG

In an unset callback to traceProc, the TCL.TRACE_DESTROYED bit is set in flags if the trace is being removed as part of the deletion. Traces on a variable are always removed whenever the variable is deleted; the only time TCL.TRACE_DESTROYED isn't set is for a whole-array trace invoked when only a single element of an array is unset.

TCL.INTERP_DESTROYED FLAG

When an interpreter is destroyed, unset traces are called for all of its variables. The TCL.INTERP_DESTROYED bit will be set in the flags argument passed to the trace procedures. Trace procedures must be extremely careful in what they do if the TCL.INTERP_DESTROYED bit is set. It is not safe for the procedures to invoke any Tcl procedures on the interpreter, since its state is partially deleted. All that trace procedures should do under these circumstances is to clean up and free their own internal data structures.

EQUIVALENT C FUNCTIONS

Tcl_TraceProc

SEE ALSO

Interp, setVar, traceVar

KEYWORDS

trace, variable 
Copyright © 1998 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.