Clarify tiny timeouts behavior and how it can affect performance (#6274…

…) (#6303)

Co-authored-by: Sviatoslav Sydorenko <sviat@redhat.com>
(cherry picked from commit 254d0e7)

Co-authored-by: Andrew Svetlov <andrew.svetlov@gmail.com>

CHANGES/6274.doc.rst

@@ -0,0 +1 @@
+Added an explanation of how tiny timeouts affect performance to the client reference document.

docs/client_reference.rst

@@ -1710,6 +1710,31 @@ ClientTimeout
 
    .. versionadded:: 3.3
 
+
+   .. note::
+
+      Timeouts larger than 5 seconds are rounded for scheduling on the next
+      second boundary (an absolute time where microseconds part is zero) for the
+      sake of performance.
+
+      E.g., assume a timeout is ``10``, absolute time when timeout should expire
+      is ``loop.time() + 5``, and it points to ``12345.67 + 10`` which is equal
+      to ``12355.67``.
+
+      The absolute time for the timeout cancellation is ``12356``.
+
+      It leads to grouping all close scheduled timeout expirations to exactly
+      the same time to reduce amount of loop wakeups.
+
+      .. versionchanged:: 3.7
+
+         Rounding to the next seconds boundary is disabled for timeouts smaller
+         than 5 seconds for the sake of easy debugging.
+
+         In turn, tiny timeouts can lead to significant performance degradation
+         on production environment.
+
+
 ETag
 ^^^^
 

docs/spelling_wordlist.txt

@@ -159,6 +159,7 @@ env
 environ
 eof
 epoll
+expirations
 etag
 facto
 fallback