[tor-commits] [tor/master] document picking infinity bin

[nickm at torproject.org]

commit 71c11d7306dbbcb81c780a7a786429e2d8eaa669
Author: George Kadianakis <desnacked at riseup.net>
Date:   Mon Feb 25 13:59:18 2019 +0200

    document picking infinity bin
---
 src/core/or/circuitpadding.c | 4 ++++
 src/core/or/circuitpadding.h | 6 ++++++
 2 files changed, 10 insertions(+)

diff --git a/src/core/or/circuitpadding.c b/src/core/or/circuitpadding.c
index 7e76cd7ad..29a618930 100644
--- a/src/core/or/circuitpadding.c
+++ b/src/core/or/circuitpadding.c
@@ -224,6 +224,10 @@ circpad_machine_current_state(const circpad_machine_state_t *mi)
 /**
  * Get the lower bound of a histogram bin. The upper bound is obtained by
  * calling this function with bin+1, and subtracting 1.
+ *
+ * This function can also be called with 'bin' set to a value equal or greater
+ * than histogram_len in which case the infinity bin is chosen and
+ * CIRCPAD_DELAY_INFINITE is returned.
  */
 STATIC circpad_delay_t
 circpad_histogram_bin_to_usec(const circpad_machine_state_t *mi,
diff --git a/src/core/or/circuitpadding.h b/src/core/or/circuitpadding.h
index 4e6454b4a..ca19e31ca 100644
--- a/src/core/or/circuitpadding.h
+++ b/src/core/or/circuitpadding.h
@@ -276,6 +276,12 @@ typedef struct circpad_state_t {
    *    histogram[] =        {   6,  10,   6,  7,    9,     6 }
    *    histogram_edges[] =  { 0, 100, 200, 350, 500, 1000 }
    *
+   * The final bin is called the "infinity bin" and if it's chosen we don't
+   * schedule any padding. The infinity bin is strange because its lower edge
+   * is the max value of possible non-infinite delay allowed by this histogram,
+   * and its upper edge is CIRCPAD_DELAY_INFINITE. You can tell if the infinity
+   * bin is chosen by inspecting its bin index or inspecting its upper edge.
+   *
    * If a delay probability distribution is used for this state, this is set
    * to 0. */
   circpad_hist_index_t histogram_len;