tor  0.4.0.1-alpha
compat_time.h
Go to the documentation of this file.
1 /* Copyright (c) 2003-2004, Roger Dingledine
2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3  * Copyright (c) 2007-2019, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
5 
18 /* Q: Should you use monotime or monotime_coarse as your source?
19  *
20  * A: Generally, you get better precision with monotime, but better
21  * performance with monotime_coarse.
22  *
23  * Q: Should you use monotime_t or monotime_coarse_t directly? Should you use
24  * usec? msec? "stamp units?"
25  *
26  * A: Using monotime_t and monotime_coarse_t directly is most time-efficient,
27  * since no conversion needs to happen. But they can potentially use more
28  * memory than you would need for a usec/msec/"stamp unit" count.
29  *
30  * Converting to usec or msec on some platforms, and working with them in
31  * general, creates a risk of doing a 64-bit division. 64-bit division is
32  * expensive on 32-bit platforms, which still do exist.
33  *
34  * The "stamp unit" type is designed to give a type that is cheap to convert
35  * from monotime_coarse, has resolution of about 1-2ms, and fits nicely in a
36  * 32-bit integer. Its downside is that it does not correspond directly
37  * to a natural unit of time.
38  *
39  * There is not much point in using "coarse usec" or "coarse nsec", since the
40  * current coarse monotime implementations give you on the order of
41  * milliseconds of precision.
42  *
43  * Q: So, what backends is monotime_coarse using?
44  *
45  * A: Generally speaking, it uses "whatever monotonic-ish time implemenation
46  * does not require a context switch." The various implementations provide
47  * this by having a view of the current time in a read-only memory page that
48  * is updated with a frequency corresponding to the kernel's tick count.
49  *
50  * On Windows, monotime_coarse uses GetCount64() [or GetTickCount() on
51  * obsolete systems]. MSDN claims that the resolution is "typically in the
52  * range of 10-16 msec", but it has said that for years. Storing
53  * monotime_coarse_t uses 8 bytes.
54  *
55  * On OSX/iOS, monotime_coarse uses uses mach_approximate_time() where
56  * available, and falls back to regular monotime. The precision is not
57  * documented, but the implementation is open-source: it reads from a page
58  * that the kernel updates. Storing monotime_coarse_t uses 8 bytes.
59  *
60  * On unixy systems, monotime_coarse uses clock_gettime() with
61  * CLOCK_MONOTONIC_COARSE where available, and falls back to CLOCK_MONOTONIC.
62  * It typically uses vdso tricks to read from a page that the kernel updates.
63  * Its precision fixed, but you can get it with clock_getres(): on my Linux
64  * desktop, it claims to be 1 msec, but it will depend on the system HZ
65  * setting. Storing monotime_coarse_t uses 16 bytes.
66  *
67  * [TODO: Try CLOCK_MONOTONIC_FAST on foobsd.]
68  *
69  * Q: What backends is regular monotonic time using?
70  *
71  * A: In general, regular monotime uses something that requires a system call.
72  * On platforms where system calls are cheap, you win! Otherwise, you lose.
73  *
74  * On Windows, monotonic time uses QuereyPerformanceCounter. Storing
75  * monotime_t costs 8 bytes.
76  *
77  * On OSX/Apple, monotonic time uses mach_absolute_time. Storing
78  * monotime_t costs 8 bytes.
79  *
80  * On unixy systems, monotonic time uses CLOCK_MONOTONIC. Storing
81  * monotime_t costs 16 bytes.
82  *
83  * Q: Tell me about the costs of converting to a 64-bit nsec, usec, or msec
84  * count.
85  *
86  * A: Windows, coarse: Cheap, since it's all multiplication.
87  *
88  * Windows, precise: Expensive on 32-bit: it needs 64-bit division.
89  *
90  * Apple, all: Expensive on 32-bit: it needs 64-bit division.
91  *
92  * Unixy, all: Fairly cheap, since the only division required is dividing
93  * tv_nsec 1000, and nanoseconds-per-second fits in a 32-bit value.
94  *
95  * All, "timestamp units": Cheap everywhere: it never divides.
96  *
97  * Q: This is only somewhat related, but how much precision could I hope for
98  * from a libevent time.?
99  *
100  * A: Actually, it's _very_ related if you're timing in order to have a
101  * timeout happen.
102  *
103  * On Windows, it uses select: you could in theory have a microsecond
104  * resolution, but it usually isn't that accurate.
105  *
106  * On OSX, iOS, and BSD, you have kqueue: You could in theory have a nanosecond
107  * resolution, but it usually isn't that accurate.
108  *
109  * On Linux, you have epoll: It has a millisecond resolution. Some recent
110  * Libevents can also use timerfd for higher resolution if
111  * EVENT_BASE_FLAG_PRECISE_TIMER is set: Tor doesn't set that flag.
112  */
113 
114 #ifndef TOR_COMPAT_TIME_H
115 #define TOR_COMPAT_TIME_H
116 
117 #include "orconfig.h"
118 #include "lib/cc/torint.h"
119 
121 
122 #ifdef _WIN32
123 #undef HAVE_CLOCK_GETTIME
124 #endif
125 
126 #if defined(HAVE_CLOCK_GETTIME)
127 /* to ensure definition of CLOCK_MONOTONIC_COARSE if it's there */
128 #include <time.h>
129 #endif
130 
131 #if !defined(HAVE_STRUCT_TIMEVAL_TV_SEC)
132 
133 struct timeval {
134  time_t tv_sec;
135  unsigned int tv_usec;
136 };
137 #endif /* !defined(HAVE_STRUCT_TIMEVAL_TV_SEC) */
138 
140 typedef struct monotime_t {
141 #ifdef __APPLE__
142  /* On apple, there is a 64-bit counter whose precision we must look up. */
143  uint64_t abstime_;
144 #elif defined(HAVE_CLOCK_GETTIME)
145  /* It sure would be nice to use clock_gettime(). Posix is a nice thing. */
146  struct timespec ts_;
147 #elif defined (_WIN32)
148  /* On Windows, there is a 64-bit counter whose precision we must look up. */
149  int64_t pcount_;
150 #else
151 #define MONOTIME_USING_GETTIMEOFDAY
152  /* Otherwise, we will be stuck using gettimeofday. */
153  struct timeval tv_;
154 #endif /* defined(__APPLE__) || ... */
155 } monotime_t;
156 
157 #if defined(CLOCK_MONOTONIC_COARSE) && \
158  defined(HAVE_CLOCK_GETTIME)
159 #define MONOTIME_COARSE_FN_IS_DIFFERENT
160 #define monotime_coarse_t monotime_t
161 #elif defined(_WIN32)
162 #define MONOTIME_COARSE_FN_IS_DIFFERENT
163 #define MONOTIME_COARSE_TYPE_IS_DIFFERENT
164 
165 typedef struct monotime_coarse_t {
166  uint64_t tick_count_;
167 } monotime_coarse_t;
168 #elif defined(__APPLE__) && defined(HAVE_MACH_APPROXIMATE_TIME)
169 #define MONOTIME_COARSE_FN_IS_DIFFERENT
170 #define monotime_coarse_t monotime_t
171 #else
172 #define monotime_coarse_t monotime_t
173 #endif /* defined(CLOCK_MONOTONIC_COARSE) && ... || ... */
174 
178 void monotime_init(void);
182 void monotime_get(monotime_t *out);
186 int64_t monotime_diff_nsec(const monotime_t *start, const monotime_t *end);
190 int64_t monotime_diff_usec(const monotime_t *start, const monotime_t *end);
194 int64_t monotime_diff_msec(const monotime_t *start, const monotime_t *end);
198 uint64_t monotime_absolute_nsec(void);
202 MOCK_DECL(uint64_t, monotime_absolute_usec,(void));
206 uint64_t monotime_absolute_msec(void);
207 
211 void monotime_zero(monotime_t *out);
215 int monotime_is_zero(const monotime_t *out);
216 
220 /* XXXX We should add a more generic function here if we ever need to */
221 void monotime_add_msec(monotime_t *out, const monotime_t *val, uint32_t msec);
222 
223 #if defined(MONOTIME_COARSE_FN_IS_DIFFERENT)
224 
227 void monotime_coarse_get(monotime_coarse_t *out);
228 uint64_t monotime_coarse_absolute_nsec(void);
229 uint64_t monotime_coarse_absolute_usec(void);
230 uint64_t monotime_coarse_absolute_msec(void);
231 #else /* !(defined(MONOTIME_COARSE_FN_IS_DIFFERENT)) */
232 #define monotime_coarse_get monotime_get
233 #define monotime_coarse_absolute_nsec monotime_absolute_nsec
234 #define monotime_coarse_absolute_usec monotime_absolute_usec
235 #define monotime_coarse_absolute_msec monotime_absolute_msec
236 #endif /* defined(MONOTIME_COARSE_FN_IS_DIFFERENT) */
237 
247 uint32_t monotime_coarse_to_stamp(const monotime_coarse_t *t);
252 uint64_t monotime_coarse_stamp_units_to_approx_msec(uint64_t units);
253 uint64_t monotime_msec_to_approx_coarse_stamp_units(uint64_t msec);
254 uint32_t monotime_coarse_get_stamp(void);
255 
256 #if defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT)
257 int64_t monotime_coarse_diff_nsec(const monotime_coarse_t *start,
258  const monotime_coarse_t *end);
259 int64_t monotime_coarse_diff_usec(const monotime_coarse_t *start,
260  const monotime_coarse_t *end);
261 int64_t monotime_coarse_diff_msec(const monotime_coarse_t *start,
262  const monotime_coarse_t *end);
263 void monotime_coarse_zero(monotime_coarse_t *out);
264 int monotime_coarse_is_zero(const monotime_coarse_t *val);
265 void monotime_coarse_add_msec(monotime_coarse_t *out,
266  const monotime_coarse_t *val, uint32_t msec);
267 #else /* !(defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT)) */
268 #define monotime_coarse_diff_nsec monotime_diff_nsec
269 #define monotime_coarse_diff_usec monotime_diff_usec
270 #define monotime_coarse_diff_msec monotime_diff_msec
271 #define monotime_coarse_zero monotime_zero
272 #define monotime_coarse_is_zero monotime_is_zero
273 #define monotime_coarse_add_msec monotime_add_msec
274 #endif /* defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT) */
275 
282 int32_t monotime_coarse_diff_msec32_(const monotime_coarse_t *start,
283  const monotime_coarse_t *end);
284 
291 static inline int32_t
292 monotime_coarse_diff_msec32(const monotime_coarse_t *start,
293  const monotime_coarse_t *end)
294 {
295 #if SIZEOF_VOID_P == 8
296  // on a 64-bit platform, let's assume 64/64 division is cheap.
297  return (int32_t) monotime_coarse_diff_msec(start, end);
298 #else
299 #define USING_32BIT_MSEC_HACK
300  return monotime_coarse_diff_msec32_(start, end);
301 #endif
302 }
303 
304 #ifdef TOR_UNIT_TESTS
305 void tor_sleep_msec(int msec);
306 
307 void monotime_enable_test_mocking(void);
308 void monotime_disable_test_mocking(void);
309 void monotime_set_mock_time_nsec(int64_t);
310 #if defined(MONOTIME_COARSE_FN_IS_DIFFERENT)
311 void monotime_coarse_set_mock_time_nsec(int64_t);
312 #else
313 #define monotime_coarse_set_mock_time_nsec monotime_set_mock_time_nsec
314 #endif
315 #endif /* defined(TOR_UNIT_TESTS) */
316 
317 #ifdef COMPAT_TIME_PRIVATE
318 #if defined(_WIN32) || defined(TOR_UNIT_TESTS)
319 STATIC int64_t ratchet_performance_counter(int64_t count_raw);
320 STATIC int64_t ratchet_coarse_performance_counter(int64_t count_raw);
321 #endif
322 #if defined(MONOTIME_USING_GETTIMEOFDAY) || defined(TOR_UNIT_TESTS)
323 STATIC void ratchet_timeval(const struct timeval *timeval_raw,
324  struct timeval *out);
325 #endif
326 #ifdef TOR_UNIT_TESTS
327 void monotime_reset_ratchets_for_testing(void);
328 #endif
329 #endif /* defined(COMPAT_TIME_PRIVATE) */
330 
331 #endif /* !defined(TOR_COMPAT_TIME_H) */
uint64_t monotime_absolute_nsec(void)
Definition: compat_time.c:779
static int32_t monotime_coarse_diff_msec32(const monotime_coarse_t *start, const monotime_coarse_t *end)
Definition: compat_time.h:292
void monotime_add_msec(monotime_t *out, const monotime_t *val, uint32_t msec)
Definitions for timing-related constants.
struct monotime_t monotime_t
void monotime_get(monotime_t *out)
Integer definitions used throughout Tor.
MOCK_DECL(uint64_t, monotime_absolute_usec,(void))
uint32_t monotime_coarse_to_stamp(const monotime_coarse_t *t)
int32_t monotime_coarse_diff_msec32_(const monotime_coarse_t *start, const monotime_coarse_t *end)
int monotime_is_zero(const monotime_t *out)
uint64_t monotime_absolute_msec(void)
Definition: compat_time.c:797
uint64_t monotime_coarse_stamp_units_to_approx_msec(uint64_t units)
Definition: compat_time.c:860
uint32_t monotime_coarse_get_stamp(void)
Definition: compat_time.c:834
int64_t monotime_diff_nsec(const monotime_t *start, const monotime_t *end)
int64_t monotime_diff_usec(const monotime_t *start, const monotime_t *end)
Definition: compat_time.c:763
void monotime_init(void)
Definition: compat_time.c:737
Header for tor_gettimeofday.c.
int64_t monotime_diff_msec(const monotime_t *start, const monotime_t *end)
Definition: compat_time.c:771
void monotime_zero(monotime_t *out)
Definition: compat_time.c:750