Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
118 lines (90 sloc) 4.54 KB
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.
You can’t perform that action at this time.