commit eb721ed2d9f3abc049b92b904f5d47d08bae9311 Author: Nick Mathewson nickm@torproject.org Date: Mon Nov 16 10:40:23 2015 -0500

Add documentation for periodic event api --- src/or/main.c | 23 +++++++++++++++++++---- src/or/periodic.c | 10 +++++++--- 2 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/src/or/main.c b/src/or/main.c index d5d4112..1dd791f 100644 --- a/src/or/main.c +++ b/src/or/main.c @@ -1228,9 +1228,11 @@ get_signewnym_epoch(void) return newnym_epoch; }

-/** DOCDOC */ +/** True iff we have initialized all the members of <b>periodic_events</b>. + * Used to prevent double-initialization. */ static int periodic_events_initialized = 0;

+/* Declare all the timer callback functions... */ #define CALLBACK(name) \ static int name ## _callback(time_t, const or_options_t *) CALLBACK(rotate_onion_key); @@ -1260,6 +1262,8 @@ CALLBACK(check_fw_helper_app); CALLBACK(heartbeat);

#undef CALLBACK + +/* Now we declare an array of periodic_event_item_t for each periodic event */ #define CALLBACK(name) PERIODIC_EVENT(name)

static periodic_event_item_t periodic_events[] = { @@ -1292,6 +1296,10 @@ static periodic_event_item_t periodic_events[] = { }; #undef CALLBACK

+/* These are pointers to members of periodic_events[] that are used to + * implement particular callbacks. We keep them separate here so that we + * can access them by name. We also keep them inside periodic_events[] + * so that we can implement "reset all timers" in a reasaonable way. */ static periodic_event_item_t *check_descriptor_event=NULL; static periodic_event_item_t *fetch_networkstatus_event=NULL; static periodic_event_item_t *launch_descriptor_fetches_event=NULL; @@ -1311,7 +1319,9 @@ reset_all_main_loop_timers(void) } }

-/**DOCDOC*/ +/** Return the member of periodic_events[] whose name is <b>name</b>. + * Return NULL if no such event is found. + */ static periodic_event_item_t * find_periodic_event(const char *name) { @@ -1323,7 +1333,11 @@ find_periodic_event(const char *name) return NULL; }

-/** DOCDOC */ +/** Helper, run one second after setup: + * Initializes all members of periodic_events and starts them running. + * + * (We do this one second after setup for backward-compatibility reasons; + * it might not actually be necessary.) */ static void initialize_periodic_events_cb(evutil_socket_t fd, short events, void *data) { @@ -1336,7 +1350,8 @@ initialize_periodic_events_cb(evutil_socket_t fd, short events, void *data) } }

-/** DOCDOC */ +/** Set up all the members of periodic_events[], and configure them all to be + * launched from a callback. */ static void initialize_periodic_events(void) { diff --git a/src/or/periodic.c b/src/or/periodic.c index 44e1714..708c009 100644 --- a/src/or/periodic.c +++ b/src/or/periodic.c @@ -12,9 +12,13 @@ #include <event.h> #endif

+/** We disable any interval greate than this number of seconds, on the ground + * that it is probably an absolute time mistakenly passed in as a relative time. + */ static const int MAX_INTERVAL = 10 * 365 * 86400;

-/** DOCDOC */ +/** Set the event <b>event</b> to run in <b>next_interval</b> seconds from + * now. */ static void periodic_event_set_interval(periodic_event_item_t *event, time_t next_interval) @@ -65,7 +69,7 @@ periodic_event_dispatch(evutil_socket_t fd, short what, void *data) log_info(LD_GENERAL, "Dispatching %s", event->name); }

-/** DOCDOC */ +/** Schedules <b>event</b> to run as soon as possible from now. */ void periodic_event_reschedule(periodic_event_item_t *event) { @@ -92,7 +96,7 @@ periodic_event_launch(periodic_event_item_t *event) periodic_event_dispatch(-1, EV_TIMEOUT, event); }

-/** DOCDOC */ +/** Release all storage associated with <b>event</b> */ void periodic_event_destroy(periodic_event_item_t *event) {