DOC: explain the relation between pool-low-conn and tune.idle-pool.shared

Disabling idle-pool sharing can result in awful performance in presence
of a not so high number of threads, because the number of available idle
connections will be shared among threads, resulting in most of them
abandonning their connections after a request is done if there are already
enough total available. This is a case where pool-low-conn ought to be
used to preserve a number of connections for each thread, but this relation
isn't obvious as is. Let's add mentions about this with both keywords.

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 7dbe4ca68f9c19c3f8a8ec07397201fdbfda0c42..450d831481b19f2b86a01b6eb97fdec6ff237cd9 100644 (file)
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -2339,7 +2339,11 @@ tune.idle-pool.shared { on | off }
   optimize the connection reuse rate. But to help with debugging or when
   suspecting a bug in HAProxy around connection reuse, it can be convenient to
   forcefully disable this idle pool sharing between multiple threads, and force
-  this option to "off". The default is on.
+  this option to "off". The default is on. It is strongly recommended against
+  disabling this option without setting a conservative value on "pool-low-conn"
+  for all servers relying on connection reuse to achieve a high performance
+  level, otherwise connections might be closed very often as the thread count
+  increases.
 
 tune.idletimer <timeout>
   Sets the duration after which haproxy will consider that an empty buffer is
@@ -14146,7 +14150,10 @@ pool-low-conn <max>
   times. The default is zero, indicating that any idle connection can be used
   at any time. It is the recommended setting for normal use. This only applies
   to connections that can be shared according to the same principles as those
-  applying to "http-reuse".
+  applying to "http-reuse". In case connection sharing between threads would
+  be disabled via "tune.idle-pool.shared", it can become very important to use
+  this setting to make sure each thread always has a few connections, or the
+  connection reuse rate will decrease as thread count increases.
 
 pool-max-conn <max>
   Set the maximum number of idling connections for a server. -1 means unlimited