rec: Document `pdns-distribute-queries` and `reuseport` in performance.md

diff --git a/docs/markdown/recursor/performance.md b/docs/markdown/recursor/performance.md
index cb935b43eb2d8351c9893761a3bfb34a9527b2ae..0f02228180d8b8656c70cafadf5f32d8e589b984 100644 (file)
--- a/docs/markdown/recursor/performance.md
+++ b/docs/markdown/recursor/performance.md
@@ -11,8 +11,11 @@ To get the best out of the PowerDNS recursor, which is important if you are doin
 
 -   A busy server may need hundreds of file descriptors on startup, and deals with spikes better if it has that many available later on. Linux by default restricts processes to 1024 file descriptors, which should suffice most of the time, but Solaris has a default limit of 256. This can be raised using the ulimit command. FreeBSD has a default limit that is high enough for even very heavy duty use.
 -   When deploying (large scale) IPv6, please be aware some Linux distributions leave IPv6 routing cache tables at very small default values. Please check and if necessary raise 'sysctl net.ipv6.route.max\_size'.
--   For older versions <3.2: If you need it, try **--fork**, this will fork the daemon into two halves, allowing it to benefit from a second CPU. This feature almost doubles performance, but is a bit of a hack.
--   for 3.2 and higher, set 'threads' to your number of CPU cores (but values above 8 rarely improve performance).
+-   For 3.2 and higher, set `threads` to your number of CPU cores (but values above 8 rarely improve performance). For older versions <3.2: If you need it, try `--fork`, this will fork the daemon into two halves, allowing it to benefit from a second CPU. This feature almost doubles performance, but is a bit of a hack.
+
+    When running with several threads, you can either ask PowerDNS to start a special thread to dispatch the incoming queries to the workers by setting `pdns-distributes-queries` to true, or let the worker threads handle the incoming queries themselves. The dispatched thread enabled by `pdns-distributes-queries` tries to send the same queries to the same thread to maximize the cache-hit ratio, but it might become a bottleneck if the incoming queries rate is too high to be handled by a single thread.
+    If `pdns-distributes-queries` is set to false and either `SO\_REUSEPORT` support is not available or the `reuseport` directive is set to false, all worker threads share the same listening sockets. This prevents a single thread from having to handle every incoming queries, but can lead to thundering herd issues where all threads are awoken at once when a query arrives. If `SO\_REUSEPORT` support is available and `reuseport` is set to true, separate listening sockets are opened for each worker thread and the query distributions is handled by the kernel, avoiding any thundering herd issue as well as preventing the distributor thread from becoming the bottleneck.
+
 -   For best PowerDNS Recursor performance, use a recent version of your operating system, since this generally offers the best event multiplexer implementation available (kqueue, epoll, ports or /dev/poll).
 -   A Recursor under high load puts a severe stress on any stateful (connection tracking) firewall, so much so that the firewall may fail.