From bcc4cb0c7d5e0590928e74cae86b0a7938c0f74b Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 21 Aug 2022 14:09:05 +1200 Subject: 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. --- Doc/library/multiprocessing.rst | 10 ++++++++++ Doc/library/threading.rst | 14 +++++++++++++- .../2022-08-19-17-07-45.gh-issue-96098.nDp43u.rst | 3 +++ 3 files changed, 26 insertions(+), 1 deletion(-) create mode 100644 Misc/NEWS.d/next/Documentation/2022-08-19-17-07-45.gh-issue-96098.nDp43u.rst diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst index eaa9464..caf24a3 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 a8851dd..b22d487 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 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. -- cgit v0.12