[tor-commits] [tor/master] Module documentation for circuitmux_ewma.c

[nickm at torproject.org]

commit 84829e336c3f72e4926e90d6f2e58eed0a538bce
Author: Nick Mathewson <nickm at torproject.org>
Date:   Tue Oct 18 11:28:40 2016 -0400

    Module documentation for circuitmux_ewma.c
---
 src/or/circuitmux_ewma.c | 27 +++++++++++++++++++++++++--
 1 file changed, 25 insertions(+), 2 deletions(-)

diff --git a/src/or/circuitmux_ewma.c b/src/or/circuitmux_ewma.c
index 13836cd..5c2ebde 100644
--- a/src/or/circuitmux_ewma.c
+++ b/src/or/circuitmux_ewma.c
@@ -4,6 +4,28 @@
 /**
  * \file circuitmux_ewma.c
  * \brief EWMA circuit selection as a circuitmux_t policy
+ *
+ * The "EWMA" in this module stands for the "exponentially weighted moving
+ * average" of the number of cells sent on each circuit.  The goal is to
+ * prioritize cells on circuits that have been quiet recently, by looking at
+ * those that have sent few cells over time, prioritizing recent times
+ * more than older ones.
+ *
+ * Specifically, a cell sent at time "now" has weight 1, but a time X ticks
+ * before now has weight ewma_scale_factor ^ X , where ewma_scale_factor is
+ * between 0.0 and 1.0.
+ *
+ * For efficiency, we do not re-scale these averages every time we send a
+ * cell: that would be horribly inefficient.  Instead, we we keep the cell
+ * count on all circuits on the same circuitmux scaled relative to a single
+ * tick.  When we add a new cell, we scale its weight depending on the time
+ * that has elapsed since the tick.  We do re-scale the circuits on the
+ * circuitmux periodically, so that we don't overflow double.
+ *
+ *
+ * This module should be used through the interfaces in circuitmux.c, which it
+ * implements.
+ *
  **/
 
 #define TOR_CIRCUITMUX_EWMA_C_
@@ -28,9 +50,10 @@
 
 /*** Some useful constant #defines ***/
 
-/*DOCDOC*/
+/** Any halflife smaller than this number of seconds is considered to be
+ * "disabled". */
 #define EPSILON 0.00001
-/*DOCDOC*/
+/** The natural logarithm of 0.5. */
 #define LOG_ONEHALF -0.69314718055994529
 
 /*** EWMA structures ***/