[tor-commits] [tor/master] Add documentation for periodic event api

[nickm at torproject.org]

commit eb721ed2d9f3abc049b92b904f5d47d08bae9311
Author: Nick Mathewson <nickm at 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)
 {