1bench_lang_intro(n) Benchmarking/Performance tools bench_lang_intro(n)
2______________________________________________________________________________
6
8 bench_lang_intro - bench language introduction
9
11 This document is an informal introduction to version 1 of the bench
12 language based on a multitude of examples. After reading this a bench‐
13 mark writer should be ready to understand the formal bench language
14 specification.
15 FUNDAMENTALS
17 In the broadest terms possible the bench language is essentially Tcl,
18 plus a number of commands to support the declaration of benchmarks. A
19 document written in this language is a Tcl script and has the same syn‐
20 tax.
21 BASICS
23 One of the most simplest benchmarks which can be written in bench is
24 bench -desc LABEL -body {
27 set a b
28 }
29 This code declares a benchmark named LABEL which measures the time it
31 takes to assign a value to a variable. The Tcl code doing this assign‐
32 ment is the -body of the benchmark.
33 PRE- AND POSTPROCESSING
35 Our next example demonstrates how to declare initialization and cleanup
36 code, i.e. code computing information for the use of the -body, and for
37 releasing such resources after the measurement is done. They are the
38 -pre- and the -post-body, respectively.
39 In our example, directly drawn from the benchmark suite of Tcllib's aes
41 package, the concrete initialization code constructs the key schedule
42 used by the encryption command whose speed we measure, and the cleanup
43 code releases any resources bound to that schedule.
44 bench -desc "AES-${len} ECB encryption core" -pre {
47 set key [aes::Init ecb $k $i]
48 } -body {
49 aes::Encrypt $key $p
50 } -post {
51 aes::Final $key
52 }
53 ADVANCED PRE- AND POSTPROCESSING
56 Our last example again deals with initialization and cleanup code. To
57 see the difference to the regular initialization and cleanup discussed
58 in the last section it is necessary to know a bit more about how bench
59 actually measures the speed of the the -body.
60 Instead of running the -body just once the system actually executes the
62 -body several hundred times and then returns the average of the found
63 execution times. This is done to remove environmental effects like
64 machine load from the result as much as possible, with outliers cancel‐
65 ing each other out in the average.
66 The drawback of doing things this way is that when we measure opera‐
68 tions which are not idempotent we will most likely not measure the time
69 for the operation we want, but of the state(s) the system is in after
70 the first iteration, a mixture of things we have no interest in.
71 Should we wish, for example, to measure the time it takes to include an
73 element into a set, with the element not yet in the set, and the set
74 having specific properties like being a shared Tcl_Obj, then the first
75 iteration will measure the time for this. However all subsequent itera‐
76 tions will measure the time to include an element which is already in
77 the set, and the Tcl_Obj holding the set will not be shared anymore
78 either. In the end the timings taken for the several hundred iterations
79 of this state will overwhelm the time taken from the first iteration,
80 the only one which actually measured what we wanted.
81 The advanced initialization and cleanup codes, -ipre- and the -ipost-
83 body respectively, are present to solve this very problem. While the
84 regular initialization and cleanup codes are executed before and after
85 the whole series of iterations the advanced codes are executed before
86 and after each iteration of the body, without being measured them‐
87 selves. This allows them to bring the system into the exact state the
88 body wishes to measure.
89 Our example, directly drawn from the benchmark suite of Tcllib's
91 struct::set package, is for exactly the example we used above to demon‐
92 strate the necessity for the advanced initialization and cleanup. Its
93 concrete initialization code constructs a variable refering to a set
94 with specific properties (The set has a string representation, which is
95 shared) affecting the speed of the inclusion command, and the cleanup
96 code releases the temporary variables created by this initialization.
97 bench -desc "set include, missing <SC> x$times $n" -ipre {
100 set A $sx($times,$n)
101 set B $A
102 } -body {
103 struct::set include A x
104 } -ipost {
105 unset A B
106 }
107
110 Now that this document has been digested the reader, assumed to be a
111 writer of benchmarks, he should be fortified enough to be able to
112 understand the formal bench language specfication. It will also serve
113 as the detailed specification and cheat sheet for all available com‐
114 mands and their syntax.
115
117 This document, and the package it describes, will undoubtedly contain
118 bugs and other problems. Please report such in the category bench of
119 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
120 also report any ideas for enhancements you may have for either package
121 and/or documentation.
122 When proposing code changes, please provide unified diffs, i.e the out‐
124 put of diff -u.
125 Note further that attachments are strongly preferred over inlined
127 patches. Attachments can be made by going to the Edit form of the
128 ticket immediately after its creation, and then using the left-most
129 button in the secondary navigation bar.
130
132 bench_intro, bench_lang_spec
133
135 bench language, benchmark, examples, performance, testing
136
138 Benchmark tools
139
141 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
142tcllib 1.0 bench_lang_intro(n)