
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  
%%  timer.tex       LiDIA documentation
%%  
%%  This file contains the documentation of the class timer
%%  
%%  Copyright   (c)   1995   by  LiDIA-Group
%%  
%%  Authors: Thomas Papanikolaou
%%

\begin{lidia_man}
\markright{\BF{timer}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\BF{timer}             \DOTFILL                             timer class

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
\BF{timer} is a class of timer utilities. It can be used for example to
calculate  the elapsed time while executing a function, the time spent in the 
system and the time spent in the execution of the function.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
\BF{timer} is a class which simulates the functions of a chronometer. An
instance \MATH{T} of the data type \BF{timer} is an object consisting of 
the integer variables \BF{user\_time}, \BF{sys\_time} and local
variables which are used to store elapsed times.

A possible scenario of the use of \BF{timer} is to \IT{start} it at any 
place \MATH{t_1} of the program then \IT{stop} it at \MATH{t_2} and 
\IT{print} the elapsed \IT{real}, \IT{system} and \IT{user} time 
between \MATH{t_2} and \MATH{t_1}. \IT{Continuing} the timing and 
\IT{stopping} the timer once again at \MATH{t_3} stores in \IT{T} the 
sum of the elapsed times between \MATH{t_1} and \MATH{t_2} and \MATH{t_2}
and \MATH{t_3}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS
\fcode{ct}{timer}{}{}
\fcode{dt}{\SIM timer}{}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\INIT
\fcode{int}{T.set\_print\_mode}{int m}
{
this function sets the output mode \MATH{m} of the \TT{T.print()} 
function for \IT{T} and returns the old print mode. 
There are two predefined output modes: \TT{TIME\_MODE} and 
\TT{HMS\_MODE}. The output of the \TT{T.print()} function when 
\TT{TIME\_MODE} is set, has the following format:
\begin{center}
\TT{rrr real uuu user sss sys},
\end{center}
where \TT{rrr, uuu, sss} denote the real, user and system
time respectively (in 1/100 sec). In \TT{HMS\_MODE} the 
\TT{T.print()} function outputs the elapsed real time in the format
\begin{center}
\TT{hhh hour, mmm min, nnn sec, ttt ms},
\end{center}
where hhh, mmm, nnn and ttt denote the consumed hours, minutes, seconds
and milliseconds respectively.}

\fcode{void}{T.start\_timer}{}
{
this function initializes the timer with the current time and 
sets the elapsed time for this timer to zero.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ACCS
\fcode{int}{T.get\_print\_mode}{}
{
returns the output mode of the timer \MATH{T}. This 
mode is used by the \TT{T.print()} function.}

\fcode{long}{T.user\_time}{}
{
returns the user time elapsed during the last call of
\TT{T.start\_timer()}. The time is given in 1/100 seconds.}

\fcode{long}{T.sys\_time}{}
{
returns the system time elapsed during the last call of
\TT{T.start\_timer()}. The time is given in 1/100 seconds.}

\fcode{long}{T.real\_time}{}
{
returns \TT{T.user\_time()} + \TT{T.sys\_time()}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\HIGH
\fcode{void}{T.stop\_timer}{}
{
this function adds in \MATH{T} the elapsed time (user + system) 
since the last call of \TT{T.start\_timer()} or \TT{T.cont\_timer()}.}

\fcode{void}{T.cont\_timer}{}
{
this function sets the starting point for timing to the current 
time without changing the elapsed time in \IT{T}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\IO
The \BF{ostream}  operator \TT{<<} is overloaded. Furthermore there
exists the following member function for the output:

\fcode{void}{T.print}{}
{
prints the times elapsed between the last subsequent calls of
\TT{T.start\_timer()} and \TT{T.stop\_timer()}
according to the print mode of \MATH{T}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
getrusage(2)

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\WARNINGS
Subsequent calls of \TT{stop\_timer()} produce wrong results.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/timer.h>

 int main()
 {
   long i;
   timer x;

   x.set_print_mode(HMS_MODE);

   x.start_timer();
   for (i=0; i < 0x7fffff; i++);
   x.stop_timer();
   cout << endl;
   x.print();
   cout << endl;
   x.cont_timer();
   for (i=0; i < 0x7fffff; i++);
   x.stop_timer();
   cout << endl;
   x.print();
   cout << endl;
 }
\end{verbatim}	

For further references please refer to\\
\TT{src/system/timer\_appl.c}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Thomas Papanikolaou

\end{lidia_man}
