bpo-38501: Add a warning section to multiprocessing.Pool docs about resource managing...

(cherry picked from commit 7ec43a73092d43c6c95e7dd2669f49d54b57966f)

Co-authored-by: Pablo Galindo <Pablogsal@gmail.com>

diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
index 492f94c30017f0acc53ff20ab521c0fbf8dd2778..ec9521f1fb4a0cc7229bb6332508b63e946d987d 100644 (file)
--- a/Doc/library/multiprocessing.rst
+++ b/Doc/library/multiprocessing.rst
@@ -439,7 +439,8 @@ process which created it.
       >>> def f(x):
       ...     return x*x
       ...
-      >>> p.map(f, [1,2,3])
+      >>> with p:
+      ...   p.map(f, [1,2,3])
       Process PoolWorker-1:
       Process PoolWorker-2:
       Process PoolWorker-3:
@@ -2127,6 +2128,16 @@ with the :class:`Pool` class.
    Note that the methods of the pool object should only be called by
    the process which created the pool.
 
+   .. warning::
+      :class:`multiprocessing.pool` objects have internal resources that need to be
+      properly managed (like any other resource) by using the pool as a context manager
+      or by calling :meth:`close` and :meth:`terminate` manually. Failure to do this
+      can lead to the process hanging on finalization.
+
+      Note that is **not correct** to rely on the garbage colletor to destroy the pool
+      as CPython does not assure that the finalizer of the pool will be called
+      (see :meth:`object.__del__` for more information).
+
    .. versionadded:: 3.2
       *maxtasksperchild*