Python Executor.map() buffersize

Python 3.14 adds a buffersize argument to concurrent.futures.Executor.map(). It limits how many submitted tasks can be waiting for results that have not yet been consumed.

Basic Usage

Example:

from concurrent.futures import ThreadPoolExecutor

def square(number):
    return number * number

with ThreadPoolExecutor(max_workers=4) as executor:
    results = executor.map(
        square,
        range(8),
        buffersize=4
    )

    for result in results:
        print(result)

Output:

0
1
4
9
16
25
36
49

Results are yielded in input order, not completion order. A slow early task can therefore delay later results.

Why buffersize Matters

Without a buffer limit, mapping a very large iterable can submit work faster than the consumer processes results. That can increase memory use and create a large queue of pending tasks.

With buffersize=20, iteration over the input pauses when the buffer is full and resumes as results are consumed.

Backpressure

This behavior provides a simple form of backpressure: the producer cannot run arbitrarily far ahead of the consumer.

The following is a pattern, not a standalone script: provide process_file, file_paths, and save_result for your application.

Example:

with ThreadPoolExecutor(max_workers=8) as executor:
    for result in executor.map(
        process_file,
        file_paths,
        buffersize=32
    ):
        save_result(result)

This pattern is useful when file_paths is large or generated lazily.

Choose a Buffer Size

The best value depends on task cost, worker count, result size, and how quickly results are consumed.

buffersize Is Not max_workers

max_workers controls how many workers can execute tasks concurrently. buffersize controls how far task submission can get ahead of result consumption.

Use buffersize when the input can be very large or infinite-like. It is not usually necessary for a small fixed list.

Conclusion

The Python 3.14 buffersize option makes Executor.map() more suitable for large streams of work by limiting queued submissions and reducing unnecessary memory pressure.