src/lib/evloop/time_periodic.md

   1
   2 @page time_periodic Time and periodic events in Tor
   3
   4 ### What time is it? ###
   5
   6 We have several notions of the current time in Tor.
   7
   8 The *wallclock time* is available from time(NULL) with
   9 second-granularity and tor_gettimeofday() with microsecond
  10 granularity.  It corresponds most closely to "the current time and date".
  11
  12 The *monotonic time* is available with the set of monotime_\*
  13 functions declared in compat_time.h.  Unlike the wallclock time, it
  14 can only move forward. It does not necessarily correspond to a real
  15 world time, and it is not portable between systems.
  16
  17 The *coarse monotonic time* is available from the set of
  18 monotime_coarse_\* functions in compat_time.h. It is the same as
  19 monotime_\* on some platforms. On others, it gives a monotonic timer
  20 with less precision, but which it's more efficient to access.
  21
  22 ### Cached views of time. ###
  23
  24 On some systems (like Linux), many time functions use a VDSO to avoid
  25 the overhead of a system call.  But on other systems, gettimeofday()
  26 and time() can be costly enough that you wouldn't want to call them
  27 tens of thousands of times.  To get a recent, but not especially
  28 accurate, view of the current time, see approx_time() and
  29 tor_gettimeofday_cached().
  30
  31
  32 ### Parsing and encoding time values ###
  33
  34 Tor has functions to parse and format time in these formats:
  35
  36  - RFC1123 format. ("Fri, 29 Sep 2006 15:54:20 GMT").  For this,
  37    use format_rfc1123_time() and parse_rfc1123_time.
  38
  39  - ISO8601 format. ("2006-10-29 10:57:20") For this, use
  40    format_local_iso_time() and format_iso_time().  We also support the
  41    variant format "2006-10-29T10:57:20" with format_iso_time_nospace(), and
  42    "2006-10-29T10:57:20.123456" with format_iso_time_nospace_usec().
  43
  44  - HTTP format collections (preferably "Mon, 25 Jul 2016 04:01:11
  45    GMT" or possibly "Wed Jun 30 21:49:08 1993" or even "25-Jul-16
  46    04:01:11 GMT"). For this, use parse_http_time().  Don't generate anything
  47    but the first format.
  48
  49 Some of these functions use struct tm. You can use the standard
  50 tor_localtime_r() and tor_gmtime_r() to wrap these in a safe way. We
  51 also have a tor_timegm() function.
  52
  53 ### Scheduling events ###
  54
  55 The main way to schedule a not-too-frequent periodic event with
  56 respect to the Tor mainloop is via the mechanism in periodic.c.
  57 There's a big table of periodic_events in mainloop.c, each of which gets
  58 invoked on its own schedule.  You should not expect more than about
  59 one second of accuracy with these timers.
  60
  61 You can create an independent timer using libevent directly, or using
  62 the periodic_timer_new() function.  But you should avoid doing this
  63 for per-connection or per-circuit timers: Libevent's internal timer
  64 implementation uses a min-heap, and those tend to start scaling poorly
  65 once you have a few thousand entries.
  66
  67 If you need to create a large number of fine-grained timers for some
  68 purpose, you should consider the mechanism in src/common/timers.c,
  69 which is optimized for the case where you have a large number of
  70 timers with not-too-long duration, many of which will be deleted
  71 before they actually expire. These timers should be reasonably
  72 accurate within a handful of milliseconds -- possibly better on some
  73 platforms.  (The timers.c module uses William Ahern's timeout.c
  74 implementation as its backend, which is based on a hierarchical timing
  75 wheel algorithm. It's cool stuff; check it out.)
  76