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__`.
This commit is contained in:
Matt Wozniski 2020-12-18 08:05:46 -05:00 committed by GitHub
parent b9735420aa
commit 84ebcf271a
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 41 additions and 0 deletions

View File

@ -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:

View File

@ -0,0 +1 @@
Add documentation for the :class:`multiprocessing.pool.ThreadPool` class.