commit 6744f6b6bba2af2d3d3712825a28e75b0304d7b8
parent b0f9ecdbb138529fb9428121a62e8a5004767761
Author: Nick Mathewson <nickm@torproject.org>
Date: Tue, 12 Nov 2019 12:14:14 -0500
HACKING/design: move 01c-time.md into doxygen.
Diffstat:
3 files changed, 80 insertions(+), 75 deletions(-)
diff --git a/doc/HACKING/design/01c-time.md b/doc/HACKING/design/01c-time.md
@@ -1,75 +0,0 @@
-
-## 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.)
diff --git a/src/lib/evloop/time_periodic.dox b/src/lib/evloop/time_periodic.dox
@@ -0,0 +1,78 @@
+/**
+
+@page time_periodic Time and periodic events 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 mainloop.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.)
+
+**/
diff --git a/src/mainpage.dox b/src/mainpage.dox
@@ -38,6 +38,8 @@ Tor repository.
@subpage strings
+@subpage time_periodic
+
**/
/**
