r14185@Kushana: nickm | 2007-08-22 11:07:01 -0400

 Add some voting-related documentation.


svn:r11255

2 files changed, 106 insertions, 44 deletions

diff --git a/src/or/dirserv.c b/src/or/dirserv.c
index 1401a6c907..6975c19887 100644
--- a/src/or/dirserv.c
+++ b/src/or/dirserv.c
@@ -1089,7 +1089,7 @@ static cached_dir_t cached_runningrouters = { NULL, NULL, 0, 0, 0, -1 };
  * cached_dir_t. */
 static digestmap_t *cached_v2_networkstatus = NULL;
 
-/** DOCDOC */
+/** The v3 consensus network status that we're currently serving. */
 static cached_dir_t *cached_v3_networkstatus = NULL;
 
 /** Possibly replace the contents of <b>d</b> with the value of
@@ -1258,7 +1258,9 @@ dirserv_set_cached_networkstatus_v2(const char *networkstatus,
   }
 }
 
-/* DOCDOC */
+/** Replace the v3 consensus networkstatus that we're serving with
+ * <b>networkstatus</b>, published at <b>published</b>.  No validation is
+ * performed. */
 void
 dirserv_set_cached_networkstatus_v3(const char *networkstatus,
                                     time_t published)
@@ -1788,9 +1790,10 @@ _compare_routerinfo_by_id_digest(const void **a, const void **b)
                 DIGEST_LEN);
 }
 
-/** DOCDOC
- *
- * sort first by addr, and then by descending order of usefulness.
+/** Helper for sorting: compares two routerinfos first by address, and then by
+ * descending order of "usefulness".  (An authority is more useful than a
+ * non-authority; a running router is more useful than a non-running router;
+ * and a router with more bandwidth is more useful than one with less.)
  **/
 static int
 _compare_routerinfo_by_ip_and_bw(const void **a, const void **b)
@@ -1806,10 +1809,9 @@ _compare_routerinfo_by_ip_and_bw(const void **a, const void **b)
   else if (first->addr > second->addr)
     return 1;
 
-  /* XXX020 k n lg n memcmps could show up bigtime in profiling. If
-   * they do, I suggest we just give authorities a free pass. -RD */
-  /* I think we're fine.  Remember, in nearly all cases, the addresses
-   * will be different and we'll never actually reach this point. -NM */
+  /* Potentially, this next bit could cause k n lg n memcmp calls.  But in
+   * reality, we will almost never get here, since addresses will usually be
+   * different. */
 
   first_is_auth =
     router_digest_is_trusted_dir(first->cache_info.identity_digest);
@@ -1839,7 +1841,9 @@ _compare_routerinfo_by_ip_and_bw(const void **a, const void **b)
   return _compare_routerinfo_by_id_digest(a, b);
 }
 
-/** DOCDOC takes list of routerinfo */
+/** Given a list of routerinfo_t in <b>routers</b>, return a new digestmap_t
+ * whose keys are the identity digests of those routers that we're going to
+ * exclude for Sybil-like appearance. */
 static digestmap_t *
 get_possible_sybil_list(const smartlist_t *routers)
 {
@@ -1868,7 +1872,11 @@ get_possible_sybil_list(const smartlist_t *routers)
   return omit_as_sybil;
 }
 
-/** DOCDOC */
+/** Extract status information from <b>ri</b> and from other authority
+ * functions and store it in <b>rs</b>>.  If <b>naming</b>, consider setting
+ * the named flag in <b>rs</b>. If not <b>exits_can_be_guards</b>, never mark
+ * an exit as a guard.  If <b>listbadexits</b>, consider setting the badexit
+ * flag. */
 static void
 set_routerstatus_from_routerinfo(routerstatus_t *rs,
                                  routerinfo_t *ri, time_t now,
@@ -1923,7 +1931,8 @@ set_routerstatus_from_routerinfo(routerstatus_t *rs,
   rs->dir_port = ri->dir_port;
 }
 
-/** DOCDOC */
+/** Return a new networkstatus_vote_t* containing our current opinion. (For v3
+ * authorities */
 static networkstatus_vote_t *
 generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
                                 authority_cert_t *cert)
@@ -2062,7 +2071,9 @@ generate_networkstatus_vote_obj(crypto_pk_env_t *private_key,
   return v3_out;
 }
 
-/* private DOCDOC */
+/** Return a new string containing teh string representation of the vote in
+ * <b>v3_ns</b>, signed with our v3 signing key <b>private_signing_key</b>.
+ * For v3 authorities. */
 char *
 format_networkstatus_vote(crypto_pk_env_t *private_signing_key,
                           networkstatus_vote_t *v3_ns)
@@ -2098,7 +2109,7 @@ format_networkstatus_vote(crypto_pk_env_t *private_signing_key,
   */
   char *version_lines = NULL;
   networkstatus_voter_info_t *voter;
-  /* XXX check that everything gets freed */
+  /* XXX020 check that everything gets freed */
 
   tor_assert(private_signing_key);
 
@@ -2793,7 +2804,9 @@ dirserv_remove_old_statuses(smartlist_t *fps, time_t cutoff)
   return found_any;
 }
 
-/** DOCDOC */
+/** Return true iff we have any of the docments (extrainfo or routerdesc)
+ * specified by the fingerprints in <b>fps</b> and <b>spool_src</b>.  Used to
+ * decide whether to send a 404.  */
 int
 dirserv_have_any_serverdesc(smartlist_t *fps, int spool_src)
 {
diff --git a/src/or/dirvote.c b/src/or/dirvote.c
index b593db5ccb..6378e6966f 100644
--- a/src/or/dirvote.c
+++ b/src/or/dirvote.c
@@ -732,7 +732,9 @@ networkstatus_check_voter_signature(networkstatus_vote_t *consensus,
   return 0;
 }
 
-/** DOCDOC */
+/** Given a v3 networkstatus consensus in <b>consensus</b>, check every
+ * as-yet-unchecked signature on <b>consensus.  Return 0 if there are enough
+ * good signatures from recognized authorities on it, and -1 otherwise. */
 int
 networkstatus_check_consensus_signature(networkstatus_vote_t *consensus)
 {
@@ -780,7 +782,16 @@ networkstatus_check_consensus_signature(networkstatus_vote_t *consensus)
     return -1;
 }
 
-/** DOCDOC */
+/** Given a consensus vote <b>target</b> and a list of
+ * notworkstatus_voter_info_t in <b>src_voter_list</b> that correspond to the
+ * same consensus, check whether there are any new signatures in
+ * <b>src_voter_list</b> that should be added to <b>target.  (A signature
+ * should be added if we have no signature for that voter in <b>target</b>
+ * yet, or if we have no verifiable signature and the new signature is
+ * verifiable.)  Set *<b>new_signatures_out</b> to a newly allocated string
+ * holding the newly added signatures; set *<b>regenerate_out</b> to true if
+ * we replaced a signature and 0 otherwise.  Return the number of signatures
+ * added or changed. */
 static int
 networkstatus_add_signatures_impl(networkstatus_vote_t *target,
                                   smartlist_t *src_voter_list,
@@ -862,7 +873,8 @@ networkstatus_add_signatures_impl(networkstatus_vote_t *target,
   return r;
 }
 
-/** DOCDOC */
+/** As networkstatus_add_consensus_signature_impl, but takes new signatures
+ * from the consensus in <b>src</b>. */
 int
 networkstatus_add_consensus_signatures(networkstatus_vote_t *target,
                                        networkstatus_vote_t *src,
@@ -886,7 +898,8 @@ networkstatus_add_consensus_signatures(networkstatus_vote_t *target,
                                            regenerate_out);
 }
 
-/** DOCDOC */
+/** As networkstatus_add_consensus_signature_impl, but takes new signatures
+ * from the detached signatures document <b>sigs</b>. */
 int
 networkstatus_add_detached_signatures(networkstatus_vote_t *target,
                                       ns_detached_signatures_t *sigs,
@@ -907,7 +920,8 @@ networkstatus_add_detached_signatures(networkstatus_vote_t *target,
                                            regenerate_out);
 }
 
-/** DOCDOC */
+/** Return a newly allocated string holding the detached-signatures document
+ * corresponding to the signatures on <b>consensus</b>. */
 char *
 networkstatus_get_detached_signatures(networkstatus_vote_t *consensus)
 {
@@ -965,7 +979,7 @@ networkstatus_get_detached_signatures(networkstatus_vote_t *consensus)
   return result;
 }
 
-/** DOCDOC */
+/** Release all storage held in <b>s</b>. */
 void
 ns_detached_signatures_free(ns_detached_signatures_t *s)
 {
@@ -1024,7 +1038,9 @@ authority_cert_dup(authority_cert_t *cert)
  * Vote scheduling
  * ===== */
 
-/** DOCDOC */
+/** Set *<b>timing_out</b> to the intervals at which we would like to vote.
+ * Note that these aren't the intervals we'll use to vote; they're the ones
+ * that we'll vote to use. */
 void
 dirvote_get_preferred_voting_intervals(vote_timing_t *timing_out)
 {
@@ -1038,7 +1054,10 @@ dirvote_get_preferred_voting_intervals(vote_timing_t *timing_out)
   timing_out->dist_delay = options->V3AuthDistDelay;
 }
 
-/** DOCDOC */
+/** Return the start of the next interval of size <b>interval</b> (in seconds)
+ * after <b>now</b>.  Midnight always starts a fresh interval, and if the last
+ * interval of a day would be truncated to less than half its size, it is
+ * rolled into the previous interval. */
 time_t
 dirvote_get_start_of_next_interval(time_t now, int interval)
 {
@@ -1069,20 +1088,28 @@ dirvote_get_start_of_next_interval(time_t now, int interval)
   return next;
 }
 
-/** DOCDOC */
+/** Scheduling information for a voting interval. */
 static struct {
+  /** When do we generate and distribute our vote for this interval? */
   time_t voting_starts;
+  /** When do we give up on getting more votes and generate a consensus? */
   time_t voting_ends;
+  /** When do we publish the consensus? */
   time_t interval_starts;
 
+  /** When do we discard old votes and pending detached signatures? */
   time_t discard_old_votes;
 
+  /* True iff we have generated and distributed our vote. */
   int have_voted;
+  /* True iff we have built a consensus and sent the signatures around. */
   int have_built_consensus;
+  /* True iff we have published our consensus. */
   int have_published_consensus;
 } voting_schedule = {0,0,0,0,0,0,0};
 
-/** DOCDOC */
+/** Set voting_schedule to hold the timing for the next vote we should be
+ * doing. */
 void
 dirvote_recalculate_timing(time_t now)
 {
@@ -1100,8 +1127,7 @@ dirvote_recalculate_timing(time_t now)
     vote_delay = consensus->vote_seconds;
     dist_delay = consensus->dist_seconds;
   } else {
-    /* XXXX020 drop this back down to 30 minutes. */
-    interval = 1200;
+    interval = 30*60;
     vote_delay = dist_delay = 300;
   }
 
@@ -1123,7 +1149,7 @@ dirvote_recalculate_timing(time_t now)
     ((end-start) - vote_delay - dist_delay)/2 ;
 }
 
-/** DOCDOC */
+/** Entry point: Take whatever voting actions are pending as of <b>now</b>. */
 void
 dirvote_act(time_t now)
 {
@@ -1165,24 +1191,30 @@ dirvote_act(time_t now)
   }
 }
 
-/** DOCDOC */
+/** A vote networkstatus_vote_t and its unparsed body: held around so we can
+ * use it to generate a consensus (at voting_ends) and so we can serve it to
+ * other authorities that might want it. */
 typedef struct pending_vote_t {
   cached_dir_t *vote_body;
   networkstatus_vote_t *vote;
 } pending_vote_t;
 
-/** DOCDOC */
+/** List of pending_vote_t for the current vote. */
 static smartlist_t *pending_vote_list = NULL;
-/** DOCDOC */
+/** The body of the consensus that we're currently building.  Once we
+ * have it built, it goes into dirserv.c */
 static char *pending_consensus_body = NULL;
-/** DOCDOC */
+/** The detached signatures for the consensus that we're currently
+ * building. */
 static char *pending_consensus_signatures = NULL;
-/** DOCDOC */
+/** The parsed in-progress consensus document. */
 static networkstatus_vote_t *pending_consensus = NULL;
-/** DOCDOC */
+/** List of ns_detached_signatures_t: hold signatures that get posted to us
+ * before we have generated the consensus on our own. */
 static smartlist_t *pending_consensus_signature_list = NULL;
 
-/** DOCDOC */
+/** Generate a networkstatus vote and post it to all the v3 authorities.
+ * (V3 Authority only) */
 void
 dirvote_perform_vote(void)
 {
@@ -1208,7 +1240,7 @@ dirvote_perform_vote(void)
   log_notice(LD_DIR, "Vote posted.");
 }
 
-/** DOCDOC */
+/** Drop all currently pending votes, consensus, and detached signatures. */
 void
 dirvote_clear_pending_votes(void)
 {
@@ -1251,7 +1283,11 @@ list_v3_auth_ids(void)
   return keys;
 }
 
-/** DOCDOC */
+/** Called when we have received a networkstatus vote in <b>vote_body</b>.
+ * Parse and validate it, and on success store it as a pending vote (which we
+ * then return).  Return NULL on failure.  Sets *<b>msg_out</b> and
+ * *<b>status_out</b> to an HTTP response and status code.  (V3 authority
+ * only) */
 pending_vote_t *
 dirvote_add_vote(const char *vote_body, const char **msg_out, int *status_out)
 {
@@ -1351,7 +1387,10 @@ dirvote_add_vote(const char *vote_body, const char **msg_out, int *status_out)
   return NULL;
 }
 
-/** DOCDOC */
+/** Try to compute a v3 networkstatus consensus from the currently pending
+ * votes.  Return 0 on success, -1 on failure.  Store the consensus in
+ * pending_consensus: it won't be ready to be published until we have
+ * everybody else's signatures collected too. (V3 Authoritity only) */
 int
 dirvote_compute_consensus(void)
 {
@@ -1448,7 +1487,9 @@ dirvote_compute_consensus(void)
   return -1;
 }
 
-/** DOCDOC */
+/** Helper: we just got the <b>deteached_signatures_body</b> sent to us as
+ * signatures on the currently pending consensus.  Add them to the consensus
+ * as appropriate.  Return the number of signatures added. (?) */
 static int
 dirvote_add_signatures_to_pending_consensus(
                        const char *detached_signatures_body,
@@ -1541,10 +1582,14 @@ dirvote_add_signatures_to_pending_consensus(
   return r;
 }
 
-/** DOCDOC */
+/** Helper: we just got the <b>deteached_signatures_body</b> sent to us as
+ * signatures on the currently pending consensus.  Add them to the pending
+ * consensus (if we have one); otherwise queue them until we have a
+ * consensus. */
 int
 dirvote_add_signatures(const char *detached_signatures_body)
 {
+  /*XXXX020 return value is senseless. */
   if (pending_consensus) {
     const char *msg=NULL;
     log_notice(LD_DIR, "Got a signature. Adding it to the pending consensus.");
@@ -1560,7 +1605,8 @@ dirvote_add_signatures(const char *detached_signatures_body)
   }
 }
 
-/** DOCDOC */
+/** Replace the consensus that we're currently serving with the one that we've
+ * been building. (V3 Authority only) */
 int
 dirvote_publish_consensus(void)
 {
@@ -1606,21 +1652,24 @@ dirvote_free_all(void)
  * Access to pending items.
  * ==== */
 
-/** DOCDOC */
+/** Return the body of the consensus that we're currently trying to build. */
 const char *
 dirvote_get_pending_consensus(void)
 {
   return pending_consensus_body;
 }
 
-/** DOCDOC */
+/** Return the signatures that we know for the consensus that we're currently
+ * trying to build */
 const char *
 dirvote_get_pending_detached_signatures(void)
 {
   return pending_consensus_signatures;
 }
 
-/** DOCDOC */
+/** Return the vote for the authority with the v3 authority identity key
+ * digest <b>id</b>.  If <b>id</b> is NULL, return our own vote. May return
+ * NULL if we have no vote for the authority in question. */
 const cached_dir_t *
 dirvote_get_vote(const char *id)
 {