.\"
.\" @(#)timing.man	2.0 98/04/24
.\"
.\"   timing - lmbench timing subsystem
.\"
.\"   Copyright (C) 1998  Carl Staelin and Larry McVoy
.\"   E-mail: staelin@hpl.hp.com
.\"
.TH "lmbench timing" 3 "$Date$" "(c)1998 Larry McVoy" "LMBENCH"
.SH "NAME"
BENCH, BENCH_OVERHEAD, BENCH1, start, stop, get_n, set_n, gettime, settime,
	get_enough, t_overhead, l_overhead \- the lmbench timing subsystem
.SH "SYNOPSIS"
.ft C
#include "lmbench.h"
.br
BENCH(loop_body, enough)
.br
BENCH_OVERHEAD(loop_body, overhead_loop, enough)
.br
BENCH1(loop_body, enough)
.br
void	start(struct timeval *begin);
.br
uint64	stop(struct timeval *begin, struct timeval *end);
.br
uint64	get_n();
.br
void	set_n(uint64 n);
.br
uint64	gettime();
.br
void	settime(uint64 u);
.br
uint64	get_enough(uint64 enough);
.br
uint64	t_overhead();
.br
double	l_overhead();
.ft R
.SH "DESCRIPTION"
The single most important element of a good benchmarking system is
the quality and reliability of its measurement system.  
.IR lmbench 's
timing subsystem manages the experimental timing process to produce
accurate results in the least possible time.  
.I lmbench 
includes methods for measuring and eliminating several factors that 
influence  the accuracy of timing measurements, such as the resolution 
of the system clock.
.PP
.I lmbench 
gets accurate results by considering clock resolution, 
auto-sizing the duration of each benchmark, and conducting multiple
experiments.  
.TP
.B "BENCH(loop_body, enough)"
measures the performance of 
.I loop_body
repeatedly and report the median result.
.TP
.B "BENCH_OVERHEAD(loop_body, overhead_loop, enough)"
repeatedly measures the performance of 
.I loop_body 
and subtract the time in 
.I overhead_loop 
and reports the median result.
.TP
.B "BENCH1(loop_body, enough)"
measures the performance of 
.I loop_body
once.
.TP
.B "void	start(struct timeval *begin)"
start a timing interval.  If
.I begin 
is non-null, save the start time in 
.I begin .
.TP
.B "uint64	stop(struct timeval *begin, struct timeval *end)"
stop a timing interval, returning the number of elapsed micro-seconds.
.TP
.B "uint64	get_n()"
returns the number of times 
.I loop_body 
was executed during the timing interval.
.TP
.B "void	set_n(uint64 n)"
sets the number of times 
.I loop_body 
was executed during the timing interval.
.TP
.B "uint64	gettime()"
returns the number of micro-seconds in the timing interval.
.TP
.B "void	settime(uint64 u)"
sets the number of micro-seconds in the timing interval.
.TP
.B "uint64	get_enough(uint64 enough)"
return the time in micro-seconds needed to accurately measure 
a timing interval.
.TP
.B "uint64	t_overhead()"
return the time in micro-seconds needed to measure time.
.TP
.B "double	l_overhead()"
return the time in micro-seconds needed to do a simple loop.
.SH "VARIABLES"
There are three environment variables that can be used to modify
the 
.I lmbench 
timing subsystem: ENOUGH, TIMING_O, and LOOP_O.
The environment variables can be used to directly set the results
of 
.B get_enough , 
.B t_overhead , 
and 
.B 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.
.SH "FUTURES"
Development of 
.I lmbench 
is continuing.  
.SH "SEE ALSO"
lmbench(8), lmbench(3), reporting(3), results(3), gettimeofday(2).
.SH "AUTHOR"
Carl Staelin and Larry McVoy
.PP
Comments, suggestions, and bug reports are always welcome.