Timer Library Original Timers and Progress Display

The timer library provides two headers and three classes:

Header	Class	Functionality
timer.hpp	timer	Measure elapsed time.
progress.hpp	progress_timer	Measure elapsed time (using timer), display on destruction.
progress.hpp	progress_display	Display an indication of progress toward a known goal.

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.

Class timer

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.

Synopsis

#include <boost/timer.hpp>
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

Exception safety

The constructors may throw std::bad_alloc.  No other member functions throw exceptions.

Future directions

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.

Class progress_timer

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.

Class progress_timer is often used to time program execution.  Its use is as simple as:

#include <boost/progress.hpp>
int main()
{
   progress_timer t;  // start timing
   // do something ...
   return 0;
}

Which will produce some appropriate output, for example:

1.23 s

Note that "s" is the official System International d'Unités abbreviation for seconds.

Synopsis

#include <boost/progress.hpp>
namespace boost {
class progress_timer : public timer, noncopyable  {
 public:
   progress_timer();
   progress_timer( std::ostream& os ); // os is hint; implementation may ignore
   ~progress_timer();
   }; // progress_display
} // namespace boost

Exception safety

The constructors may throw std::bad_alloc.  No other member functions throw exceptions.

Class progress_display

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.

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:

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

After 70% of the elements have been processed, the display might look something like this:

0%   10   20   30   40   50   60   70   80   90   100%
|----|----|----|----|----|----|----|----|----|----|
************************************

Synopsis

#include <boost/progress.hpp>
namespace boost {
class progress_display : noncopyable {
 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

Exception safety

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.

History

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

Rationale

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.

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.

Revised: 04 October 2011

© Copyright Beman Dawes 1999.

Distributed under the Boost Software License, Version 1.0. See www.boost.org/LICENSE_1_0.txt