Commit 59b1b087 authored by Nick Mathewson's avatar Nick Mathewson
Browse files

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
parent 35abfa1f
......@@ -4363,7 +4363,6 @@ get_datadir_fname2_suffix(const char *sub1, const char *sub2,
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
......
......@@ -2716,7 +2716,10 @@ dir_networkstatus_download_failed(smartlist_t *failed, int status_code)
});
}
/** 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 @@ download_status_increment_failure(download_status_t *dls, int status_code,
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)
{
......
......@@ -1474,7 +1474,6 @@ dirvote_add_vote(const char *vote_body, const char **msg_out, int *status_out)
}
}
return any_failed ? NULL : pending_vote;
}
......
......@@ -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
* <b>nickname</b>. */
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 <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 @@ 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 <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 @@ getinfo_helper_networkstatus(control_connection_t *conn,
return 0;
}
/** DOCDOC */
/** Free all storage held locally in this module. */
void
networkstatus_free_all(void)
{
......
......@@ -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 <b>severity</b>. */
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 <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 @@ 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 <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 @@ 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. */
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment