Provided by: lmbench-doc_3.0-a9-1_all bug

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)