SoPlex Doxygen Documentation
timer.h
Go to the documentation of this file.
1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2 /* */
3 /* This file is part of the class library */
4 /* SoPlex --- the Sequential object-oriented simPlex. */
5 /* */
6 /* Copyright (C) 1996-2012 Konrad-Zuse-Zentrum */
7 /* fuer Informationstechnik Berlin */
8 /* */
9 /* SoPlex is distributed under the terms of the ZIB Academic Licence. */
10 /* */
11 /* You should have received a copy of the ZIB Academic License */
12 /* along with SoPlex; see the file COPYING. If not email to soplex@zib.de. */
13 /* */
14 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
15 
16 /**@file timer.h
17  * @brief Timer class.
18  */
19 
20 #ifndef _TIMER_H_
21 #define _TIMER_H_
22 
23 #include "spxdefines.h"
24 
25 namespace soplex
26 {
27 /**@class Timer
28  @ingroup Elementary
29 
30  @brief Wrapper for the system time query methods.
31 
32  In C or C++ programs, the usual way to measure time intervals,
33  e.g., running times of some complex computations, is to call one
34  of the provided system functions like %clock(), %time(), %times(),
35  %gettimeofday(), %getrusage() etc. By these functions one can
36  gather information about the process' user and system time and the
37  system clock (real time).
38 
39  Unfortunately, these functions are rather clumsy. The programmer
40  determines computation times by querying a (virtual) clock value
41  at the beginning and another one at the end of some computation
42  and converting the difference of these values into seconds. Some
43  functions impose restrictions; for instance, the values of
44  the ANSI C function %clock() are of high resolution but will wrap
45  around after about 36 minutes (cpu time). Most timing functions
46  take some data structure as argument that has to be allocated
47  before the call and from which the user has to pick up the
48  information of interest after the call. Problems can arise when
49  porting programs to other operating systems that do not support
50  standards like POSIX etc.
51 
52  In order to simplify measuring computation times and to hide the
53  system-dependencies involved, a concept of \em timers accounting the
54  process' user, system and real time is implemented. C and C++ interfaces
55  are provided as a set of functions operating on timers and a timer class
56  respectively.
57 
58  The idea is to provide a type Timer for objects that act like a stopwatch.
59  Operations on such an objects include: start accounting time, stop
60  accounting, read the actual time account and reset the objects time account
61  to zero.
62 
63  After initialization, accounting for user, system and real time can be
64  started by calling a function start(). Accounting is suspended by calling
65  a function stop() and can be resumed at any time by calling start()
66  again.
67 
68  The user, system or real time actually accounted by a timer can be accessed
69  at any time by the methods shown in this code section:
70 
71  \verbatim
72  Real utime, stime, rtime;
73 
74  utime = timer.userTime();
75  stime = timer.systemTime();
76  rtime = timer.realTime();
77 
78  timer.getTimes(utime, stime rtime);
79  \endverbatim
80 
81  For convenience, the actually accounted user time is returned by stop()
82  too. Function reset() re-initializes a timer clearing all time
83  accounts.
84 
85  Function resolution() returns the smallest (non-zero) time intervall which
86  is resolved by the underlying system function: res = 1/Timer_resolution().
87 
88 
89  The process' user and system times are accessed by calling
90  function %times(), which is declared in \c <sys/times.h>. If OS
91  supports POSIX compatibility through providing \c <sys/unistd.h>,
92  set \c -DHAVE_UNISTD_H when compiling \c timer.c. Ignore compiler
93  warnings about missing prototypes of functions.
94 */
95 class Timer
96 {
97 private:
98 
99  //------------------------------------
100  /**@name Types */
101  //@{
102  /// status of the timer
103  enum
104  {
105  RESET, ///< reset
106  STOPPED, ///< stopped
107  RUNNING ///< running
108  } status; ///< timer status
109  //@}
110 
111  //------------------------------------
112  /**@name number of ticks per second */
113  //@{
114  static const long ticks_per_sec; ///< ticks per secound, should be constant
115  //@}
116 
117  //------------------------------------
118  /**@name Data */
119  //@{
120  long uAccount; ///< user time
121  long sAccount; ///< system time
122  long rAccount; ///< real time
123  mutable long uTicks; ///< user ticks
124  mutable long sTicks; ///< system ticks
125  mutable long rTicks; ///< real ticks
126  //@}
127 
128  //------------------------------------
129  /**@name Internal helpers */
130  //@{
131  /// convert ticks to secounds.
132  Real ticks2sec(long ticks) const
133  {
134  return (Real(ticks) * 1000.0 / Real(ticks_per_sec)) / 1000.0;
135  }
136 
137  /// get actual user, system and real ticks from the system.
138  void updateTicks() const;
139  //@}
140 
141 public:
142 
143  //------------------------------------
144  /**@name Construction / destruction */
145  //@{
146  /// default constructor
147  Timer()
148  : status(RESET), uAccount(0), sAccount(0), rAccount(0)
149  {
150  assert(ticks_per_sec > 0);
151  }
152  //@}
153 
154  //------------------------------------
155  /**@name Control */
156  //@{
157  /// initialize timer, set timing accounts to zero.
158  void reset()
159  {
160  status = RESET;
161  uAccount = rAccount = sAccount = 0;
162  }
163 
164  /// start timer, resume accounting user, system and real time.
165  void start();
166 
167  /// stop timer, return accounted user time.
168  Real stop();
169  //@}
170 
171  //------------------------------------
172  /**@name Access */
173  //@{
174  /// get accounted user, system or real time.
175  void getTimes( Real* userTime, Real* systemTime, Real* realTime) const;
176 
177  /// return accounted user time.
178  Real userTime() const;
179 
180  /// return accounted system time.
181  Real systemTime() const;
182 
183  /// return accounted real time.
184  Real realTime() const;
185 
186  /// return resolution of timer as 1/seconds.
187  long resolution() const { return ticks_per_sec; }
188  //@}
189 };
190 } // namespace soplex
191 #endif // _TIMER_H_
192 
193 //-----------------------------------------------------------------------------
194 //Emacs Local Variables:
195 //Emacs mode:c++
196 //Emacs c-basic-offset:3
197 //Emacs tab-width:8
198 //Emacs indent-tabs-mode:nil
199 //Emacs End:
200 //-----------------------------------------------------------------------------
201 
202 
203 
204 
205 
© 2003-2013 by Zuse Institute Berlin (ZIB), Imprint Generated on Wed Jan 9 2013 for SoPlex by doxygen