r18291@catbus: nickm | 2008-02-20 22:35:32 -0500

Resolve all DOCDOC issues, and document some other undocumented code, and fix a changelog entry.


svn:r13638

ChangeLog

@@ -14,9 +14,9 @@ Changes in version 0.2.0.20-?? - 2008-02-??
       by nwf; bugfix on 0.1.2.x.
     - When counting the number of open sockets, count not only the number
       of sockets we have received from the socket() call, but also the
-      number we've gotten from accept().  This bug made us fail to count
+      number we've gotten from accept() and socketpair().  This bug made us
-      all sockets that we were using for incoming connections.  Bugfix on
+      fail to count all sockets that we were using for incoming
-      0.2.0.x
+      connections.  Bugfix on 0.2.0.x.
     - Fix code used to find strings within buffers, when those strings
       are not in the first chunk of the buffer.
     - Fix potential segfault when parsing HTTP headers. Bugfix on 0.2.0.x.

src/common/compat.c

@@ -489,7 +489,10 @@ touch_file(const char *fname)
 
 #undef DEBUG_SOCKET_COUNTING
 #ifdef DEBUG_SOCKET_COUNTING
+/** A bitarray of all fds that should be passed to tor_socket_close(). Only
+ * used if DEBUG_SOCKET_COUNTING is defined. */
 static bitarray_t *open_sockets = NULL;
+/** The size of <b>open_sockets</b>, in bits. */
 static int max_socket = -1;
 #endif
 
@@ -547,6 +550,8 @@ tor_close_socket(int s)
 }
 
 #ifdef DEBUG_SOCKET_COUNTING
+/** Helper: if DEBUG_SOCKET_COUNTING is enabled, remember that <b>s</b> is
+ * now an open socket. */
 static INLINE void
 mark_socket_open(int s)
 {

src/common/compat.h

@@ -331,7 +331,8 @@ struct sockaddr_in6 {
 
 typedef uint8_t maskbits_t;
 struct in_addr;
-/** DOCDOC */
+/** Holds an IPv4 or IPv6 address.  (Uses less memory than struct
+ * sockaddr_storage.) */
 typedef struct tor_addr_t
 {
   sa_family_t family;

src/or/config.c

@@ -2446,7 +2446,7 @@ options_init(or_options_t *options)
   config_init(&options_format, options);
 }
 
-/* Set all vars in the configuration object 'options' to their default
+/** Set all vars in the configuration object 'options' to their default
  * values. */
 static void
 config_init(config_format_t *fmt, void *options)

src/or/connection_edge.c

@@ -2593,7 +2593,7 @@ connection_exit_connect(edge_connection_t *edge_conn)
  * conn, and join them together.  Return 0 on success (or if there was an
  * error we could send back an end cell for).  Return -(some circuit end
  * reason) if the circuit needs to be torn down.  Either connects
- * <b>exitconn<b/>, frees it, or marks it, as appropriate.
+ * <b>exitconn</b>, frees it, or marks it, as appropriate.
  */
 static int
 connection_exit_connect_dir(edge_connection_t *exitconn)

src/or/dirserv.c

@@ -1614,6 +1614,7 @@ should_generate_v2_networkstatus(void)
 /* Thresholds for server performance: set by
  * dirserv_compute_performance_thresholds, and used by
  * generate_v2_networkstatus */
+/* XXXX stick these all in a struct. */
 static uint32_t stable_uptime = 0; /* start at a safe value */
 static double stable_mtbf = 0.0;
 static int enough_mtbf_info = 0;
@@ -1687,12 +1688,14 @@ dirserv_thinks_router_is_hs_dir(routerinfo_t *router, time_t now)
           router->is_running);
 }
 
-/** Look through the routerlist, and assign the median uptime of running valid
+/** Look through the routerlist, the Mean Time Between Failure history, and
- * servers to stable_uptime, and the relative bandwidth capacities to
+ * the Weighted Fractional Uptime history, and use them to set thresholds for
- * fast_bandwidth and guard_bandwidth.  Set total_bandwidth to the total
+ * the Stable, Fast, and Guard flags.  Update the fields stable_uptime,
- * capacity of all running valid servers and total_exit_bandwidth to the
+ * stable_mtbf, enough_mtbf_info, guard_wfu, guard_tk, fast_bandwidth,
- * capacity of all running valid exits.  Set the is_exit flag of each router
+ * guard_bandwidh_including_exits, guard_bandwidth_excluding_exits,
- * appropriately. */
+ * total_bandwidth, and total_exit_bandwidth.
+ *
+ * Also, set the is_exit flag of each router appropriately. */
 static void
 dirserv_compute_performance_thresholds(routerlist_t *rl)
 {
@@ -1702,8 +1705,6 @@ dirserv_compute_performance_thresholds(routerlist_t *rl)
   double *mtbfs, *wfus;
   time_t now = time(NULL);
 
-  /* DOCDOC this is a litle tricky; comment this function better. */
-
   /* initialize these all here, in case there are no routers */
   stable_uptime = 0;
   stable_mtbf = 0;
@@ -1712,19 +1713,27 @@ dirserv_compute_performance_thresholds(routerlist_t *rl)
   guard_bandwidth_excluding_exits = 0;
   guard_tk = 0;
   guard_wfu = 0;
-
   total_bandwidth = 0;
   total_exit_bandwidth = 0;
 
+  /* Initialize arrays that will hold values for each router.  We'll
+   * sort them and use that to compute thresholds. */
   n_active = n_active_nonexit = 0;
+  /* Uptime for every active router. */
   uptimes = tor_malloc(sizeof(uint32_t)*smartlist_len(rl->routers));
+  /* Bandwidth for every active router. */
   bandwidths = tor_malloc(sizeof(uint32_t)*smartlist_len(rl->routers));
+  /* Bandwidth for every active non-exit router. */
   bandwidths_excluding_exits =
     tor_malloc(sizeof(uint32_t)*smartlist_len(rl->routers));
+  /* Weighted mean time between failure for each active router. */
   mtbfs = tor_malloc(sizeof(double)*smartlist_len(rl->routers));
+  /* Time-known for each active router. */
   tks = tor_malloc(sizeof(long)*smartlist_len(rl->routers));
+  /* Weighted fractional uptime for each active router. */
   wfus = tor_malloc(sizeof(double)*smartlist_len(rl->routers));
 
+  /* Now, fill in the arrays. */
   SMARTLIST_FOREACH(rl->routers, routerinfo_t *, ri, {
     if (router_is_active(ri, now)) {
       const char *id = ri->cache_info.identity_digest;
@@ -1745,11 +1754,15 @@ dirserv_compute_performance_thresholds(routerlist_t *rl)
     }
   });
 
+  /* Now, compute thresholds. */
   if (n_active) {
+    /* The median uptime is stable. */
     stable_uptime = median_uint32(uptimes, n_active);
+    /* The median mtbf is stable, if we have enough mtbf info */
     stable_mtbf = median_double(mtbfs, n_active);
+    /* The 12.5th percentile bandwidth is fast. */
     fast_bandwidth = find_nth_uint32(bandwidths, n_active, n_active/8);
-    /* Now bandwidths is sorted. */
+    /* (Now bandwidths is sorted.) */
     if (fast_bandwidth < ROUTER_REQUIRED_MIN_BANDWIDTH)
       fast_bandwidth = bandwidths[n_active/4];
     guard_bandwidth_including_exits = bandwidths[(n_active-1)/2];
@@ -1762,6 +1775,8 @@ dirserv_compute_performance_thresholds(routerlist_t *rl)
   if (fast_bandwidth > BANDWIDTH_TO_GUARANTEE_FAST)
     fast_bandwidth = BANDWIDTH_TO_GUARANTEE_FAST;
 
+  /* Now that we have a time-known that 7/8 routers are known longer than,
+   * fill wfus with the wfu of every such "familiar" router. */
   n_familiar = 0;
   SMARTLIST_FOREACH(rl->routers, routerinfo_t *, ri, {
       if (router_is_active(ri, now)) {

src/or/main.c

@@ -1473,11 +1473,6 @@ do_main_loop(void)
         continue;
       }
     }
-
-    /* refilling buckets and sending cells happens at the beginning of the
-     * next iteration of the loop, inside prepare_for_poll()
-     * DOCDOC No longer so; fix comment.
-     */
   }
 }