[or-cvs] r12018: Document some functions while I can still rememberf what the (in tor/trunk: . src/or)
nickm at seul.org
nickm at seul.org
Thu Oct 18 14:19:52 UTC 2007
Author: nickm
Date: 2007-10-18 10:19:51 -0400 (Thu, 18 Oct 2007)
New Revision: 12018
Modified:
tor/trunk/
tor/trunk/src/or/config.c
tor/trunk/src/or/directory.c
tor/trunk/src/or/dirvote.c
tor/trunk/src/or/networkstatus.c
tor/trunk/src/or/routerlist.c
Log:
r15905 at catbus: nickm | 2007-10-18 09:58:54 -0400
Document some functions while I can still rememberf what they do. Fix up some whitespace.
Property changes on: tor/trunk
___________________________________________________________________
svk:merge ticket from /tor/trunk [r15905] on 8246c3cf-6607-4228-993b-4d95d33730f1
Modified: tor/trunk/src/or/config.c
===================================================================
--- tor/trunk/src/or/config.c 2007-10-18 13:43:29 UTC (rev 12017)
+++ tor/trunk/src/or/config.c 2007-10-18 14:19:51 UTC (rev 12018)
@@ -4363,7 +4363,6 @@
return fname;
}
-
/** Return 0 if every setting in <b>state</b> is reasonable, and a
* permissible transition from <b>old_state</b>. Else warn and return -1.
* Should have no side effects, except for normalizing the contents of
Modified: tor/trunk/src/or/directory.c
===================================================================
--- tor/trunk/src/or/directory.c 2007-10-18 13:43:29 UTC (rev 12017)
+++ tor/trunk/src/or/directory.c 2007-10-18 14:19:51 UTC (rev 12018)
@@ -2716,7 +2716,10 @@
});
}
-/** DOCDOC */
+/** Called when an attempt to download <b>dls</b> has failed with HTTP status
+ * <b>status_code</b>. Increment the failure count (if the code indicates a
+ * real failure) and set <b>dls<b>->next_attempt_at to an appropriate time in
+ * the future. */
time_t
download_status_increment_failure(download_status_t *dls, int status_code,
const char *item, int server, time_t now)
@@ -2761,7 +2764,8 @@
return dls->next_attempt_at;
}
-/** DOCDOC */
+/** Reset <b>dls</b> so that it will be considered downloadable
+ * immediately. */
void
download_status_reset(download_status_t *dls)
{
Modified: tor/trunk/src/or/dirvote.c
===================================================================
--- tor/trunk/src/or/dirvote.c 2007-10-18 13:43:29 UTC (rev 12017)
+++ tor/trunk/src/or/dirvote.c 2007-10-18 14:19:51 UTC (rev 12018)
@@ -1474,7 +1474,6 @@
}
}
-
return any_failed ? NULL : pending_vote;
}
Modified: tor/trunk/src/or/networkstatus.c
===================================================================
--- tor/trunk/src/or/networkstatus.c 2007-10-18 13:43:29 UTC (rev 12017)
+++ tor/trunk/src/or/networkstatus.c 2007-10-18 14:19:51 UTC (rev 12018)
@@ -7,23 +7,27 @@
"$Id$";
/**
- * DOCDOC
+ * \file Functions and structures for handling network status documents as a
+ * client or cache.
*/
#include "or.h"
-/** XXXXX020 are all these still needed */
+/* For tracking v2 networkstatus documents. Only caches do this now. */
-/** DOCDOC */
+/** Map from descriptor digest of routers listed in the v2 networkstatus
+ * documents to download_status_t* */
static digestmap_t *v2_download_status_map = NULL;
+/** Global list of all of the current v2 network_status documents that we know
+ * about. This list is kept sorted by published_on. */
+static smartlist_t *networkstatus_v2_list = NULL;
+/** True iff any member of networkstatus_v2_list has changed since the last
+ * time we called download_status_map_update_from_v2_networkstatus() */
+static int networkstatus_v2_list_has_changed = 0;
/** Map from lowercase nickname to digest of named server, if any. */
static strmap_t *named_server_map = NULL;
-/** Global list of all of the current v2 network_status documents that we know
- * about. This list is kept sorted by published_on. */
-static smartlist_t *networkstatus_v2_list = NULL;
-
/** Most recently received and validated v3 consensus network status. */
static networkstatus_vote_t *current_consensus = NULL;
@@ -32,18 +36,16 @@
static networkstatus_vote_t *consensus_waiting_for_certs = NULL;
static char *consensus_waiting_for_certs_body = NULL;
-/** True iff any member of networkstatus_v2_list has changed since the last
- * time we called routerstatus_list_update_from_networkstatus(). */
-static int networkstatus_v2_list_has_changed = 0;
-
/** The last time we tried to download a networkstatus, or 0 for "never". We
* use this to rate-limit download attempts for directory caches (including
* mirrors). Clients don't use this now. */
static time_t last_networkstatus_download_attempted = 0;
-/**DOCDOC*/
+/** A time before which we shouldn't try to replace the current consensus:
+ * this will be at some point after the next consensus becomes valid, but
+ * before the current consensus becomes invalid. */
static time_t time_to_download_next_consensus = 0;
-/**DOCDOC*/
+/** Download status for the current consensus networkstatus. */
static download_status_t consensus_dl_status = { 0, 0};
/** List of strings for nicknames or fingerprints we've already warned about
@@ -60,10 +62,11 @@
* listed by the authorities */
static int have_warned_about_new_version = 0;
-static void routerstatus_list_update_from_v2_networkstatus(void);
+static void download_status_map_update_from_v2_networkstatus(void);
static void routerstatus_list_update_named_server_map(void);
-/** DOCDOC */
+/** Forget that we've warned about anything networkstatus-related, so we will
+ * give fresh warnings if the same behavior happens again. */
void
networkstatus_reset_warnings(void)
{
@@ -520,7 +523,7 @@
_compare_digest_to_routerstatus_entry);
}
-/** DOCDOC */
+/** Return a list of the v2 networkstatus documents. */
const smartlist_t *
networkstatus_get_v2_list(void)
{
@@ -547,7 +550,8 @@
return digestmap_get(current_consensus->desc_digest_map, digest);
}
-/** DOCDOC */
+/** Given the digest of a router descriptor, return its current download
+ * status, or NULL if the digest is unrecognized. */
download_status_t *
router_get_dl_status_by_descriptor_digest(const char *d)
{
@@ -648,7 +652,8 @@
return best;
}
-/** DOCDOC */
+/** Return the identity digest that's mapped to officially by
+ * <b>nickname</b>. */
const char *
networkstatus_get_router_digest_by_nickname(const char *nickname)
{
@@ -723,28 +728,31 @@
}
}
-/** DOCDOC */
+/** If we want to download a fresh consensus, launch a new download as
+ * appropriate. */
static void
update_consensus_networkstatus_downloads(time_t now)
{
or_options_t *options = get_options();
if (!networkstatus_get_live_consensus(now))
- time_to_download_next_consensus = now;
+ time_to_download_next_consensus = now; /* No live consensus? Get one now!*/
if (time_to_download_next_consensus > now)
- return;
+ return; /* Wait until the current consensus is older. */
if (authdir_mode_v3(options))
- return;
+ return; /* Authorities never fetch a consensus */
+ /*XXXX020 magic number 8.*/
if (!download_status_is_ready(&consensus_dl_status, now, 8))
- return; /*XXXX020 magic number 8.*/
+ return; /* We failed downloading a consensus too recently. */
if (connection_get_by_type_purpose(CONN_TYPE_DIR,
DIR_PURPOSE_FETCH_CONSENSUS))
- return;
+ return; /* There's an in-progress download.*/
directory_get_from_dirserver(DIR_PURPOSE_FETCH_CONSENSUS,
ROUTER_PURPOSE_GENERAL, NULL, 1);
}
-/** DOCDOC */
+/** Called when an attempt to download a consensus fails: note that the
+ * failure occurred, and possibly retry. */
void
networkstatus_consensus_download_failed(int status_code)
{
@@ -753,7 +761,8 @@
update_consensus_networkstatus_downloads(time(NULL));
}
-/** DOCDOC */
+/** Update the time at which we'll consider replacing the current
+ * consensus. */
static void
update_consensus_networkstatus_fetch_time(time_t now)
{
@@ -851,7 +860,8 @@
return NULL;
}
-/** DOCDOC */
+/** Copy all the ancillary information (like router download status and so on)
+ * from <b>old_c</b> to <b>new_c</b> */
static void
networkstatus_copy_old_consensus_info(networkstatus_vote_t *new_c,
const networkstatus_vote_t *old_c)
@@ -999,7 +1009,8 @@
return result;
}
-/** DOCDOC */
+/** Called when we have gotten more certificates: see whether we can
+ * now verify a pending consensus. */
void
networkstatus_note_certs_arrived(void)
{
@@ -1027,10 +1038,8 @@
router_dir_info_changed(); /*XXXX020 really? */
- if (networkstatus_v2_list_has_changed) {
- routerstatus_list_update_from_v2_networkstatus();
- networkstatus_v2_list_has_changed = 0;
- }
+ if (networkstatus_v2_list_has_changed)
+ download_status_map_update_from_v2_networkstatus();
if (!consensus)
return;
@@ -1096,9 +1105,10 @@
}
}
-/** DOCDOC */
+/** Update v2_download_status_map to contain an entry for every router
+ * descriptor listed in the v2 networkstatuses. */
static void
-routerstatus_list_update_from_v2_networkstatus(void)
+download_status_map_update_from_v2_networkstatus(void)
{
digestmap_t *dl_status;
if (!networkstatus_v2_list)
@@ -1123,13 +1133,11 @@
});
digestmap_free(v2_download_status_map, _tor_free);
v2_download_status_map = dl_status;
+ networkstatus_v2_list_has_changed = 0;
}
-/** Update our view of router status (as stored in routerstatus_list) from the
- * current set of network status documents (as stored in networkstatus_list).
- * Do nothing unless the network status list has changed since the last time
- * this function was called. DOCDOC
- */
+/** Update our view of the list of named servers from the most recently
+ * retrieved networkstatus consensus */
static void
routerstatus_list_update_named_server_map(void)
{
@@ -1148,9 +1156,9 @@
});
}
-/** Given a list <b>routers</b> of routerinfo_t *, update each routers's
- * is_named, is_valid, and is_running fields according to our current
- * networkstatus_t documents. May re-order <b>router</b>. DOCDOC */
+/** Given a list <b>routers</b> of routerinfo_t *, update each status fields
+ * according to our current consensus networkstatus. May re-order
+ * <b>router</b>. */
void
routers_update_status_from_consensus_networkstatus(smartlist_t *routers,
int reset_failures)
@@ -1285,7 +1293,7 @@
return 0;
}
-/** DOCDOC */
+/** Free all storage held locally in this module. */
void
networkstatus_free_all(void)
{
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2007-10-18 13:43:29 UTC (rev 12017)
+++ tor/trunk/src/or/routerlist.c 2007-10-18 14:19:51 UTC (rev 12018)
@@ -2101,7 +2101,8 @@
router_dir_info_changed();
}
-/** DOCDOC */
+/** Log information about how much memory is being used for routerlist,
+ * at log level <b>severity</b>. */
void
dump_routerlist_mem_usage(int severity)
{
@@ -3357,7 +3358,10 @@
return 0;
}
-/** DOCDOC */
+/** For every current directory connection whose purpose is <b>purpose</b>,
+ * and where the resource being downloaded begins with <b>prefix</b>, split
+ * rest of the resource into base16 fingerprints, decode them, and set the
+ * corresponding elements of <b>result</b> to a nonzero value. */
static void
list_pending_downloads(digestmap_t *result,
int purpose, const char *prefix)
@@ -3490,7 +3494,9 @@
* them until they have more, or until this amount of time has passed. */
#define MAX_CLIENT_INTERVAL_WITHOUT_REQUEST (10*60)
-/** DOCDOC */
+/** Given a list of router descriptor digests in <b>downloadable</b>, decide
+ * whether to delay fetching until we have more. If we don't want to delay,
+ * launch one or more requests to the appropriate directory authorities. */
static void
launch_router_descriptor_downloads(smartlist_t *downloadable, time_t now)
{
@@ -3691,7 +3697,8 @@
digestmap_free(map,NULL);
}
-/** DOCDOC */
+/** For any descriptor that we want that's currently listed in the live
+ * consensus, download it as appropriate. */
static void
update_consensus_router_descriptor_downloads(time_t now)
{
@@ -3721,10 +3728,9 @@
}
if (!download_status_is_ready(&rs->dl_status, now,
MAX_ROUTERDESC_DOWNLOAD_FAILURES)) {
- ++n_delayed;
+ ++n_delayed; /* Not ready for retry. */
continue;
}
-
if (authdir && dirserv_would_reject_router(rs)) {
++n_would_reject;
continue; /* We would throw it out immediately. */
More information about the tor-commits
mailing list