1timerate(n) Tcl Built-In Commands timerate(n)
2______________________________________________________________________________
6
8 timerate - Calibrated performance measurements of script execution time
9
11 timerate script ?time? ?max-count?
12 timerate ?-direct? ?-overhead double? script ?time? ?max-count?
14 timerate ?-calibrate? ?-direct? script ?time? ?max-count?
16______________________________________________________________________________
17
19 The timerate command does calibrated performance measurement of a Tcl
20 command or script, script. The script should be written so that it can
21 be executed multiple times during the performance measurement process.
22 Time is measured in elapsed time using the finest timer resolution as
23 possible, not CPU time; if script interacts with the OS, the cost of
24 that interaction is included. This command may be used to provide
25 information as to how well a script or Tcl command is performing, and
26 can help determine bottlenecks and fine-tune application performance.
27 The first and second form will evaluate script until the interval time
29 given in milliseconds elapses, or for 1000 milliseconds (1 second) if
30 time is not specified.
31 The parameter max-count could additionally impose a further restriction
33 by the maximal number of iterations to evaluate the script. If max-
34 count is specified, the evalution will stop either this count of itera‐
35 tions is reached or the time is exceeded.
36 It will then return a canonical tcl-list of the form:
38 0.095977 µs/# 52095836 # 10419167 #/sec 5000.000 net-ms
40 which indicates:
42 · the average amount of time required per iteration, in microseconds
44 ([lindex $result 0])
45 · the count how many times it was executed ([lindex $result 2])
47 · the estimated rate per second ([lindex $result 4])
49 · the estimated real execution time without measurement overhead
51 ([lindex $result 6])
52 The following options may be supplied to the timerate command:
54 -calibrate
56 To measure very fast scripts as exactly as possible, a calibra‐
57 tion process may be required. The -calibrate option is used to
58 calibrate timerate itself, calculating the estimated overhead of
59 the given script as the default overhead for future invocations
60 of the timerate command. If the time parameter is not specified,
61 the calibrate procedure runs for up to 10 seconds.
62 Note that calibration is not thread safe in the current imple‐
64 mentation.
65 -overhead double
67 The -overhead parameter supplies an estimate (in microseconds)
68 of the measurement overhead of each iteration of the tested
69 script. This quantity will be subtracted from the measured time
70 prior to reporting results. This can be useful for removing the
71 cost of interpreter state reset commands from the script being
72 measured.
73 -direct
75 The -direct option causes direct execution of the supplied
76 script, without compilation, in a manner similar to the time
77 command. It can be used to measure the cost of Tcl_EvalObjEx, of
78 the invocation of canonical lists, and of the uncompiled ver‐
79 sions of bytecoded commands.
80 As opposed to the time commmand, which runs the tested script for a
82 fixed number of iterations, the timerate command runs it for a fixed
83 time. Additionally, the compiled variant of the script will be used
84 during the entire measurement, as if the script were part of a compiled
85 procedure, if the -direct option is not specified. The fixed time
86 period and possibility of compilation allow for more precise results
87 and prevent very long execution times by slow scripts, making it prac‐
88 tical for measuring scripts with highly uncertain execution times.
89
91 Estimate how fast it takes for a simple Tcl for loop (including opera‐
92 tions on variable i) to count to ten:
93 # calibrate
95 timerate -calibrate {}
96 # measure
98 timerate { for {set i 0} {$i<10} {incr i} {} } 5000
99 Estimate how fast it takes for a simple Tcl for loop, ignoring the
101 overhead of the management of the variable that controls the loop:
102 # calibrate for overhead of variable operations
104 set i 0; timerate -calibrate {expr {$i<10}; incr i} 1000
105 # measure
107 timerate {
108 for {set i 0} {$i<10} {incr i} {}
109 } 5000
110 Estimate the speed of calculating the hour of the day using clock for‐
112 mat only, ignoring overhead of the portion of the script that prepares
113 the time for it to calculate:
114 # calibrate
116 timerate -calibrate {}
117 # estimate overhead
119 set tm 0
120 set ovh [lindex [timerate {
121 incr tm [expr {24*60*60}]
122 }] 0]
123 # measure using estimated overhead
125 set tm 0
126 timerate -overhead $ovh {
127 clock format $tm -format %H
128 incr tm [expr {24*60*60}]; # overhead for this is ignored
129 } 5000
130
132 time(n)
133
135 performance measurement, script, time
136Tcl timerate(n)