mirror of
https://github.com/boostorg/timer.git
synced 2026-01-20 17:12:14 +00:00
213 lines
9.6 KiB
HTML
213 lines
9.6 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<title>Boost Timer Documentation</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
|
|
<h1>
|
|
<img src="../../boost.png" alt="boost.png (6897 bytes)" align="center" width="277" height="86">
|
|
Timer Library</h1>
|
|
<p>The timer library provides two headers and three classes: </p>
|
|
|
|
<blockquote>
|
|
<table border="1" cellpadding="5">
|
|
<tr>
|
|
<td><b>Header</b></td>
|
|
<td><b>Class</b></td>
|
|
<td><b>Functionality</b></td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="../../boost/timer.hpp">timer.hpp</a></td>
|
|
<td><a href="#Class timer">timer</a></td>
|
|
<td>Measure elapsed time.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="../../boost/progress.hpp">progress.hpp</a></td>
|
|
<td><a href="#Class progress_timer">progress_timer</a></td>
|
|
<td>Measure elapsed time (using timer), display on destruction.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="../../boost/progress.hpp">progress.hpp</a></td>
|
|
<td><a href="#Class progress_display">progress_display</a></td>
|
|
<td>Display an indication of progress toward a known goal.</td>
|
|
</tr>
|
|
</table>
|
|
</blockquote>
|
|
<p>The objective in designing these classes was fairly limited - they are
|
|
intended for simple uses like timing and reporting progress for programmer's
|
|
tests or batch job streams. The specifications of the progress classes are
|
|
worded in very general terms to permit alternate implementations such as for
|
|
graphical user interfaces.</p>
|
|
<h2><a name="Class timer">Class timer</a></h2>
|
|
<p>Class timer measures elapsed time. It is generally useful for minor
|
|
timing tasks. Its supplied implementation offers moderate portability at
|
|
the cost of depending on the unknown accuracy and precision of the C Standard
|
|
Library clock() function. The maximum measurable elapsed time may be as
|
|
low as 596.5 hours (or even less) for the supplied implementation. Because of
|
|
these limitations, this timer cannot be depended upon to
|
|
be robust, and should not be used if that is of any concern.</p>
|
|
<h3>Synopsis</h3>
|
|
<pre>#include <<a href="../../boost/timer.hpp">boost/timer.hpp</a>>
|
|
namespace boost {
|
|
class timer {
|
|
public:
|
|
timer(); // postcondition: elapsed()==0
|
|
// compiler generated copy constructor, copy assignment, and dtor apply
|
|
void restart(); // post: elapsed()==0
|
|
double elapsed() const; // return elapsed time in seconds
|
|
|
|
double elapsed_max() const; // return estimated maximum value for elapsed()
|
|
// Portability warning: elapsed_max() may return too high a value on systems
|
|
// where std::clock_t overflows or resets at surprising values.
|
|
|
|
double elapsed_min() const; // return minimum value for elapsed()
|
|
}; // timer
|
|
} // namespace boost</pre>
|
|
<h3>Exception safety</h3>
|
|
<p>The constructors may throw <code>std::bad_alloc</code>. No other member
|
|
functions throw exceptions.</p>
|
|
<h3>Future directions</h3>
|
|
<p>There was a very reasonable request from Ed Brey for a method of determining
|
|
the maximum value which may be returned by elapsed(), but there isn't a way to do so
|
|
portably. The issue has been raised with the group working on extended time functionality for the C language. A solution
|
|
may be years in the future. In the meantime, elapsed_max() provides an
|
|
approximation.</p>
|
|
<h2><a name="Class progress_timer">Class progress_timer</a></h2>
|
|
<p>Class progress_timer automatically measures elapsed time, and then on
|
|
destruction displays an elapsed time message at an appropriate place in an appropriate form.
|
|
The supplied implementation defaults to a character display on std::cout.</p>
|
|
<p>Class progress_timer is often used to time program execution. Its use is as simple as:</p>
|
|
<blockquote>
|
|
<pre>#include <<a href="../../boost/progress.hpp">boost/progress.hpp</a>>
|
|
int main()
|
|
{
|
|
progress_timer t; // start timing
|
|
// do something ...
|
|
return 0;
|
|
}</pre>
|
|
</blockquote>
|
|
<p>Which will produce some appropriate output, for example:</p>
|
|
<blockquote>
|
|
<pre>1.23 s</pre>
|
|
</blockquote>
|
|
<p>Note that "s" is the official System International d'Unités
|
|
abbreviation for seconds.</p>
|
|
<h3>Synopsis</h3>
|
|
<pre>#include <<a href="../../boost/progress.hpp">boost/progress.hpp</a>>
|
|
namespace boost {
|
|
class progress_timer : public <a href="#Class timer">timer</a>, <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
|
|
public:
|
|
progress_timer();
|
|
progress_timer( std::ostream& os ); // os is hint; implementation may ignore
|
|
~progress_timer();
|
|
}; // progress_display
|
|
} // namespace boost</pre>
|
|
<h3>Exception safety</h3>
|
|
<p>The constructors may throw <code>std::bad_alloc</code>. No other member
|
|
functions throw exceptions.</p>
|
|
<h2><a name="Class progress_display">Class progress_display</a></h2>
|
|
<p>Class progress_display displays an appropriate indication of progress toward
|
|
a predefined goal at an appropriate place in an appropriate form. This
|
|
meets a human need to know if a program is progressing.</p>
|
|
<p>For example, if a lengthy computation must be done on a std::map<>
|
|
named big_map, the follow code would display an indication of progress:</p>
|
|
<pre> progress_display show_progress( big_map.size() );
|
|
for ( big_map_t::iterator itr = big_map:begin();
|
|
itr != big_map.end(); ++itr )
|
|
{
|
|
// do the computation
|
|
...
|
|
++show_progress;
|
|
}</pre>
|
|
<p>After 70% of the elements have been processed, the display might look
|
|
something like this:</p>
|
|
<blockquote>
|
|
<pre>0% 10 20 30 40 50 60 70 80 90 100%
|
|
|----|----|----|----|----|----|----|----|----|----|
|
|
************************************</pre>
|
|
</blockquote>
|
|
|
|
<h2>Synopsis</h2>
|
|
<pre>#include <boost/progress.hpp>
|
|
namespace boost {
|
|
class progress_display : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> {
|
|
public:
|
|
progress_display( unsigned long expected_count );
|
|
// Effects: restart(expected_count)
|
|
|
|
progress_display( unsigned long expected_count,
|
|
std::ostream& os, // os is hint; implementation may ignore
|
|
const std::string & s1 = "\n", //leading strings
|
|
const std::string & s2 = "",
|
|
const std::string & s3 = "" )
|
|
// Effects: save copy of leading strings, restart(expected_count)
|
|
|
|
void restart( unsigned long expected_count );
|
|
// Effects: display appropriate scale on three lines,
|
|
// prefaced by stored copy of s1, s2, s3, respectively, from constructor
|
|
// Postconditions: count()==0, expected_count()==expected_count
|
|
|
|
unsigned long operator+=( unsigned long increment )
|
|
// Effects: Display appropriate progress tic if needed.
|
|
// Postconditions: count()== original count() + increment
|
|
// Returns: count().
|
|
|
|
unsigned long operator++()
|
|
// Returns: operator+=( 1 ).
|
|
|
|
unsigned long count() const
|
|
// Returns: The internal count.
|
|
|
|
unsigned long expected_count() const
|
|
// Returns: The expected_count from the constructor.
|
|
|
|
}; // progress_display
|
|
} // namespace boost</pre>
|
|
<h3>Exception safety</h3>
|
|
<p>All member functions except count() and expected_count() do output, and so in
|
|
theory may throw exceptions. In practice it seems an exception being
|
|
thrown is pretty unlikely, and probably implies such serious problems that an
|
|
exception is warranted. Note that there is no explicit destructor, so the
|
|
destructor throwing is not an issue.</p>
|
|
<h2>History</h2>
|
|
<p>These classes are descended from older C++ and C functionality found useful
|
|
by programmers for many years. Via the Boost mailing list, Reid Sweatman
|
|
suggested separating the more widely useful timer class from the more targeted
|
|
progress classes. Sean Corfield suggested allowing output to any ostream.
|
|
Dave Abrahams, Valentin Bonnard, Ed Brey, Andy Glew, and Dietmar Kühl also
|
|
provided useful comments. Ed Brey suggested timer::elapsed_max(). John
|
|
Maddock suggested timer::elapsed_min(). Toon Knapen suggested the optional
|
|
leading strings, to allow for labeling the progress display</p>
|
|
<h2>Rationale</h2>
|
|
<p>The early versions of the timer classes had separate implementation
|
|
files. This caused problems for users not wishing to build libraries,
|
|
caused difficulties building DLL's (because of cascaded use of other libraries
|
|
which in turn brought illuminated compiler deficiencies), and caused the classes
|
|
not to be used even when clearly applicable. Thus the implementation was
|
|
changed to all inline code.</p>
|
|
<p>There have been several requests for platform specific implementations to use
|
|
supposedly high-performance timers from the operating system API. John
|
|
Maddock submitted an implementation using the Win32 API. Tests showed that
|
|
while the precision of these timers was high, the latency was sometimes very
|
|
much higher than for the std::clock() function, and that is very bad.
|
|
Furthermore, results using the Win32 API were very dependent on both the
|
|
compiler (Microsoft and Borland were tested) and the operating system version
|
|
(Windows NT, Windows 95, etc.) Thus the std::clock() function was much
|
|
more reliable, and so was retained even on this platform with its own timer API.</p>
|
|
<hr>
|
|
<p>© Copyright Beman Dawes 1999.<br>
|
|
Distributed under the Boost Software License, Version 1.0. See
|
|
<a href="http://www.boost.org/LICENSE_1_0.txt">www.boost.org/LICENSE_1_0.txt</a></p>
|
|
|
|
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->November 07, 2007<!--webbot bot="Timestamp" i-checksum="39599" endspan -->
|
|
</p>
|
|
|
|
</body>
|
|
|
|
</html> |