1bench_lang_spec(n)            Documentation tools           bench_lang_spec(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       bench_lang_spec - bench language specification
9

SYNOPSIS

11       bench_rm path...
12
13       bench_tmpfile
14
15       bench options...
16
17______________________________________________________________________________
18

DESCRIPTION

20       This document specifies both names and syntax of all the commands which
21       together are the bench  language,  version  1.   As  this  document  is
22       intended  to  be  a  reference  the commands are listed in alphabetical
23       order, and the descriptions are relatively short.   A  beginner  should
24       read the more informally written bench language introduction first.
25

COMMANDS

27       bench_rm path...
28              This  command  silently removes the files specified as its argu‐
29              ments and then returns the empty string as its result.  The com‐
30              mand is trusted, there is no checking if the specified files are
31              outside of whatever restricted area the benchmarks are run in.
32
33       bench_tmpfile
34              This command returns the path to a bench specific unique  tempo‐
35              rary  file. The uniqueness means that multiple calls will return
36              different paths. While the path may exist  from  previous  runs,
37              the command itself does not create aynthing.
38
39              The base location of the temporary files is platform dependent:
40
41              Unix, and indeterminate platform
42                     "/tmp"
43
44              Windows
45                     $TEMP
46
47              Anything else
48                     The current working directory.
49
50
51       bench options...
52              This  command  declares  a  single  benchmark. Its result is the
53              empty string. All  parts  of  the  benchmark  are  declared  via
54              options,  and  their values. The options can occur in any order.
55              The accepted options are:
56
57              -body script
58                     The argument of this option  declares  the  body  of  the
59                     benchmark,  the  Tcl  script whose performance we wish to
60                     measure. This option, and -desc,  are  the  two  required
61                     parts of each benchmark.
62
63              -desc msg
64                     The  argument  of  this  option  declares the name of the
65                     benchmark. It has to be unique, or timing data from  dif‐
66                     ferent benchmarks will be mixed together.
67
68                     Beware!  This  requirement is not checked when benchmarks
69                     are executed, and the system will silently produce  bogus
70                     data.  This option, and -body, are the two required parts
71                     of each benchmark.
72
73              -ipost script
74                     The argument of this option declares a  script  which  is
75                     run  immediately  after  each  iteration of the body. Its
76                     responsibility is to release  resources  created  by  the
77                     body,  or  -ipre-bodym  which we do not wish to live into
78                     the next iteration.
79
80              -ipre script
81                     The argument of this option declares a  script  which  is
82                     run  immediately  before  each iteration of the body. Its
83                     responsibility is to  create  the  state  of  the  system
84                     expected by the body so that we measure the right thing.
85
86              -iterations num
87                     The  argument  of this option declares the maximum number
88                     of times to run the -body of the benchmark. During execu‐
89                     tion this and the global maximum number of iterations are
90                     compared and the smaller of the two values is used.
91
92                     This option should be used only for benchmarks which  are
93                     expected  or  known  to  take  a  long time per run. I.e.
94                     reduce the number of times they are run to keep the over‐
95                     all  time for the execution of the whole benchmark within
96                     manageable limits.
97
98              -post script
99                     The argument of this option declares a  script  which  is
100                     run  after  all iterations of the body have been run. Its
101                     responsibility is to release  resources  created  by  the
102                     body, or -pre-body.
103
104              -pre script
105                     The  argument  of  this option declares a script which is
106                     run before any of the iterations of the body are run. Its
107                     responsibility is to create whatever resources are needed
108                     by the body to run without failing.
109

BUGS, IDEAS, FEEDBACK

111       This document, and the package it describes, will  undoubtedly  contain
112       bugs  and  other problems.  Please report such in the category bench of
113       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
114       also  report any ideas for enhancements you may have for either package
115       and/or documentation.
116
117       When proposing code changes, please provide unified diffs, i.e the out‐
118       put of diff -u.
119
120       Note  further  that  attachments  are  strongly  preferred over inlined
121       patches. Attachments can be made by going  to  the  Edit  form  of  the
122       ticket  immediately  after  its  creation, and then using the left-most
123       button in the secondary navigation bar.
124

SEE ALSO

126       bench_intro, bench_lang_intro
127

KEYWORDS

129       bench language, benchmark, performance, specification, testing
130

CATEGORY

132       Benchmark tools
133
135       Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
136
137
138
139
140tcllib                                1.0                   bench_lang_spec(n)
Impressum