diff --git a/CHANGES/6274.doc.rst b/CHANGES/6274.doc.rst new file mode 100644 index 00000000000..38d0ea1c992 --- /dev/null +++ b/CHANGES/6274.doc.rst @@ -0,0 +1 @@ +Added an explanation of how tiny timeouts affect performance to the client reference document. diff --git a/docs/client_reference.rst b/docs/client_reference.rst index 5df691e128d..fb19e307245 100644 --- a/docs/client_reference.rst +++ b/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 ^^^^ diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt index f337fb95ca8..8efeb54ee3e 100644 --- a/docs/spelling_wordlist.txt +++ b/docs/spelling_wordlist.txt @@ -160,6 +160,7 @@ env environ eof epoll +expirations etag facto fallback