From: Nick Mathewson Date: Thu, 18 Oct 2007 14:19:51 +0000 (+0000) Subject: r15905@catbus: nickm | 2007-10-18 09:58:54 -0400 X-Git-Tag: tor-0.2.0.9-alpha~86 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=59b1b0875341a1592e23d59639f364328e9b27ad;p=thirdparty%2Ftor.git r15905@catbus: nickm | 2007-10-18 09:58:54 -0400 Document some functions while I can still rememberf what they do. Fix up some whitespace. svn:r12018 --- diff --git a/src/or/config.c b/src/or/config.c index 7d64ede61c..338f53875e 100644 --- a/src/or/config.c +++ b/src/or/config.c @@ -4363,7 +4363,6 @@ get_datadir_fname2_suffix(const char *sub1, const char *sub2, return fname; } - /** Return 0 if every setting in state is reasonable, and a * permissible transition from old_state. Else warn and return -1. * Should have no side effects, except for normalizing the contents of diff --git a/src/or/directory.c b/src/or/directory.c index 36e2b05a56..f12eb7588e 100644 --- a/src/or/directory.c +++ b/src/or/directory.c @@ -2716,7 +2716,10 @@ dir_networkstatus_download_failed(smartlist_t *failed, int status_code) }); } -/** DOCDOC */ +/** Called when an attempt to download dls has failed with HTTP status + * status_code. Increment the failure count (if the code indicates a + * real failure) and set dls->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 @@ download_status_increment_failure(download_status_t *dls, int status_code, return dls->next_attempt_at; } -/** DOCDOC */ +/** Reset dls so that it will be considered downloadable + * immediately. */ void download_status_reset(download_status_t *dls) { diff --git a/src/or/dirvote.c b/src/or/dirvote.c index 721e8bee1f..f28a7311bd 100644 --- a/src/or/dirvote.c +++ b/src/or/dirvote.c @@ -1474,7 +1474,6 @@ dirvote_add_vote(const char *vote_body, const char **msg_out, int *status_out) } } - return any_failed ? NULL : pending_vote; } diff --git a/src/or/networkstatus.c b/src/or/networkstatus.c index 8a174482e5..f395d0103c 100644 --- a/src/or/networkstatus.c +++ b/src/or/networkstatus.c @@ -7,22 +7,26 @@ const char networkstatus_c_id[] = "$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; - -/** 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; +/** 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; /** Most recently received and validated v3 consensus network status. */ static networkstatus_vote_t *current_consensus = NULL; @@ -32,18 +36,16 @@ static networkstatus_vote_t *current_consensus = NULL; 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 @@ static int have_warned_about_old_version = 0; * 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 @@ networkstatus_vote_find_entry(networkstatus_vote_t *ns, const char *digest) _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 @@ router_get_consensus_status_by_descriptor_digest(const char *digest) 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 @@ router_get_consensus_status_by_nickname(const char *nickname, return best; } -/** DOCDOC */ +/** Return the identity digest that's mapped to officially by + * nickname. */ const char * networkstatus_get_router_digest_by_nickname(const char *nickname) { @@ -723,28 +728,31 @@ update_v2_networkstatus_cache_downloads(time_t now) } } -/** 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 @@ networkstatus_consensus_download_failed(int status_code) 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 @@ networkstatus_get_live_consensus(time_t now) return NULL; } -/** DOCDOC */ +/** Copy all the ancillary information (like router download status and so on) + * from old_c to new_c */ static void networkstatus_copy_old_consensus_info(networkstatus_vote_t *new_c, const networkstatus_vote_t *old_c) @@ -999,7 +1009,8 @@ networkstatus_set_current_consensus(const char *consensus, int from_cache, 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 @@ routers_update_all_from_networkstatus(time_t now) 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 @@ routers_update_all_from_networkstatus(time_t now) } } -/** 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 @@ routerstatus_list_update_from_v2_networkstatus(void) }); 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 @@ routerstatus_list_update_named_server_map(void) }); } -/** Given a list routers 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 router. DOCDOC */ +/** Given a list routers of routerinfo_t *, update each status fields + * according to our current consensus networkstatus. May re-order + * router. */ void routers_update_status_from_consensus_networkstatus(smartlist_t *routers, int reset_failures) @@ -1285,7 +1293,7 @@ getinfo_helper_networkstatus(control_connection_t *conn, return 0; } -/** DOCDOC */ +/** Free all storage held locally in this module. */ void networkstatus_free_all(void) { diff --git a/src/or/routerlist.c b/src/or/routerlist.c index 77d9dc4377..cea82a5b64 100644 --- a/src/or/routerlist.c +++ b/src/or/routerlist.c @@ -2101,7 +2101,8 @@ routerlist_free(routerlist_t *rl) router_dir_info_changed(); } -/** DOCDOC */ +/** Log information about how much memory is being used for routerlist, + * at log level severity. */ void dump_routerlist_mem_usage(int severity) { @@ -3357,7 +3358,10 @@ any_trusted_dir_is_v1_authority(void) return 0; } -/** DOCDOC */ +/** For every current directory connection whose purpose is purpose, + * and where the resource being downloaded begins with prefix, split + * rest of the resource into base16 fingerprints, decode them, and set the + * corresponding elements of result to a nonzero value. */ static void list_pending_downloads(digestmap_t *result, int purpose, const char *prefix) @@ -3490,7 +3494,9 @@ client_would_use_router(routerstatus_t *rs, time_t now, or_options_t *options) * 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 downloadable, 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 @@ update_router_descriptor_cache_downloads(time_t now) 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 @@ update_consensus_router_descriptor_downloads(time_t now) } 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. */