'''[http://www.tcl.tk/man/tcl/TclCmd/trace.htm%|%trace]''' a [Tcl Commands%|%built-in] [Tcl] command, monitors [variable] accesses [command] definition and execution.



** See Also **

   [An equation solver]:   with an example of using trace to update dependent resources

   [Traces]:   examples and discussion

   [Tracing inappropriate variable access]:   

   [Whole-Script Tracing]:   by [DKF]

   [An example of data objects]:   [AM] Using the trace command, I implemented an idea by [George Howlett] (the author of [BLT])



** Synopsis **

    :   '''trace''' ''option'' ''?arg arg ...?''



** Documentation **

   [http://www.tcl.tk/man/tcl/TclCmd/trace.htm%|%official documentation%|%]:   



** Description **

Examples of what to do with `trace`:

   * Communicate between parts of a [GUI] and the internal state of the app. (Simplified [MVC], observer). In general Communicate between different parts of an app without coupling them strongly.

   * Compute simple constraints for a number of variables ("if this flag is on and that one is on, then no other is allowed to be set", and some such).

   * `[bind]` [Canvas] text items to a variable, effecting dynamic updates 

   * Debug - call a proc when a variable is modified (detect setting from wrong routine).

   * Trace works in Itcl [Itcl trace] but not quite trivially.



** Order of Processing **

[JCW]:

======
proc tellme {id a e op} {
    puts "  $id a=$a e=$e op=$op\
                ax=[info exists ::$a] ex=[info exists ::${a}($e)]"
}

proc do {args} {
    puts "<$args>"
    uplevel $args
}

trace var a wu {tellme array}
trace var a(1) wu {tellme element}

puts [trace vinfo a]
puts [trace vinfo a(1)]

do set a(0) zero
do set a(1) one
do set a(2) two
do unset a(0)
do unset a(2)
do unset a

# output is:
#
#   {wu {tellme array}}
#   {wu {tellme element}}
#   <set a(0) zero>
#     array a=a e=0 op=w ax=1 ex=1
#   <set a(1) one>
#     array a=a e=1 op=w ax=1 ex=1
#     element a=a e=1 op=w ax=1 ex=1
#   <set a(2) two>
#     array a=a e=2 op=w ax=1 ex=1
#   <unset a(0)>
#     array a=a e=0 op=u ax=1 ex=0
#   <unset a(2)>
#     array a=a e=2 op=u ax=1 ex=0
#   <unset a>
#     array a=a e= op=u ax=0 ex=0
#     element a=a e=1 op=u ax=0 ex=0
======



** Variable Trace Arguments vs Upvar **

Be careful how you use the `name1` and `name2` parameters provided to a variable trace.
It's tempting to write a single handler which tracks access to multiple variables thus:
======
proc traceHandler {name _ op} {  ;# we ignore name2 for a non-array trace
    puts "trace: variable {$name} $op"
}
unset -nocomplain x y
trace add variable x {write} traceHandler
trace add variable y {write} traceHandler
incr x
#  trace: variable {x} write
incr y
#  trace: variable {y} write
======

So far, so good.  But look what happens when the variable is [https://en.wikipedia.org/wiki/Aliasing_%28computing%29%%|%aliased] with `upvar`:

======
proc loop {_var first limit script} { ;# http://wiki.tcl.tk/2025
    upvar 1 $_var var
    for {set var $first} {$var < $limit} {incr var} {
        uplevel 1 $script
    }
}
loop x 0 2 {
  ;# no loop body - we just want to see what happens to x
}
#  trace: variable {var} write
#  trace: variable {var} write
#  trace: variable {var} write
======

The trace fires as expected ... but the name is now coming from somebody else's code.
This is sufficient if you just want to access the variable by `[upvar]` or `[uplevel]`, but useless for identifying changes to different variables managed by the same trace handler.

Bugs stemming from code not considering this behaviour can lie dormant for a very long time and be mystifying when they arise.  Therefore, when the name of the variable matters to the trace handler, it's a good idea (and good practice for other kinds of callbacks) to pass that name explicitly, rather than relying on the arguments supplied by the trace:

======
proc traceHandler {name} {
    puts "trace: $name"
}
trace add variable x {write} [lambda {varname args} {traceHandler $varname} x]
======

[PYK]: I prefer an example that uses `[apply]` directly, because its execution
[namespace] can be specified, and in contrast with `[lambda]` (at least as
currently defined on that page), its `[uplevel]` is still the context that
triggered the trace:

======
trace add variable x write [
    list apply [
        list {varname args} {traceHandler $varname} [namespace current]] x]
======

[aspect]:  updated the [lambda] page to more prominently feature the Tcllib package which supports a namespace argument.

** Local Variable Traces **

On [comp.lang.tcl], 2004-05, [CLN] answers [Erik Leunissen]'s question: Erik
Leunissen wrote:

======
> The following passage from the man page to the trace command is
> mystifying to me:
> 
> "If an unset occurs because of a procedure return, then the trace will
> be invoked in the variable context of the procedure being returned to:
> the stack frame of the returning procedure will no longer exist."
> 
> I've read it again and again; I can't imagine how a procedure return
> affects/causes an unset.
> ...


   proc foo { } { 
      set x 1
      trace variable x u {some code here}
   }

When foo is invoked, x is created (locally), has a trace associated with
it, then becomes unset as foo exits.
======



** Arrays **

Non-array variables give a null string for the ''name2'' argument  in the trace
invocation, but the null string is a perfectly valid array index (it is also a
valid array variable name), so a null value for ''name2'' doesn't necessarily
indicate that the traced variable is scalar.  To determine whether a variable
is an array, use:

======
if {[array exists $varname]} {...}
======


All of the following operations result in the argument values `a {} u`:

======
unset a ;# regular var a
array unset a
unset a()
======

including a null index string.  `[array exists]` always returns false for
the first two cases, and true for the third (even if the null index was the
only array element). There is no way for the trace to be sure which operation
was performed.

[Lars H]: Hmm... might this be a sign that the format of these parameter lists
is not well designed? An alternative would have been to put the operation first
and the variable name second, so that there needn't be an index for non-array
accesses. Probably too late to change now, though. (Adding a second interface
which is just like the current except that it produces parameter lists in a new
format is possible, but probably seen as superfluous.)



** Arrays and Upvar **

A surprising (?) result that is documented in the [upvar] manpage:

===
If  otherVar  refers  to an element of an array, then variable traces
set for the entire array will not be invoked when myVar is accessed (but
traces on the particular element will still be invoked).
===

This means that using a trace on an array is ''not'' sufficient to capture all
the ways elements can be accessed.  For instance:

======
package require lambda
unset -nocomplain a x y
array set a {x 1 y 2}
trace add variable a {array read write unset} [lambda args {puts "::a trace: $args"}]
======

Any direct use of `a` will trigger the trace:

======
% incr a(x)    ;# existing element
::a trace: a x read
::a trace: a x write
 2
% incr a(z)    ;# new element
::a trace: a z read
::a trace: a z write
 1
% unset a(x)
::a trace: a x unset
======

so far so good.  But throw [upvar] into the mix:

======
% upvar 0 a(y) y    ;# existing element
% upvar 0 a(w) w    ;# new element
% incr y
 3
% incr w
 1
% unset y
% unset w
======

No traces were fired!  If you're tracing an array whose elements might be [upvar]ed, beware.


** What about a "variable create" Trace? **

[male] 2006-01-24: I wanted to trace the creation of an
array element and used the write event, but ... the write event is fired after
the new array element was already created! What's about a new event like
"create"? Since a trace may be created on non-existent variables, this could be
useful not only for arrays.

----

[Donald Arseneau]: Yes, write traces fire after the variable has already been
set, so if you want validation of variables' values, in analogy with Tk's
[entry validation], then you must maintain shadow copies of the previous
values, in order to undo improper settings.



** Triggering Traces when using a variable at the [C] level ** 

On [comp.lang.tcl], [Kevin Kenny] answers someone wanting to link a C variable
and a Tcl variable, and have a Tcl proc invoked when the C code modified the
variable:


    :   Look in the manual for Tcl_UpdateLinkedVar.  The Tcl engine has no way of telling that you've changed the variable in C; if you call Tcl_UpdateLinkedVar, that tells it your value has changed, and it fires the traces.



** Simple file I/O in traces: **

======
trace var stdout w {puts stdout $stdout ;#}
trace var stdin  r {gets stdin  stdin   ;#}
======

The variables are named like the file handles. Little demo, that waits for
input and prints it capitalized:

======
set stdout [string toupper $stdin]
======



** Managing Traces **

Traces are like [widget]s and [image]s in that they are resources that can be
leaked and/or need clean-up.  Counter-intuitive results sometimes arise because
traces are additive rather than substitutive; a particular trace can fire a
whole chain of commands.  To wipe the global space clean of traces,

======
foreach variable [info glob] {
    foreach pair [trace info variable ::$variable] {
        foreach {op traced_command} $pair {}
        set op [string range $op 0 0] 
        trace vdelete ::$variable $op $traced_command
    }
}
======


** Swallowed Errors: Command Delete Traces ** 

[PYK] 2015-04-02:

Errors are ignored in command delete traces:

======
variable var1 {1 one 2 two}
proc p1 args {}
#intentional bad code here: the commandPrefix doesn't have the right command signature.
trace add command p1 delete [list dict unset var1 1]
rename p1 {}
puts $var1 ;# -> 1 one 2 two
======

This is the current design, not a bug.  Anyone have any info on the rationale?




** Traces of Command Executions **




*** step traces ***

'''enterstep''' and '''leavestep''' traces fire for all steps,
[recursion%|%recursively%|%].  When this is undesired, the depth of the
recursion can be constrained by having the trace procedure look at `[info
level]`. 

    :   [http://groups.google.com/d/msg/comp.lang.tcl/d8KWS-VmxDs/rx0aZp7qOdUJ%|%Interesting experience with execution traces], [comp.lang.tcl], 2003-11-24


----

[Donald Arseneau]: Another tricky trap is that errors in traces may give error
messages, but no context; the only context is for whatever triggered the trace.
Thus, if you ever see Tk error messages like 

======
can't set "xv": invalid command name "oops"
    while executing
"incr xv"
======

then you should look for a variable trace on the xv variable.

----

[Schnexel]: Oh the tricky trace traps! I tried to automaticly update a
derivedData array by setting a trace on the parentData array (scenario
simplified)... Now I get a surreal result:

======
set bla "What happened:\n"

namespace eval bbb {

    array set lala [list 1 v1 2 v2 3 v3]
    trace add variable ::bbb::lala {read array} ::bbb::tra
    proc tra args {
        append ::bla "\n (TRACE $args)"
        array unset ::bbb::lala                         ;# also deletes trace (yet the "array" op still fires)
        foreach {n v}  [list 1 trv1 2 trv2 3 trv3] { set ::bbb::lala($n) $v }
    }
}

namespace eval aaa {
    append ::bla "\n\[info exists ::bbb::lala(1)\]==..."; append ::bla ... [info exists ::bbb::lala(1)]
    append ::bla "\n\[info exists ::bbb::lala(1)\]==..."; append ::bla ... [info exists ::bbb::lala(1)]
    append ::bla "\n\$::bbb::lala(1)==...";               append ::bla ... $::bbb::lala(1)
}

puts $bla
======

which gives the output

======none
What happened:
[info exists ::bbb::lala(1)]==...
 (TRACE ::bbb::lala 1 read)
 (TRACE ::bbb::lala {} array)...0
[info exists ::bbb::lala(1)]==......1
$::bbb::lala(1)==......trv1
======

So, upon first read access of lala, it does not exist anymore, whilst upon
second read it is there. Can anybody make sense of this?

[Lars H]: Regarding why the "array" op fires: It it fires at the very `array
unset ::bbb::lala` where you comment upon this, i.e., before the `[foreach]`,
which is consistent with the `[trace]` manpage (only read and write traces are
disabled inside a read or write trace). But why `[info exists]` reports `0` I don't
know... Perhaps some caching issue (the variable that was looked up is not the
one that is there when the result is returned)? You'll probably need to read
the source to find out.

[Schnexel]: Wrrr... Here´s a simpler example. Array trace is bugged!

======
array set ::lala [list 1 v1  2 v2]
array set ::lala [list 3 v3  4 v4]
puts "\$::lala==[array get ::lala]"                                   ;# O.K.

trace add variable ::lala read ::tra


proc tra args {
    puts "    (TRACE $args)"
    trace remove variable ::lala read ::tra

    array set ::lala   [list A trvA  B trvB]
    puts "    within trace:  \$::lala==[array get ::lala]" ;# O.K.
}

puts "1st read outside:  \$::lala==[array get ::lala]"      ;# not O.K. !
puts "2nd read outside:  \$::lala==[array get ::lala]"      ;# O.K.
======

Output:

======none
$::lala==4 v4 1 v1 2 v2 3 v3
reading ::lala
    (TRACE ::lala 4 read)
    within trace:  $::lala==4 v4 A trvA 1 v1 B trvB 2 v2 3 v3
1st read outside:  $::lala==4 v4 1 v1 2 v2 3 v3
2nd read outside:  $::lala==4 v4 A trvA 1 v1 B trvB 2 v2 3 v3
======



** Proposal:  Modify `trace command ... enter` to Act as a Command Filter **

[PYK] 2013-12-22: The result of a command run as a trace are currently
discarded.  It could instead be used as the command to actually call.
For exampe, the result of the following script would be `12`, not `21`

======
proc add args {
    ::tcl::mathop::+ {*}$args
}

trace add execution add enter {apply {{cmd op} {
    set args [lassign $cmd name]
    foreach arg $args[set args {}] {
        if {$arg % 2 == 0} {
            lappend args $arg
        }
    }
    return [linsert $args 0 $name] 
}}}

add 1 2 3 4 5 6
======




<<categories>> Tcl syntax | Arts and crafts of Tcl-Tk programming | Command