clarify doc: specify that it is the size of a buffer of tasks and not results

Author: ebonnal

Doc/library/concurrent.futures.rst

@@ -44,9 +44,10 @@ Executor Objects
 
       Similar to :func:`map(fn, *iterables) <map>` except:
 
-      * the *iterables* are collected immediately rather than lazily, unless a
-        *buffersize* is specified: If the buffer is full, then the iteration
-        over *iterables* is paused until a result is yielded from the buffer.
+      * The *iterables* are 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.
 
       * *fn* is executed asynchronously and several calls to
         *fn* may be made concurrently.
@@ -70,10 +71,10 @@ Executor Objects
       *chunksize* has no effect.
 
       .. versionchanged:: 3.5
-         Added the *chunksize* argument.
+         Added the *chunksize* parameter.
 
       .. versionchanged:: next
-         Added the *buffersize* argument.
+         Added the *buffersize* parameter.
 
    .. method:: shutdown(wait=True, *, cancel_futures=False)
 

Doc/whatsnew/3.14.rst

@@ -326,8 +326,10 @@ concurrent.futures
   (Contributed by Gregory P.  Smith in :gh:`84559`.)
 
 * Add the optional ``buffersize`` parameter to
-  :meth:`concurrent.futures.Executor.map` to specify the number
-  of results that can be buffered before being yielded.
+  :meth:`concurrent.futures.Executor.map` 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.
   (Contributed by Enzo Bonnal and Josh Rosenberg in :gh:`74028`.)
 
 ctypes

Lib/concurrent/futures/_base.py

@@ -586,10 +586,11 @@ def map(self, fn, *iterables, timeout=None, chunksize=1, buffersize=None):
                 before being passed to a child process. This argument is only
                 used by ProcessPoolExecutor; it is ignored by
                 ThreadPoolExecutor.
-            buffersize: The number of results that can be buffered before being
-                yielded. When the buffer is full, iteration over the input
-                iterables is paused until a result is yielded from the buffer.
-                If None, buffering is unlimited.
+            buffersize: 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.
+                If None, all input elements are eagerly collected, and a task is
+                submitted for each.
 
         Returns:
             An iterator equivalent to: map(func, *iterables) but the calls may

Lib/concurrent/futures/process.py

@@ -816,10 +816,11 @@ def map(self, fn, *iterables, timeout=None, chunksize=1, buffersize=None):
             chunksize: If greater than one, the iterables will be chopped into
                 chunks of size chunksize and submitted to the process pool.
                 If set to one, the items in the list will be sent one at a time.
-            buffersize: The number of result chunks that can be buffered before
-                being yielded. When the buffer is full, iteration over the
-                input iterables is paused until a result chunk is yielded from
-                the buffer. If None, buffering is unlimited.
+            buffersize: 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.
+                If None, all input elements are eagerly collected, and a task is
+                submitted for each.
 
         Returns:
             An iterator equivalent to: map(func, *iterables) but the calls may

Misc/NEWS.d/next/Library/2024-10-18-10-27-54.gh-issue-74028.4d4vVD.rst

@@ -1,2 +1,4 @@
-Add the optional ``buffersize`` parameter to :meth:`concurrent.futures.Executor.map`
-to specify the number of results that can be buffered before being yielded.
+Add the optional ``buffersize`` parameter to
+:meth:`concurrent.futures.Executor.map` 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.