oracular (3) bench_lang_intro.3tcl.gz
NAME
bench_lang_intro - bench language introduction
DESCRIPTION
This document is an informal introduction to version 1 of the bench language based on a multitude of
examples. After reading this a benchmark writer should be ready to understand the formal bench language
specification.
FUNDAMENTALS
In the broadest terms possible the bench language is essentially Tcl, plus a number of commands to
support the declaration of benchmarks. A document written in this language is a Tcl script and has the
same syntax.
BASICS
One of the most simplest benchmarks which can be written in bench is
bench -desc LABEL -body {
set a b
}
This code declares a benchmark named LABEL which measures the time it takes to assign a value to a
variable. The Tcl code doing this assignment is the -body of the benchmark.
PRE- AND POSTPROCESSING
Our next example demonstrates how to declare initialization and cleanup code, i.e. code computing
information for the use of the -body, and for releasing such resources after the measurement is done.
They are the -pre- and the -post-body, respectively.
In our example, directly drawn from the benchmark suite of Tcllib's aes package, the concrete
initialization code constructs the key schedule used by the encryption command whose speed we measure,
and the cleanup code releases any resources bound to that schedule.
bench -desc "AES-${len} ECB encryption core" -pre {
set key [aes::Init ecb $k $i]
} -body {
aes::Encrypt $key $p
} -post {
aes::Final $key
}
ADVANCED PRE- AND POSTPROCESSING
Our last example again deals with initialization and cleanup code. To see the difference to the regular
initialization and cleanup discussed in the last section it is necessary to know a bit more about how
bench actually measures the speed of the the -body.
Instead of running the -body just once the system actually executes the -body several hundred times and
then returns the average of the found execution times. This is done to remove environmental effects like
machine load from the result as much as possible, with outliers canceling each other out in the average.
The drawback of doing things this way is that when we measure operations which are not idempotent we will
most likely not measure the time for the operation we want, but of the state(s) the system is in after
the first iteration, a mixture of things we have no interest in.
Should we wish, for example, to measure the time it takes to include an element into a set, with the
element not yet in the set, and the set having specific properties like being a shared Tcl_Obj, then the
first iteration will measure the time for this. However all subsequent iterations will measure the time
to include an element which is already in the set, and the Tcl_Obj holding the set will not be shared
anymore either. In the end the timings taken for the several hundred iterations of this state will
overwhelm the time taken from the first iteration, the only one which actually measured what we wanted.
The advanced initialization and cleanup codes, -ipre- and the -ipost-body respectively, are present to
solve this very problem. While the regular initialization and cleanup codes are executed before and after
the whole series of iterations the advanced codes are executed before and after each iteration of the
body, without being measured themselves. This allows them to bring the system into the exact state the
body wishes to measure.
Our example, directly drawn from the benchmark suite of Tcllib's struct::set package, is for exactly the
example we used above to demonstrate the necessity for the advanced initialization and cleanup. Its
concrete initialization code constructs a variable refering to a set with specific properties (The set
has a string representation, which is shared) affecting the speed of the inclusion command, and the
cleanup code releases the temporary variables created by this initialization.
bench -desc "set include, missing <SC> x$times $n" -ipre {
set A $sx($times,$n)
set B $A
} -body {
struct::set include A x
} -ipost {
unset A B
}
FURTHER READING
Now that this document has been digested the reader, assumed to be a writer of benchmarks, he should be
fortified enough to be able to understand the formal bench language specfication. It will also serve as
the detailed specification and cheat sheet for all available commands and their syntax.
BUGS, IDEAS, FEEDBACK
This document, and the package it describes, will undoubtedly contain bugs and other problems. Please
report such in the category bench of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
also report any ideas for enhancements you may have for either package and/or documentation.
When proposing code changes, please provide unified diffs, i.e the output of diff -u.
Note further that attachments are strongly preferred over inlined patches. Attachments can be made by
going to the Edit form of the ticket immediately after its creation, and then using the left-most button
in the secondary navigation bar.
SEE ALSO
bench_intro, bench_lang_spec
KEYWORDS
bench language, benchmark, examples, performance, testing
CATEGORY
Benchmark tools
COPYRIGHT
Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>