NAME

       benchmp,  benchmp_getstate, benchmp_interval, start, stop, get_n, set_n, gettime, settime,
       get_enough, t_overhead, l_overhead - the lmbench timing subsystem

SYNOPSIS

       #include

       typedef u_long iter_t;

       typedef (*bench_f)(iter_t iterations, void* cookie);

       typedef (*support_f)(iter_t iterations, void* cookie);

       void benchmp(support_f initialize, bench_f benchmark, support_f cleanup, int  enough,  int
       parallel, int warmup, int repetitions, void* cookie);

       void* benchmp_getstate();

       iter_t benchmp_interval(void* state);

       void start(struct timeval *begin);

       uint64    stop(struct timeval *begin, struct timeval *end);

       uint64    get_n();

       void set_n(uint64 n);

       uint64    gettime();

       void settime(uint64 u);

       uint64    get_enough(uint64 enough);

       uint64    t_overhead();

       double    l_overhead();

DESCRIPTION

       The  single  most  important  element  of  a  good  benchmarking system is the quality and
       reliability  of  its  measurement  system.   lmbench's  timing   subsystem   manages   the
       experimental  timing  process  to  produce  accurate  results  in the least possible time.
       lmbench includes methods for measuring and eliminating several factors that influence  the
       accuracy of timing measurements, such as the resolution of the system clock.

       lmbench gets accurate results by considering clock resolution, auto-sizing the duration of
       each benchmark, and conducting multiple experiments.

       void  benchmp(initialize,  benchmark,  cleanup,  enough,  parallel,  warmup,  repetitions,
       cookie)
              measures  the  performance  of  benchmark repeatedly and reports the median result.
              benchmp creates parallel sub-processes  which  run  benchmark  in  parallel.   This
              allows  lmbench  to  measure  the system's ability to scale as the number of client
              processes increases.  Each sub-process  executes  initialize  before  starting  the
              benchmarking  cycle.   It  will  call  benchmark  several times in order to collect
              repetitions results.  After all the benchmark results have been collected,  cleanup
              is  called  to cleanup any resources which may have been allocated by initialize or
              benchmark .  cookie is a void pointer to a hunk of memory that can be used to store
              any parameters or state that is needed by the benchmark.

       void benchmp_getstate()
              returns a void pointer to the lmbench-internal state used during benchmarking.  The
              state is not to be used or accessed directly by clients, but rather would be passed
              into benchmp_interval.

       iter_t benchmp_interval(void* state)
              returns  the number of times the benchmark should execute its benchmark loop during
              this timing interval.   This  is  used  only  for  weird  benchmarks  which  cannot
              implement the benchmark body in a function which can return, such as the page fault
              handler.  Please see lat_sig.c for sample usage.

       void start(struct timeval *begin)
              starts a timing interval.  If begin is non-null, save the start time in begin .

       uint64 stop(struct timeval *begin, struct timeval *end)
              stops a timing interval, returning the number of elapsed micro-seconds.

       uint64 get_n()
              returns the number of times loop_body was executed during the timing interval.

       void set_n(uint64 n)
              sets the number of times loop_body was executed during the timing interval.

       uint64 gettime()
              returns the number of micro-seconds in the timing interval.

       void settime(uint64 u)
              sets the number of micro-seconds in the timing interval.

       uint64 get_enough(uint64 enough)
              return the time in micro-seconds needed to accurately measure a timing interval.

       uint64 t_overhead()
              return the time in micro-seconds needed to measure time.

       double l_overhead()
              return the time in micro-seconds needed to do a simple loop.

VARIABLES

       There are three environment variables that can  be  used  to  modify  the  lmbench  timing
       subsystem:  ENOUGH,  TIMING_O,  and  LOOP_O.   The  environment  variables  can be used to
       directly set the results of get_enough , t_overhead , and l_overhead  .   When  running  a
       large number of benchmarks, or repeating the same benchmark many times, this can save time
       by eliminating the necessity of recalculating these values for each run.

FUTURES

       Development of lmbench is continuing.

SEE ALSO

       lmbench(8), lmbench(3), reporting(3), results(3).

AUTHOR

       Carl Staelin and Larry McVoy

       Comments, suggestions, and bug reports are always welcome.

(c)1998 Larry McVoy                          $Date:$                            lmbench timing(3)