Tor  0.4.7.0-alpha-dev
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-2021, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
5 
6 /**
7  * \file compat_time.h
8  *
9  * \brief Functions and types for monotonic times.
10  *
11  * monotime_* functions try to provide a high-resolution monotonic timer with
12  * something the best resolution the system provides. monotime_coarse_*
13  * functions run faster (if the operating system gives us a way to do that)
14  * but produce a less accurate timer: accuracy will probably be on the order
15  * of tens of milliseconds.
16  */
17 
18 /* Q: When should I use monotonic time?
19  *
20  * A: If you need a time that never decreases, use monotonic time. If you need
21  * to send a time to a user or another process, or store a time, use the
22  * wall-clock time.
23  *
24  * Q: Should you use monotime or monotime_coarse as your source?
25  *
26  * A: Generally, you get better precision with monotime, but better
27  * performance with monotime_coarse.
28  *
29  * Q: What is a "monotonic" time, exactly?
30  *
31  * A: Monotonic times are strictly non-decreasing. The difference between any
32  * previous monotonic time, and the current monotonic time, is always greater
33  * than *or equal to* zero.
34  * Zero deltas happen more often:
35  * - on Windows (due to an OS bug),
36  * - when using monotime_coarse, or on systems with low-resolution timers,
37  * - on platforms where we emulate monotonic time using wall-clock time, and
38  * - when using time units that are larger than nanoseconds (due to
39  * truncation on division).
40  *
41  * Q: Should you use monotime_t or monotime_coarse_t directly? Should you use
42  * usec? msec? "stamp units?"
43  *
44  * A: Using monotime_t and monotime_coarse_t directly is most time-efficient,
45  * since no conversion needs to happen. But they can potentially use more
46  * memory than you would need for a usec/msec/"stamp unit" count.
47  *
48  * Converting to usec or msec on some platforms, and working with them in
49  * general, creates a risk of doing a 64-bit division. 64-bit division is
50  * expensive on 32-bit platforms, which still do exist.
51  *
52  * The "stamp unit" type is designed to give a type that is cheap to convert
53  * from monotime_coarse, has resolution of about 1-2ms, and fits nicely in a
54  * 32-bit integer. Its downside is that it does not correspond directly
55  * to a natural unit of time.
56  *
57  * There is not much point in using "coarse usec" or "coarse nsec", since the
58  * current coarse monotime implementations give you on the order of
59  * milliseconds of precision.
60  *
61  * Q: So, what backends is monotime_coarse using?
62  *
63  * A: Generally speaking, it uses "whatever monotonic-ish time implementation
64  * does not require a context switch." The various implementations provide
65  * this by having a view of the current time in a read-only memory page that
66  * is updated with a frequency corresponding to the kernel's tick count.
67  *
68  * On Windows, monotime_coarse uses GetCount64() [or GetTickCount() on
69  * obsolete systems]. MSDN claims that the resolution is "typically in the
70  * range of 10-16 msec", but it has said that for years. Storing
71  * monotime_coarse_t uses 8 bytes.
72  *
73  * On OSX/iOS, monotime_coarse uses uses mach_approximate_time() where
74  * available, and falls back to regular monotime. The precision is not
75  * documented, but the implementation is open-source: it reads from a page
76  * that the kernel updates. Storing monotime_coarse_t uses 8 bytes.
77  *
78  * On unixy systems, monotime_coarse uses clock_gettime() with
79  * CLOCK_MONOTONIC_COARSE where available, and falls back to CLOCK_MONOTONIC.
80  * It typically uses vdso tricks to read from a page that the kernel updates.
81  * Its precision fixed, but you can get it with clock_getres(): on my Linux
82  * desktop, it claims to be 1 msec, but it will depend on the system HZ
83  * setting. Storing monotime_coarse_t uses 16 bytes.
84  *
85  * [TODO: Try CLOCK_MONOTONIC_FAST on foobsd.]
86  *
87  * Q: What backends is regular monotonic time using?
88  *
89  * A: In general, regular monotime uses something that requires a system call.
90  * On platforms where system calls are cheap, you win! Otherwise, you lose.
91  *
92  * On Windows, monotonic time uses QuereyPerformanceCounter. Storing
93  * monotime_t costs 8 bytes.
94  *
95  * On OSX/Apple, monotonic time uses mach_absolute_time. Storing
96  * monotime_t costs 8 bytes.
97  *
98  * On unixy systems, monotonic time uses CLOCK_MONOTONIC. Storing
99  * monotime_t costs 16 bytes.
100  *
101  * Q: Tell me about the costs of converting to a 64-bit nsec, usec, or msec
102  * count.
103  *
104  * A: Windows, coarse: Cheap, since it's all multiplication.
105  *
106  * Windows, precise: Expensive on 32-bit: it needs 64-bit division.
107  *
108  * Apple, all: Expensive on 32-bit: it needs 64-bit division.
109  *
110  * Unixy, all: Fairly cheap, since the only division required is dividing
111  * tv_nsec 1000, and nanoseconds-per-second fits in a 32-bit value.
112  *
113  * All, "timestamp units": Cheap everywhere: it never divides.
114  *
115  * Q: This is only somewhat related, but how much precision could I hope for
116  * from a libevent time?
117  *
118  * A: Actually, it's _very_ related if you're timing in order to have a
119  * timeout happen.
120  *
121  * On Windows, it uses select: you could in theory have a microsecond
122  * resolution, but it usually isn't that accurate.
123  *
124  * On OSX, iOS, and BSD, you have kqueue: You could in theory have a nanosecond
125  * resolution, but it usually isn't that accurate.
126  *
127  * On Linux, you have epoll: It has a millisecond resolution. Some recent
128  * Libevents can also use timerfd for higher resolution if
129  * EVENT_BASE_FLAG_PRECISE_TIMER is set: Tor doesn't set that flag.
130  */
131 
132 #ifndef TOR_COMPAT_TIME_H
133 #define TOR_COMPAT_TIME_H
134 
135 #include "orconfig.h"
136 #include "lib/cc/torint.h"
137 
139 
140 #ifdef _WIN32
141 #undef HAVE_CLOCK_GETTIME
142 #endif
143 
144 #if defined(HAVE_CLOCK_GETTIME)
145 /* to ensure definition of CLOCK_MONOTONIC_COARSE if it's there */
146 #include <time.h>
147 #endif
148 
149 #if !defined(HAVE_STRUCT_TIMEVAL_TV_SEC)
150 /** Implementation of timeval for platforms that don't have it. */
151 struct timeval {
152  time_t tv_sec;
153  unsigned int tv_usec;
154 };
155 #endif /* !defined(HAVE_STRUCT_TIMEVAL_TV_SEC) */
156 
157 /** Represents a monotonic timer in a platform-dependent way. */
158 typedef struct monotime_t {
159 #ifdef __APPLE__
160  /* On apple, there is a 64-bit counter whose precision we must look up. */
161  uint64_t abstime_;
162 #elif defined(HAVE_CLOCK_GETTIME)
163  /* It sure would be nice to use clock_gettime(). Posix is a nice thing. */
164  struct timespec ts_;
165 #elif defined (_WIN32)
166  /* On Windows, there is a 64-bit counter whose precision we must look up. */
167  int64_t pcount_;
168 #else
169 #define MONOTIME_USING_GETTIMEOFDAY
170  /* Otherwise, we will be stuck using gettimeofday. */
171  struct timeval tv_;
172 #endif /* defined(__APPLE__) || ... */
173 } monotime_t;
174 
175 #if defined(CLOCK_MONOTONIC_COARSE) && \
176  defined(HAVE_CLOCK_GETTIME)
177 #define MONOTIME_COARSE_FN_IS_DIFFERENT
178 #define monotime_coarse_t monotime_t
179 #elif defined(_WIN32)
180 #define MONOTIME_COARSE_FN_IS_DIFFERENT
181 #define MONOTIME_COARSE_TYPE_IS_DIFFERENT
182 /** Represents a coarse monotonic time in a platform-independent way. */
183 typedef struct monotime_coarse_t {
184  uint64_t tick_count_;
185 } monotime_coarse_t;
186 #elif defined(__APPLE__) && defined(HAVE_MACH_APPROXIMATE_TIME)
187 #define MONOTIME_COARSE_FN_IS_DIFFERENT
188 #define monotime_coarse_t monotime_t
189 #else
190 #define monotime_coarse_t monotime_t
191 #endif /* defined(CLOCK_MONOTONIC_COARSE) && ... || ... */
192 
193 /**
194  * Initialize the timing subsystem. This function is idempotent.
195  */
196 void monotime_init(void);
197 /**
198  * Set <b>out</b> to the current time.
199  */
201 /**
202  * Return the number of nanoseconds between <b>start</b> and <b>end</b>.
203  * The returned value may be equal to zero.
204  */
205 int64_t monotime_diff_nsec(const monotime_t *start, const monotime_t *end);
206 /**
207  * Return the number of microseconds between <b>start</b> and <b>end</b>.
208  * The returned value may be equal to zero.
209  * Fractional units are truncated, not rounded.
210  */
211 int64_t monotime_diff_usec(const monotime_t *start, const monotime_t *end);
212 /**
213  * Return the number of milliseconds between <b>start</b> and <b>end</b>.
214  * The returned value may be equal to zero.
215  * Fractional units are truncated, not rounded.
216  */
217 int64_t monotime_diff_msec(const monotime_t *start, const monotime_t *end);
218 /**
219  * Return the number of nanoseconds since the timer system was initialized.
220  * The returned value may be equal to zero.
221  */
222 uint64_t monotime_absolute_nsec(void);
223 /**
224  * Return the number of microseconds since the timer system was initialized.
225  * The returned value may be equal to zero.
226  * Fractional units are truncated, not rounded.
227  */
228 MOCK_DECL(uint64_t, monotime_absolute_usec,(void));
229 /**
230  * Return the number of milliseconds since the timer system was initialized.
231  * The returned value may be equal to zero.
232  * Fractional units are truncated, not rounded.
233  */
234 uint64_t monotime_absolute_msec(void);
235 
236 /**
237  * Set <b>out</b> to zero.
238  */
239 void monotime_zero(monotime_t *out);
240 /**
241  * Return true iff <b>out</b> is zero
242  */
243 int monotime_is_zero(const monotime_t *out);
244 
245 /**
246  * Set <b>out</b> to N milliseconds after <b>val</b>.
247  */
248 /* XXXX We should add a more generic function here if we ever need to */
249 void monotime_add_msec(monotime_t *out, const monotime_t *val, uint32_t msec);
250 
251 #if defined(MONOTIME_COARSE_FN_IS_DIFFERENT)
252 /**
253  * Set <b>out</b> to the current coarse time.
254  */
255 void monotime_coarse_get(monotime_coarse_t *out);
256 /**
257  * Like monotime_absolute_*(), but faster on some platforms.
258  */
259 uint64_t monotime_coarse_absolute_nsec(void);
260 uint64_t monotime_coarse_absolute_usec(void);
261 uint64_t monotime_coarse_absolute_msec(void);
262 #else /* !defined(MONOTIME_COARSE_FN_IS_DIFFERENT) */
263 #define monotime_coarse_get monotime_get
264 #define monotime_coarse_absolute_nsec monotime_absolute_nsec
265 #define monotime_coarse_absolute_usec monotime_absolute_usec
266 #define monotime_coarse_absolute_msec monotime_absolute_msec
267 #endif /* defined(MONOTIME_COARSE_FN_IS_DIFFERENT) */
268 
269 /**
270  * Return a "timestamp" approximation for a coarse monotonic timer.
271  * This timestamp is meant to be fast to calculate and easy to
272  * compare, and have a unit of something roughly around 1 msec.
273  *
274  * It will wrap over from time to time.
275  *
276  * It has no defined zero point.
277  */
278 uint32_t monotime_coarse_to_stamp(const monotime_coarse_t *t);
279 /**
280  * Convert a difference, expressed in the units of monotime_coarse_to_stamp,
281  * into an approximate number of milliseconds.
282  *
283  * The returned value may be equal to zero.
284  * Fractional units are truncated, not rounded.
285  */
286 uint64_t monotime_coarse_stamp_units_to_approx_msec(uint64_t units);
287 uint64_t monotime_msec_to_approx_coarse_stamp_units(uint64_t msec);
288 uint32_t monotime_coarse_get_stamp(void);
289 
290 #if defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT)
291 /**
292  * Like monotime_diff_*(), but faster on some platforms.
293  */
294 int64_t monotime_coarse_diff_nsec(const monotime_coarse_t *start,
295  const monotime_coarse_t *end);
296 int64_t monotime_coarse_diff_usec(const monotime_coarse_t *start,
297  const monotime_coarse_t *end);
298 int64_t monotime_coarse_diff_msec(const monotime_coarse_t *start,
299  const monotime_coarse_t *end);
300 /**
301  * Like monotime_*(), but faster on some platforms.
302  */
303 void monotime_coarse_zero(monotime_coarse_t *out);
304 int monotime_coarse_is_zero(const monotime_coarse_t *val);
305 void monotime_coarse_add_msec(monotime_coarse_t *out,
306  const monotime_coarse_t *val, uint32_t msec);
307 #else /* !defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT) */
308 #define monotime_coarse_diff_nsec monotime_diff_nsec
309 #define monotime_coarse_diff_usec monotime_diff_usec
310 #define monotime_coarse_diff_msec monotime_diff_msec
311 #define monotime_coarse_zero monotime_zero
312 #define monotime_coarse_is_zero monotime_is_zero
313 #define monotime_coarse_add_msec monotime_add_msec
314 #endif /* defined(MONOTIME_COARSE_TYPE_IS_DIFFERENT) */
315 
316 /**
317  * As monotime_coarse_diff_msec, but avoid 64-bit division.
318  *
319  * Requires that the difference fit into an int32_t; not for use with
320  * large time differences.
321  *
322  * The returned value may be equal to zero.
323  * Fractional units are truncated, not rounded.
324  */
325 int32_t monotime_coarse_diff_msec32_(const monotime_coarse_t *start,
326  const monotime_coarse_t *end);
327 
328 /**
329  * As monotime_coarse_diff_msec, but avoid 64-bit division if it is expensive.
330  *
331  * Requires that the difference fit into an int32_t; not for use with
332  * large time differences.
333  *
334  * The returned value may be equal to zero.
335  * Fractional units are truncated, not rounded.
336  */
337 static inline int32_t
338 monotime_coarse_diff_msec32(const monotime_coarse_t *start,
339  const monotime_coarse_t *end)
340 {
341 #if SIZEOF_VOID_P == 8
342  // on a 64-bit platform, let's assume 64/64 division is cheap.
343  return (int32_t) monotime_coarse_diff_msec(start, end);
344 #else
345 #define USING_32BIT_MSEC_HACK
346  return monotime_coarse_diff_msec32_(start, end);
347 #endif /* SIZEOF_VOID_P == 8 */
348 }
349 
350 #ifdef TOR_UNIT_TESTS
351 void tor_sleep_msec(int msec);
352 
353 void monotime_enable_test_mocking(void);
354 void monotime_disable_test_mocking(void);
355 void monotime_set_mock_time_nsec(int64_t);
356 #if defined(MONOTIME_COARSE_FN_IS_DIFFERENT)
357 void monotime_coarse_set_mock_time_nsec(int64_t);
358 #else
359 #define monotime_coarse_set_mock_time_nsec monotime_set_mock_time_nsec
360 #endif
361 #endif /* defined(TOR_UNIT_TESTS) */
362 
363 #ifdef COMPAT_TIME_PRIVATE
364 #if defined(_WIN32) || defined(TOR_UNIT_TESTS)
365 STATIC int64_t ratchet_performance_counter(int64_t count_raw);
366 STATIC int64_t ratchet_coarse_performance_counter(int64_t count_raw);
367 #endif
368 #if defined(MONOTIME_USING_GETTIMEOFDAY) || defined(TOR_UNIT_TESTS)
369 STATIC void ratchet_timeval(const struct timeval *timeval_raw,
370  struct timeval *out);
371 #endif
372 #ifdef TOR_UNIT_TESTS
373 void monotime_reset_ratchets_for_testing(void);
374 #endif
375 #endif /* defined(COMPAT_TIME_PRIVATE) */
376 
377 #endif /* !defined(TOR_COMPAT_TIME_H) */
void monotime_get(monotime_t *out)
int monotime_is_zero(const monotime_t *out)
static int32_t monotime_coarse_diff_msec32(const monotime_coarse_t *start, const monotime_coarse_t *end)
Definition: compat_time.h:338
int64_t monotime_diff_msec(const monotime_t *start, const monotime_t *end)
Definition: compat_time.c:781
uint32_t monotime_coarse_to_stamp(const monotime_coarse_t *t)
uint64_t monotime_coarse_stamp_units_to_approx_msec(uint64_t units)
Definition: compat_time.c:870
void monotime_zero(monotime_t *out)
Definition: compat_time.c:760
void monotime_add_msec(monotime_t *out, const monotime_t *val, uint32_t msec)
uint64_t monotime_absolute_nsec(void)
Definition: compat_time.c:789
int64_t monotime_diff_nsec(const monotime_t *start, const monotime_t *end)
uint32_t monotime_coarse_get_stamp(void)
Definition: compat_time.c:844
void monotime_init(void)
Definition: compat_time.c:747
int64_t monotime_diff_usec(const monotime_t *start, const monotime_t *end)
Definition: compat_time.c:773
int32_t monotime_coarse_diff_msec32_(const monotime_coarse_t *start, const monotime_coarse_t *end)
uint64_t monotime_absolute_msec(void)
Definition: compat_time.c:807
uint64_t monotime_absolute_usec(void)
Definition: compat_time.c:801
#define STATIC
Definition: testsupport.h:32
#define MOCK_DECL(rv, funcname, arglist)
Definition: testsupport.h:127
Definitions for timing-related constants.
Header for tor_gettimeofday.c.
Integer definitions used throughout Tor.