mirror of
https://github.com/boostorg/timer.git
synced 2026-01-21 17:32:18 +00:00
196 lines
8.1 KiB
HTML
196 lines
8.1 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 4.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<title>Boost Timer Documentation</title>
|
|
</head>
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000">
|
|
|
|
<h1><img src="../../c++boost.gif" alt="c++boost.gif (8819 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>timer.hpp</td>
|
|
<td><a href="#Class timer">timer</a></td>
|
|
<td>Measure elapsed time.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>progress.hpp</td>
|
|
<td><a href="#Class progress_timer">progress_timer</a></td>
|
|
<td>Measure elapsed time (using timer), display on destruction.</td>
|
|
</tr>
|
|
<tr>
|
|
<td>progress.hpp</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 <boost/timer.hpp>
|
|
namespace boost {
|
|
class timer {
|
|
public:
|
|
timer(); // postcondition: elapsed()==0
|
|
timer( const timer& src ); // post: elapsed()==src.elapsed()
|
|
~timer();
|
|
timer& operator=( const timer& src ); // post: elapsed()==src.elapsed()
|
|
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 <boost/progress.hpp>
|
|
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 <boost/progress.hpp>
|
|
namespace boost {
|
|
class progress_timer : public <a href="#Class timer">timer</a>, <a href="../utility/utility.htm#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( big_map.size() ) show_progress;
|
|
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#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
|
|
// Effects: restart(expected_count)
|
|
|
|
void restart( unsigned long expected_count );
|
|
// Effects: display appropriate scale
|
|
// 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().</p>
|
|
<hr>
|
|
<p>© Copyright Beman Dawes 1999. Permission to copy, use, modify, sell and
|
|
distribute this document is granted provided this copyright notice appears in
|
|
all copies. The software described is provided "as is" without express
|
|
or implied warranty, and with no claim as to its suitability for any
|
|
purpose.</p>
|
|
|
|
<p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->May 05, 2000<!--webbot bot="Timestamp" endspan i-checksum="11109" -->
|
|
</p>
|
|
|
|
</body>
|
|
|
|
</html>
|