DOKK / manpages / debian 12 / tcl8.6-doc / timerate.3tcl.en
timerate(3tcl) Tcl Built-In Commands timerate(3tcl) 







timerate - Calibrated performance measurements of script execution
    time








timerate script ?time? ?max-count?


timerate ?-direct? ?-overhead double?
    script ?time? ?max-count?


timerate ?-calibrate? ?-direct? script
    ?time? ?max-count?










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:



  

  
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.





  

  
The -overhead parameter supplies an estimate (in microseconds) 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.

  

  
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.








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










time(3tcl)








performance measurement, script, time







  

    
    Tcl