| <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> |
