boost/timer
2
0
Fork 0
mirror of https://github.com/boostorg/timer.git synced 2026-01-22 17:52:19 +00:00
Code Issues Projects Releases Wiki Activity

This commit was manufactured by cvs2svn to create tag

Browse Source 
'Version_1_18_2'.

[SVN r8120]
This commit is contained in:
nobody
2000-11-03 20:02:18 +00:00
parent 77f6a79f5f 6d7f6b95a3
commit 925c170ec5
2 changed files with 238 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
index.htm Normal file
View File

@@ -0,0 +1,43 @@
<html>
<head>
<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 Library</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<table border="1" bgcolor="#007F7F" cellpadding="2">
<tr>
<td bgcolor="#FFFFFF"><img src="../../c++boost.gif" alt="c++boost.gif (8819 bytes)" width="277" height="86"></td>
<td><a href="../../index.htm"><font face="Arial" color="#FFFFFF"><big>Home </big></font></a></td>
<td><a href="../../libraries.htm"><font face="Arial" color="#FFFFFF"><big>Libraries </big></font></a></td>
<td><a href="../../people.htm"><font face="Arial" color="#FFFFFF"><big>People </big></font></a></td>
<td><a href="../../more/faq.htm"><font face="Arial" color="#FFFFFF"><big>FAQ </big></font></a></td>
<td><a href="../../more/index.htm"><font face="Arial" color="#FFFFFF"><big>More </big></font></a></td>
</tr>
</table>
<h1>Timer library</h1>
<p>The timer library supplies a timer class for measuring elapsed time, a
progress_timer class for reporting elapsed time, and a progress_display class
for displaying an indication of progress toward a goal.
<ul>
<li><a href="timer.htm">Documentation</a> (HTML).</li>
<li>Headers <a href="../../boost/timer.hpp">timer.hpp</a> and <a href="../../boost/progress.hpp">progress.hpp</a></li>
<li>Test program <a href="timer_test.cpp">timer_test.cpp</a></li>
<li>Implementation files&nbsp;<a href="timer.cpp">timer.cpp</a>, <a href="prg_display.cpp">prg_display.cpp</a>,
<a href="prg_timer.cpp">prg_timer.cpp</a>.</li>
<li>Download <a href="../../boost_all.zip"> all of Boost</a> (ZIP format).</li>
<li>Submitted by <a href="../../people/beman_dawes.html">Beman Dawes</a>.</li>
</ul>
<p>Revised July 23, 1999</p>
</body>
</html>

195
timer.htm Normal file
View File

@@ -0,0 +1,195 @@
<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.&nbsp; It is generally useful for minor
timing tasks.&nbsp; Its supplied implementation offers moderate portability at
the cost of depending on the unknown accuracy and precision of the C Standard
Library clock() function.&nbsp; 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 &lt;boost/timer.hpp&gt;
namespace boost {
class timer {
public:
timer(); // postcondition: elapsed()==0
timer( const timer&amp; src ); // post: elapsed()==src.elapsed()
~timer();
timer&amp; operator=( const timer&amp; 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>.&nbsp; 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.&nbsp;
The supplied implementation defaults to a character display on std::cout.</p>
<p>Class progress_timer is often used to time program execution.&nbsp; Its use is as simple as:</p>
<blockquote>
<pre>#include &lt;boost/progress.hpp&gt;
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 &quot;s&quot; is the official System International d'Unités
abbreviation for seconds.</p>
<h3>Synopsis</h3>
<pre>#include &lt;boost/progress.hpp&gt;
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&amp; 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>.&nbsp; 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.&nbsp; 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&lt;&gt;
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 &lt;boost/progress.hpp&gt;
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&amp; 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.&nbsp; In practice it seems an exception being
thrown is pretty unlikely, and probably implies such serious problems that an
exception is warranted.&nbsp; 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.&nbsp;
Dave Abrahams, Valentin Bonnard, Ed Brey, Andy Glew, and Dietmar Kühl also
provided useful comments.&nbsp; 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 &quot;as is&quot; without express
or implied&nbsp; 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>