ceph/src/boost/libs/timer/doc/original_timer.html

   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> &nbsp;&nbsp;
  37     <a href="cpu_timers.html">CPU timers</a> &nbsp;&nbsp;
  38     <a href="original_timer.html">Original timers</a> &nbsp;&nbsp;
  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
  50 of Boost and do not conform
  51 to 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
  95 intended for simple uses like timing and reporting progress for programmer's
  96 tests or batch job streams. The specifications of the progress classes are
  97 worded in very general terms to permit alternate implementations such as for
  98 graphical user interfaces.</p>
  99 <h2><a name="Class timer">Class timer</a></h2>
 100 <p>Class timer measures elapsed time.&nbsp; It is generally useful for minor
 101 timing tasks.&nbsp; Its supplied implementation offers moderate portability at
 102 the cost of depending on the unknown accuracy and precision of the C Standard
 103 Library clock() function.&nbsp; The maximum measurable elapsed time may be as
 104 low as 596.5 hours (or even less) for the supplied implementation. Because of
 105 these limitations, this timer cannot be depended upon to
 106 be robust, and should not be used if that is of any concern.</p>
 107 <h3>Synopsis</h3>
 108 <pre>#include &lt;<a href="../../boost/timer.hpp">boost/timer.hpp</a>&gt;
 109 namespace boost {
 110 class 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>.&nbsp; No other member
 126 functions throw exceptions.</p>
 127 <h3>Future directions</h3>
 128 <p>There was a very reasonable request from Ed Brey for a method of determining
 129 the maximum value which may be returned by elapsed(), but there isn't a way to do so
 130 portably.  The issue has been raised with the group working on extended time functionality for the C language.  A solution
 131 may be years in the future. In the meantime, elapsed_max() provides an
 132 approximation.</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
 135 destruction displays an elapsed time message at an appropriate place in an appropriate form.&nbsp;
 136 The supplied implementation defaults to a character display on std::cout.</p>
 137 <p>Class progress_timer is often used to time program execution.&nbsp; Its use is as simple as:</p>
 138 <blockquote>
 139   <pre>#include &lt;<a href="../../boost/progress.hpp">boost/progress.hpp</a>&gt;
 140 int 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 &quot;s&quot; is the official System International d'Unités
 152 abbreviation for seconds.</p>
 153 <h3>Synopsis</h3>
 154 <pre>#include &lt;<a href="../../boost/progress.hpp">boost/progress.hpp</a>&gt;
 155 namespace boost {
 156 class progress_timer : public <a href="#Class timer">timer</a>, <a href="../utility/utility.htm#Class_noncopyable">noncopyable</a>  {
 157  public:
 158    progress_timer();
 159    progress_timer( std::ostream&amp; 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>.&nbsp; No other member
 165 functions 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
 168 a predefined goal at an appropriate place in an appropriate form.&nbsp; This
 169 meets 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&lt;&gt;
 171 named 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
 181 something 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 &lt;boost/progress.hpp&gt;
 190 namespace boost {
 191 class progress_display : <a href="../utility/utility.htm#Class_noncopyable">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&amp; os,  // os is hint; implementation may ignore
 198                      const std::string &amp; s1 = &quot;\n&quot;, //leading strings
 199                      const std::string &amp; s2 = &quot;&quot;,
 200                      const std::string &amp; s3 = &quot;&quot; )
 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
 226 theory may throw exceptions.&nbsp; In practice it seems an exception being
 227 thrown is pretty unlikely, and probably implies such serious problems that an
 228 exception is warranted.&nbsp; Note that there is no explicit destructor, so the
 229 destructor throwing is not an issue.</p>
 230 <h2>History</h2>
 231 <p>These classes are descended from older C++ and C functionality found useful
 232 by programmers for many years. Via the Boost mailing list, Reid Sweatman
 233 suggested separating the more widely useful timer class from the more targeted
 234 progress classes. Sean Corfield suggested allowing output to any ostream.&nbsp;
 235 Dave Abrahams, Valentin Bonnard, Ed Brey, Andy Glew, and Dietmar Kühl also
 236 provided useful comments.&nbsp; Ed Brey suggested timer::elapsed_max(). John
 237 Maddock suggested timer::elapsed_min(). Toon Knapen suggested the optional
 238 leading 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
 241 files.&nbsp; This caused problems for users not wishing to build libraries,
 242 caused difficulties building DLL's (because of cascaded use of other libraries
 243 which in turn brought illuminated compiler deficiencies), and caused the classes
 244 not to be used even when clearly applicable.&nbsp; Thus the implementation was
 245 changed to all inline code.</p>
 246 <p>There have been several requests for platform specific implementations to use
 247 supposedly high-performance timers from the operating system API.&nbsp; John
 248 Maddock submitted an implementation using the Win32 API.&nbsp; Tests showed that
 249 while the precision of these timers was high, the latency was sometimes very
 250 much higher than for the std::clock() function, and that is very bad.&nbsp;
 251 Furthermore, results using the Win32 API were very dependent on both the
 252 compiler (Microsoft and Borland were tested) and the operating system version
 253 (Windows NT, Windows 95, etc.)&nbsp; Thus the std::clock() function was much
 254 more 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>