[or-cvs] r17783: {tor} Add more missing documentation, and correct an error in cont (in tor/trunk/src: common or)
nickm at seul.org
nickm at seul.org
Fri Dec 26 17:35:09 UTC 2008
Author: nickm
Date: 2008-12-26 12:35:08 -0500 (Fri, 26 Dec 2008)
New Revision: 17783
Modified:
tor/trunk/src/common/container.c
tor/trunk/src/or/connection.c
tor/trunk/src/or/dirserv.c
tor/trunk/src/or/networkstatus.c
tor/trunk/src/or/rephist.c
tor/trunk/src/or/routerlist.c
Log:
Add more missing documentation, and correct an error in container.c documentation: Don't introduce two parameters called n when you're calling an algorithm O(n).
Modified: tor/trunk/src/common/container.c
===================================================================
--- tor/trunk/src/common/container.c 2008-12-26 10:13:26 UTC (rev 17782)
+++ tor/trunk/src/common/container.c 2008-12-26 17:35:08 UTC (rev 17783)
@@ -1199,7 +1199,7 @@
* function for an array of type <b>elt_t</b>*.
*
* NOTE: The implementation kind of sucks: It's O(n log n), whereas finding
- * the nth element of a list can be done in O(n). Then again, this
+ * the kth element of an n-element list can be done in O(n). Then again, this
* implementation is not in critical path, and it is obviously correct. */
#define IMPLEMENT_ORDER_FUNC(funcname, elt_t) \
static int \
Modified: tor/trunk/src/or/connection.c
===================================================================
--- tor/trunk/src/or/connection.c 2008-12-26 10:13:26 UTC (rev 17782)
+++ tor/trunk/src/or/connection.c 2008-12-26 17:35:08 UTC (rev 17783)
@@ -34,9 +34,11 @@
static void client_check_address_changed(int sock);
static void set_constrained_socket_buffers(int sock, int size);
-/* DOCDOC last_interface_ip */
+/** The last IPv4 address that our network interface seemed to have been
+ * binding to, in host order. We use this to detect when our IP changes. */
static uint32_t last_interface_ip = 0;
-/* DOCDOC outgoing_addrs */
+/** A list of uint32_ts for addresses we've used in outgoing connections.
+ * Used to detect IP address changes. */
static smartlist_t *outgoing_addrs = NULL;
/**************************************************************/
Modified: tor/trunk/src/or/dirserv.c
===================================================================
--- tor/trunk/src/or/dirserv.c 2008-12-26 10:13:26 UTC (rev 17782)
+++ tor/trunk/src/or/dirserv.c 2008-12-26 17:35:08 UTC (rev 17783)
@@ -1646,25 +1646,30 @@
* dirserv_compute_performance_thresholds, and used by
* generate_v2_networkstatus */
-/* DOCDOC stable_uptime */
+/** Any router with an uptime of at least this value is stable. */
static uint32_t stable_uptime = 0; /* start at a safe value */
-/* DOCDOC stable_mtbf */
+/** Any router with an mtbf of at least this value is stable. */
static double stable_mtbf = 0.0;
-/* DOCDOC enough_mtbf_info */
+/** If true, we have measured enough mtbf info to look at stable_mtbf rather
+ * than stable_uptime. */
static int enough_mtbf_info = 0;
-/* DOCDOC guard_wfu */
+/** Any router with a weighted fractional uptime of at least this much might
+ * be good as a guard. */
static double guard_wfu = 0.0;
-/* DOCDOC guard_tk */
+/** Don't call a router a guard unless we've known about it for at least this
+ * many seconds. */
static long guard_tk = 0;
-/* DOCDOC fast_bandwidth */
+/** Any router with a bandwidth at least this high is "Fast" */
static uint32_t fast_bandwidth = 0;
-/* DOCDOC guard_bandwidth_including_exits */
+/** If exits can be guards, then all guards must have a bandwidth this
+ * high. */
static uint32_t guard_bandwidth_including_exits = 0;
-/* DOCDOC guard_bandwidth_excluding_exits */
+/** If exits can't be guards, then all guards must have a bandwidth this
+ * high. */
static uint32_t guard_bandwidth_excluding_exits = 0;
-/* DOCDOC total_bandwidth */
+/** Total bandwidth of all the routers we're considering. */
static uint64_t total_bandwidth = 0;
-/* DOCDOC total_exit_bandwidth */
+/** Total bandwidth of all the exit routers we're considering. */
static uint64_t total_exit_bandwidth = 0;
/** Helper: estimate the uptime of a router given its stated uptime and the
Modified: tor/trunk/src/or/networkstatus.c
===================================================================
--- tor/trunk/src/or/networkstatus.c 2008-12-26 10:13:26 UTC (rev 17782)
+++ tor/trunk/src/or/networkstatus.c 2008-12-26 17:35:08 UTC (rev 17783)
@@ -710,12 +710,12 @@
if (!found)
smartlist_add(networkstatus_v2_list, ns);
-/*XXXX021 magic. */
-/*DOCDOC */
-#define V2_NETWORKSTATUS_LIFETIME (3*60*60)
+/** Retain any routerinfo mentioned in a V2 networkstatus for at least this
+ * long. */
+#define V2_NETWORKSTATUS_ROUTER_LIFETIME (3*60*60)
{
- time_t live_until = ns->published_on + V2_NETWORKSTATUS_LIFETIME;
+ time_t live_until = ns->published_on + V2_NETWORKSTATUS_ROUTER_LIFETIME;
SMARTLIST_FOREACH(ns->entries, routerstatus_t *, rs,
{
signed_descriptor_t *sd =
@@ -1755,7 +1755,7 @@
/* Now update last_listed_as_valid_until from v2 networkstatuses. */
/* XXXX If this is slow, we need to rethink the code. */
SMARTLIST_FOREACH(networkstatus_v2_list, networkstatus_v2_t *, ns, {
- time_t live_until = ns->published_on + V2_NETWORKSTATUS_LIFETIME;
+ time_t live_until = ns->published_on + V2_NETWORKSTATUS_ROUTER_LIFETIME;
SMARTLIST_FOREACH_JOIN(ns->entries, routerstatus_t *, rs,
routers, routerinfo_t *, ri,
memcmp(rs->identity_digest,
Modified: tor/trunk/src/or/rephist.c
===================================================================
--- tor/trunk/src/or/rephist.c 2008-12-26 10:13:26 UTC (rev 17782)
+++ tor/trunk/src/or/rephist.c 2008-12-26 17:35:08 UTC (rev 17783)
@@ -1263,9 +1263,9 @@
return b;
}
-/* DOCDOC read_array */
+/** Recent history of bandwidth observations for read operations. */
static bw_array_t *read_array = NULL;
-/* DOCDOC write_array */
+/** Recent history of bandwidth observations for write operations. */
static bw_array_t *write_array = NULL;
/** Set up read_array and write_array. */
@@ -1913,7 +1913,7 @@
time_t start_of_next_period;
} hs_usage_current_observation_period_t;
-/* DOCDOC current_period */
+/** Usage statistics for the current observation period. */
static hs_usage_current_observation_period_t *current_period = NULL;
/* DOCDOC publish_total */
static hs_usage_service_related_observation_t *publish_total = NULL;
Modified: tor/trunk/src/or/routerlist.c
===================================================================
--- tor/trunk/src/or/routerlist.c 2008-12-26 10:13:26 UTC (rev 17782)
+++ tor/trunk/src/or/routerlist.c 2008-12-26 17:35:08 UTC (rev 17783)
@@ -80,9 +80,12 @@
* download is low. */
static time_t last_routerdesc_download_attempted = 0;
-/* DOCDOC This is a massive massive kludge XXXX */
-static uint64_t sl_last_total_weighted_bw = 0;
-static uint64_t sl_last_weighted_bw_of_me = 0;
+/** When we last computed the weights to use for bandwidths on directory
+ * requests, what were the total weighted bandwidth, and our share of that
+ * bandwidth? Used to determine what fraction of directory requests we should
+ * expect to see. */
+static uint64_t sl_last_total_weighted_bw = 0,
+ sl_last_weighted_bw_of_me = 0;
/** Return the number of directory authorities whose type matches some bit set
* in <b>type</b> */
@@ -899,7 +902,10 @@
return choice;
}
-/** DOCDOC */
+/** Try to determine which fraction of v2 and v3 directory requsts aimed at
+ * caches will be sent to us. Set *<b>v2_share_out</b> and
+ * *<b>v3_share_out</b> to the fractions of v2 and v3 protocol shares we
+ * expect to see, respectively. Return 0 on success, negative on failue. */
int
router_get_my_share_of_directory_requests(double *v2_share_out,
double *v3_share_out)
@@ -915,6 +921,7 @@
return -1;
/* Calling for side effect */
+ /* XXXX This is a bit of a kludge */
if (rs->is_v2_dir) {
sl_last_total_weighted_bw = 0;
router_pick_directory_server(V2_AUTHORITY, pds_flags);
@@ -4379,7 +4386,10 @@
return dir_info_status;
}
-/* DOCDOC count_usable_descriptors */
+/** Iterate over the servers listed in <b>consensus</b>, and count how many of
+ * them seem like ones we'd use, and how many of <em>those</em> we have
+ * descriptors for. Store the former in *<b>num_usable</b> and the latter in
+ * *<b>num_present</b>. */
static void
count_usable_descriptors(int *num_present, int *num_usable,
const networkstatus_t *consensus,
More information about the tor-commits
mailing list