1bench_lang_intro(n)     Benchmarking/Performance tools     bench_lang_intro(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       bench_lang_intro - bench language introduction
9

DESCRIPTION

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
16   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
22   BASICS
23       One of the most simplest benchmarks which can be written in bench is
24
25
26              bench -desc LABEL -body {
27                  set a b
28              }
29
30       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
34   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
40       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
45
46              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
54
55   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
61       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
67       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
72       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
82       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
90       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
98
99              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
108

FURTHER READING

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

BUGS, IDEAS, FEEDBACK

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
123       When proposing code changes, please provide unified diffs, i.e the out‐
124       put of diff -u.
125
126       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

SEE ALSO

132       bench_intro, bench_lang_spec
133

KEYWORDS

135       bench language, benchmark, examples, performance, testing
136

CATEGORY

138       Benchmark tools
139
141       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
142
143
144
145
146tcllib                                1.0                  bench_lang_intro(n)
Impressum