1bench_lang_spec(n) Documentation tools bench_lang_spec(n)
2______________________________________________________________________________
6
8 bench_lang_spec - bench language specification
9
11 bench_rm path...
12 bench_tmpfile
14 bench options...
16______________________________________________________________________________
18
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
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 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 The base location of the temporary files is platform dependent:
40 Unix, and indeterminate platform
42 "/tmp"
43 Windows
45 $TEMP
46 Anything else
48 The current working directory.
49 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 -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 -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 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 -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 -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 -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 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 -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 -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
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 When proposing code changes, please provide unified diffs, i.e the out‐
118 put of diff -u.
119 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
126 bench_intro, bench_lang_intro
127
129 bench language, benchmark, performance, specification, testing
130
132 Benchmark tools
133
135 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
136tcllib 1.0 bench_lang_spec(n)