as_completed vs wait: Futures Localhost Lab

Intro — what this post promises

You already picked ThreadPoolExecutor. How should you drain the futures — as_completed, wait(..., ALL_COMPLETED), a FIRST_COMPLETED loop, or .result() in submit order? This lab measures wall time and tasks/s on Linux localhost.

It is not ThreadPool vs sequential (lab 58) or ProcessPool vs sequential (lab 80). The pool is fixed at 8 workers; the variable is the completion API.

Related links:

• threadpoolexecutor vs sequential localhost lab
• processpoolexecutor vs sequential localhost lab
• asyncio gather vs taskgroup localhost lab
• scandir vs listdir localhost lab
• tarfile vs zipfile localhost lab
• secrets vs urandom localhost lab
• textwrap fill vs manual localhost lab
• threading event vs condition localhost lab

Lab honesty (1 Oct 2026 IST): Python 3.13.5, max_workers=8. Affiliates: 0. No Docker.

Verdict up front (40× sleep(5 ms) drain): all barrier-style drains clustered ~25.75–28.08 ms (~1553 tasks/s). Time-to-first: as_completed ~2.47 ms vs wait(FIRST) ~4.15 ms vs submit-order ~4.22 ms. On CPU-light tasks, as_completed ~16.4 ms beat wait(ALL) ~24.34 ms.

Arms

Lab topology

workers=8 · rounds=7 · p50 wall for drain phase
sleep: 40× / 80× 5 ms
cpu_light: 40× sum-of-squares(50k)
also: time-to-first-result on 40×5 ms

Script: lab-evidence/92-futures-as-completed-vs-wait/results/run_lab.py.

Lead table — sleep drain (p50 ms)

Wall ≈ sleep depth / workers — orchestration overhead is noise until you care about ordering or first result.

CPU-light drain (40 tasks)

Time-to-first (40×5 ms)

Reading it

• Barrier completion (wait ALL / submit-order gather): fine when you need every result before continuing — sleep drains tied.
• Incremental results: prefer as_completed (clear API; best time-to-first here).
• wait(FIRST) loops work but are clunkier; similar total drain, slower first-byte in this run.
• Submit-order .result() can stall on a slow early future while later ones are done — wrong tool for streaming.

When which API

Sleep vs CPU-light

Equal sleeps make drain APIs look identical because the wall is the sleep schedule. Uneven or CPU-bound tasks expose ordering: as_completed lets you start follow-up work sooner, which showed up as a lower total drain time on the CPU-light arm in this run.

Pitfalls

• Using submit-order .result() when you meant completion order.
• Ignoring exceptions until the end — as_completed surfaces them as you iterate.
• Confusing this post with “threads vs processes” pool choice labs.

Reproduce

python3 lab-evidence/92-futures-as-completed-vs-wait/results/run_lab.py

Evidence: summary.json, summary.txt.

Limits

One Linux box, ThreadPool only. Sleep stands in for I/O wait. Not ProcessPool, not asyncio.

Takeaway

For full drains of equal sleep tasks, as_completed ≈ wait(ALL) ≈ submit-order (~25.75 ms @40×5 ms). For first result, as_completed ~2.47 ms led. Use as_completed when incremental progress matters; use wait(ALL) for a simple barrier.