How do Executor.map and concurrent.futures.as_completed differ in ordering and error timing?

Both `Executor.map` and `concurrent.futures.as_completed` fan work out over the same pool. They differ in the order results arrive, in when an error hits you, and in how much you can do per item. ### `Executor.map` `pool.map(fn, iterable)` submits jobs and returns a **generator**, not a list. Under the hood it creates one `Future` per input and the generator pops them off the front in input order, calling `result()` on each. Three consequences follow directly: 1. **Ordered output.** Result *i* always corresponds to input *i*, regardless of which job actually finished first. That is exactly what you want when the results feed a positional structure. 2. **Head-of-line blocking.** If input 0 takes ten seconds and inputs 1..99 take ten milliseconds each, you get nothing for ten seconds even though 99 results are already computed and waiting in memory. 3. **Errors stop the stream.** When the generator reaches a `Future` that failed, `result()` re-raises there, and the generator's cleanup cancels the futures that have not started. You cannot see the results *after* the failing item, and you do not learn how many other items failed — only the first one in input order. `map` also has two parameters worth knowing. `chunksize` batches inputs into groups so a `ProcessPoolExecutor` pays the inter-process round trip once per batch rather than once per item; `ThreadPoolExecutor` ignores it entirely, since there is no serialization to amortize. And `buffersize`, **new in Python 3.14**, caps how far ahead `map` consumes its input iterable: before 3.14, `map` drained the whole iterable and submitted every job up front, which meant an infinite or huge input either hung or blew up memory. With `buffersize=n` it keeps roughly `n` items in flight and pulls more only as results are consumed, giving you backpressure. ### `as_completed` `as_completed(futures, timeout=None)` takes an iterable of futures you already submitted and yields them **in the order they finish**. Futures that are already done come out first, then the rest as they complete. It yields the `Future`, not the value, so you still call `result()` or `exception()` yourself — which is the whole point: you get to handle each item's failure individually and keep going. This is the shape you want for progress reporting (`for i, fut in enumerate(as_completed(futures), 1): ...`), for a first-result-wins race, and for collecting a full failure report instead of stopping at the first error. Its cost is that you must keep every `Future` alive to pass in, and to know *which* input a yielded `Future` belongs to you need a side mapping — the common idiom is a dict `{pool.submit(fn, item): item for item in items}`, then look up `futures[fut]` on the way out. The `timeout` argument applies to the whole iteration, not per future, and raises `TimeoutError` when it expires. ### `wait` `concurrent.futures.wait(futures, timeout=None, return_when=ALL_COMPLETED)` is the blocking, non-streaming sibling. It returns a named tuple of two sets, `done` and `not_done`, and never raises a job's exception itself. `return_when` accepts `FIRST_COMPLETED`, `FIRST_EXCEPTION` (return as soon as any job raises, or when all finish if none does) and `ALL_COMPLETED`. `FIRST_EXCEPTION` is the natural building block for fail-fast batch jobs: wait for it, then shut the pool down. ### Memory, correlation and cancellation on failure The two shapes also differ in what you must hold. `as_completed` needs the full list of futures in memory for the whole run, and a `Future` carries no reference to the arguments it was called with, so correlating a result back to its input needs a side mapping you build at submit time. `map` needs no such bookkeeping — position *is* the correlation — and on 3.14 with `buffersize` it does not even need the input list materialized. There is one behaviour people miss: when the `map` generator is closed, whether by an exception or by garbage collection, its cleanup cancels the futures that have not started yet. Breaking out of a `for` loop over `pool.map(...)` therefore drops the remaining queued work, while breaking out of a loop over `as_completed` leaves every outstanding job running. ### Choosing A useful decision rule: if you would have written a plain list comprehension over `map()` in single-threaded code and you want the same shape back, use `Executor.map`. The moment you need per-item error handling, progress as work lands, correlation back to the input, or a reaction to the first failure, drop to `submit` plus `as_completed` or `wait`. Rewriting `map` into `submit` + `as_completed` is a two-line change, so this is not a decision to agonize over up front. A final gotcha that shows up in reviews: `pool.map` is lazy, so calling it and never iterating the result does almost nothing visible — the work is submitted, but the exceptions stay unread. Wrapping it in `list(...)` inside the `with` block is what actually forces both the results and the errors out.