| [12] | 1 | <html> |
|---|
| 2 | |
|---|
| 3 | <head> |
|---|
| 4 | <meta http-equiv="Content-Language" content="en-us"> |
|---|
| 5 | <meta http-equiv="Content-Type" content="text/html; charset=windows-1252"> |
|---|
| 6 | <meta name="GENERATOR" content="Microsoft FrontPage 5.0"> |
|---|
| 7 | <meta name="ProgId" content="FrontPage.Editor.Document"> |
|---|
| 8 | <title>Boost Timer Documentation</title> |
|---|
| 9 | </head> |
|---|
| 10 | |
|---|
| 11 | <body bgcolor="#FFFFFF" text="#000000"> |
|---|
| 12 | |
|---|
| 13 | <h1> |
|---|
| 14 | <img src="../../boost.png" alt="boost.png (6897 bytes)" align="center" width="277" height="86"> |
|---|
| 15 | Timer Library</h1> |
|---|
| 16 | <p>The timer library provides two headers and three classes: </p> |
|---|
| 17 | |
|---|
| 18 | <blockquote> |
|---|
| 19 | <table border="1" cellpadding="5"> |
|---|
| 20 | <tr> |
|---|
| 21 | <td><b>Header</b></td> |
|---|
| 22 | <td><b>Class</b></td> |
|---|
| 23 | <td><b>Functionality</b></td> |
|---|
| 24 | </tr> |
|---|
| 25 | <tr> |
|---|
| 26 | <td><a href="../../boost/timer.hpp">timer.hpp</a></td> |
|---|
| 27 | <td><a href="#Class timer">timer</a></td> |
|---|
| 28 | <td>Measure elapsed time.</td> |
|---|
| 29 | </tr> |
|---|
| 30 | <tr> |
|---|
| 31 | <td><a href="../../boost/progress.hpp">progress.hpp</a></td> |
|---|
| 32 | <td><a href="#Class progress_timer">progress_timer</a></td> |
|---|
| 33 | <td>Measure elapsed time (using timer), display on destruction.</td> |
|---|
| 34 | </tr> |
|---|
| 35 | <tr> |
|---|
| 36 | <td><a href="../../boost/progress.hpp">progress.hpp</a></td> |
|---|
| 37 | <td><a href="#Class progress_display">progress_display</a></td> |
|---|
| 38 | <td>Display an indication of progress toward a known goal.</td> |
|---|
| 39 | </tr> |
|---|
| 40 | </table> |
|---|
| 41 | </blockquote> |
|---|
| 42 | <p>The objective in designing these classes was fairly limited - they are |
|---|
| 43 | intended for simple uses like timing and reporting progress for programmer's |
|---|
| 44 | tests or batch job streams. The specifications of the progress classes are |
|---|
| 45 | worded in very general terms to permit alternate implementations such as for |
|---|
| 46 | graphical user interfaces.</p> |
|---|
| 47 | <h2><a name="Class timer">Class timer</a></h2> |
|---|
| 48 | <p>Class timer measures elapsed time. It is generally useful for minor |
|---|
| 49 | timing tasks. Its supplied implementation offers moderate portability at |
|---|
| 50 | the cost of depending on the unknown accuracy and precision of the C Standard |
|---|
| 51 | Library clock() function. The maximum measurable elapsed time may be as |
|---|
| 52 | low as 596.5 hours (or even less) for the supplied implementation. Because of |
|---|
| 53 | these limitations, this timer cannot be depended upon to |
|---|
| 54 | be robust, and should not be used if that is of any concern.</p> |
|---|
| 55 | <h3>Synopsis</h3> |
|---|
| 56 | <pre>#include <<a href="../../boost/timer.hpp">boost/timer.hpp</a>> |
|---|
| 57 | namespace boost { |
|---|
| 58 | class timer { |
|---|
| 59 | public: |
|---|
| 60 | timer(); // postcondition: elapsed()==0 |
|---|
| 61 | // compiler generated copy constructor, copy assignment, and dtor apply |
|---|
| 62 | void restart(); // post: elapsed()==0 |
|---|
| 63 | double elapsed() const; // return elapsed time in seconds |
|---|
| 64 | |
|---|
| 65 | double elapsed_max() const; // return estimated maximum value for elapsed() |
|---|
| 66 | // Portability warning: elapsed_max() may return too high a value on systems |
|---|
| 67 | // where std::clock_t overflows or resets at surprising values. |
|---|
| 68 | |
|---|
| 69 | double elapsed_min() const; // return minimum value for elapsed() |
|---|
| 70 | }; // timer |
|---|
| 71 | } // namespace boost</pre> |
|---|
| 72 | <h3>Exception safety</h3> |
|---|
| 73 | <p>The constructors may throw <code>std::bad_alloc</code>. No other member |
|---|
| 74 | functions throw exceptions.</p> |
|---|
| 75 | <h3>Future directions</h3> |
|---|
| 76 | <p>There was a very reasonable request from Ed Brey for a method of determining |
|---|
| 77 | the maximum value which may be returned by elapsed(), but there isn't a way to do so |
|---|
| 78 | portably. The issue has been raised with the group working on extended time functionality for the C language. A solution |
|---|
| 79 | may be years in the future. In the meantime, elapsed_max() provides an |
|---|
| 80 | approximation.</p> |
|---|
| 81 | <h2><a name="Class progress_timer">Class progress_timer</a></h2> |
|---|
| 82 | <p>Class progress_timer automatically measures elapsed time, and then on |
|---|
| 83 | destruction displays an elapsed time message at an appropriate place in an appropriate form. |
|---|
| 84 | The supplied implementation defaults to a character display on std::cout.</p> |
|---|
| 85 | <p>Class progress_timer is often used to time program execution. Its use is as simple as:</p> |
|---|
| 86 | <blockquote> |
|---|
| 87 | <pre>#include <<a href="../../boost/progress.hpp">boost/progress.hpp</a>> |
|---|
| 88 | int main() |
|---|
| 89 | { |
|---|
| 90 | progress_timer t; // start timing |
|---|
| 91 | // do something ... |
|---|
| 92 | return 0; |
|---|
| 93 | }</pre> |
|---|
| 94 | </blockquote> |
|---|
| 95 | <p>Which will produce some appropriate output, for example:</p> |
|---|
| 96 | <blockquote> |
|---|
| 97 | <pre>1.23 s</pre> |
|---|
| 98 | </blockquote> |
|---|
| 99 | <p>Note that "s" is the official System International d'Unités |
|---|
| 100 | abbreviation for seconds.</p> |
|---|
| 101 | <h3>Synopsis</h3> |
|---|
| 102 | <pre>#include <<a href="../../boost/progress.hpp">boost/progress.hpp</a>> |
|---|
| 103 | namespace boost { |
|---|
| 104 | class progress_timer : public <a href="#Class timer">timer</a>, <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> { |
|---|
| 105 | public: |
|---|
| 106 | progress_timer(); |
|---|
| 107 | progress_timer( std::ostream& os ); // os is hint; implementation may ignore |
|---|
| 108 | ~progress_timer(); |
|---|
| 109 | }; // progress_display |
|---|
| 110 | } // namespace boost</pre> |
|---|
| 111 | <h3>Exception safety</h3> |
|---|
| 112 | <p>The constructors may throw <code>std::bad_alloc</code>. No other member |
|---|
| 113 | functions throw exceptions.</p> |
|---|
| 114 | <h2><a name="Class progress_display">Class progress_display</a></h2> |
|---|
| 115 | <p>Class progress_display displays an appropriate indication of progress toward |
|---|
| 116 | a predefined goal at an appropriate place in an appropriate form. This |
|---|
| 117 | meets a human need to know if a program is progressing.</p> |
|---|
| 118 | <p>For example, if a lengthy computation must be done on a std::map<> |
|---|
| 119 | named big_map, the follow code would display an indication of progress:</p> |
|---|
| 120 | <pre> progress_display show_progress( big_map.size() ); |
|---|
| 121 | for ( big_map_t::iterator itr = big_map:begin(); |
|---|
| 122 | itr != big_map.end(); ++itr ) |
|---|
| 123 | { |
|---|
| 124 | // do the computation |
|---|
| 125 | ... |
|---|
| 126 | ++show_progress; |
|---|
| 127 | }</pre> |
|---|
| 128 | <p>After 70% of the elements have been processed, the display might look |
|---|
| 129 | something like this:</p> |
|---|
| 130 | <blockquote> |
|---|
| 131 | <pre>0% 10 20 30 40 50 60 70 80 90 100% |
|---|
| 132 | |----|----|----|----|----|----|----|----|----|----| |
|---|
| 133 | ************************************</pre> |
|---|
| 134 | </blockquote> |
|---|
| 135 | |
|---|
| 136 | <h2>Synopsis</h2> |
|---|
| 137 | <pre>#include <boost/progress.hpp> |
|---|
| 138 | namespace boost { |
|---|
| 139 | class progress_display : <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a> { |
|---|
| 140 | public: |
|---|
| 141 | progress_display( unsigned long expected_count ); |
|---|
| 142 | // Effects: restart(expected_count) |
|---|
| 143 | |
|---|
| 144 | progress_display( unsigned long expected_count, |
|---|
| 145 | std::ostream& os, // os is hint; implementation may ignore |
|---|
| 146 | const std::string & s1 = "\n", //leading strings |
|---|
| 147 | const std::string & s2 = "", |
|---|
| 148 | const std::string & s3 = "" ) |
|---|
| 149 | // Effects: save copy of leading strings, restart(expected_count) |
|---|
| 150 | |
|---|
| 151 | void restart( unsigned long expected_count ); |
|---|
| 152 | // Effects: display appropriate scale on three lines, |
|---|
| 153 | // prefaced by stored copy of s1, s2, s3, respectively, from constructor |
|---|
| 154 | // Postconditions: count()==0, expected_count()==expected_count |
|---|
| 155 | |
|---|
| 156 | unsigned long operator+=( unsigned long increment ) |
|---|
| 157 | // Effects: Display appropriate progress tic if needed. |
|---|
| 158 | // Postconditions: count()== original count() + increment |
|---|
| 159 | // Returns: count(). |
|---|
| 160 | |
|---|
| 161 | unsigned long operator++() |
|---|
| 162 | // Returns: operator+=( 1 ). |
|---|
| 163 | |
|---|
| 164 | unsigned long count() const |
|---|
| 165 | // Returns: The internal count. |
|---|
| 166 | |
|---|
| 167 | unsigned long expected_count() const |
|---|
| 168 | // Returns: The expected_count from the constructor. |
|---|
| 169 | |
|---|
| 170 | }; // progress_display |
|---|
| 171 | } // namespace boost</pre> |
|---|
| 172 | <h3>Exception safety</h3> |
|---|
| 173 | <p>All member functions except count() and expected_count() do output, and so in |
|---|
| 174 | theory may throw exceptions. In practice it seems an exception being |
|---|
| 175 | thrown is pretty unlikely, and probably implies such serious problems that an |
|---|
| 176 | exception is warranted. Note that there is no explicit destructor, so the |
|---|
| 177 | destructor throwing is not an issue.</p> |
|---|
| 178 | <h2>History</h2> |
|---|
| 179 | <p>These classes are descended from older C++ and C functionality found useful |
|---|
| 180 | by programmers for many years. Via the Boost mailing list, Reid Sweatman |
|---|
| 181 | suggested separating the more widely useful timer class from the more targeted |
|---|
| 182 | progress classes. Sean Corfield suggested allowing output to any ostream. |
|---|
| 183 | Dave Abrahams, Valentin Bonnard, Ed Brey, Andy Glew, and Dietmar Kühl also |
|---|
| 184 | provided useful comments. Ed Brey suggested timer::elapsed_max(). John |
|---|
| 185 | Maddock suggested timer::elapsed_min(). Toon Knapen suggested the optional |
|---|
| 186 | leading strings, to allow for labeling the progress display</p> |
|---|
| 187 | <h2>Rationale</h2> |
|---|
| 188 | <p>The early versions of the timer classes had separate implementation |
|---|
| 189 | files. This caused problems for users not wishing to build libraries, |
|---|
| 190 | caused difficulties building DLL's (because of cascaded use of other libraries |
|---|
| 191 | which in turn brought illuminated compiler deficiencies), and caused the classes |
|---|
| 192 | not to be used even when clearly applicable. Thus the implementation was |
|---|
| 193 | changed to all inline code.</p> |
|---|
| 194 | <p>There have been several requests for platform specific implementations to use |
|---|
| 195 | supposedly high-performance timers from the operating system API. John |
|---|
| 196 | Maddock submitted an implementation using the Win32 API. Tests showed that |
|---|
| 197 | while the precision of these timers was high, the latency was sometimes very |
|---|
| 198 | much higher than for the std::clock() function, and that is very bad. |
|---|
| 199 | Furthermore, results using the Win32 API were very dependent on both the |
|---|
| 200 | compiler (Microsoft and Borland were tested) and the operating system version |
|---|
| 201 | (Windows NT, Windows 95, etc.) Thus the std::clock() function was much |
|---|
| 202 | more reliable, and so was retained even on this platform with its own timer API.</p> |
|---|
| 203 | <hr> |
|---|
| 204 | <p>© Copyright Beman Dawes 1999. Permission to copy, use, modify, sell and |
|---|
| 205 | distribute this document is granted provided this copyright notice appears in |
|---|
| 206 | all copies. The software described is provided "as is" without express |
|---|
| 207 | or implied warranty, and with no claim as to its suitability for any |
|---|
| 208 | purpose.</p> |
|---|
| 209 | |
|---|
| 210 | <p>Revised <!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%B %d, %Y" startspan -->January 11, 2002<!--webbot bot="Timestamp" i-checksum="31071" endspan --> |
|---|
| 211 | </p> |
|---|
| 212 | |
|---|
| 213 | </body> |
|---|
| 214 | |
|---|
| 215 | </html> |
|---|
