Merge branch 'maint-0.3.2' into release-0.3.2

changes/ticket24158

@@ -0,0 +1,3 @@
+  o Minor bugfixes (logging):
+    Only log about no longer having KIST support once. Fixes bug 24158; bugfix
+    on 0.3.2

changes/ticket24254

@@ -0,0 +1,3 @@
+  o Documentation:
+    Add notes in man page regarding OS support for the various scheduler types.
+    Attempt to use less jargon in the scheduler section. Closes ticket 24254.

doc/tor.1.txt

@@ -791,27 +791,35 @@ GENERAL OPTIONS
     restarting Tor. (Default: 0)
 
 [[Schedulers]] **Schedulers** **KIST**|**KISTLite**|**Vanilla**::
-    Specify the scheduler type that tor should use to handle outbound data on
-    channels. This is an ordered list by priority which means that the first
-    value will be tried first and if unavailable, the second one is tried and
-    so on. It is possible to change thse values at runtime.
+    Specify the scheduler type that tor should use. The scheduler is
+    responsible for moving data around within a Tor process. This is an ordered
+    list by priority which means that the first value will be tried first and if
+    unavailable, the second one is tried and so on. It is possible to change
+    these values at runtime. This option mostly effects relays, and most
+    operators should leave it set to its default value.
     (Default: KIST,KISTLite,Vanilla)
  +
     The possible scheduler types are:
  +
-    **KIST**: Kernel Informed Socket Transport. Tor will use the kernel tcp
-    information stack per-socket to make an informed decision on if it should
-    send or not the data. (Only available on Linux)
+    **KIST**: Kernel-Informed Socket Transport. Tor will use TCP information
+    from the kernel to make informed decisions regarding how much data to send
+    and when to send it. KIST also handles traffic in batches (see
+    KISTSchedRunInterval) in order to improve traffic prioritization decisions.
+    As implemented, KIST will only work on Linux kernel version 2.6.39 or
+    higher.
  +
-    **KISTLite**: Same as KIST but without kernel support which means that tor
-    will use all the same mecanics as KIST but without the TCP information the
-    kernel can provide.
+    **KISTLite**: Same as KIST but without kernel support. Tor will use all
+    the same mechanics as with KIST, including the batching, but its decisions
+    regarding how much data to send will not be as good. KISTLite will work on
+    all kernels and operating systems, and the majority of the benefits of KIST
+    are still realized with KISTLite.
  +
-    **Vanilla**: The scheduler that tor has always used that is do as much as
-    possible or AMAP.
+    **Vanilla**: The scheduler that Tor used before KIST was implemented. It
+    sends as much data as possible, as soon as possible. Vanilla will work on
+    all kernels and operating systems.
 
 [[KISTSchedRunInterval]] **KISTSchedRunInterval** __NUM__ **msec**::
-    If KIST or KISTLite is used in Schedulers option, this control at which
+    If KIST or KISTLite is used in the Schedulers option, this controls at which
     interval the scheduler tick is. If the value is 0 msec, the value is taken
     from the consensus if possible else it will fallback to the default 10
     msec. Maximum possible value is 100 msec. (Default: 0 msec)

src/or/scheduler.c

@@ -171,6 +171,8 @@ STATIC smartlist_t *channels_pending = NULL;
  */
 STATIC struct event *run_sched_ev = NULL;
 
+static int have_logged_kist_suddenly_disabled = 0;
+
 /*****************************************************************************
  * Scheduling system static function definitions
  *
@@ -252,13 +254,31 @@ select_scheduler(void)
     case SCHEDULER_KIST:
       if (!scheduler_can_use_kist()) {
 #ifdef HAVE_KIST_SUPPORT
-        log_notice(LD_SCHED, "Scheduler type KIST has been disabled by "
-                             "the consensus or no kernel support.");
+        if (!have_logged_kist_suddenly_disabled) {
+          /* We should only log this once in most cases. If it was the kernel
+           * losing support for kist that caused scheduler_can_use_kist() to
+           * return false, then this flag makes sure we only log this message
+           * once. If it was the consensus that switched from "yes use kist" to
+           * "no don't use kist", then we still set the flag so we log once, but
+           * we unset the flag elsewhere if we ever can_use_kist() again.
+           */
+          have_logged_kist_suddenly_disabled = 1;
+          log_notice(LD_SCHED, "Scheduler type KIST has been disabled by "
+                               "the consensus or no kernel support.");
+        }
 #else /* !(defined(HAVE_KIST_SUPPORT)) */
         log_info(LD_SCHED, "Scheduler type KIST not built in");
 #endif /* defined(HAVE_KIST_SUPPORT) */
         continue;
       }
+      /* This flag will only get set in one of two cases:
+       * 1 - the kernel lost support for kist. In that case, we don't expect to
+       *     ever end up here
+       * 2 - the consensus went from "yes use kist" to "no don't use kist".
+       * We might end up here if the consensus changes back to "yes", in which
+       * case we might want to warn the user again if it goes back to "no"
+       * yet again. Thus we unset the flag */
+      have_logged_kist_suddenly_disabled = 0;
       new_scheduler = get_kist_scheduler();
       scheduler_kist_set_full_mode();
       goto end;