The first and second form will evaluate script until the interval time given in milliseconds elapses, or for 1000 milliseconds (1 second) if time is not specified.
The parameter max-count could additionally impose a further restriction by the maximal number of iterations to evaluate the script. If max-count is specified, the evaluation will stop either this count of iterations is reached or the time is exceeded.
It will then return a canonical Tcl-list of the form:
0.095977 µs/# 52095836 # 10419167 #/sec 5000.000 net-ms
which indicates:
The following options may be supplied to the timerate command:
Note that the calibration process is not thread safe in the current implementation.
As opposed to the time command, which runs the tested script for a fixed number of iterations, the timerate command runs it for a fixed time. Additionally, the compiled variant of the script will be used during the entire measurement, as if the script were part of a compiled procedure, if the -direct option is not specified. The fixed time period and possibility of compilation allow for more precise results and prevent very long execution times by slow scripts, making it practical for measuring scripts with highly uncertain execution times.
# calibrate
timerate -calibrate {}
# measure
timerate { for {set i 0} {$i<10} {incr i} {} } 5000
Estimate how fast it takes for a simple Tcl for loop, ignoring the overhead of the management of the variable that controls the loop:
# calibrate for overhead of variable operations
set i 0; timerate -calibrate {expr {$i<10}; incr i} 1000
# measure
timerate {
for {set i 0} {$i<10} {incr i} {}
} 5000
Estimate the speed of calculating the hour of the day using clock format only, ignoring overhead of the portion of the script that prepares the time for it to calculate:
# calibrate
timerate -calibrate {}
# estimate overhead
set tm 0
set ovh [lindex [timerate -overhead 0 {
incr tm [expr {24*60*60}]
}] 0]
# measure using estimated overhead
set tm 0
timerate -overhead $ovh {
clock format $tm -format %H
incr tm [expr {24*60*60}]; # overhead for this is ignored
} 5000
In this last example, note that the overhead itself is measured using timerate invoked with -overhead 0. This is necessary because explicit overheads are assumed to be absolute values, and not an increment over the default calibrated overhead. It is therefore important that the calibrated overhead is excluded in the measurement of the overhead value itself. This is accomplished by passing -overhead 0 when measuring the overhead.