[Python-checkins] gh-96098: Clearly link concurrent.futures from threading & multiprocessing docs (GH-96112)
ncoghlan
webhook-mailer at python.org
Sat Aug 20 22:09:17 EDT 2022
https://github.com/python/cpython/commit/bcc4cb0c7d5e0590928e74cae86b0a7938c0f74b
commit: bcc4cb0c7d5e0590928e74cae86b0a7938c0f74b
branch: main
author: Nick Coghlan <ncoghlan at gmail.com>
committer: ncoghlan <ncoghlan at gmail.com>
date: 2022-08-21T14:09:05+12:00
summary:
gh-96098: Clearly link concurrent.futures from threading & multiprocessing docs (GH-96112)
Clearly link concurrent.futures from threading & multiprocessing docs
Also link directly to asyncio from the beginning of the threading docs.
files:
A Misc/NEWS.d/next/Documentation/2022-08-19-17-07-45.gh-issue-96098.nDp43u.rst
M Doc/library/multiprocessing.rst
M Doc/library/threading.rst
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index eaa946462a11..caf24a35fdfc 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -45,6 +45,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 a8851dd15052..b22d48766224 100644
--- 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
index 000000000000..5ead20bbb535
--- /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.
More information about the Python-checkins
mailing list