1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
|
/** @file
@brief Header defining a dependency-free, cross-platform substitute for
struct timeval
Must be c-safe!
@date 2014
@author
Sensics, Inc.
<http://sensics.com/osvr>
*/
/*
// Copyright 2014 Sensics, Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
*/
#ifndef INCLUDED_TimeValueC_h_GUID_A02C6917_124D_4CB3_E63E_07F2DA7144E9
#define INCLUDED_TimeValueC_h_GUID_A02C6917_124D_4CB3_E63E_07F2DA7144E9
/* Internal Includes */
#include <osvr/Util/Export.h>
#include <osvr/Util/APIBaseC.h>
#include <osvr/Util/AnnotationMacrosC.h>
#include <osvr/Util/PlatformConfig.h>
#include <osvr/Util/StdInt.h>
#include <osvr/Util/BoolC.h>
/* Library/third-party includes */
/* none */
/* Standard includes */
/* none */
OSVR_EXTERN_C_BEGIN
/** @defgroup UtilTime Timestamp interaction
@ingroup Util
This provides a level of interoperability with struct timeval on systems
with that facility. It provides a neutral representation with sufficiently
large types.
For C++ code, use of std::chrono or boost::chrono instead is recommended.
Note that these time values may not necessarily correlate between processes
so should not be used to estimate or measure latency, etc.
@{
*/
/** @brief The signed integer type storing the seconds in a struct
OSVR_TimeValue */
typedef int64_t OSVR_TimeValue_Seconds;
/** @brief The signed integer type storing the microseconds in a struct
OSVR_TimeValue */
typedef int32_t OSVR_TimeValue_Microseconds;
/** @brief Standardized, portable parallel to struct timeval for representing
both absolute times and time intervals.
Where interpreted as an absolute time, its meaning is to be considered the
same as that of the POSIX struct timeval:
time since 00:00 Coordinated Universal Time (UTC), January 1, 1970.
For best results, please keep normalized. Output of all functions here
is normalized.
*/
typedef struct OSVR_TimeValue {
/** @brief Seconds portion of the time value. */
OSVR_TimeValue_Seconds seconds;
/** @brief Microseconds portion of the time value. */
OSVR_TimeValue_Microseconds microseconds;
} OSVR_TimeValue;
#ifdef OSVR_HAVE_STRUCT_TIMEVAL
/** @brief Gets the current time in the TimeValue. Parallel to gettimeofday. */
OSVR_UTIL_EXPORT void osvrTimeValueGetNow(OSVR_OUT OSVR_TimeValue *dest)
OSVR_FUNC_NONNULL((1));
struct timeval; /* forward declaration */
/** @brief Converts from a TimeValue struct to your system's struct timeval.
@param dest Pointer to an empty struct timeval for your platform.
@param src A pointer to an OSVR_TimeValue you'd like to convert from.
If either parameter is NULL, the function will return without doing
anything.
*/
OSVR_UTIL_EXPORT void
osvrTimeValueToStructTimeval(OSVR_OUT struct timeval *dest,
OSVR_IN_PTR const OSVR_TimeValue *src)
OSVR_FUNC_NONNULL((1, 2));
/** @brief Converts from a TimeValue struct to your system's struct timeval.
@param dest An OSVR_TimeValue destination pointer.
@param src Pointer to a struct timeval you'd like to convert from.
The result is normalized.
If either parameter is NULL, the function will return without doing
anything.
*/
OSVR_UTIL_EXPORT void
osvrStructTimevalToTimeValue(OSVR_OUT OSVR_TimeValue *dest,
OSVR_IN_PTR const struct timeval *src)
OSVR_FUNC_NONNULL((1, 2));
#endif
/** @brief "Normalizes" a time value so that the absolute number of microseconds
is less than 1,000,000, and that the sign of both components is the same.
@param tv Address of a struct TimeValue to normalize in place.
If the given pointer is NULL, this function returns without doing anything.
*/
OSVR_UTIL_EXPORT void osvrTimeValueNormalize(OSVR_INOUT_PTR OSVR_TimeValue *tv)
OSVR_FUNC_NONNULL((1));
/** @brief Sums two time values, replacing the first with the result.
@param tvA Destination and first source.
@param tvB second source
If a given pointer is NULL, this function returns without doing anything.
Both parameters are expected to be in normalized form.
*/
OSVR_UTIL_EXPORT void osvrTimeValueSum(OSVR_INOUT_PTR OSVR_TimeValue *tvA,
OSVR_IN_PTR const OSVR_TimeValue *tvB)
OSVR_FUNC_NONNULL((1, 2));
/** @brief Computes the difference between two time values, replacing the first
with the result.
Effectively, `*tvA = *tvA - *tvB`
@param tvA Destination and first source.
@param tvB second source
If a given pointer is NULL, this function returns without doing anything.
Both parameters are expected to be in normalized form.
*/
OSVR_UTIL_EXPORT void
osvrTimeValueDifference(OSVR_INOUT_PTR OSVR_TimeValue *tvA,
OSVR_IN_PTR const OSVR_TimeValue *tvB)
OSVR_FUNC_NONNULL((1, 2));
/** @brief Compares two time values (assumed to be normalized), returning
the same values as strcmp
@return <0 if A is earlier than B, 0 if they are the same, and >0 if A
is later than B.
*/
OSVR_UTIL_EXPORT int osvrTimeValueCmp(OSVR_IN_PTR const OSVR_TimeValue *tvA,
OSVR_IN_PTR const OSVR_TimeValue *tvB)
OSVR_FUNC_NONNULL((1, 2));
OSVR_EXTERN_C_END
/** @brief Compute the difference between the two time values, returning the
duration as a double-precision floating-point number of seconds.
Effectively, `ret = *tvA - *tvB`
@param tvA first source.
@param tvB second source
@return Duration of timespan in seconds (floating-point)
*/
OSVR_INLINE double
osvrTimeValueDurationSeconds(OSVR_IN_PTR const OSVR_TimeValue *tvA,
OSVR_IN_PTR const OSVR_TimeValue *tvB) {
OSVR_TimeValue A = *tvA;
osvrTimeValueDifference(&A, tvB);
double dt = A.seconds + A.microseconds / 1000000.0;
return dt;
}
/** @brief True if A is later than B */
OSVR_INLINE OSVR_CBool
osvrTimeValueGreater(OSVR_IN_PTR const OSVR_TimeValue *tvA,
OSVR_IN_PTR const OSVR_TimeValue *tvB) {
if (!tvA || !tvB) {
return OSVR_FALSE;
}
return ((tvA->seconds > tvB->seconds) ||
(tvA->seconds == tvB->seconds &&
tvA->microseconds > tvB->microseconds))
? OSVR_TRUE
: OSVR_FALSE;
}
#ifdef __cplusplus
#include <cmath>
#include <cassert>
/// Returns true if the time value is normalized. Typically used in assertions.
inline bool osvrTimeValueIsNormalized(const OSVR_TimeValue &tv) {
#ifdef __APPLE__
// apparently standard library used on mac only has floating-point abs?
return std::abs(double(tv.microseconds)) < 1000000 &&
#else
return std::abs(tv.microseconds) < 1000000 &&
#endif
((tv.seconds > 0) == (tv.microseconds > 0));
}
/// True if A is later than B
inline bool osvrTimeValueGreater(const OSVR_TimeValue &tvA,
const OSVR_TimeValue &tvB) {
assert(osvrTimeValueIsNormalized(tvA) &&
"First timevalue argument to comparison was not normalized!");
assert(osvrTimeValueIsNormalized(tvB) &&
"Second timevalue argument to comparison was not normalized!");
return (tvA.seconds > tvB.seconds) ||
(tvA.seconds == tvB.seconds && tvA.microseconds > tvB.microseconds);
}
/// Operator > overload for time values
inline bool operator>(const OSVR_TimeValue &tvA, const OSVR_TimeValue &tvB) {
return osvrTimeValueGreater(tvA, tvB);
}
/// Operator < overload for time values
inline bool operator<(const OSVR_TimeValue &tvA, const OSVR_TimeValue &tvB) {
// Change the order of arguments before forwarding.
return osvrTimeValueGreater(tvB, tvA);
}
/// Operator == overload for time values
inline bool operator==(const OSVR_TimeValue &tvA, const OSVR_TimeValue &tvB) {
assert(
osvrTimeValueIsNormalized(tvA) &&
"First timevalue argument to equality comparison was not normalized!");
assert(
osvrTimeValueIsNormalized(tvB) &&
"Second timevalue argument to equality comparison was not normalized!");
return (tvA.seconds == tvB.seconds) &&
(tvA.microseconds == tvB.microseconds);
}
/// Operator == overload for time values
inline bool operator!=(const OSVR_TimeValue &tvA, const OSVR_TimeValue &tvB) {
assert(osvrTimeValueIsNormalized(tvA) && "First timevalue argument to "
"inequality comparison was not "
"normalized!");
assert(osvrTimeValueIsNormalized(tvB) && "Second timevalue argument to "
"inequality comparison was not "
"normalized!");
return (tvA.seconds != tvB.seconds) ||
(tvA.microseconds != tvB.microseconds);
}
#endif
/** @} */
#endif
|
