diff options
Diffstat (limited to 'toxcore/mono_time.h')
-rw-r--r-- | toxcore/mono_time.h | 37 |
1 files changed, 32 insertions, 5 deletions
diff --git a/toxcore/mono_time.h b/toxcore/mono_time.h index 97759560..1d2dd539 100644 --- a/toxcore/mono_time.h +++ b/toxcore/mono_time.h | |||
@@ -8,7 +8,39 @@ | |||
8 | extern "C" { | 8 | extern "C" { |
9 | #endif | 9 | #endif |
10 | 10 | ||
11 | #ifndef MONO_TIME_DEFINED | ||
12 | #define MONO_TIME_DEFINED | ||
13 | /** | ||
14 | * The timer portion of the toxcore event loop. | ||
15 | * | ||
16 | * We update the time exactly once per tox_iterate call. Programs built on lower | ||
17 | * level APIs such as the DHT bootstrap node must update the time manually in | ||
18 | * each iteration. | ||
19 | * | ||
20 | * Time is kept per Tox instance, not globally, even though "time" as a concept | ||
21 | * is global. This is because by definition `mono_time` represents the time at | ||
22 | * the start of an iteration, and also by definition the time when all network | ||
23 | * events for the current iteration occurred. This affects mainly two situations: | ||
24 | * | ||
25 | * 1. Two timers started in the same iteration: e.g. two timers set to expire in | ||
26 | * 10 seconds will both expire at the same time, i.e. about 10 seconds later. | ||
27 | * If the time were global, `mono_time` would be a random number that is | ||
28 | * either the time at the start of an iteration, or 1 second later (since the | ||
29 | * timer resolution is 1 second). This can happen when one update happens at | ||
30 | * e.g. 10:00:00.995 and a few milliseconds later a concurrently running | ||
31 | * instance updates the time at 10:00:01.005, making one timer expire a | ||
32 | * second after the other. | ||
33 | * 2. One timer based on an event: if we want to encode a behaviour of a timer | ||
34 | * expiring e.g. 10 seconds after a network event occurred, we simply start a | ||
35 | * timer in the event handler. If a concurrent instance updates the time | ||
36 | * underneath us, it may instead expire 9 seconds after the event. | ||
37 | * | ||
38 | * Both these situations cause incorrect behaviour randomly. In practice, | ||
39 | * toxcore is somewhat robust against strange timer behaviour, but the | ||
40 | * implementation should at least theoretically match the specification. | ||
41 | */ | ||
11 | typedef struct Mono_Time Mono_Time; | 42 | typedef struct Mono_Time Mono_Time; |
43 | #endif /* MONO_TIME_DEFINED */ | ||
12 | 44 | ||
13 | Mono_Time *mono_time_new(void); | 45 | Mono_Time *mono_time_new(void); |
14 | void mono_time_free(Mono_Time *monotime); | 46 | void mono_time_free(Mono_Time *monotime); |
@@ -17,11 +49,6 @@ void mono_time_update(Mono_Time *monotime); | |||
17 | uint64_t mono_time_get(const Mono_Time *monotime); | 49 | uint64_t mono_time_get(const Mono_Time *monotime); |
18 | bool mono_time_is_timeout(const Mono_Time *monotime, uint64_t timestamp, uint64_t timeout); | 50 | bool mono_time_is_timeout(const Mono_Time *monotime, uint64_t timestamp, uint64_t timeout); |
19 | 51 | ||
20 | // TODO(#405): Use per-tox monotime, delete these functions. | ||
21 | void unix_time_update(void); | ||
22 | uint64_t unix_time(void); | ||
23 | int is_timeout(uint64_t timestamp, uint64_t timeout); | ||
24 | |||
25 | /* return current monotonic time in milliseconds (ms). */ | 52 | /* return current monotonic time in milliseconds (ms). */ |
26 | uint64_t current_time_monotonic(void); | 53 | uint64_t current_time_monotonic(void); |
27 | 54 | ||