[PR #6274/254d0e7d backport][3.8] Clarify tiny timeouts behavior and how it can affect performance

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