- tcl.lang.VarTrace -- Interface for montoring the access on Tcl variables.
- abstract void traceProc(Interp interp, String name1, String name2, int flags)
- ACCESSING VARIABLES DURING TRACES
- ERROR RETURNS
- TCL.TRACE_DESTROYED FLAG
- TCL.INTERP_DESTROYED FLAG
- EQUIVALENT C FUNCTIONS
- SEE ALSO
tcl.lang.VarTrace -- Interface for montoring the access on Tcl variables.
abstract void traceProc(Interp interp, String name1, String name2, int flags)
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).
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.
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.
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.
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
Interp, setVar, traceVar
- 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.
Copyright © 1998 Sun Microsystems, Inc.
Copyright © 1995-1997 Roger E. Critchlow Jr.