gh-96098: Clearly link concurrent.futures from threading & multiprocessing docs ...

Clearly link concurrent.futures from threading & multiprocessing docs

Also link directly to asyncio from the beginning of the threading docs.
(cherry picked from commit bcc4cb0c7d5e0590928e74cae86b0a7938c0f74b)

Co-authored-by: Nick Coghlan <ncoghlan@gmail.com>

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 0de44855a50c04bb2d1ebb578dd71da84927d5b4..18e9b1ee8cb3d4b555924aa035c9e1901220f361 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -43,6 +43,16 @@ will print to standard output ::
    [1, 4, 9]
 
 
+.. seealso::
+
+   :class:`concurrent.futures.ProcessPoolExecutor` offers a higher level interface
+   to push tasks to a background process without blocking execution of the
+   calling process. Compared to using the :class:`~multiprocessing.pool.Pool`
+   interface directly, the :mod:`concurrent.futures` API more readily allows
+   the submission of work to the underlying process pool to be separated from
+   waiting for the results.
+
+
 The :class:`Process` class
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 14434fbd52d0821adfca66e5fe5608d7f34e3975..47ff74dfc67ff256e24340a222cc6dc4212b9f7c 100644 (file)
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -9,11 +9,23 @@
 --------------
 
 This module constructs higher-level threading interfaces on top of the lower
-level :mod:`_thread` module.  See also the :mod:`queue` module.
+level :mod:`_thread` module.
 
 .. versionchanged:: 3.7
    This module used to be optional, it is now always available.
 
+.. seealso::
+
+   :class:`concurrent.futures.ThreadPoolExecutor` offers a higher level interface
+   to push tasks to a background thread without blocking execution of the
+   calling thread, while still being able to retrieve their results when needed.
+
+   :mod:`queue` provides a thread-safe interface for exchanging data between
+   running threads.
+
+   :mod:`asyncio` offers an alternative approach to achieving task level
+   concurrency without requiring the use of multiple operating system threads.
+
 .. note::
 
    In the Python 2.x series, this module contained ``camelCase`` names

diff --git a/Misc/NEWS.d/next/Documentation/2022-08-19-17-07-45.gh-issue-96098.nDp43u.rst b/Misc/NEWS.d/next/Documentation/2022-08-19-17-07-45.gh-issue-96098.nDp43u.rst
new file mode 100644 (file)
index 0000000..5ead20b
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2022-08-19-17-07-45.gh-issue-96098.nDp43u.rst
@@ -0,0 +1,3 @@
+Improve discoverability of the higher level concurrent.futures module by
+providing clearer links from the lower level threading and multiprocessing
+modules.