[3.12] gh-112169: Documented getaddrinfo/getnameinfo default loop executor usage and implications. (GH-112191) (#120936)

miss-islington · alex-kowalczyk · gvanrossum · web-flow · commit 3afb856dda9f · 2024-06-24T08:45:46.000Z
gh-112169: Documented getaddrinfo/getnameinfo default loop executor usage and implications. (GH-112191) (cherry picked from commit fc297b4) Co-authored-by: Alek Kowalczyk <alek.kowalczyk@gmail.com> Co-authored-by: Guido van Rossum <gvanrossum@gmail.com> Co-authored-by: Kumar Aditya <kumaraditya@python.org> Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
diff --git a/Doc/library/asyncio-eventloop.rst b/Doc/library/asyncio-eventloop.rst
@@ -1139,6 +1139,14 @@ DNS
 
    Asynchronous version of :meth:`socket.getnameinfo`.
 
+.. note::
+   Both *getaddrinfo* and *getnameinfo* internally utilize their synchronous
+   versions through the loop's default thread pool executor.
+   When this executor is saturated, these methods may experience delays,
+   which higher-level networking libraries may report as increased timeouts.
+   To mitigate this, consider using a custom executor for other user tasks,
+   or setting a default executor with a larger number of workers.
+
 .. versionchanged:: 3.7
    Both *getaddrinfo* and *getnameinfo* methods were always documented
    to return a coroutine, but prior to Python 3.7 they were, in fact,
