Tcl trace Command

last modified April 3, 2025

The Tcl trace command monitors variables for specific operations. It allows executing custom scripts when variables are accessed or modified. This powerful feature enables debugging and reactive programming patterns.

Basic Definition

The trace command sets up callbacks for variable operations. These operations include read, write, and unset actions on variables.

Syntax: trace add variable name ops command. The command specifies what happens when the traced operation occurs. Multiple traces can be added to the same variable.

Simple Variable Write Trace

This example demonstrates tracing write operations on a variable.

write_trace.tcl

proc traceWrite {varName index op} {
    puts "Variable $varName was modified"
    puts "New value: [set $varName]"
}

set x 10
trace add variable x write traceWrite

set x 20
set x 30

The traceWrite procedure is called whenever x is modified. It receives the variable name, array index (empty for scalars), and operation type. This helps track all changes to the variable.

Read Operation Tracing

This example shows how to trace when a variable is read.

read_trace.tcl

proc traceRead {varName index op} {
    puts "Variable $varName was read"
}

set y 100
trace add variable y read traceRead

puts "Value: $y"
set z [expr {$y + 50}]

The traceRead procedure executes whenever y is accessed. This helps monitor all read operations, useful for debugging or implementing computed properties.

Array Element Tracing

Traces work with array elements similarly to scalar variables.

array_trace.tcl

proc arrayTrace {arrName index op} {
    puts "Array $arrName\($index) operation: $op"
    if {$op eq "write"} {
        puts "New value: $::${arrName}($index)"
    }
}

array set colors {red #ff0000 green #00ff00}
trace add variable colors write arrayTrace
trace add variable colors read arrayTrace

set colors(blue) #0000ff
puts $colors(green)

This traces both read and write operations on array elements. The index parameter contains the array key being accessed. The global namespace qualifier (::) is needed to access the array from the trace procedure.

Unset Operation Tracing

Traces can detect when variables are unset or go out of scope.

unset_trace.tcl

proc traceUnset {varName index op} {
    puts "Variable $varName is being unset"
}

set temp "temporary value"
trace add variable temp unset traceUnset

unset temp

The traceUnset procedure executes before the variable is actually removed. This allows cleanup operations or logging when variables are destroyed.

Multiple Traces on Single Variable

Multiple traces can be added to the same variable for different operations.

multi_trace.tcl

proc writeHandler {varName index op} {
    puts "WRITE: $varName changed to [set $varName]"
}

proc readHandler {varName index op} {
    puts "READ: $varName was accessed"
}

set counter 0
trace add variable counter write writeHandler
trace add variable counter read readHandler

incr counter
set x [expr {$counter * 2}]

This example adds separate traces for read and write operations. The handlers provide different output for each operation type. Traces execute in the order they were added to the variable.

Removing Traces

Traces can be removed when they're no longer needed.

remove_trace.tcl

proc logChange {varName index op} {
    puts "Change detected in $varName"
}

set debugVar "test"
trace add variable debugVar write logChange

set debugVar "new value"

trace remove variable debugVar write logChange
set debugVar "no tracing now"

The trace remove command stops the tracing. After removal, variable operations no longer trigger the callback. This is important for managing performance and avoiding unwanted side effects.

Best Practices

Performance: Use traces sparingly as they add overhead.
Debugging: Traces are excellent for debugging variable changes.
Cleanup: Remove traces when they're no longer needed.
Namespaces: Be mindful of namespace contexts in trace commands.
Recursion: Avoid infinite recursion in trace callbacks.

This tutorial covered the Tcl trace command with practical examples showing its usage for monitoring variable operations.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Tcl Tutorials.

Ebooks