commit 56933787d55f74c667f364ae58cd277d79d9fc27 Author: Nick Mathewson nickm@torproject.org Date: Tue Oct 18 11:17:34 2016 -0400
Turn circuitmux.c comments into module docs. --- src/or/circuitmux.c | 89 ++++++++++++++++++++++++++++------------------------- 1 file changed, 47 insertions(+), 42 deletions(-)
diff --git a/src/or/circuitmux.c b/src/or/circuitmux.c index 038904e..96a3647 100644 --- a/src/or/circuitmux.c +++ b/src/or/circuitmux.c @@ -4,49 +4,20 @@ /** * \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 {