Add doc for buffersize argument of imap and imap_unordered

obaltian · obaltian · commit fc37cb46765f · 2025-07-28T00:37:41.000+02:00
diff --git a/Doc/library/multiprocessing.rst b/Doc/library/multiprocessing.rst
@@ -2408,7 +2408,7 @@ with the :class:`Pool` class.
       Callbacks should complete immediately since otherwise the thread which
       handles the results will get blocked.
 
-   .. method:: imap(func, iterable[, chunksize])
+   .. method:: imap(func, iterable[, chunksize[, buffersize]])
 
       A lazier version of :meth:`.map`.
 
@@ -2422,6 +2422,17 @@ with the :class:`Pool` class.
       ``next(timeout)`` will raise :exc:`multiprocessing.TimeoutError` if the
       result cannot be returned within *timeout* seconds.
 
+      The *iterable* is collected immediately rather than lazily, unless a
+      *buffersize* is specified to limit the number of submitted tasks whose
+      results have not yet been yielded. If the buffer is full, iteration over
+      the *iterables* pauses until a result is yielded from the buffer.
+      To fully utilize pool's capacity, set *buffersize* to the number of
+      processes in pool (to consume *iterable* as you go) or even higher
+      (to prefetch *buffersize - processes* arguments).
+
+      .. versionadded:: 3.15
+         Added the *buffersize* parameter.
+
    .. method:: imap_unordered(func, iterable[, chunksize])
 
       The same as :meth:`imap` except that the ordering of the results from the
diff --git a/Misc/NEWS.d/next/Library/2025-07-20-14-41-16.gh-issue-64192._0Rbp_.rst b/Misc/NEWS.d/next/Library/2025-07-20-14-41-16.gh-issue-64192._0Rbp_.rst
@@ -0,0 +1,9 @@
+Add the optional ``buffersize`` parameter to
+:meth:`multiprocessing.pool.Pool.imap` and
+:meth:`multiprocessing.pool.Pool.imap_unordered` to limit the number of
+submitted tasks whose results have not yet been yielded. If the buffer is full,
+iteration over the *iterables* pauses until a result is yielded from the buffer.
+
+To fully utilize pool's capacity, set *buffersize* to the number of
+processes in pool (to consume *iterable* as you go) or even higher
+(to prefetch *buffersize - processes* arguments).
diff --git a/Misc/NEWS.d/next/Library/2025-07-28-00-37-22.gh-issue-64192.iCGeQ5.rst b/Misc/NEWS.d/next/Library/2025-07-28-00-37-22.gh-issue-64192.iCGeQ5.rst
@@ -0,0 +1,8 @@
+Add the optional ``buffersize`` parameter to
+:meth:`multiprocessing.pool.Pool.imap` and
+:meth:`multiprocessing.pool.Pool.imap_unordered` to limit the number of
+submitted tasks whose results have not yet been yielded. If the buffer is
+full, iteration over the *iterables* pauses until a result is yielded from
+the buffer. To fully utilize pool's capacity, set *buffersize* to the number
+of processes in pool (to consume *iterable* as you go) or even higher (to
+prefetch *buffersize - processes* arguments).
