The stopwatch module measures the elapsed (wall clock) time, CPU time,
and system time consumed by any part of a program.

The simple way to measure the CPU time consumption in an ANSI C
program is:

\begin{cchunk}
    clock_t  t0, t1;
    t0 = clock();
    /* do_stuff */
    t1 = clock();
    printf("cpu time: %.2f\n", (double) (t1-t0)/(double) CLOCKS_PER_SEC);
\end{cchunk}

The stopwatch module is just an elaboration of this.  It tracks
elapsed and system time, in addition to cpu time; it hides the details
of converting a time difference in hardware clock ticks to a
human-interpretable time in seconds; and it provides a standard output
function for formatting times, similar to the output of the standard
UNIX \ccode{time} command line utility for timing processes.

\begin{table}[hb]
\begin{tabular}{ll}\hline
\ccode{esl\_stopwatch\_Create()}  & Creates new stopwatch.\\
\ccode{esl\_stopwatch\_Destroy()} & Frees a stopwatch.\\
\ccode{esl\_stopwatch\_Start()}   & Starts a stopwatch.\\
\ccode{esl\_stopwatch\_Stop()}    & Stops a stopwatch.\\
\ccode{esl\_stopwatch\_Display()} & Displays elapsed, cpu, and system time.\\
\ccode{esl\_stopwatch\_Include()} & Merges a stopwatch's time into a master.\\
\hline
\end{tabular}
\caption{The \eslmod{stopwatch} API.}
\label{tbl:stopwatch_api}
\end{table}

Table~\ref{tbl:stopwatch_api} lists the functions in the API.

Starting a stopwatch with \ccode{esl\_stopwatch\_Start()} initializes
a base time, t0. Stopping a stopwatch with
\ccode{esl\_stopwatch\_Stop()} takes the current time t1, and
internally computes and stores elapsed, cpu, and system time
differences (t1-t0). These stored times can be displayed at any time
using \ccode{esl\_stopwatch\_Display()}, until the next time the watch
is stopped. A stopwatch can be stopped any number of times, measuring
increasing time from the same base. A stopwatch can also be started
any number of times, resetting the base each time it is set.

Figure~\ref{fig:stopwatch_example} shows a small example that measures
a boring \ccode{sleep(5)} call, which will of course show an elapsed
wall time of 5 seconds.  Change the \ccode{sleep(5)} call to something
cpu- or system-intensive to see a non-zero measurement of cpu or
system time.

\begin{figure}
\input{cexcerpts/stopwatch_example}
\caption{An example of using the \eslmod{stopwatch} module.}
\label{fig:stopwatch_example}
\end{figure}

\subsection{Displaying and retrieving times}

The \ccode{esl\_stopwatch\_Display()} function prints a line
containing the cpu time, system time, aggregated cpu+system time, and
the elapsed (wall clock) time. For example:

\begin{cchunk}
CPU Time: 142.55u 7.17s 00:02:29.72 Elapsed: 00:02:35
\end{cchunk}

If you want to access the times in seconds for your own purposes, the
relevant fields in a stopped \ccode{ESL\_STOPWATCH} object are:

\begin{cchunk}
  double elapsed;               /* elapsed time, seconds */
  double user;                  /* CPU time, seconds     */
  double sys;                   /* system time, seconds  */
\end{cchunk}



\subsection{Stopwatch precision and system dependency}

Elapsed wall time is typically measured at low resolution, in units of
seconds (depending on the ANSI C \ccode{time\_t} definition on your
system). It is displayed with a precision of 1 sec.

CPU time is typically measured in high resolution, in units of
microseconds (depending on the value of POSIX \ccode{\_SC\_CLK\_TCK} or
ANSI C \ccode{CLOCKS\_PER\_SEC} on your system). It is displayed with a
precision of 0.01 sec.

System time is only determined on systems that provide a POSIX
\ccode{times()} function. Like CPU time, it is typically measured at
high resolution, in units of microseconds (depending on the POSIX
\ccode{\_SC\_CLK\_TCK} value on your system). It is displayed with a
precision of 0.01 sec.  On systems that do not provide a
POSIX-compliant \ccode{times()} function, system time is always
reported as 0.

\subsection{Aggregate times in parallelized code}

In parallelized code, you may want to aggregate results from multiple
stopwatches into a single overall time measurement. Examples include
aggregating times from worker processes in PVM or MPI applications, or
aggregating times from multiple execution threads on systems where the
\ccode{times()} function does not correctly aggregate threads for you.

The \ccode{esl\_stopwatch\_Include()} function adds the cpu and system
times in a ``client'' stopwatch to a ``master'' stopwatch. Both the
client and the master stopwatch must be stopped. The elapsed time in
the master stopwatch is not affected; it is assumed to be keeping
track of the real (wall clock) time.