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 31 namespace canvas 32 { 33 namespace tools 34 { 35 /** Calculate elapsed time. 36 37 This class provides several time-measurement and 38 -management functions. In its simplest use-case, it 39 measures the time from its creation. 40 */ 41 class ElapsedTime 42 { 43 public: 44 /** Create a new ElapsedTime object 45 46 The moment of construction starts the time 47 measurement. That means, a subsequent getElapsedTime() 48 call will return the time difference between object 49 creation and getElapsedTime() call. 50 */ 51 ElapsedTime(); 52 53 /** Creates a new ElapsedTime object based on another 54 timer. 55 56 The moment of construction starts the time 57 measurement. That means, a subsequent getElapsedTime() 58 call will return the time difference between object 59 creation and getElapsedTime() call. All time values 60 are not taken from the system's time base, but from 61 the provided timer. 62 */ 63 ElapsedTime( ::boost::shared_ptr<ElapsedTime> const & pTimeBase ); 64 65 /** Gets this timer's base timer. 66 */ 67 ::boost::shared_ptr<ElapsedTime> const & getTimeBase() const; 68 69 /** Reset the time 70 71 The instance of the reset() call starts the time 72 measurement from scratch. That means, a subsequent 73 getElapsedTime() call will return the time difference 74 between reset() and getElapsedTime() call. 75 */ 76 void reset(); 77 78 /** Query the elapsed time 79 80 This method returns the elapsed time in seconds 81 between either the construction of this object, or the 82 last reset() call, if any (but see the time modulation 83 methods below, for means to modify the otherwise 84 continuous flow of time). 85 86 @return the elapsed time in seconds. 87 */ 88 double getElapsedTime() const; 89 90 /** Pauses the running timer. 91 92 This method stops the time, as returned by this 93 object, until continueTimer() is called. During this 94 period, getElapsedTime() will always return the same 95 time value (i.e. the instant when pauseTimer() was 96 called). 97 */ 98 void pauseTimer(); 99 100 /** Continues the paused timer. 101 102 This method re-enables the time flow, that is, time 103 starts running again for clients calling 104 getElapsedTime(). The (subtle) difference to the 105 holdTimer/releaseTimer() methods below is, that there 106 is no perceived time 'jump' between the pauseTimer() 107 call and the continueTimer() call, i.e. the time 108 starts over with the same value it has stopped on 109 pauseTimer(). 110 */ 111 void continueTimer(); 112 113 /** Adjusts the timer, hold and pause times. 114 115 This method modifies the time as returned by this 116 object by the specified amount. This affects the time 117 as returned by getElapsedTime(), regardless of the 118 mode (e.g. paused, or on hold). 119 120 @param fOffset 121 This value will be added to the current time, i.e. the 122 next call to getElapsedTime() (when performed 123 immediately) will be adjusted by fOffset. 124 125 @param bLimitToLastQueriedTime 126 Limits the given offset to the time that has been 127 taken via getElapsedTime() 128 */ 129 void adjustTimer( double fOffset, 130 bool bLimitToLastQueriedTime = true ); 131 132 /** Holds the current time. 133 134 This call makes the timer hold the current time 135 (e.g. getElapsedTime() will return the time when 136 holdTimer() was called), while the underlying time is 137 running on. When releaseTimer() is called, the time 138 will 'jump' to the then-current, underlying time. This 139 is equivalent to pressing the "interim time" button on 140 a stop watch, which shows this stopped time, while the 141 clock keeps running internally. 142 */ 143 void holdTimer(); 144 145 /** Releases a held timer. 146 147 After this call, the timer again returns the running 148 time on getElapsedTime(). 149 */ 150 void releaseTimer(); 151 152 private: 153 static double getSystemTime(); 154 double getCurrentTime() const; 155 double getElapsedTimeImpl() const; // does not set m_fLastQueriedTime 156 157 const ::boost::shared_ptr<ElapsedTime> m_pTimeBase; 158 159 /// To validate adjustTimer() calls with bLimitToLastQueriedTime=true 160 mutable double m_fLastQueriedTime; 161 162 /// Start time, from which the difference to the time base is returned 163 double m_fStartTime; 164 165 /// Instant, when last pause or hold started, relative to m_fStartTime 166 double m_fFrozenTime; 167 168 /// True, when in pause mode 169 bool m_bInPauseMode; 170 171 /// True, when in hold mode 172 bool m_bInHoldMode; 173 }; 174 175 } 176 } 177 178 #endif /* INCLUDED_CANVAS_ELAPSEDTIME_HXX */ 179