bench_lang_spec(3tcl) Documentation tools bench_lang_spec(3tcl)
______________________________________________________________________________
NAME
bench_lang_spec - bench language specification
SYNOPSIS
bench_rm path...
bench_tmpfile
bench options...
______________________________________________________________________________
DESCRIPTION
This document specifies both names and syntax of all the commands which
together are the bench language, version 1. As this document is in-
tended to be a reference the commands are listed in alphabetical order,
and the descriptions are relatively short. A beginner should read the
more informally written bench language introduction first.
COMMANDS
bench_rm path...
This command silently removes the files specified as its argu-
ments and then returns the empty string as its result. The com-
mand is trusted, there is no checking if the specified files are
outside of whatever restricted area the benchmarks are run in.
bench_tmpfile
This command returns the path to a bench specific unique tempo-
rary file. The uniqueness means that multiple calls will return
different paths. While the path may exist from previous runs,
the command itself does not create aynthing.
The base location of the temporary files is platform dependent:
Unix, and indeterminate platform
"/tmp"
Windows
$TEMP
Anything else
The current working directory.
bench options...
This command declares a single benchmark. Its result is the
empty string. All parts of the benchmark are declared via op-
tions, and their values. The options can occur in any order. The
accepted options are:
-body script
The argument of this option declares the body of the
benchmark, the Tcl script whose performance we wish to
measure. This option, and -desc, are the two required
parts of each benchmark.
-desc msg
The argument of this option declares the name of the
benchmark. It has to be unique, or timing data from dif-
ferent benchmarks will be mixed together.
Beware! This requirement is not checked when benchmarks
are executed, and the system will silently produce bogus
data. This option, and -body, are the two required parts
of each benchmark.
-ipost script
The argument of this option declares a script which is
run immediately after each iteration of the body. Its re-
sponsibility is to release resources created by the body,
or -ipre-bodym which we do not wish to live into the next
iteration.
-ipre script
The argument of this option declares a script which is
run immediately before each iteration of the body. Its
responsibility is to create the state of the system ex-
pected by the body so that we measure the right thing.
-iterations num
The argument of this option declares the maximum number
of times to run the -body of the benchmark. During execu-
tion this and the global maximum number of iterations are
compared and the smaller of the two values is used.
This option should be used only for benchmarks which are
expected or known to take a long time per run. I.e. re-
duce the number of times they are run to keep the overall
time for the execution of the whole benchmark within man-
ageable limits.
-post script
The argument of this option declares a script which is
run after all iterations of the body have been run. Its
responsibility is to release resources created by the
body, or -pre-body.
-pre script
The argument of this option declares a script which is
run before any of the iterations of the body are run. Its
responsibility is to create whatever resources are needed
by the body to run without failing.
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 out-
put 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_intro
KEYWORDS
bench language, benchmark, performance, specification, testing
CATEGORY
Benchmark tools
COPYRIGHT
Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
tcllib 1.0 bench_lang_spec(3tcl)