1 /************************************************************** 2 * 3 * Licensed to the Apache Software Foundation (ASF) under one 4 * or more contributor license agreements. See the NOTICE file 5 * distributed with this work for additional information 6 * regarding copyright ownership. The ASF licenses this file 7 * to you under the Apache License, Version 2.0 (the 8 * "License"); you may not use this file except in compliance 9 * with the License. You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, 14 * software distributed under the License is distributed on an 15 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 16 * KIND, either express or implied. See the License for the 17 * specific language governing permissions and limitations 18 * under the License. 19 * 20 *************************************************************/ 21 22 23 24 #ifndef INCLUDED_CANVAS_ELAPSEDTIME_HXX 25 #define INCLUDED_CANVAS_ELAPSEDTIME_HXX 26 27 #include <sal/types.h> 28 29 #include "boost/shared_ptr.hpp" 30 #include <canvas/canvastoolsdllapi.h> 31 32 namespace canvas 33 { 34 namespace tools 35 { 36 /** Calculate elapsed time. 37 38 This class provides several time-measurement and 39 -management functions. In its simplest use-case, it 40 measures the time from its creation. 41 */ 42 class CANVASTOOLS_DLLPUBLIC ElapsedTime 43 { 44 public: 45 /** Create a new ElapsedTime object 46 47 The moment of construction starts the time 48 measurement. That means, a subsequent getElapsedTime() 49 call will return the time difference between object 50 creation and getElapsedTime() call. 51 */ 52 ElapsedTime(); 53 54 /** Creates a new ElapsedTime object based on another 55 timer. 56 57 The moment of construction starts the time 58 measurement. That means, a subsequent getElapsedTime() 59 call will return the time difference between object 60 creation and getElapsedTime() call. All time values 61 are not taken from the system's time base, but from 62 the provided timer. 63 */ 64 ElapsedTime( ::boost::shared_ptr<ElapsedTime> const & pTimeBase ); 65 66 /** Gets this timer's base timer. 67 */ 68 ::boost::shared_ptr<ElapsedTime> const & getTimeBase() const; 69 70 /** Reset the time 71 72 The instance of the reset() call starts the time 73 measurement from scratch. That means, a subsequent 74 getElapsedTime() call will return the time difference 75 between reset() and getElapsedTime() call. 76 */ 77 void reset(); 78 79 /** Query the elapsed time 80 81 This method returns the elapsed time in seconds 82 between either the construction of this object, or the 83 last reset() call, if any (but see the time modulation 84 methods below, for means to modify the otherwise 85 continuous flow of time). 86 87 @return the elapsed time in seconds. 88 */ 89 double getElapsedTime() const; 90 91 /** Pauses the running timer. 92 93 This method stops the time, as returned by this 94 object, until continueTimer() is called. During this 95 period, getElapsedTime() will always return the same 96 time value (i.e. the instant when pauseTimer() was 97 called). 98 */ 99 void pauseTimer(); 100 101 /** Continues the paused timer. 102 103 This method re-enables the time flow, that is, time 104 starts running again for clients calling 105 getElapsedTime(). The (subtle) difference to the 106 holdTimer/releaseTimer() methods below is, that there 107 is no perceived time 'jump' between the pauseTimer() 108 call and the continueTimer() call, i.e. the time 109 starts over with the same value it has stopped on 110 pauseTimer(). 111 */ 112 void continueTimer(); 113 114 /** Adjusts the timer, hold and pause times. 115 116 This method modifies the time as returned by this 117 object by the specified amount. This affects the time 118 as returned by getElapsedTime(), regardless of the 119 mode (e.g. paused, or on hold). 120 121 @param fOffset 122 This value will be added to the current time, i.e. the 123 next call to getElapsedTime() (when performed 124 immediately) will be adjusted by fOffset. 125 126 @param bLimitToLastQueriedTime 127 Limits the given offset to the time that has been 128 taken via getElapsedTime() 129 */ 130 void adjustTimer( double fOffset, 131 bool bLimitToLastQueriedTime = true ); 132 133 /** Holds the current time. 134 135 This call makes the timer hold the current time 136 (e.g. getElapsedTime() will return the time when 137 holdTimer() was called), while the underlying time is 138 running on. When releaseTimer() is called, the time 139 will 'jump' to the then-current, underlying time. This 140 is equivalent to pressing the "interim time" button on 141 a stop watch, which shows this stopped time, while the 142 clock keeps running internally. 143 */ 144 void holdTimer(); 145 146 /** Releases a held timer. 147 148 After this call, the timer again returns the running 149 time on getElapsedTime(). 150 */ 151 void releaseTimer(); 152 153 private: 154 static double getSystemTime(); 155 double getCurrentTime() const; 156 double getElapsedTimeImpl() const; // does not set m_fLastQueriedTime 157 158 const ::boost::shared_ptr<ElapsedTime> m_pTimeBase; 159 160 /// To validate adjustTimer() calls with bLimitToLastQueriedTime=true 161 mutable double m_fLastQueriedTime; 162 163 /// Start time, from which the difference to the time base is returned 164 double m_fStartTime; 165 166 /// Instant, when last pause or hold started, relative to m_fStartTime 167 double m_fFrozenTime; 168 169 /// True, when in pause mode 170 bool m_bInPauseMode; 171 172 /// True, when in hold mode 173 bool m_bInHoldMode; 174 }; 175 176 } 177 } 178 179 #endif /* INCLUDED_CANVAS_ELAPSEDTIME_HXX */ 180