mirror of
https://gitlab.torproject.org/tpo/core/tor.git
synced 2024-12-11 13:13:37 +01:00
469051f650
I started this repository a while ago to work on documentation for Tor's internals. It needs substantial revision, but first, let's get it copied into Tor's repository. These files are copied, "warts and all", from the tor-guts.git repo, commit de1e34259178b09861c0dea319c760fa80d0099a. Part of 31819.
76 lines
3.2 KiB
Markdown
76 lines
3.2 KiB
Markdown
|
|
## Time in tor ##
|
|
|
|
### What time is it? ###
|
|
|
|
We have several notions of the current time in Tor.
|
|
|
|
The *wallclock time* is available from time(NULL) with
|
|
second-granularity and tor_gettimeofday() with microsecond
|
|
granularity. It corresponds most closely to "the current time and date".
|
|
|
|
The *monotonic time* is available with the set of monotime_\*
|
|
functions declared in compat_time.h. Unlike the wallclock time, it
|
|
can only move forward. It does not necessarily correspond to a real
|
|
world time, and it is not portable between systems.
|
|
|
|
The *coarse monotonic time* is available from the set of
|
|
monotime_coarse_\* functions in compat_time.h. It is the same as
|
|
monotime_\* on some platforms. On others, it gives a monotonic timer
|
|
with less precision, but which it's more efficient to access.
|
|
|
|
### Cached views of time. ###
|
|
|
|
On some systems (like Linux), many time functions use a VDSO to avoid
|
|
the overhead of a system call. But on other systems, gettimeofday()
|
|
and time() can be costly enough that you wouldn't want to call them
|
|
tens of thousands of times. To get a recent, but not especially
|
|
accurate, view of the current time, see approx_time() and
|
|
tor_gettimeofday_cached().
|
|
|
|
|
|
### Parsing and encoding time values ###
|
|
|
|
Tor has functions to parse and format time in these formats:
|
|
|
|
* RFC1123 format. ("Fri, 29 Sep 2006 15:54:20 GMT"). For this,
|
|
use format_rfc1123_time() and parse_rfc1123_time.
|
|
|
|
* ISO8601 format. ("2006-10-29 10:57:20") For this, use
|
|
format_local_iso_time and format_iso_time. We also support the
|
|
variant format "2006-10-29T10:57:20" with format_iso_time_nospace, and
|
|
"2006-10-29T10:57:20.123456" with format_iso_time_nospace_usec.
|
|
|
|
* HTTP format collections (preferably "Mon, 25 Jul 2016 04:01:11
|
|
GMT" or possibly "Wed Jun 30 21:49:08 1993" or even "25-Jul-16
|
|
04:01:11 GMT"). For this, use parse_http_time. Don't generate anything
|
|
but the first format.
|
|
|
|
Some of these functions use struct tm. You can use the standard
|
|
tor_localtime_r and tor_gmtime_r() to wrap these in a safe way. We
|
|
also have a tor_timegm() function.
|
|
|
|
### Scheduling events ###
|
|
|
|
The main way to schedule a not-too-frequent periodic event with
|
|
respect to the Tor mainloop is via the mechanism in periodic.c.
|
|
There's a big table of periodic_events in main.c, each of which gets
|
|
invoked on its own schedule. You should not expect more than about
|
|
one second of accuracy with these timers.
|
|
|
|
You can create an independent timer using libevent directly, or using
|
|
the periodic_timer_new() function. But you should avoid doing this
|
|
for per-connection or per-circuit timers: Libevent's internal timer
|
|
implementation uses a min-heap, and those tend to start scaling poorly
|
|
once you have a few thousand entries.
|
|
|
|
If you need to create a large number of fine-grained timers for some
|
|
purpose, you should consider the mechanism in src/common/timers.c,
|
|
which is optimized for the case where you have a large number of
|
|
timers with not-too-long duration, many of which will be deleted
|
|
before they actually expire. These timers should be reasonably
|
|
accurate within a handful of milliseconds -- possibly better on some
|
|
platforms. (The timers.c module uses William Ahern's timeout.c
|
|
implementation as its backend, which is based on a hierarchical timing
|
|
wheel algorithm. It's cool stuff; check it out.)
|