polish r9933-r9994

svn:r10335

src/common/mempool.c

@@ -14,7 +14,7 @@
  *
  *     Generally, a memory pool is an allocation strategy optimized for large
  *     numbers of identically-sized objects.  Rather than the elaborate arena
- *     and coalescing strategeis you need to get good performance for a
+ *     and coalescing strategies you need to get good performance for a
  *     general-purpose malloc(), pools use a series of large memory "chunks",
  *     each of which is carved into a bunch of smaller "items" or
  *     "allocations".
@@ -33,7 +33,7 @@
  *
  *     I wrote this after looking at 3 or 4 other pooling allocators, but
  *     without copying.  The strategy this most resembles (which is funny,
- *     since that's the one I looked at longest ago) the pool allocator
+ *     since that's the one I looked at longest ago) is the pool allocator
  *     underlying Python's obmalloc code.  Major differences from obmalloc's
  *     pools are:
  *       - We don't even try to be threadsafe.
@@ -93,7 +93,7 @@
 /** Largest type that we need to ensure returned memory items are aligned to.
  * Change this to "double" if we need to be safe for structs with doubles. */
 #define ALIGNMENT_TYPE void *
-/** Increment that we need to align allocated  */
+/** Increment that we need to align allocated. */
 #define ALIGNMENT sizeof(ALIGNMENT_TYPE)
 /** Largest memory chunk that we should allocate. */
 #define MAX_CHUNK (8*(1L<<20))
@@ -128,14 +128,14 @@ struct mp_chunk_t {
   unsigned long magic; /**< Must be MP_CHUNK_MAGIC if this chunk is valid. */
   mp_chunk_t *next; /**< The next free, used, or full chunk in sequence. */
   mp_chunk_t *prev; /**< The previous free, used, or full chunk in sequence. */
-  mp_pool_t *pool; /**< The pool that this chunk is part of */
+  mp_pool_t *pool; /**< The pool that this chunk is part of. */
   /** First free item in the freelist for this chunk.  Note that this may be
    * NULL even if this chunk is not at capacity: if so, the free memory at
    * next_mem has not yet been carved into items.
    */
   mp_allocated_t *first_free;
-  int n_allocated; /**< Number of currently allocated items in this chunk */
-  int capacity; /**< Largest number of items that can be fit into this chunk */
+  int n_allocated; /**< Number of currently allocated items in this chunk. */
+  int capacity; /**< Largest number of items that can be fit into this chunk. */
   size_t mem_size; /**< Number of usable bytes in mem. */
   char *next_mem; /**< Pointer into part of <b>mem</b> not yet carved up. */
   char mem[1]; /**< Storage for this chunk. (Not actual size.) */
@@ -383,7 +383,7 @@ mp_pool_new(size_t item_size, size_t chunk_capacity)
 }
 
 /** If there are more than <b>n</b> empty chunks in <b>pool</b>, free the
- * excess ones that have been empty for the longest.   (If <b>n</b> is less
+ * excess ones that have been empty for the longest.  (If <b>n</b> is less
  * than zero, free only empty chunks that were not used since the last
  * call to mp_pool_clean(), leaving only -<b>n</b>.) */
 void

src/or/config.c

@@ -2081,7 +2081,7 @@ get_default_nickname(void)
   return out;
 }
 
-/** Release storage held by <b>options</b> */
+/** Release storage held by <b>options</b>. */
 static void
 config_free(config_format_t *fmt, void *options)
 {

src/or/connection.c

@@ -215,7 +215,7 @@ connection_new(int type)
   return conn;
 }
 
-/** Create a link between <b>conn_a</b> and <b>conn_b</b> */
+/** Create a link between <b>conn_a</b> and <b>conn_b</b>. */
 void
 connection_link_connections(connection_t *conn_a, connection_t *conn_b)
 {

src/or/connection_edge.c

@@ -570,7 +570,7 @@ addressmap_ent_free(void *_ent)
   tor_free(ent);
 }
 
-/** Free storage held by a virtaddress_entry_t* entry in <b>ent</b> */
+/** Free storage held by a virtaddress_entry_t* entry in <b>ent</b>. */
 static void
 addressmap_virtaddress_ent_free(void *_ent)
 {
@@ -580,7 +580,7 @@ addressmap_virtaddress_ent_free(void *_ent)
   tor_free(ent);
 }
 
-/** Free storage held by a virtaddress_entry_t* entry in <b>ent</b> */
+/** Free storage held by a virtaddress_entry_t* entry in <b>ent</b>. */
 static void
 addressmap_virtaddress_remove(const char *address, addressmap_entry_t *ent)
 {
@@ -2094,8 +2094,9 @@ connection_ap_handshake_socks_reply(edge_connection_t *conn, char *reply,
   return;
 }
 
-/** A relay 'begin' cell has arrived, and either we are an exit hop
- * for the circuit, or we are the origin and it is a rendezvous begin.
+/** A relay 'begin' or 'begin_dir' cell has arrived, and either we are
+ * an exit hop for the circuit, or we are the origin and it is a
+ * rendezvous begin.
  *
  * Launch a new exit connection and initialize things appropriately.
  *
@@ -2273,7 +2274,7 @@ connection_exit_begin_conn(cell_t *cell, circuit_t *circ)
 
   /* send it off to the gethostbyname farm */
   switch (dns_resolve(n_stream)) {
-    case 1: /* resolve worked */
+    case 1: /* resolve worked; now n_stream is attached to circ. */
       assert_circuit_ok(circ);
       log_debug(LD_EXIT,"about to call connection_exit_connect().");
       connection_exit_connect(n_stream);
@@ -2282,12 +2283,11 @@ connection_exit_begin_conn(cell_t *cell, circuit_t *circ)
       end_payload[0] = END_STREAM_REASON_RESOLVEFAILED;
       relay_send_command_from_edge(rh.stream_id, circ, RELAY_COMMAND_END,
                                    end_payload, 1, NULL);
-      /* n_stream got detached and freed. don't touch it. */
+      /* n_stream got freed. don't touch it. */
       break;
     case 0: /* resolve added to pending list */
-      /* add it into the linked list of resolving_streams on this circuit */
       assert_circuit_ok(circ);
-      ;
+      break;
   }
   return 0;
 }
@@ -2466,6 +2466,7 @@ connection_exit_connect_dir(edge_connection_t *exitconn)
     return 0;
   }
 
+  /* link exitconn to circ, now that we know we can use it. */
   exitconn->next_stream = circ->n_streams;
   circ->n_streams = exitconn;
 

src/or/connection_or.c

@@ -120,6 +120,9 @@ connection_or_set_identity_digest(or_connection_t *conn, const char *digest)
 /** Pack the cell_t host-order structure <b>src</b> into network-order
  * in the buffer <b>dest</b>. See tor-spec.txt for details about the
  * wire format.
+ *
+ * Note that this function doesn't touch <b>dst</b>-\>next: the caller
+ * should set it or clear it as appropriate.
  */
 void
 cell_pack(packed_cell_t *dst, const cell_t *src)

src/or/dns.c

@@ -503,7 +503,7 @@ parse_inaddr_arpa_address(const char *address, struct in_addr *in)
 
 /** See if we have a cache entry for <b>exitconn</b>-\>address. if so,
  * if resolve valid, put it into <b>exitconn</b>-\>addr and return 1.
- * If resolve failed, unlink exitconn if needed, free it, and return -1.
+ * If resolve failed, free exitconn and return -1.
  *
  * (For EXIT_PURPOSE_RESOLVE connections, send back a RESOLVED error cell
  * on returning -1.  For EXIT_PURPOSE_CONNECT connections, there's no
@@ -548,6 +548,7 @@ dns_resolve(edge_connection_t *exitconn)
       }
       break;
     case 0:
+      /* add it into the linked list of resolving_streams on this circuit */
       exitconn->_base.state = EXIT_CONN_STATE_RESOLVING;
       exitconn->next_stream = oncirc->resolving_streams;
       oncirc->resolving_streams = exitconn;
@@ -558,7 +559,6 @@ dns_resolve(edge_connection_t *exitconn)
         send_resolved_cell(exitconn,
              (r == -1) ? RESOLVED_TYPE_ERROR : RESOLVED_TYPE_ERROR_TRANSIENT);
       }
-      //circuit_detach_stream(TO_CIRCUIT(oncirc), exitconn);
       exitconn->on_circuit = NULL;
       if (!exitconn->_base.marked_for_close) {
         connection_free(TO_CONN(exitconn));
@@ -583,8 +583,9 @@ dns_resolve(edge_connection_t *exitconn)
  *     - linking connections to n_streams/resolving_streams,
  *     - sending resolved cells if we have an answer/error right away,
  *
- * Returns -2 on a transient error.  Sets *<b>hostname_out</b> to a newly
- * allocated string holding a cached reverse DNS value, if any.
+ * Return -2 on a transient error. If it's a reverse resolve and it's
+ * successful, sets *<b>hostname_out</b> to a newly allocated string
+ * holding the cached reverse DNS value.
  */
 static int
 dns_resolve_impl(edge_connection_t *exitconn, int is_resolve,
@@ -1209,7 +1210,7 @@ evdns_callback(int result, char type, int count, int ttl, void *addresses,
 }
 
 /** For eventdns: start resolving as necessary to find the target for
- * <b>exitconn</b>.  Returns -1 on error, -2 on transient errror,
+ * <b>exitconn</b>.  Returns -1 on error, -2 on transient error,
  * 0 on "resolve launched." */
 static int
 launch_resolve(edge_connection_t *exitconn)

src/or/policies.c

@@ -687,7 +687,7 @@ getinfo_helper_policies(control_connection_t *conn,
   return 0;
 }
 
-/** Release all storage held by <b>p</b> */
+/** Release all storage held by <b>p</b>. */
 void
 addr_policy_free(addr_policy_t *p)
 {

src/or/relay.c

@@ -1483,7 +1483,8 @@ circuit_consider_sending_sendme(circuit_t *circ, crypt_path_t *layer_hint)
 /** DOCDOC */
 static int total_cells_allocated = 0;
 
-#ifdef ENABLE_CELL_POOL
+#ifdef ENABLE_CELL_POOL /* Defined in ./configure. True by default. */
+/* XXX020 make cell pools the only option once we know they work? -RD */
 static mp_pool_t *cell_pool = NULL;
 /** Allocate structures to hold cells. */
 void
@@ -1678,7 +1679,7 @@ prev_circ_on_conn_p(circuit_t *circ, or_connection_t *conn)
 }
 
 /** Add <b>circ</b> to the list of circuits with pending cells on
- * <b>conn</b>.   No effect if <b>circ</b> is already unlinked. */
+ * <b>conn</b>.  No effect if <b>circ</b> is already unlinked. */
 void
 make_circuit_active_on_conn(circuit_t *circ, or_connection_t *conn)
 {

src/or/routerlist.c

@@ -1780,7 +1780,7 @@ _extrainfo_free(void *e)
   extrainfo_free(e);
 }
 
-/** Free all storage held by a routerlist <b>rl</b> */
+/** Free all storage held by a routerlist <b>rl</b>. */
 void
 routerlist_free(routerlist_t *rl)
 {
@@ -3567,7 +3567,7 @@ add_trusted_dir_server(const char *nickname, const char *address,
   router_dir_info_changed();
 }
 
-/** Free storage held in <b>ds</b> */
+/** Free storage held in <b>ds</b>. */
 static void
 trusted_dir_server_free(trusted_dir_server_t *ds)
 {
@@ -4982,7 +4982,7 @@ routerinfo_incompatible_with_extrainfo(routerinfo_t *ri, extrainfo_t *ei,
   }
 
   /* The nickname must match exactly to have been generated at the same time
-   * by the same rotuer.  */
+   * by the same router. */
   if (strcmp(ri->nickname, ei->nickname) ||
       memcmp(ri->cache_info.identity_digest, ei->cache_info.identity_digest,
              DIGEST_LEN)) {

src/or/routerparse.c

@@ -214,7 +214,7 @@ static token_rule_t extrainfo_token_table[] = {
 /** List of tokens allowable in the body part of v2 and v3 networkstatus
  * documents. */
 static token_rule_t rtrstatus_token_table[] = {
-  T1( "r",                   K_R,                   GE(8),    NO_OBJ ),
+  T1( "r",                   K_R,                   GE(8),   NO_OBJ ),
   T1( "s",                   K_S,                   ARGS,    NO_OBJ ),
   T01("v",                   K_V,               CONCAT_ARGS, NO_OBJ ),
   T0N("opt",                 K_OPT,             CONCAT_ARGS, OBJ_OK ),
@@ -234,7 +234,7 @@ static token_rule_t netstatus_token_table[] = {
   T1( "dir-source",          K_DIR_SOURCE,          GE(3),   NO_OBJ ),
   T01("dir-options",         K_DIR_OPTIONS,         ARGS,    NO_OBJ ),
   T01("client-versions",     K_CLIENT_VERSIONS, CONCAT_ARGS, NO_OBJ ),
-  T01("server-versions",     K_SERVER_VERSIONS, CONCAT_ARGS,    NO_OBJ ),
+  T01("server-versions",     K_SERVER_VERSIONS, CONCAT_ARGS, NO_OBJ ),
 
   END_OF_TABLE
 };
@@ -269,7 +269,7 @@ static token_rule_t dir_token_table[] = {
  * footers. */
 #define CERTIFICATE_MEMBERS                                                  \
   T1("dir-key-certificate-version", K_DIR_KEY_CERTIFICATE_VERSION,           \
-                                                 GE(1),       NO_OBJ ),      \
+                                                     GE(1),       NO_OBJ ),  \
   T1("dir-identity-key", K_DIR_IDENTITY_KEY,         NO_ARGS,     NEED_KEY ),\
   T1("dir-key-published",K_DIR_KEY_PUBLISHED,        CONCAT_ARGS, NO_OBJ),   \
   T1("dir-key-expires",  K_DIR_KEY_EXPIRES,          CONCAT_ARGS, NO_OBJ),   \
@@ -979,7 +979,7 @@ router_parse_entry_from_string(const char *s, const char *end,
   }
   tokens = smartlist_create();
   if (tokenize_string(s,end,tokens,routerdesc_token_table)) {
-    log_warn(LD_DIR, "Error tokeninzing router descriptor.");
+    log_warn(LD_DIR, "Error tokenizing router descriptor.");
     goto err;
   }
 
@@ -1199,7 +1199,7 @@ extrainfo_parse_entry_from_string(const char *s, const char *end,
   }
   tokens = smartlist_create();
   if (tokenize_string(s,end,tokens,extrainfo_token_table)) {
-    log_warn(LD_DIR, "Error tokeninzing router descriptor.");
+    log_warn(LD_DIR, "Error tokenizing router descriptor.");
     goto err;
   }