boost_1_45_0/libs/timer/timer.htm - nest-learning-thermostat/5.0/boost - Git at Google

 <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.&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;<a href="../../boost/timer.hpp">boost/timer.hpp</a>&gt;
 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>.&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;<a href="../../boost/progress.hpp">boost/progress.hpp</a>&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;<a href="../../boost/progress.hpp">boost/progress.hpp</a>&gt;
 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&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 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 &lt;boost/progress.hpp&gt;
 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&amp; os,  // os is hint; implementation may ignore
                      const std::string &amp; s1 = &quot;\n&quot;, //leading strings
                      const std::string &amp; s2 = &quot;&quot;,
                      const std::string &amp; s3 = &quot;&quot; )
    // 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.&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(). 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.&nbsp; 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.&nbsp; 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.&nbsp; John
 Maddock submitted an implementation using the Win32 API.&nbsp; 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.&nbsp;
 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.)&nbsp; 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>
	<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>