timerate manual page - Built-In Commands

## Tcl/Tk Documentation > Tcl Commands, version 8.6.18 > timerate

### Tcl/Tk Applications | Tcl Commands | Tk Commands | [incr Tcl] Package Commands | SQLite3 Package Commands | TDBC Package Commands | tdbc::mysql Package Commands | tdbc::odbc Package Commands | tdbc::postgres Package Commands | tdbc::sqlite3 Package Commands | Thread Package Commands | Tcl C API | Tk C API | [incr Tcl] Package C API | TDBC Package C API

  NAME
    timerate — Calibrated performance measurements of script execution time
  SYNOPSIS
  DESCRIPTION
    -calibrate
    -overhead double
    -direct
  EXAMPLES
  SEE ALSO
  KEYWORDS

### NAME

timerate — Calibrated performance measurements of script execution time

### SYNOPSIS

timerate script ?time? ?max-count?
timerate ?-direct? ?-overhead double? 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 evalution 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 calibration is not thread safe in the current implementation.

-overhead double
  The -overhead parameter supplies an estimate (in microseconds) of the measurement overhead of each iteration of the tested script. The passed value overrides, for the current invocation of timerate, the overhead estimated by a previous calibration. Overrides may themselves be measured using timerate as illustrated by a later example.

-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 commmand, 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 -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.

### SEE ALSO

time

### KEYWORDS

performance measurement, script, time
Copyright © 2005 Sergey Brester aka sebres.