From 579ba3123dc90259f357b0b9f28f054fe853254b Mon Sep 17 00:00:00 2001 From: ebonnal Date: Sat, 11 Jan 2025 00:46:29 +0100 Subject: [PATCH] doc: specify that it is the size of a buffer of tasks and not results --- Doc/library/concurrent.futures.rst | 11 ++++++----- Doc/whatsnew/3.14.rst | 6 ++++-- Lib/concurrent/futures/_base.py | 9 +++++---- Lib/concurrent/futures/process.py | 9 +++++---- .../2024-10-18-10-27-54.gh-issue-74028.4d4vVD.rst | 6 ++++-- 5 files changed, 24 insertions(+), 17 deletions(-) diff --git a/Doc/library/concurrent.futures.rst b/Doc/library/concurrent.futures.rst index 1a0a441c109b5a..8df0379fe0a6bc 100644 --- a/Doc/library/concurrent.futures.rst +++ b/Doc/library/concurrent.futures.rst @@ -44,9 +44,10 @@ Executor Objects Similar to :func:`map(fn, *iterables) ` 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) diff --git a/Doc/whatsnew/3.14.rst b/Doc/whatsnew/3.14.rst index 5d97f3403f3df7..a77b4f339a5b0f 100644 --- a/Doc/whatsnew/3.14.rst +++ b/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 diff --git a/Lib/concurrent/futures/_base.py b/Lib/concurrent/futures/_base.py index 0431d3d45be2c0..9cb119ecc75c0d 100644 --- a/Lib/concurrent/futures/_base.py +++ b/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 diff --git a/Lib/concurrent/futures/process.py b/Lib/concurrent/futures/process.py index cf795a32e27b66..bdbfe3e7834316 100644 --- a/Lib/concurrent/futures/process.py +++ b/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 diff --git a/Misc/NEWS.d/next/Library/2024-10-18-10-27-54.gh-issue-74028.4d4vVD.rst b/Misc/NEWS.d/next/Library/2024-10-18-10-27-54.gh-issue-74028.4d4vVD.rst index 9cfc55e649af1c..6760e2b935430c 100644 --- a/Misc/NEWS.d/next/Library/2024-10-18-10-27-54.gh-issue-74028.4d4vVD.rst +++ b/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.