1    	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
2    	/*                                                                           */
3    	/*                  This file is part of the class library                   */
4    	/*       SoPlex --- the Sequential object-oriented simPlex.                  */
5    	/*                                                                           */
6    	/*  Copyright (c) 1996-2023 Zuse Institute Berlin (ZIB)                      */
7    	/*                                                                           */
8    	/*  Licensed under the Apache License, Version 2.0 (the "License");          */
9    	/*  you may not use this file except in compliance with the License.         */
10   	/*  You may obtain a copy of the License at                                  */
11   	/*                                                                           */
12   	/*      http://www.apache.org/licenses/LICENSE-2.0                           */
13   	/*                                                                           */
14   	/*  Unless required by applicable law or agreed to in writing, software      */
15   	/*  distributed under the License is distributed on an "AS IS" BASIS,        */
16   	/*  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. */
17   	/*  See the License for the specific language governing permissions and      */
18   	/*  limitations under the License.                                           */
19   	/*                                                                           */
20   	/*  You should have received a copy of the Apache-2.0 license                */
21   	/*  along with SoPlex; see the file LICENSE. If not email to soplex@zib.de.  */
22   	/*                                                                           */
23   	/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
24   	
25   	/**@file  timer.h
26   	 * @brief Timer class.
27   	 */
28   	
29   	#ifndef _TIMER_H_
30   	#define _TIMER_H_
31   	
32   	#include "soplex/spxdefines.h"
33   	
34   	namespace soplex
35   	{
36   	/**@class   Timer
37   	   @ingroup Elementary
38   	
39   	   @brief Wrapper for the system time query methods.
40   	
41   	    In C or C++ programs, the usual way to measure time intervals,
42   	    e.g., running times of some complex computations, is to call one
43   	    of the provided system functions like %clock(), %time(), %times(),
44   	    %gettimeofday(), %getrusage() etc.  By these functions one can
45   	    gather information about the process' user and system time and the
46   	    system clock (real time).
47   	
48   	    Unfortunately, these functions are rather clumsy.  The programmer
49   	    determines computation times by querying a (virtual) clock value
50   	    at the beginning and another one at the end of some computation
51   	    and converting the difference of these values into seconds.  Some
52   	    functions impose restrictions; for instance, the values of
53   	    the ANSI C function %clock() are of high resolution but will wrap
54   	    around after about 36 minutes (cpu time).  Most timing functions
55   	    take some data structure as argument that has to be allocated
56   	    before the call and from which the user has to pick up the
57   	    information of interest after the call.  Problems can arise when
58   	    porting programs to other operating systems that do not support
59   	    standards like POSIX etc.
60   	
61   	    In order to simplify measuring computation times and to hide the
62   	    system-dependencies involved, a concept of \em timers accounting the
63   	    process' system and real time is implemented.  C and C++ interfaces
64   	    are provided as a set of functions operating on timers and a timer class
65   	    respectively.
66   	
67   	    Look into the file timerfactory.h to see how to switch between different
68   	    timing types or to disable timing altogether.
69   	
70   	    The idea is to provide a type Timer for objects that act like a stopwatch.
71   	    Operations on such an objects include: start accounting time, stop
72   	    accounting, read the actual time account and reset the objects time account
73   	    to zero.
74   	
75   	    After initialization, accounting for the time can be
76   	    started by calling a function start(). Accounting is suspended by calling
77   	    a function stop() and can be resumed at any time by calling start()
78   	    again.
79   	
80   	    For convenience, the actually accounted user time is returned by stop()
81   	    too.  Function reset() re-initializes a timer clearing all time
82   	    accounts.
83   	
84   	*/
85   	class Timer
86   	{
87   	protected:
88   	
89   	   //------------------------------------
90   	   /**@name Types */
91   	   ///@{
92   	   /// status of the timer
93   	   enum
94   	   {
95   	      RESET,                   ///< reset
96   	      STOPPED,                 ///< stopped
97   	      RUNNING                  ///< running
98   	   } status;                   ///< timer status
99   	
100  	   ///@}
101  	
102  	public:
103  	
104  	   //------------------------------------
105  	   /**@name Timers */
106  	   ///@{
107  	   /// types of timers
108  	   typedef enum
109  	   {
110  	      OFF = 0,
111  	      USER_TIME = 1,
112  	      WALLCLOCK_TIME = 2
113  	   } TYPE;
114  	   ///@}
115  	
116  	   //------------------------------------
117  	   /**@name Construction / destruction */
118  	   ///@{
119  	   /// default constructor
120  	   Timer()
121  	      : status(RESET)
122  	   {}
123  	   /// copy constructor
124  	   Timer(const Timer& old)
125  	      : status(old.status)
126  	   {}
127  	   /// assignment operator
128  	   Timer& operator=(const Timer& old)
129  	   {
130  	      status = old.status;
131  	      return *this;
132  	   }
133  	   virtual ~Timer()
134  	   {}
135  	   ///@}
136  	
137  	   //------------------------------------
138  	   /**@name Control */
139  	   ///@{
140  	   /// initialize timer, set timing accounts to zero.
141  	   virtual void reset() = 0;
142  	
143  	   /// start timer, resume accounting user, system and real time.
144  	   virtual void start() = 0;
145  	
146  	   /// stop timer, return accounted user time.
147  	   virtual Real stop() = 0;
148  	
149  	   /// return type of timer
150  	   virtual TYPE type() = 0;
151  	   ///@}
152  	
153  	   //------------------------------------
154  	   /**@name Access */
155  	   ///@{
156  	   /// return accounted time.
157  	   /// get accounted user, system, or real time when ticks were updated last
158  	   void getLastTimes(Real* userTime, Real* systemTime, Real* realTime) const;
159  	
160  	
161  	   virtual Real time() const = 0;
162  	
163  	   /// return last accounted time without rechecking the clock
164  	   virtual Real lastTime() const = 0;
165  	
166  	
167  	   /// return accounted real time without rechecking the clock
168  	   Real realTimeLast() const;
169  	
170  	   ///@}
171  	};
172  	} // namespace soplex
173  	#endif // _TIMER_H_
174