diff options
| -rw-r--r-- | doc/timerate.n | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/doc/timerate.n b/doc/timerate.n new file mode 100644 index 0000000..df9a8f7 --- /dev/null +++ b/doc/timerate.n @@ -0,0 +1,114 @@ +'\" +'\" Copyright (c) 2005 Sergey Brester aka sebres. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +.TH timerate n "" Tcl "Tcl Built-In Commands" +.so man.macros +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +timerate \- Time-related execution resp. performance measurement of a script +.SH SYNOPSIS +\fBtimerate \fIscript\fR \fI?time?\fR +.sp +\fBtimerate \fI?-direct?\fR \fI?-overhead double?\fR \fIscript\fR \fI?time?\fR +.sp +\fBtimerate \fI?-calibrate?\fR \fI?-direct?\fR \fIscript\fR \fI?time?\fR +.BE +.SH DESCRIPTION +.PP +The first and second form will evaluate \fIscript\fR until the interval +\fItime\fR given in milliseconds elapses, or for 1000 milliseconds (1 second) +if \fItime\fR is not specified. +.sp +It will then return a canonical tcl-list of the form +.PP +.CS +\f0.095977 µs/# 52095836 # 10419167 #/sec 5000.000 nett-ms\fR +.CE +.PP +which indicates: +.IP \(bu +the average amount of time required per iteration, in microseconds (lindex $result 0) +.IP \(bu +the count how many times it was executed (lindex $result 2) +.IP \(bu +the estimated rate per second (lindex $result 4) +.IP \(bu +the estimated real execution time without measurement overhead (lindex $result 6) +.PP +Time is measured in elapsed time using heighest timer resolution as possible, not CPU time. +This command may be used to provide information as to how well the script or a tcl-command +is performing and can help determine bottlenecks and fine-tune application performance. +.PP +\fI-calibrate\fR +. +To measure very fast scripts as exact as posible the calibration process +may be required. + +This parameter used to calibrate \fBtimerate\fR calculating the estimated overhead +of given \fIscript\fR as default overhead for further execution of \fBtimerate\fR. +It can take up to 10 seconds if parameter \fItime\fR is not specified. +.PP +\fI-overhead double\fR +. +This parameter used to supply the measurement overhead of single iteration +(in microseconds) that should be ignored during whole evaluation process. +.PP +\fI-direct\fR +. +Causes direct execution per iteration (not compiled variant of evaluation used). +.PP +In opposition to \fBtime\fR the execution limited here by fixed time instead of +repetition count. +Additionally the compiled variant of the script will be used during whole evaluation +(as if it were part of a compiled \fBproc\fR), if parameter \fI-direct\fR is not specified. +Therefore it provides more precise results and prevents very long execution time +by slow scripts resp. scripts with unknown speed. + +.SH EXAMPLE +Estimate how fast it takes for a simple Tcl \fBfor\fR loop (including +operations on variable \fIi\fR) to count to a ten: +.PP +.CS +# calibrate: +timerate -calibrate {} +# measure: +timerate { for {set i 0} {$i<10} {incr i} {} } 5000 +.CE +.PP +Estimate how fast it takes for a simple Tcl \fBfor\fR loop only (ignoring the +overhead for operations on variable \fIi\fR) to count to a ten: +.PP +.CS +# 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 +.CE +.PP +Estimate the rate of calculating the hour using \fBclock format\fR only, ignoring +overhead of the rest, without measurement how fast it takes for a whole script: +.PP +.CS +# calibrate: +timerate -calibrate {} +# estimate overhead: +set tm 0 +set ovh [lindex [timerate { incr tm [expr {24*60*60}] }] 0] +# measure using esimated overhead: +set tm 0 +timerate -overhead $ovh { + clock format $tm -format %H + incr tm [expr {24*60*60}]; # overhead for this is ignored +} 5000 +.CE +.SH "SEE ALSO" +time(n) +.SH KEYWORDS +script, timerate, time +.\" Local Variables: +.\" mode: nroff +.\" End: |