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>Original Timers</title> 9<style type="text/css"> 10 ins {background-color:#A0FFA0} 11 del {background-color:#FFA0A0} 12 body 13 { 14 font-family: sans-serif; 15 max-width : 8.5in; 16 margin: 1em; 17 } 18</style> 19</head> 20 21<body bgcolor="#FFFFFF" text="#000000"> 22 23<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="750"> 24 <tr> 25 <td width="300"> 26<a href="../../../index.htm"> 27<img src="../../../boost.png" alt="boost.png (6897 bytes)" align="middle" width="300" height="86" border="0"></a></td> 28 <td align="middle" width="430"> 29 <font size="7">Timer Library<br> 30 Original Timers and Progress Display</font></td> 31 </tr> 32</table> 33 34<table border="0" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" bgcolor="#D7EEFF" width="100%"> 35 <tr> 36 <td><a href="index.html">Timer Home</a> 37 <a href="cpu_timers.html">CPU timers</a> 38 <a href="original_timer.html">Original timers</a> 39 </td> 40 </tr> 41</table> 42 43<p></p> 44 45<center> 46 <table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse" bordercolor="#111111" width="80%"> 47 <tr> 48 <td width="100%" bgcolor="#FFFF66"> 49<p><i><b>These timers are deprecated.</b></i> They date from the earliest days 50of Boost and do not conform 51to current Boost practice.</p> 52<ul> 53 <li>The interfaces are the same across all platforms, but the semantics differ 54 according to platform. Wall-clock time is measured on Windows, while CPU time 55 is measured on POSIX-like systems.</li> 56 <li>The internal implementation uses only C/C++ standard library functions, so 57 cannot supply desirable precision and functionality.</li> 58 <li>The headers live in the main Boost header directory.</li> 59 <li>The content are in namespace <code>boost</code>.</li> 60</ul> 61 Please see the Version 2 62 <a href="cpu_timers.html">CPU timers</a> for replacements that conform to 63 current Boost practice.</td> 64 </tr> 65 </table> 66</center> 67 68<p>The timer library provides two headers and three classes: </p> 69 70<blockquote> 71 <table border="1" cellpadding="5"> 72 <tr> 73 <td><b>Header</b></td> 74 <td><b>Class</b></td> 75 <td><b>Functionality</b></td> 76 </tr> 77 <tr> 78 <td><a href="../../../boost/timer.hpp">timer.hpp</a></td> 79 <td><a href="#Class timer">timer</a></td> 80 <td>Measure elapsed time.</td> 81 </tr> 82 <tr> 83 <td><a href="../../../boost/progress.hpp">progress.hpp</a></td> 84 <td><a href="#Class progress_timer">progress_timer</a></td> 85 <td>Measure elapsed time (using timer), display on destruction.</td> 86 </tr> 87 <tr> 88 <td><a href="../../../boost/progress.hpp">progress.hpp</a></td> 89 <td><a href="#Class progress_display">progress_display</a></td> 90 <td>Display an indication of progress toward a known goal.</td> 91 </tr> 92 </table> 93</blockquote> 94<p>The objective in designing these classes was fairly limited - they are 95intended for simple uses like timing and reporting progress for programmer's 96tests or batch job streams. The specifications of the progress classes are 97worded in very general terms to permit alternate implementations such as for 98graphical user interfaces.</p> 99<h2><a name="Class timer">Class timer</a></h2> 100<p>Class timer measures elapsed time. It is generally useful for minor 101timing tasks. Its supplied implementation offers moderate portability at 102the cost of depending on the unknown accuracy and precision of the C Standard 103Library clock() function. The maximum measurable elapsed time may be as 104low as 596.5 hours (or even less) for the supplied implementation. Because of 105these limitations, this timer cannot be depended upon to 106be robust, and should not be used if that is of any concern.</p> 107<h3>Synopsis</h3> 108<pre>#include <<a href="../../../boost/timer.hpp">boost/timer.hpp</a>> 109namespace boost { 110class timer { 111 public: 112 timer(); // postcondition: elapsed()==0 113 // compiler generated copy constructor, copy assignment, and dtor apply 114 void restart(); // post: elapsed()==0 115 double elapsed() const; // return elapsed time in seconds 116 117 double elapsed_max() const; // return estimated maximum value for elapsed() 118 // Portability warning: elapsed_max() may return too high a value on systems 119 // where std::clock_t overflows or resets at surprising values. 120 121 double elapsed_min() const; // return minimum value for elapsed() 122 }; // timer 123} // namespace boost</pre> 124<h3>Exception safety</h3> 125<p>The constructors may throw <code>std::bad_alloc</code>. No other member 126functions throw exceptions.</p> 127<h3>Future directions</h3> 128<p>There was a very reasonable request from Ed Brey for a method of determining 129the maximum value which may be returned by elapsed(), but there isn't a way to do so 130portably. The issue has been raised with the group working on extended time functionality for the C language. A solution 131may be years in the future. In the meantime, elapsed_max() provides an 132approximation.</p> 133<h2><a name="Class progress_timer">Class progress_timer</a></h2> 134<p>Class progress_timer automatically measures elapsed time, and then on 135destruction displays an elapsed time message at an appropriate place in an appropriate form. 136The supplied implementation defaults to a character display on std::cout.</p> 137<p>Class progress_timer is often used to time program execution. Its use is as simple as:</p> 138<blockquote> 139 <pre>#include <<a href="../../../boost/progress.hpp">boost/progress.hpp</a>> 140int main() 141{ 142 progress_timer t; // start timing 143 // do something ... 144 return 0; 145}</pre> 146</blockquote> 147<p>Which will produce some appropriate output, for example:</p> 148<blockquote> 149 <pre>1.23 s</pre> 150</blockquote> 151<p>Note that "s" is the official System International d'Unit�s 152abbreviation for seconds.</p> 153<h3>Synopsis</h3> 154<pre>#include <<a href="../../../boost/progress.hpp">boost/progress.hpp</a>> 155namespace boost { 156class progress_timer : public <a href="#Class timer">timer</a>, <a href="../../core/doc/html/core/noncopyable.html">noncopyable</a> { 157 public: 158 progress_timer(); 159 progress_timer( std::ostream& os ); // os is hint; implementation may ignore 160 ~progress_timer(); 161 }; // progress_display 162} // namespace boost</pre> 163<h3>Exception safety</h3> 164<p>The constructors may throw <code>std::bad_alloc</code>. No other member 165functions throw exceptions.</p> 166<h2><a name="Class progress_display">Class progress_display</a></h2> 167<p>Class progress_display displays an appropriate indication of progress toward 168a predefined goal at an appropriate place in an appropriate form. This 169meets a human need to know if a program is progressing.</p> 170<p>For example, if a lengthy computation must be done on a std::map<> 171named big_map, the follow code would display an indication of progress:</p> 172<pre> progress_display show_progress( big_map.size() ); 173 for ( big_map_t::iterator itr = big_map:begin(); 174 itr != big_map.end(); ++itr ) 175 { 176 // do the computation 177 ... 178 ++show_progress; 179 }</pre> 180<p>After 70% of the elements have been processed, the display might look 181something like this:</p> 182<blockquote> 183 <pre>0% 10 20 30 40 50 60 70 80 90 100% 184|----|----|----|----|----|----|----|----|----|----| 185************************************</pre> 186</blockquote> 187 188<h2>Synopsis</h2> 189<pre>#include <boost/progress.hpp> 190namespace boost { 191class progress_display : <a href="../../core/doc/html/core/noncopyable.html">noncopyable</a> { 192 public: 193 progress_display( unsigned long expected_count ); 194 // Effects: restart(expected_count) 195 196 progress_display( unsigned long expected_count, 197 std::ostream& os, // os is hint; implementation may ignore 198 const std::string & s1 = "\n", //leading strings 199 const std::string & s2 = "", 200 const std::string & s3 = "" ) 201 // Effects: save copy of leading strings, restart(expected_count) 202 203 void restart( unsigned long expected_count ); 204 // Effects: display appropriate scale on three lines, 205 // prefaced by stored copy of s1, s2, s3, respectively, from constructor 206 // Postconditions: count()==0, expected_count()==expected_count 207 208 unsigned long operator+=( unsigned long increment ) 209 // Effects: Display appropriate progress tic if needed. 210 // Postconditions: count()== original count() + increment 211 // Returns: count(). 212 213 unsigned long operator++() 214 // Returns: operator+=( 1 ). 215 216 unsigned long count() const 217 // Returns: The internal count. 218 219 unsigned long expected_count() const 220 // Returns: The expected_count from the constructor. 221 222 }; // progress_display 223} // namespace boost</pre> 224<h3>Exception safety</h3> 225<p>All member functions except count() and expected_count() do output, and so in 226theory may throw exceptions. In practice it seems an exception being 227thrown is pretty unlikely, and probably implies such serious problems that an 228exception is warranted. Note that there is no explicit destructor, so the 229destructor throwing is not an issue.</p> 230<h2>History</h2> 231<p>These classes are descended from older C++ and C functionality found useful 232by programmers for many years. Via the Boost mailing list, Reid Sweatman 233suggested separating the more widely useful timer class from the more targeted 234progress classes. Sean Corfield suggested allowing output to any ostream. 235Dave Abrahams, Valentin Bonnard, Ed Brey, Andy Glew, and Dietmar K�hl also 236provided useful comments. Ed Brey suggested timer::elapsed_max(). John 237Maddock suggested timer::elapsed_min(). Toon Knapen suggested the optional 238leading strings, to allow for labeling the progress display</p> 239<h2>Rationale</h2> 240<p>The early versions of the timer classes had separate implementation 241files. This caused problems for users not wishing to build libraries, 242caused difficulties building DLL's (because of cascaded use of other libraries 243which in turn brought illuminated compiler deficiencies), and caused the classes 244not to be used even when clearly applicable. Thus the implementation was 245changed to all inline code.</p> 246<p>There have been several requests for platform specific implementations to use 247supposedly high-performance timers from the operating system API. John 248Maddock submitted an implementation using the Win32 API. Tests showed that 249while the precision of these timers was high, the latency was sometimes very 250much higher than for the std::clock() function, and that is very bad. 251Furthermore, results using the Win32 API were very dependent on both the 252compiler (Microsoft and Borland were tested) and the operating system version 253(Windows NT, Windows 95, etc.) Thus the std::clock() function was much 254more reliable, and so was retained even on this platform with its own timer API.</p> 255<hr> 256<p><font size="2">Revised: 257<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B %Y" startspan -->04 October 2011<!--webbot bot="Timestamp" endspan i-checksum="32185" --></font></p> 258 259<p><font size="2">� Copyright Beman Dawes 1999.</font></p> 260 261<p><font size="2">Distributed under the Boost Software License, Version 1.0. See 262</font> 263<a href="http://www.boost.org/LICENSE_1_0.txt"><font size="2">www.boost.org/LICENSE_1_0.txt</font></a></p> 264 265</body> 266 267</html>
