qelapsedtimer.cpp

Jenkins

qelapsedtimer.cpp

Absolute File Name:

/home/qt/qt5_coco/qt5/qtbase/src/corelib/tools/qelapsedtimer.cpp

Line	Source	Count
1	/****************************************************************************	-
2	**	-
3	** Copyright (C) 2016 The Qt Company Ltd.	-
4	** Contact: https://www.qt.io/licensing/	-
5	**	-
6	** This file is part of the QtCore module of the Qt Toolkit.	-
7	**	-
8	** $QT_BEGIN_LICENSE:LGPL$	-
9	** Commercial License Usage	-
10	** Licensees holding valid commercial Qt licenses may use this file in	-
11	** accordance with the commercial license agreement provided with the	-
12	** Software or, alternatively, in accordance with the terms contained in	-
13	** a written agreement between you and The Qt Company. For licensing terms	-
14	** and conditions see https://www.qt.io/terms-conditions. For further	-
15	** information use the contact form at https://www.qt.io/contact-us.	-
16	**	-
17	** GNU Lesser General Public License Usage	-
18	** Alternatively, this file may be used under the terms of the GNU Lesser	-
19	** General Public License version 3 as published by the Free Software	-
20	** Foundation and appearing in the file LICENSE.LGPL3 included in the	-
21	** packaging of this file. Please review the following information to	-
22	** ensure the GNU Lesser General Public License version 3 requirements	-
23	** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.	-
24	**	-
25	** GNU General Public License Usage	-
26	** Alternatively, this file may be used under the terms of the GNU	-
27	** General Public License version 2.0 or (at your option) the GNU General	-
28	** Public license version 3 or any later version approved by the KDE Free	-
29	** Qt Foundation. The licenses are as published by the Free Software	-
30	** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3	-
31	** included in the packaging of this file. Please review the following	-
32	** information to ensure the GNU General Public License requirements will	-
33	** be met: https://www.gnu.org/licenses/gpl-2.0.html and	-
34	** https://www.gnu.org/licenses/gpl-3.0.html.	-
35	**	-
36	** $QT_END_LICENSE$	-
37	**	-
38	****************************************************************************/	-
39		-
40	#include "qelapsedtimer.h"	-
41		-
42	QT_BEGIN_NAMESPACE	-
43		-
44	/*!	-
45	\class QElapsedTimer	-
46	\inmodule QtCore	-
47	\brief The QElapsedTimer class provides a fast way to calculate elapsed times.	-
48	\since 4.7	-
49		-
50	\reentrant	-
51	\ingroup tools	-
52		-
53	The QElapsedTimer class is usually used to quickly calculate how much	-
54	time has elapsed between two events. Its API is similar to that of QTime,	-
55	so code that was using that can be ported quickly to the new class.	-
56		-
57	However, unlike QTime, QElapsedTimer tries to use monotonic clocks if	-
58	possible. This means it's not possible to convert QElapsedTimer objects	-
59	to a human-readable time.	-
60		-
61	The typical use-case for the class is to determine how much time was	-
62	spent in a slow operation. The simplest example of such a case is for	-
63	debugging purposes, as in the following example:	-
64		-
65	\snippet qelapsedtimer/main.cpp 0	-
66		-
67	In this example, the timer is started by a call to start() and the	-
68	elapsed timer is calculated by the elapsed() function.	-
69		-
70	The time elapsed can also be used to recalculate the time available for	-
71	another operation, after the first one is complete. This is useful when	-
72	the execution must complete within a certain time period, but several	-
73	steps are needed. The \tt{waitFor}-type functions in QIODevice and its	-
74	subclasses are good examples of such need. In that case, the code could	-
75	be as follows:	-
76		-
77	\snippet qelapsedtimer/main.cpp 1	-
78		-
79	Another use-case is to execute a certain operation for a specific	-
80	timeslice. For this, QElapsedTimer provides the hasExpired() convenience	-
81	function, which can be used to determine if a certain number of	-
82	milliseconds has already elapsed:	-
83		-
84	\snippet qelapsedtimer/main.cpp 2	-
85		-
86	\section1 Reference Clocks	-
87		-
88	QElapsedTimer will use the platform's monotonic reference clock in all	-
89	platforms that support it (see QElapsedTimer::isMonotonic()). This has	-
90	the added benefit that QElapsedTimer is immune to time adjustments, such	-
91	as the user correcting the time. Also unlike QTime, QElapsedTimer is	-
92	immune to changes in the timezone settings, such as daylight-saving	-
93	periods.	-
94		-
95	On the other hand, this means QElapsedTimer values can only be compared	-
96	with other values that use the same reference. This is especially true if	-
97	the time since the reference is extracted from the QElapsedTimer object	-
98	(QElapsedTimer::msecsSinceReference()) and serialised. These values	-
99	should never be exchanged across the network or saved to disk, since	-
100	there's no telling whether the computer node receiving the data is the	-
101	same as the one originating it or if it has rebooted since.	-
102		-
103	It is, however, possible to exchange the value with other processes	-
104	running on the same machine, provided that they also use the same	-
105	reference clock. QElapsedTimer will always use the same clock, so it's	-
106	safe to compare with the value coming from another process in the same	-
107	machine. If comparing to values produced by other APIs, you should check	-
108	that the clock used is the same as QElapsedTimer (see	-
109	QElapsedTimer::clockType()).	-
110		-
111	\section2 32-bit overflows	-
112		-
113	Some of the clocks used by QElapsedTimer have a limited range and may	-
114	overflow after hitting the upper limit (usually 32-bit). QElapsedTimer	-
115	deals with this overflow issue and presents a consistent timing. However,	-
116	when extracting the time since reference from QElapsedTimer, two	-
117	different processes in the same machine may have different understanding	-
118	of how much time has actually elapsed.	-
119		-
120	The information on which clocks types may overflow and how to remedy that	-
121	issue is documented along with the clock types.	-
122		-
123	\sa QTime, QTimer	-
124	*/	-
125		-
126	/*!	-
127	\enum QElapsedTimer::ClockType	-
128		-
129	This enum contains the different clock types that QElapsedTimer may use.	-
130		-
131	QElapsedTimer will always use the same clock type in a particular	-
132	machine, so this value will not change during the lifetime of a program.	-
133	It is provided so that QElapsedTimer can be used with other non-Qt	-
134	implementations, to guarantee that the same reference clock is being	-
135	used.	-
136		-
137	\value SystemTime The human-readable system time. This clock is not monotonic.	-
138	\value MonotonicClock The system's monotonic clock, usually found in Unix systems. This clock is monotonic and does not overflow.	-
139	\value TickCounter The system's tick counter, used on Windows systems. This clock may overflow.	-
140	\value MachAbsoluteTime The Mach kernel's absolute time (\macos and iOS). This clock is monotonic and does not overflow.	-
141	\value PerformanceCounter The high-resolution performance counter provided by Windows. This clock is monotonic and does not overflow.	-
142		-
143	\section2 SystemTime	-
144		-
145	The system time clock is purely the real time, expressed in milliseconds	-
146	since Jan 1, 1970 at 0:00 UTC. It's equivalent to the value returned by	-
147	the C and POSIX \tt{time} function, with the milliseconds added. This	-
148	clock type is currently only used on Unix systems that do not support	-
149	monotonic clocks (see below).	-
150		-
151	This is the only non-monotonic clock that QElapsedTimer may use.	-
152		-
153	\section2 MonotonicClock	-
154		-
155	This is the system's monotonic clock, expressed in milliseconds since an	-
156	arbitrary point in the past. This clock type is used on Unix systems	-
157	which support POSIX monotonic clocks (\tt{_POSIX_MONOTONIC_CLOCK}).	-
158		-
159	This clock does not overflow.	-
160		-
161	\section2 TickCounter	-
162		-
163	The tick counter clock type is based on the system's or the processor's	-
164	tick counter, multiplied by the duration of a tick. This clock type is	-
165	used on Windows platforms. If the high-precision performance	-
166	counter is available on Windows, the \tt{PerformanceCounter} clock type	-
167	is used instead.	-
168		-
169	The TickCounter clock type is the only clock type that may overflow.	-
170	Windows Vista and Windows Server 2008 support the extended 64-bit tick	-
171	counter, which allows avoiding the overflow.	-
172		-
173	On Windows systems, the clock overflows after 2^32 milliseconds, which	-
174	corresponds to roughly 49.7 days. This means two processes' reckoning of	-
175	the time since the reference may be different by multiples of 2^32	-
176	milliseconds. When comparing such values, it's recommended that the high	-
177	32 bits of the millisecond count be masked off.	-
178		-
179	\section2 MachAbsoluteTime	-
180		-
181	This clock type is based on the absolute time presented by Mach kernels,	-
182	such as that found on \macos. This clock type is presented separately	-
183	from MonotonicClock since \macos and iOS are also Unix systems and may support	-
184	a POSIX monotonic clock with values differing from the Mach absolute	-
185	time.	-
186		-
187	This clock is monotonic and does not overflow.	-
188		-
189	\section2 PerformanceCounter	-
190		-
191	This clock uses the Windows functions \tt{QueryPerformanceCounter} and	-
192	\tt{QueryPerformanceFrequency} to access the system's high-precision	-
193	performance counter. Since this counter may not be available on all	-
194	systems, QElapsedTimer will fall back to the \tt{TickCounter} clock	-
195	automatically, if this clock cannot be used.	-
196		-
197	This clock is monotonic and does not overflow.	-
198		-
199	\sa clockType(), isMonotonic()	-
200	*/	-
201		-
202	/*!	-
203	\fn QElapsedTimer::QElapsedTimer()	-
204	\since 5.4	-
205		-
206	Constructs an invalid QElapsedTimer. A timer becomes valid once it has been	-
207	started.	-
208		-
209	\sa isValid(), start()	-
210	*/	-
211		-
212		-
213	/*!	-
214	\fn bool QElapsedTimer::operator ==(const QElapsedTimer &other) const	-
215		-
216	Returns \c true if this object and \a other contain the same time.	-
217	*/	-
218		-
219	/*!	-
220	\fn bool QElapsedTimer::operator !=(const QElapsedTimer &other) const	-
221		-
222	Returns \c true if this object and \a other contain different times.	-
223	*/	-
224		-
225	static const qint64 invalidData = Q_INT64_C(0x8000000000000000);	-
226		-
227	/*!	-
228	Marks this QElapsedTimer object as invalid.	-
229		-
230	An invalid object can be checked with isValid(). Calculations of timer	-
231	elapsed since invalid data are undefined and will likely produce bizarre	-
232	results.	-
233		-
234	\sa isValid(), start(), restart()	-
235	*/	-
236	void QElapsedTimer::invalidate() Q_DECL_NOTHROW	-
237	{	-
238	t1 = t2 = invalidData;	-
239	} executed 134678 times by 81 tests: `end of block` Executed by: tst_Gestures tst_ModelTest tst_QAbstractAnimation tst_QAbstractItemView tst_QAbstractNetworkCache tst_QAccessibility tst_QCalendarWidget tst_QColumnView tst_QComboBox tst_QCompleter tst_QDataWidgetMapper tst_QDateTimeEdit tst_QDebug tst_QDirModel tst_QDockWidget tst_QElapsedTimer tst_QFileDialog2 tst_QFileSystemModel tst_QFiledialog tst_QFontComboBox tst_QFontDialog tst_QFuture tst_QFutureSynchronizer tst_QFutureWatcher tst_QGestureRecognizer ...	134678
240		-
241	/*!	-
242	Returns \c false if the timer has never been started or invalidated by a	-
243	call to invalidate().	-
244		-
245	\sa invalidate(), start(), restart()	-
246	*/	-
247	bool QElapsedTimer::isValid() const Q_DECL_NOTHROW	-
248	{	-
249	return t1 != invalidData && t2 != invalidData; executed 160919 times by 64 tests: `return t1 != invalidData && t2 != invalidData;` Executed by: tst_Gestures tst_QAbstractAnimation tst_QAbstractItemView tst_QAccessibility tst_QCalendarWidget tst_QColumnView tst_QComboBox tst_QCompleter tst_QDateTimeEdit tst_QDebug tst_QDockWidget tst_QElapsedTimer tst_QFileDialog2 tst_QFileIconProvider tst_QFileSystemModel tst_QFiledialog tst_QFontComboBox tst_QFuture tst_QFutureWatcher tst_QGraphicsProxyWidget tst_QGraphicsWidget tst_QGuiApplication tst_QGuiVariant tst_QIcon tst_QLineEdit ...	160919
250	}	-
251		-
252	/*!	-
253	Returns \c true if this QElapsedTimer has already expired by \a timeout	-
254	milliseconds (that is, more than \a timeout milliseconds have elapsed).	-
255	The value of \a timeout can be -1 to indicate that this timer does not	-
256	expire, in which case this function will always return false.	-
257		-
258	\sa elapsed()	-
259	*/	-
260	bool QElapsedTimer::hasExpired(qint64 timeout) const Q_DECL_NOTHROW	-
261	{	-
262	// if timeout is -1, quint64(timeout) is LLINT_MAX, so this will be	-
263	// considered as never expired	-
264	return quint64(elapsed()) > quint64(timeout); executed 79506 times by 3 tests: `return quint64(elapsed()) > quint64(timeout);` Executed by: tst_QElapsedTimer tst_QEventDispatcher tst_QLockFile	79506
265	}	-
266		-
267	QT_END_NAMESPACE	-

Line

Source

Count

/****************************************************************************

** Contact: https://www.qt.io/licensing/

** This file is part of the QtCore module of the Qt Toolkit.

** $QT_BEGIN_LICENSE:LGPL$

** Commercial License Usage

** Licensees holding valid commercial Qt licenses may use this file in

** accordance with the commercial license agreement provided with the

** Software or, alternatively, in accordance with the terms contained in

** a written agreement between you and The Qt Company. For licensing terms

** and conditions see https://www.qt.io/terms-conditions. For further

** information use the contact form at https://www.qt.io/contact-us.

** GNU Lesser General Public License Usage

** Alternatively, this file may be used under the terms of the GNU Lesser

** General Public License version 3 as published by the Free Software

** Foundation and appearing in the file LICENSE.LGPL3 included in the

** packaging of this file. Please review the following information to

** ensure the GNU Lesser General Public License version 3 requirements

** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.

** GNU General Public License Usage

** Alternatively, this file may be used under the terms of the GNU

** General Public License version 2.0 or (at your option) the GNU General

** Public license version 3 or any later version approved by the KDE Free

** Qt Foundation. The licenses are as published by the Free Software

** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3

** included in the packaging of this file. Please review the following

** information to ensure the GNU General Public License requirements will

** be met: https://www.gnu.org/licenses/gpl-2.0.html and

** https://www.gnu.org/licenses/gpl-3.0.html.

** $QT_END_LICENSE$

****************************************************************************/

#include "qelapsedtimer.h"

QT_BEGIN_NAMESPACE

/*!

\class QElapsedTimer

\inmodule QtCore

\brief The QElapsedTimer class provides a fast way to calculate elapsed times.

\since 4.7

\reentrant

\ingroup tools

The QElapsedTimer class is usually used to quickly calculate how much

time has elapsed between two events. Its API is similar to that of QTime,

so code that was using that can be ported quickly to the new class.

However, unlike QTime, QElapsedTimer tries to use monotonic clocks if

possible. This means it's not possible to convert QElapsedTimer objects

to a human-readable time.

The typical use-case for the class is to determine how much time was

spent in a slow operation. The simplest example of such a case is for

debugging purposes, as in the following example:

\snippet qelapsedtimer/main.cpp 0

In this example, the timer is started by a call to start() and the

elapsed timer is calculated by the elapsed() function.

The time elapsed can also be used to recalculate the time available for

another operation, after the first one is complete. This is useful when

the execution must complete within a certain time period, but several

steps are needed. The \tt{waitFor}-type functions in QIODevice and its

subclasses are good examples of such need. In that case, the code could

be as follows:

\snippet qelapsedtimer/main.cpp 1

Another use-case is to execute a certain operation for a specific

timeslice. For this, QElapsedTimer provides the hasExpired() convenience

function, which can be used to determine if a certain number of

milliseconds has already elapsed:

\snippet qelapsedtimer/main.cpp 2

\section1 Reference Clocks

QElapsedTimer will use the platform's monotonic reference clock in all

platforms that support it (see QElapsedTimer::isMonotonic()). This has

the added benefit that QElapsedTimer is immune to time adjustments, such

as the user correcting the time. Also unlike QTime, QElapsedTimer is

immune to changes in the timezone settings, such as daylight-saving

periods.

On the other hand, this means QElapsedTimer values can only be compared

with other values that use the same reference. This is especially true if

the time since the reference is extracted from the QElapsedTimer object

(QElapsedTimer::msecsSinceReference()) and serialised. These values

should never be exchanged across the network or saved to disk, since

100

there's no telling whether the computer node receiving the data is the

101

same as the one originating it or if it has rebooted since.

102

103

It is, however, possible to exchange the value with other processes

104

running on the same machine, provided that they also use the same

105

reference clock. QElapsedTimer will always use the same clock, so it's

106

safe to compare with the value coming from another process in the same

107

machine. If comparing to values produced by other APIs, you should check

108

that the clock used is the same as QElapsedTimer (see

109

QElapsedTimer::clockType()).

110

111

\section2 32-bit overflows

112

113

Some of the clocks used by QElapsedTimer have a limited range and may

114

overflow after hitting the upper limit (usually 32-bit). QElapsedTimer

115

deals with this overflow issue and presents a consistent timing. However,

116

when extracting the time since reference from QElapsedTimer, two

117

different processes in the same machine may have different understanding

118

of how much time has actually elapsed.

119

120

The information on which clocks types may overflow and how to remedy that

121

issue is documented along with the clock types.

\sa QTime, QTimer

/*!

\enum QElapsedTimer::ClockType

128

129

This enum contains the different clock types that QElapsedTimer may use.

130

131

QElapsedTimer will always use the same clock type in a particular

132

machine, so this value will not change during the lifetime of a program.

133

It is provided so that QElapsedTimer can be used with other non-Qt

134

implementations, to guarantee that the same reference clock is being

135

used.

136

137

\value SystemTime The human-readable system time. This clock is not monotonic.

138

\value MonotonicClock The system's monotonic clock, usually found in Unix systems. This clock is monotonic and does not overflow.

139

\value TickCounter The system's tick counter, used on Windows systems. This clock may overflow.

140

\value MachAbsoluteTime The Mach kernel's absolute time (\macos and iOS). This clock is monotonic and does not overflow.

141

\value PerformanceCounter The high-resolution performance counter provided by Windows. This clock is monotonic and does not overflow.

\section2 SystemTime

The system time clock is purely the real time, expressed in milliseconds

146

since Jan 1, 1970 at 0:00 UTC. It's equivalent to the value returned by

147

the C and POSIX \tt{time} function, with the milliseconds added. This

148

clock type is currently only used on Unix systems that do not support

149

monotonic clocks (see below).

150

151

This is the only non-monotonic clock that QElapsedTimer may use.

152

153

\section2 MonotonicClock

154

155

This is the system's monotonic clock, expressed in milliseconds since an

156

arbitrary point in the past. This clock type is used on Unix systems

157

which support POSIX monotonic clocks (\tt{_POSIX_MONOTONIC_CLOCK}).

158

159

This clock does not overflow.

160

161

\section2 TickCounter

162

163

The tick counter clock type is based on the system's or the processor's

164

tick counter, multiplied by the duration of a tick. This clock type is

165

used on Windows platforms. If the high-precision performance

166

counter is available on Windows, the \tt{PerformanceCounter} clock type

167

is used instead.

168

169

The TickCounter clock type is the only clock type that may overflow.

170

Windows Vista and Windows Server 2008 support the extended 64-bit tick

171

counter, which allows avoiding the overflow.

172

173

On Windows systems, the clock overflows after 2^32 milliseconds, which

174

corresponds to roughly 49.7 days. This means two processes' reckoning of

175

the time since the reference may be different by multiples of 2^32

176

milliseconds. When comparing such values, it's recommended that the high

177

32 bits of the millisecond count be masked off.

178

179

\section2 MachAbsoluteTime

180

181

This clock type is based on the absolute time presented by Mach kernels,

182

such as that found on \macos. This clock type is presented separately

183

from MonotonicClock since \macos and iOS are also Unix systems and may support

184

a POSIX monotonic clock with values differing from the Mach absolute

185

time.

186

187

This clock is monotonic and does not overflow.

188

189

\section2 PerformanceCounter

190

191

This clock uses the Windows functions \tt{QueryPerformanceCounter} and

192

\tt{QueryPerformanceFrequency} to access the system's high-precision

193

performance counter. Since this counter may not be available on all

194

systems, QElapsedTimer will fall back to the \tt{TickCounter} clock

195

automatically, if this clock cannot be used.

196

197

This clock is monotonic and does not overflow.

198

199

\sa clockType(), isMonotonic()

/*!

\fn QElapsedTimer::QElapsedTimer()

204

\since 5.4

205

206

Constructs an invalid QElapsedTimer. A timer becomes valid once it has been

207

started.

208

209

\sa isValid(), start()

/*!

\fn bool QElapsedTimer::operator ==(const QElapsedTimer &other) const

215

216

Returns \c true if this object and \a other contain the same time.

/*!

\fn bool QElapsedTimer::operator !=(const QElapsedTimer &other) const

221

222

Returns \c true if this object and \a other contain different times.

223

224

225

static const qint64 invalidData = Q_INT64_C(0x8000000000000000);

226

227

/*!

228

Marks this QElapsedTimer object as invalid.

229

230

An invalid object can be checked with isValid(). Calculations of timer

231

elapsed since invalid data are undefined and will likely produce bizarre

232

results.

233

234

\sa isValid(), start(), restart()

235

236

void QElapsedTimer::invalidate() Q_DECL_NOTHROW

237

{

238

t1 = t2 = invalidData;

239

}

executed 134678 times by 81 tests: end of block

Executed by:

tst_Gestures
tst_ModelTest
tst_QAbstractAnimation
tst_QAbstractItemView
tst_QAbstractNetworkCache
tst_QAccessibility
tst_QCalendarWidget
tst_QColumnView
tst_QComboBox
tst_QCompleter
tst_QDataWidgetMapper
tst_QDateTimeEdit
tst_QDebug
tst_QDirModel
tst_QDockWidget
tst_QElapsedTimer
tst_QFileDialog2
tst_QFileSystemModel
tst_QFiledialog
tst_QFontComboBox
tst_QFontDialog
tst_QFuture
tst_QFutureSynchronizer
tst_QFutureWatcher
tst_QGestureRecognizer
...

134678

240

241

/*!

242

Returns \c false if the timer has never been started or invalidated by a

243

call to invalidate().

244

245

\sa invalidate(), start(), restart()

246

247

bool QElapsedTimer::isValid() const Q_DECL_NOTHROW

248

{

249

return t1 != invalidData && t2 != invalidData;

executed 160919 times by 64 tests: return t1 != invalidData && t2 != invalidData;

Executed by:

tst_Gestures
tst_QAbstractAnimation
tst_QAbstractItemView
tst_QAccessibility
tst_QCalendarWidget
tst_QColumnView
tst_QComboBox
tst_QCompleter
tst_QDateTimeEdit
tst_QDebug
tst_QDockWidget
tst_QElapsedTimer
tst_QFileDialog2
tst_QFileIconProvider
tst_QFileSystemModel
tst_QFiledialog
tst_QFontComboBox
tst_QFuture
tst_QFutureWatcher
tst_QGraphicsProxyWidget
tst_QGraphicsWidget
tst_QGuiApplication
tst_QGuiVariant
tst_QIcon
tst_QLineEdit
...

160919

}

/*!

Returns \c true if this QElapsedTimer has already expired by \a timeout

254

milliseconds (that is, more than \a timeout milliseconds have elapsed).

255

The value of \a timeout can be -1 to indicate that this timer does not

256

expire, in which case this function will always return false.

\sa elapsed()

bool QElapsedTimer::hasExpired(qint64 timeout) const Q_DECL_NOTHROW

261

{

262

// if timeout is -1, quint64(timeout) is LLINT_MAX, so this will be

263

// considered as never expired

264

return quint64(elapsed()) > quint64(timeout);

executed 79506 times by 3 tests: return quint64(elapsed()) > quint64(timeout);

Executed by:

tst_QElapsedTimer
tst_QEventDispatcher
tst_QLockFile

79506

265

}

266

267

QT_END_NAMESPACE

Generated by Squish Coco Non-Commercial 4.3.0-BETA-master-30-08-2018-4cb69e9