1 files changed, 52 insertions, 53 deletions

diff --git a/src/or/circuitmux.c b/src/or/circuitmux.c
index cc1c4cd401..f3b8aecb1b 100644
--- a/src/or/circuitmux.c
+++ b/src/or/circuitmux.c
@@ -1,52 +1,23 @@
-/* * Copyright (c) 2012-2016, The Tor Project, Inc. */
+/* * Copyright (c) 2012-2017, The Tor Project, Inc. */
 /* See LICENSE for licensing information */
 
 /**
  * \file circuitmux.c
  * \brief Circuit mux/cell selection abstraction
- **/
-
-#include "or.h"
-#include "channel.h"
-#include "circuitlist.h"
-#include "circuitmux.h"
-#include "relay.h"
-
-/*
- * Private typedefs for circuitmux.c
- */
-
-/*
- * Map of muxinfos for circuitmux_t to use; struct is defined below (name
- * of struct must match HT_HEAD line).
- */
-typedef struct chanid_circid_muxinfo_map chanid_circid_muxinfo_map_t;
-
-/*
- * Hash table entry (yeah, calling it chanid_circid_muxinfo_s seems to
- * break the hash table code).
- */
-typedef struct chanid_circid_muxinfo_t chanid_circid_muxinfo_t;
-
-/*
- * Anything the mux wants to store per-circuit in the map; right now just
- * a count of queued cells.
- */
-
-typedef struct circuit_muxinfo_s circuit_muxinfo_t;
-
-/*
- * Structures for circuitmux.c
- */
-
-/*
- * A circuitmux is a collection of circuits; it tracks which subset
- * of the attached circuits are 'active' (i.e., have cells available
- * to transmit) and how many cells on each.  It expoes three distinct
+ *
+ * A circuitmux is responsible for <b>MU</b>ltiple<b>X</b>ing all of the
+ * circuits that are writing on a single channel. It keeps track of which of
+ * these circuits has something to write (aka, "active" circuits), and which
+ * one should write next.  A circuitmux corresponds 1:1 with a channel.
+ *
+ * There can be different implementations of the circuitmux's rules (which
+ * decide which circuit is next to write).
+ *
+ * A circuitmux exposes three distinct
  * interfaces to other components:
  *
  * To channels, which each have a circuitmux_t, the supported operations
- * are:
+ * (invoked from relay.c) are:
  *
  *   circuitmux_get_first_active_circuit():
  *
@@ -74,7 +45,9 @@ typedef struct circuit_muxinfo_s circuit_muxinfo_t;
  *
  *   circuitmux_set_num_cells():
  *
- *     Set the circuitmux's cell counter for this circuit.
+ *     Set the circuitmux's cell counter for this circuit. One of
+ *     circuitmuc_clear_num_cells() or circuitmux_set_num_cells() MUST be
+ *     called when the number of cells queued on a circuit changes.
  *
  * See circuitmux.h for the circuitmux_policy_t data structure, which contains
  * a table of function pointers implementing a circuit selection policy, and
@@ -94,7 +67,39 @@ typedef struct circuit_muxinfo_s circuit_muxinfo_t;
  *
  *     Install a policy on a circuitmux_t; the appropriate callbacks will be
  *     made to attach all existing circuits to the new policy.
- *
+ **/
+
+#include "or.h"
+#include "channel.h"
+#include "circuitlist.h"
+#include "circuitmux.h"
+#include "relay.h"
+
+/*
+ * Private typedefs for circuitmux.c
+ */
+
+/*
+ * Map of muxinfos for circuitmux_t to use; struct is defined below (name
+ * of struct must match HT_HEAD line).
+ */
+typedef struct chanid_circid_muxinfo_map chanid_circid_muxinfo_map_t;
+
+/*
+ * Hash table entry (yeah, calling it chanid_circid_muxinfo_s seems to
+ * break the hash table code).
+ */
+typedef struct chanid_circid_muxinfo_t chanid_circid_muxinfo_t;
+
+/*
+ * Anything the mux wants to store per-circuit in the map; right now just
+ * a count of queued cells.
+ */
+
+typedef struct circuit_muxinfo_s circuit_muxinfo_t;
+
+/*
+ * Structures for circuitmux.c
  */
 
 struct circuitmux_s {
@@ -180,7 +185,7 @@ struct chanid_circid_muxinfo_t {
   circuitmux_assert_okay(cmux)
 #else
 #define circuitmux_assert_okay_paranoid(cmux)
-#endif
+#endif /* defined(CMUX_PARANOIA) */
 
 /*
  * Static function declarations
@@ -256,13 +261,11 @@ circuitmux_move_active_circ_to_tail(circuitmux_t *cmux, circuit_t *circ,
     if (circ->n_mux == cmux) {
       next_p = &(circ->next_active_on_n_chan);
       prev_p = &(circ->prev_active_on_n_chan);
-      direction = CELL_DIRECTION_OUT;
     } else {
       or_circ = TO_OR_CIRCUIT(circ);
       tor_assert(or_circ->p_mux == cmux);
       next_p = &(or_circ->next_active_on_p_chan);
       prev_p = &(or_circ->prev_active_on_p_chan);
-      direction = CELL_DIRECTION_IN;
     }
   }
   tor_assert(next_p);
@@ -362,7 +365,7 @@ HT_HEAD(chanid_circid_muxinfo_map, chanid_circid_muxinfo_t);
 
 /* Emit a bunch of hash table stuff */
 HT_PROTOTYPE(chanid_circid_muxinfo_map, chanid_circid_muxinfo_t, node,
-             chanid_circid_entry_hash, chanid_circid_entries_eq);
+             chanid_circid_entry_hash, chanid_circid_entries_eq)
 HT_GENERATE2(chanid_circid_muxinfo_map, chanid_circid_muxinfo_t, node,
              chanid_circid_entry_hash, chanid_circid_entries_eq, 0.6,
              tor_reallocarray_, tor_free_)
@@ -1650,7 +1653,6 @@ circuitmux_assert_okay_pass_one(circuitmux_t *cmux)
   circid_t circ_id;
   circuit_t *circ;
   or_circuit_t *or_circ;
-  unsigned int circ_is_active;
   circuit_t **next_p, **prev_p;
   unsigned int n_circuits, n_active_circuits, n_cells;
 
@@ -1674,8 +1676,6 @@ circuitmux_assert_okay_pass_one(circuitmux_t *cmux)
     tor_assert(chan);
     circ = circuit_get_by_circid_channel_even_if_marked(circ_id, chan);
     tor_assert(circ);
-    /* Clear the circ_is_active bit to start */
-    circ_is_active = 0;
 
     /* Assert that we know which direction this is going */
     tor_assert((*i)->muxinfo.direction == CELL_DIRECTION_OUT ||
@@ -1702,7 +1702,7 @@ circuitmux_assert_okay_pass_one(circuitmux_t *cmux)
      * Should this circuit be active?  I.e., does the mux know about > 0
      * cells on it?
      */
-    circ_is_active = ((*i)->muxinfo.cell_count > 0);
+    const int circ_is_active = ((*i)->muxinfo.cell_count > 0);
 
     /* It should be in the linked list iff it's active */
     if (circ_is_active) {
@@ -1754,7 +1754,6 @@ circuitmux_assert_okay_pass_two(circuitmux_t *cmux)
   circuit_t **next_p, **prev_p;
   channel_t *chan;
   unsigned int n_active_circuits = 0;
-  cell_direction_t direction;
   chanid_circid_muxinfo_t search, *hashent = NULL;
 
   tor_assert(cmux);
@@ -1773,7 +1772,7 @@ circuitmux_assert_okay_pass_two(circuitmux_t *cmux)
     curr_or_circ = NULL;
     next_circ = NULL;
     next_p = prev_p = NULL;
-    direction = 0;
+    cell_direction_t direction;
 
     /* Figure out if this is n_mux or p_mux */
     if (cmux == curr_circ->n_mux) {