concurrent.futures — High-Level Parallelism

from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
import math

# ThreadPoolExecutor — best for I/O-BOUND work
# (network requests, file reads, database queries)
# While one thread waits for I/O, others run. The GIL is released
# during I/O, so threads genuinely overlap waiting time.

# ProcessPoolExecutor — best for CPU-BOUND work
# (heavy computation, number crunching, image processing)
# Each process has its own interpreter and GIL, so they run on
# multiple CPU cores in true parallel.

def cpu_heavy(n):
    return sum(math.isqrt(i) for i in range(n))

numbers = [10_000_000] * 8

# For CPU-bound work, processes use all cores — threads would not help
# because the GIL serialises Python bytecode execution.
with ProcessPoolExecutor() as executor:        # defaults to os.cpu_count()
    results = list(executor.map(cpu_heavy, numbers))
    print(f"Computed {len(results)} results across CPU cores")

# Rule of thumb:
#   Waiting on I/O?  -> ThreadPoolExecutor
#   Burning CPU?     -> ProcessPoolExecutor
#   The API is identical, so switching is a one-line change.

from concurrent.futures import ThreadPoolExecutor, as_completed

# Pattern: map inputs to futures so you know which result is which
def process(item):
    return item * 2

items = ["a", "b", "c"]
with ThreadPoolExecutor() as executor:
    # A dict mapping each future back to its input
    future_to_item = {executor.submit(process, item): item for item in items}
    for future in as_completed(future_to_item):
        item = future_to_item[future]
        try:
            result = future.result()
            print(f"{item} -> {result}")
        except Exception as e:
            print(f"{item} failed: {e}")     # one task failing won't stop others

# PITFALL: ProcessPoolExecutor must run inside if __name__ == "__main__"
# on Windows/macOS (spawn start method), or it recursively spawns.
# def main():
#     with ProcessPoolExecutor() as ex:
#         ...
# if __name__ == "__main__":
#     main()

# PITFALL: arguments and return values for ProcessPoolExecutor must be
# picklable (they're sent between processes). Lambdas and local
# functions can't be pickled — use module-level functions.

from concurrent.futures import (ThreadPoolExecutor, wait,
                                FIRST_COMPLETED, ALL_COMPLETED)

with ThreadPoolExecutor() as executor:
    futures = [executor.submit(pow, 2, n) for n in range(5)]

    # Callbacks fire when a future completes (in a worker thread)
    futures[0].add_done_callback(lambda f: print("first done:", f.result()))

    # wait() with return_when gives precise control
    done, not_done = wait(futures, timeout=10, return_when=ALL_COMPLETED)
    print(f"{len(done)} completed, {len(not_done)} pending")

    # exception() retrieves an error without raising it
    for f in done:
        err = f.exception()        # None if successful
        if err:
            print(f"failed with {err}")

# initializer runs once per worker — useful for per-worker setup
def init_worker():
    # e.g. open a per-process database connection or set up logging
    pass

with ThreadPoolExecutor(max_workers=4, initializer=init_worker) as ex:
    ...

# chunksize matters for ProcessPoolExecutor.map with many small tasks:
# batching reduces inter-process overhead
# with ProcessPoolExecutor() as ex:
#     ex.map(func, big_iterable, chunksize=100)

# InterpreterPoolExecutor (3.14+) — sub-interpreters, each with its own
# GIL, giving process-like parallelism with lower overhead than processes.