NAME

       timerate - Calibrated performance measurements of script execution time

SYNOPSIS

       timerate script ?time? ?max-count?
       timerate ?-direct? ?-overhead estimate? script ?time? ?max-count?
       timerate ?-calibrate? ?-direct? script ?time? ?max-count?
________________________________________________________________________________________________________________

DESCRIPTION

       The  timerate  command  does  calibrated  performance measurement of a Tcl command or script, script. The
       script should be written so that it can be executed multiple times  during  the  performance  measurement
       process.   Time  is measured in elapsed time using the finest timer resolution as possible, not CPU time;
       if script interacts with the OS, the cost of that interaction is included.  This command may be  used  to
       provide  information  as  to  how  well  a  script  or  Tcl command is performing, and can help determine
       bottlenecks and fine-tune application performance.

       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 average amount of time required per iteration, in microseconds ([lindex $result 0])

       •  the count how many times it was executed ([lindex $result 2])

       •  the estimated rate per second ([lindex $result 4])

       •  the estimated real execution time without measurement overhead ([lindex $result 6])

       The following options may be supplied to the timerate command:

       -calibrate
              To measure very fast scripts as exactly as possible, a calibration process may be  required.   The
              -calibrate  option is used to calibrate timerate itself, calculating the estimated overhead of the
              given script as the default overhead for future invocations of the timerate command. If  the  time
              parameter is not specified, the calibrate procedure runs for up to 10 seconds.

              Note that the calibration process is not thread safe in the current implementation.

       -overhead estimate
              The  -overhead  parameter  supplies  an  estimate  (in microseconds, which may be a floating point
              number) of the measurement overhead of each iteration of the tested script. This quantity will  be
              subtracted  from the measured time prior to reporting results. This can be useful for removing the
              cost of interpreter state reset commands from the script being measured.

       -direct
              The -direct option causes direct execution of the  supplied  script,  without  compilation,  in  a
              manner  similar  to  the time command. It can be used to measure the cost of Tcl_EvalObjEx, of the
              invocation of canonical lists, and of the uncompiled versions of bytecoded commands.

       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.

EXAMPLES

       Estimate  how  fast  it  takes for a simple Tcl for loop (including operations on variable i) to count to
       ten:

              # 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 {
                  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

SEE ALSO

       time(3tcl)

KEYWORDS

       performance measurement, script, time

Tcl                                                                                               timerate(3tcl)