[Python-checkins] bpo-17140: Document multiprocessing's ThreadPool (GH-23812)

[miss-islington]

https://github.com/python/cpython/commit/14619924c36435e356135988c244cbc28652c82b
commit: 14619924c36435e356135988c244cbc28652c82b
branch: 3.9
author: Miss Islington (bot) <31488909+miss-islington at users.noreply.github.com>
committer: miss-islington <31488909+miss-islington at users.noreply.github.com>
date: 2020-12-18T05:27:02-08:00
summary:

bpo-17140: Document multiprocessing's ThreadPool (GH-23812)


Up until now, the `multiprocessing.pool.ThreadPool` class has gone
undocumented, despite being a public class in multiprocessing that is
included in `multiprocessing.pool.__all__`.
(cherry picked from commit 84ebcf271a2cc8bfd1762acb279502b8b6ef236e)

Co-authored-by: Matt Wozniski <mwozniski at bloomberg.net>

files:
A Misc/NEWS.d/next/Documentation/2020-12-16-21-06-16.bpo-17140.1leSEg.rst
M Doc/library/multiprocessing.rst

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index ab84d39ed0516..352f48f513df9 100644
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -2661,6 +2661,46 @@ The :mod:`multiprocessing.dummy` module
 :mod:`multiprocessing.dummy` replicates the API of :mod:`multiprocessing` but is
 no more than a wrapper around the :mod:`threading` module.
 
+.. currentmodule:: multiprocessing.pool
+
+In particular, the ``Pool`` function provided by :mod:`multiprocessing.dummy`
+returns an instance of :class:`ThreadPool`, which is a subclass of
+:class:`Pool` that supports all the same method calls but uses a pool of
+worker threads rather than worker processes.
+
+
+.. class:: ThreadPool([processes[, initializer[, initargs]]])
+
+   A thread pool object which controls a pool of worker threads to which jobs
+   can be submitted.  :class:`ThreadPool` instances are fully interface
+   compatible with :class:`Pool` instances, and their resources must also be
+   properly managed, either by using the pool as a context manager or by
+   calling :meth:`~multiprocessing.pool.Pool.close` and
+   :meth:`~multiprocessing.pool.Pool.terminate` manually.
+
+   *processes* is the number of worker threads to use.  If *processes* is
+   ``None`` then the number returned by :func:`os.cpu_count` is used.
+
+   If *initializer* is not ``None`` then each worker process will call
+   ``initializer(*initargs)`` when it starts.
+
+   Unlike :class:`Pool`, *maxtasksperchild* and *context* cannot be provided.
+
+    .. note::
+
+        A :class:`ThreadPool` shares the same interface as :class:`Pool`, which
+        is designed around a pool of processes and predates the introduction of
+        the :class:`concurrent.futures` module.  As such, it inherits some
+        operations that don't make sense for a pool backed by threads, and it
+        has its own type for representing the status of asynchronous jobs,
+        :class:`AsyncResult`, that is not understood by any other libraries.
+
+        Users should generally prefer to use
+        :class:`concurrent.futures.ThreadPoolExecutor`, which has a simpler
+        interface that was designed around threads from the start, and which
+        returns :class:`concurrent.futures.Future` instances that are
+        compatible with many other libraries, including :mod:`asyncio`.
+
 
 .. _multiprocessing-programming:
 
diff --git a/Misc/NEWS.d/next/Documentation/2020-12-16-21-06-16.bpo-17140.1leSEg.rst b/Misc/NEWS.d/next/Documentation/2020-12-16-21-06-16.bpo-17140.1leSEg.rst
new file mode 100644
index 0000000000000..cb1fd23a56e63
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2020-12-16-21-06-16.bpo-17140.1leSEg.rst
@@ -0,0 +1 @@
+Add documentation for the :class:`multiprocessing.pool.ThreadPool` class.