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 intended 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 arguments and then returns the empty
              string as its result.  The command 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 temporary 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  options,  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 different 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 responsibility 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 expected  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 execution 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. reduce the number of times they are run to keep the overall time for the
                     execution of the whole benchmark within manageable 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 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_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)