Parallelism with concurrent.futures

Published by Brayan K

Master Python's concurrent.futures module to build high-performance parallel systems using ThreadPoolExecutor and ProcessPoolExecutor.

Part of the free Python course at LearnCodingFast — hands-on lessons with examples you run in your browser, plus practice exercises and a quick quiz.

submit() hands you a Future straight away

Concurrency in Python: Threads vs Processes used a pool through with ThreadPoolExecutor(max_workers=4) as pool: and pool.map(), which gives the results in the order of the inputs. Underneath, the thread pool's map() calls submit() for each input. This lesson is about submit() and what it hands back: a Future, which you can wait on, ask for its error, take as soon as it finishes, cancel, or give a timeout. Whether a pool makes your program faster is something to measure, which is Profiling & Optimising Python Performance 's subject.

This site's Run button can't start threads or processes: the Python in your browser runs in the page's only thread. An example that starts one shows a note there instead of its output, and its ✅ panel shows what Python prints on a computer. The examples that fill a Future by hand, without a pool, run in the browser too.

A Future is the same idea as in AsyncIO: Event Loop, Tasks & Futures: a box for a result that something fills in later. In a pool, a worker fills it when your function returns. You can fill one yourself to see how it behaves:

from concurrent.futures import Future

box = Future()
print("done?", box.done())
box.set_result(42)          # what a pool's worker does when your function returns
print("done?", box.done())
print(box.result(timeout=0))

# ✅ Expected output:
# done? False
# done? True
# 42

result() waits until the box is filled; timeout=0 tells it not to wait at all. In the browser, a result() on a box nobody fills would never return and would freeze the page, so the examples that fill a box by hand ask with timeout=0.

pool.submit(function, *args, **kwargs) passes the function and its arguments on, as in *args & **kwargs, and returns a Future at once, while a worker runs the call:

from concurrent.futures import ThreadPoolExecutor

def square(n):
    return n * n

with ThreadPoolExecutor(max_workers=2) as pool:
    future = pool.submit(square, 12)
    print(type(future).__name__)
    print(future.result())
    print(pool.submit(round, 3.14159, ndigits=2).result())

# ✅ Expected output:
# Future
# 144
# 3.14

The usual slip is to call the function yourself. pool.submit(square(4)) runs square(4) in your own thread, before submit() is even called, and hands the pool the number 16, which it then tries to call:

from concurrent.futures import ThreadPoolExecutor

def square(n):
    print("squaring", n)
    return n * n

with ThreadPoolExecutor(max_workers=2) as pool:
    future = pool.submit(square(4))
    print("submitted")
    print(future.result())

# ✅ Expected output:
# squaring 4
# submitted

# ✅ Expected error:
# TypeError: 'int' object is not callable

squaring 4 comes first, from your own thread. The TypeError happened in the worker, and it only appears at result(), the line that asks for it.

A task's error waits in its Future until you ask

When the function raises, the worker puts the error in the Future, and result() raises it again in your program:

from concurrent.futures import ThreadPoolExecutor

def share(total, people):
    return total / people

with ThreadPoolExecutor(max_workers=2) as pool:
    future = pool.submit(share, 10, 0)
    print("submitted")
    print(future.result())

# ✅ Expected output:
# submitted

# ✅ Expected error:
# ZeroDivisionError: division by zero

In a process pool the last line is the same, and above it Python prints the worker's own traceback, then "The above exception was the direct cause of the following exception". exception() hands the error back without raising it, and gives None when the task succeeded:

from concurrent.futures import ThreadPoolExecutor

def parse(text):
    return int(text)

with ThreadPoolExecutor(max_workers=2) as pool:
    good = pool.submit(parse, "42")
    bad = pool.submit(parse, "forty-two")
    print(good.exception())
    print(repr(bad.exception()))
    print(good.result())

# ✅ Expected output:
# None
# ValueError("invalid literal for int() with base 10: 'forty-two'")
# 42

If nothing asks, the error is never shown at all:

from concurrent.futures import ThreadPoolExecutor

def parse(text):
    return int(text)

with ThreadPoolExecutor(max_workers=2) as pool:
    pool.submit(parse, "forty-two")
print("finished, and no error was shown")

# ✅ Expected output:
# finished, and no error was shown

The program ends normally, with nothing on the screen about the ValueError. So ask every Future you submit, with result() inside a try (Exception Handling) or with exception(). A worker that fails does to the box what this does by hand:

from concurrent.futures import Future

box = Future()
box.set_exception(ValueError("bad price"))   # what a worker does when your function raises
print("done?", box.done())
print(repr(box.exception(timeout=0)))
box.result(timeout=0)

# ✅ Expected output:
# done? True
# ValueError('bad price')

# ✅ Expected error:
# ValueError: bad price

as_completed() hands you futures as they finish

To deal with each result as soon as it's ready, give as_completed() a list of futures. It yields each one when it finishes, in the order they finish. That order depends on the machine: three tasks of different sizes finished in two or three different orders in 20 runs on each of Python 3.10–3.13. So the example below holds the big download back until the loop has handled the small one. threading.Event() is a flag: wait() blocks until another thread calls set(). Threading & the GIL covers it.

import threading
from concurrent.futures import ThreadPoolExecutor, as_completed

go = threading.Event()

def big_download():
    go.wait()                  # held back until the loop has handled a result
    return "big.zip"

def small_download():
    return "small.txt"

with ThreadPoolExecutor(max_workers=2) as pool:
    futures = [pool.submit(big_download), pool.submit(small_download)]
    for future in as_completed(futures):
        print("finished:", future.result())
        go.set()               # now big_download may finish
print([f.result() for f in futures])

# ✅ Expected output:
# finished: small.txt
# finished: big.zip
# ['big.zip', 'small.txt']

The list at the end is still in the order the tasks were submitted. Take out go.set() and the program never ends: big_download() waits for a flag nobody sets, and the with block waits for it.

as_completed() gives you futures, not inputs, so the usual pattern keeps a dictionary from each future to the input it was given:

from concurrent.futures import ThreadPoolExecutor, as_completed

def word_length(word):
    if not word.isalpha():
        raise ValueError(f"not a word: {word}")
    return len(word)

words = ["pool", "future", "3rd", "thread"]
lengths, failed = {}, []
with ThreadPoolExecutor(max_workers=2) as pool:
    futures = {pool.submit(word_length, w): w for w in words}
    for future in as_completed(futures):
        word = futures[future]
        try:
            lengths[word] = future.result()
        except ValueError as e:
            failed.append(str(e))
print(sorted(lengths.items()))
print(failed)

# ✅ Expected output:
# [('future', 6), ('pool', 4), ('thread', 6)]
# ['not a word: 3rd']

Sorting at the end makes the output the same whatever order the tasks finished in. wait() is the other way to watch several futures: with return_when=FIRST_COMPLETED it returns as soon as one has finished, as two sets, the finished futures and the rest. Print their results, not the sets: a Future prints with its memory address.

import threading
from concurrent.futures import ThreadPoolExecutor, wait, FIRST_COMPLETED

go = threading.Event()

def slow():
    go.wait()
    return "slow"

def fast():
    return "fast"

with ThreadPoolExecutor(max_workers=2) as pool:
    futures = [pool.submit(slow), pool.submit(fast)]
    done, not_done = wait(futures, return_when=FIRST_COMPLETED)
    print([f.result() for f in done], len(not_done))
    go.set()

# ✅ Expected output:
# ['fast'] 1

as_completed() also takes a timeout. When it runs out, it raises a TimeoutError that says how many futures were still unfinished:

import concurrent.futures
from concurrent.futures import Future, as_completed

ready, later = Future(), Future()
ready.set_result("ready")
try:
    for future in as_completed([ready, later], timeout=0):
        print("finished:", future.result())
except concurrent.futures.TimeoutError as e:
    print("gave up:", e)

# ✅ Expected output:
# finished: ready
# gave up: 1 (of 2) futures unfinished

cancel() works only on a task that hasn't started

A running task can't be cancelled. With one worker, the first task below is running and the second waits in the queue, so only the second can be cancelled:

import threading
from concurrent.futures import ThreadPoolExecutor

started = threading.Event()
go = threading.Event()

def first():
    started.set()
    go.wait()
    return "first"

def second():
    return "second"

with ThreadPoolExecutor(max_workers=1) as pool:
    a = pool.submit(first)          # the only worker takes this one
    b = pool.submit(second)         # and this one waits in the queue
    started.wait()                  # until first() is really running
    print("running?", a.running(), b.running())
    print("cancel a:", a.cancel())
    print("cancel b:", b.cancel())
    go.set()
print(a.result(), b.cancelled())

# ✅ Expected output:
# running? True False
# cancel a: False
# cancel b: True
# first True

Asking a cancelled Future for its result raises CancelledError. Unlike asyncio's, this CancelledError is an ordinary Exception, so except Exception catches it:

from concurrent.futures import Future

box = Future()               # nothing has started it, so it can still be cancelled
print("cancelled?", box.cancel())
print(box.cancelled(), box.done())
box.result(timeout=0)

# ✅ Expected output:
# cancelled? True
# True True

# ✅ Expected error:
# concurrent.futures._base.CancelledError

Leaving a with block early cancels nothing either. Its exit calls shutdown(wait=True), which waits for every task, the queued ones included, as Context Managers & the with Statement in Depth explains for exits in general:

from concurrent.futures import ThreadPoolExecutor

done = []

def record(n):
    done.append(n)
    return n

try:
    with ThreadPoolExecutor(max_workers=1) as pool:
        for n in range(3):
            pool.submit(record, n)
        raise ValueError("stop everything")
except ValueError as e:
    print("caught:", e)
print("tasks that still ran:", sorted(done))

# ✅ Expected output:
# caught: stop everything
# tasks that still ran: [0, 1, 2]

To drop the queued tasks, call shutdown(cancel_futures=True) yourself. The running task still finishes:

import threading
from concurrent.futures import ThreadPoolExecutor

started = threading.Event()
go = threading.Event()

def job(n):
    if n == 0:
        started.set()
        go.wait()
    return n

pool = ThreadPoolExecutor(max_workers=1)
futures = [pool.submit(job, n) for n in range(4)]
started.wait()                       # job 0 is running now
pool.shutdown(wait=False, cancel_futures=True)
go.set()
print([f.cancelled() for f in futures])
print(futures[0].result())

# ✅ Expected output:
# [False, True, True, True]
# 0

A pool that has shut down takes no more work, so a submit() after the block fails:

from concurrent.futures import ThreadPoolExecutor

with ThreadPoolExecutor(max_workers=2) as pool:
    pass
print("the with block has ended")
pool.submit(print, "hello")

# ✅ Expected output:
# the with block has ended

# ✅ Expected error:
# RuntimeError: cannot schedule new futures after shutdown

A timeout stops the waiting, not the task

result(timeout=...) gives up waiting after that many seconds and raises a TimeoutError. The task itself carries on, and you can ask again later:

import threading
import concurrent.futures
from concurrent.futures import ThreadPoolExecutor

go = threading.Event()

def slow():
    go.wait()
    return "slow"

with ThreadPoolExecutor(max_workers=1) as pool:
    future = pool.submit(slow)
    try:
        future.result(timeout=0)
    except concurrent.futures.TimeoutError:
        print("not finished yet")
    go.set()
    print(future.result())

# ✅ Expected output:
# not finished yet
# slow

That is the opposite of Advanced Async & Await Patterns ' asyncio.wait_for(), which cancels the job when its time is up. The same happens with a Future you fill by hand:

import concurrent.futures
from concurrent.futures import Future

box = Future()
try:
    box.result(timeout=0)
except concurrent.futures.TimeoutError:
    print("not finished yet")
box.set_result("done now")
print(box.result(timeout=0))

# ✅ Expected output:
# not finished yet
# done now

Catch it as concurrent.futures.TimeoutError, which works on every version. From Python 3.11 on it is the built-in TimeoutError; on 3.10 it is a class of its own, so except TimeoutError doesn't catch it there. map() and as_completed() raise the same error when their timeout runs out.

A process pool has to pickle the function, its arguments and its result

A process pool sends each task to another process by pickling it: the function goes as its name, and the arguments as bytes. The result comes back the same way. A thread pool sends nothing, so code that works in a thread pool can fail in a process pool. pickle.dumps() shows what can be sent; Serialization with pickle covers it. This one runs in the browser too:

import pickle
import threading

for thing in [[1, 2, 3], {"a": 1}, threading.Lock(), (n for n in range(3))]:
    try:
        pickle.dumps(thing)
        print(type(thing).__name__, "can be sent")
    except TypeError as e:
        print(type(thing).__name__, "->", e)

# ✅ Expected output:
# list can be sent
# dict can be sent
# lock -> cannot pickle '_thread.lock' object
# generator -> cannot pickle 'generator' object

The function is sent by name, so it has to be a def at the top of the file. A lambda fails, as Concurrency in Python: Threads vs Processes showed, and so does a function made inside another function, such as a closure from a factory (Closures & Lexical Scope in Real Projects). Their error messages change between Python versions. To give a top-level function some fixed settings, use functools.partial, which functools: lru_cache, partial, reduce covers:

from concurrent.futures import ProcessPoolExecutor
from functools import partial

def multiply(n, factor):
    return n * factor

if __name__ == "__main__":
    triple = partial(multiply, factor=3)
    with ProcessPoolExecutor(max_workers=2) as pool:
        print(list(pool.map(triple, [1, 2, 3])))

# ✅ Expected output:
# [3, 6, 9]

The arguments have to pickle too. A lock can't be sent, and the error comes back from result(), not from submit():

import threading
from concurrent.futures import ProcessPoolExecutor

def add_one(n, lock):
    with lock:
        return n + 1

if __name__ == "__main__":
    lock = threading.Lock()
    with ProcessPoolExecutor(max_workers=2) as pool:
        future = pool.submit(add_one, 1, lock)
        print("submitted")
        try:
            print(future.result())
        except TypeError as e:
            print("TypeError:", e)

# ✅ Expected output:
# submitted
# TypeError: cannot pickle '_thread.lock' object

Left uncaught, that TypeError is the last line of the traceback up to Python 3.13. From 3.14, a line under it names what was being sent, such as when serializing concurrent.futures.process._CallItem object. A generator can't be sent either, as an argument or as the result. The same function works in a thread pool, which sends nothing:

from concurrent.futures import ProcessPoolExecutor, ThreadPoolExecutor

def evens(limit):
    return (n for n in range(limit) if n % 2 == 0)

if __name__ == "__main__":
    with ThreadPoolExecutor(max_workers=2) as pool:
        print(list(pool.submit(evens, 10).result()))
    with ProcessPoolExecutor(max_workers=2) as pool:
        future = pool.submit(evens, 10)
        try:
            print(list(future.result()))
        except TypeError as e:
            print("TypeError:", e)

# ✅ Expected output:
# [0, 2, 4, 6, 8]
# TypeError: cannot pickle 'generator' object

An open file can't be sent either, and that message changes between versions too. Send the file's name, and let the task open it:

from concurrent.futures import ProcessPoolExecutor

def first_line(path):
    with open(path) as f:
        return f.readline().strip()

if __name__ == "__main__":
    with open("notes.txt", "w") as f:
        f.write("hello\n")
    with ProcessPoolExecutor(max_workers=2) as pool:
        print(pool.submit(first_line, "notes.txt").result())

# ✅ Expected output:
# hello

When a worker process dies, the whole pool breaks

os._exit(1) ends a process at once, as a crash would. A pool that loses a worker that way marks itself broken, and every Future still waiting fails with BrokenProcessPool:

import os
from concurrent.futures import ProcessPoolExecutor

def crash(n):
    os._exit(1)

if __name__ == "__main__":
    with ProcessPoolExecutor(max_workers=2) as pool:
        future = pool.submit(crash, 1)
        print(future.result())

# ✅ Expected error:
# concurrent.futures.process.BrokenProcessPool: A process in the process pool was terminated abruptly while the future was running or pending.

Catching the error doesn't mend the pool. It stays broken, and the next task fails at once:

import os
from concurrent.futures import ProcessPoolExecutor
from concurrent.futures.process import BrokenProcessPool

def crash(n):
    os._exit(1)

if __name__ == "__main__":
    with ProcessPoolExecutor(max_workers=2) as pool:
        try:
            pool.submit(crash, 1).result()
        except BrokenProcessPool:
            print("the pool broke")
        pool.submit(abs, -1)

# ✅ Expected output:
# the pool broke

# ✅ Expected error:
# concurrent.futures.process.BrokenProcessPool: A child process terminated abruptly, the process pool is not usable anymore

A thread pool breaks the same way when its initializer fails. That is a function each worker runs once, when it starts, with the arguments in initargs:

from concurrent.futures import ThreadPoolExecutor

def setup(name):
    print("worker ready:", name)

with ThreadPoolExecutor(max_workers=1, initializer=setup, initargs=("db",)) as pool:
    results = list(pool.map(len, ["a", "bb", "ccc"]))
print(results)

# ✅ Expected output:
# worker ready: db
# [1, 2, 3]
from concurrent.futures import ThreadPoolExecutor

def setup():
    raise ValueError("no database")

with ThreadPoolExecutor(max_workers=1, initializer=setup) as pool:
    future = pool.submit(pow, 2, 10)
    print(future.result())

# ✅ Expected error:
# concurrent.futures.thread.BrokenThreadPool: A thread initializer failed, the thread pool is not usable anymore

A process pool using spawn or forkserver needs the if __name__ == "__main__": guard so importing the main module does not start another pool. Defaults vary by platform and version, as Concurrency in Python: Threads vs Processes explains. Code that happens to work with fork is not thereby portable to the other start methods.

An executor is anything with submit()

ThreadPoolExecutor and ProcessPoolExecutor are both children of Executor, which builds map() and the with block on top of the child's submit() and shutdown(). So a class that writes those two gets the rest, as a child does in Inheritance and Polymorphism. Executor's own shutdown() does nothing, so this one writes a shutdown() that turns later tasks away, as the pools do. It runs each call at once, in this thread, which also makes it a pool that works in the browser. The / after fn is from Advanced Functions & Parameters Masterclass: it lets a task take a keyword argument called fn too.

from concurrent.futures import Executor, Future

class InlineExecutor(Executor):
    """Runs each call at once, in this thread, and hands back a finished Future."""
    def __init__(self):
        self.closed = False

    def submit(self, fn, /, *args, **kwargs):
        if self.closed:
            raise RuntimeError("cannot schedule new futures after shutdown")
        future = Future()
        try:
            future.set_result(fn(*args, **kwargs))
        except BaseException as e:
            future.set_exception(e)
        return future

    def shutdown(self, wait=True, *, cancel_futures=False):
        self.closed = True

with InlineExecutor() as pool:
    f = pool.submit(pow, 2, 10)
    print(f.done(), f.result())
    print(list(pool.map(len, ["a", "bb", "ccc"])))
    bad = pool.submit(int, "three")
    print(repr(bad.exception()))

try:
    pool.submit(pow, 2, 3)
except RuntimeError as e:
    print("after the with block:", e)

# ✅ Expected output:
# True 1024
# [1, 2, 3]
# ValueError("invalid literal for int() with base 10: 'three'")
# after the with block: cannot schedule new futures after shutdown

It catches BaseException, not just Exception, because a pool's worker does too: that's how a task's sys.exit() ends up in its Future, as the FAQ at the end says.

add_done_callback() gives a Future a function to call with it when it finishes. Added to a Future that has already finished, it runs at once:

from concurrent.futures import Future

def report(fut):
    print("callback got", fut.result())

box = Future()
box.add_done_callback(report)
print("callback added")
box.set_result(7)
print("after set_result")
box.add_done_callback(report)

# ✅ Expected output:
# callback added
# callback got 7
# after set_result
# callback got 7

In a thread pool, a callback added while the task is still running is called by the worker thread that finishes the task, not yours. In a process pool, it's called by a helper thread in your own process: the task ran in another process, but its Future lives in yours.

Process pools also take chunksize in map(), which sends the inputs in batches. When every call succeeds, that changes only the speed. When one raises, its whole batch fails with it: with chunksize=2, map(f, [1, 2, 3]) gives no result for 1 if f(2) raises, while chunksize=1 gives 1 first. A thread pool ignores chunksize.

Practice: a pool's worker, by hand

run_job() does what a pool's worker does with each task: it calls the function and puts the result, or the error, in a Future. Fill the two blanks: the method that puts a result in the box, and the one that asks whether the task failed. If you're stuck, the two 👉 lines under the code answer them, first blank first. This one runs in the browser too.

from concurrent.futures import Future

def run_job(job, arg):
    # what a pool's worker does with each task
    box = Future()
    try:
        box.___(job(arg))
    except BaseException as e:
        box.set_exception(e)
    return box

boxes = [run_job(float, text) for text in ["4.50", "free", "3.25"]]
for box in boxes:
    if box.___() is None:
        print("price:", box.result())
    else:
        print("failed:", box.exception())

# 👉 replace ___ with set_result
# 👉 replace ___ with exception

# ✅ Expected output:
# price: 4.5
# failed: could not convert string to float: 'free'
# price: 3.25

Use result() as the check instead of exception(), and the loop prints failed: None for the first price, then stops with the ValueError at the second: asking for the result of a failed task raises its error.

On your own: count a word in four sentences

Count the word "the" in each of four sentences with a ProcessPoolExecutor of two workers, under the __main__ guard:

Use the sentences "the cat sat on the mat", "a dog", "the end" and "then there were the three". Run it with python3 on your computer.

from concurrent.futures import ProcessPoolExecutor, as_completed
from functools import partial

# your code here
from concurrent.futures import ProcessPoolExecutor, as_completed
from functools import partial

def count_word(text, word):
    return text.split().count(word)

if __name__ == "__main__":
    sentences = ["the cat sat on the mat", "a dog", "the end", "then there were the three"]
    count_the = partial(count_word, word="the")
    counts = {}
    with ProcessPoolExecutor(max_workers=2) as pool:
        futures = {pool.submit(count_the, s): i for i, s in enumerate(sentences)}
        for future in as_completed(futures):
            counts[futures[future]] = future.result()
    print(sorted(counts.items()))
    print("total:", sum(counts.values()))

# ✅ Expected output:
# [(0, 2), (1, 0), (2, 1), (3, 1)]
# total: 4

"then" isn't counted: split() makes whole words, and count() compares them whole. A lambda in place of partial() stops with a PicklingError.

Practice quiz

parse(text) returns int(text). Inside a with ThreadPoolExecutor() block, pool.submit(parse, "forty-two") is called and its Future is never used again. After the block, the program prints finished. What happens?

  • It stops with ValueError before printing finished
  • It prints finished and ends normally: the ValueError is never shown
  • It prints finished, then stops with ValueError
  • It prints the ValueError's traceback, then finished

Answer: It prints finished and ends normally: the ValueError is never shown. The error waits in the Future, and nothing ever asks for it, so it is lost.

square(n) prints squaring and the number, then returns n * n. The program runs future = pool.submit(square(4)), then print("submitted"), then print(future.result()). What is shown?

  • squaring 4, submitted, 16
  • submitted, squaring 4, 16
  • squaring 4, submitted, then TypeError: 'int' object is not callable
  • TypeError: 'int' object is not callable, before anything is printed

Answer: squaring 4, submitted, then TypeError: 'int' object is not callable. square(4) runs at once in your own thread and hands the pool 16, which it can't call. The error waits in the Future until result() asks.

A pool has one worker. Task a is running and task b is waiting in the queue. What do a.cancel() and b.cancel() return?

  • True and True
  • False and False
  • True and False
  • False and True

Answer: False and True. Only a task that hasn't started can be cancelled.

In the as_completed() example, big_download() waits for a flag the loop sets after it has handled the first result. What does the program print?

  • finished: small.txt, finished: big.zip, then ['big.zip', 'small.txt']
  • finished: big.zip, finished: small.txt, then ['big.zip', 'small.txt']
  • finished: small.txt, finished: big.zip, then ['small.txt', 'big.zip']
  • Nothing: it never finishes

Answer: finished: small.txt, finished: big.zip, then ['big.zip', 'small.txt']. as_completed() yields futures as they finish, but the list built from futures keeps the order they were submitted in.

A task waits for a flag. The program calls future.result(timeout=0) inside a try, prints not finished yet on the timeout, then sets the flag and prints future.result(). What is printed?

  • not finished yet, then CancelledError
  • slow only
  • not finished yet, then slow
  • not finished yet only: the timeout cancelled the task

Answer: not finished yet, then slow. A timeout gives up the waiting, not the task, which finishes once the flag is set.

A function that takes a threading.Lock is submitted to a ProcessPoolExecutor with a Lock as its argument. The program prints submitted, then the result. What happens?

  • It prints submitted, then stops with TypeError: cannot pickle '_thread.lock' object
  • It prints 2
  • It prints submitted, then 2
  • It stops with RuntimeError before printing submitted

Answer: It prints submitted, then stops with TypeError: cannot pickle '_thread.lock' object. A process pool pickles the arguments to send them, and a Lock can't be pickled. The error comes back from result(), not from submit().

Three tasks are submitted to a one-worker pool, then the with block's body raises ValueError("stop everything"), which a try around the block catches and prints. Each task records its number. What is printed?

  • caught: stop everything, then tasks that still ran: []
  • tasks that still ran: [0]
  • It stops with ValueError
  • caught: stop everything, then tasks that still ran: [0, 1, 2]

Answer: caught: stop everything, then tasks that still ran: [0, 1, 2]. Leaving a with block calls shutdown(wait=True): it waits for every task and cancels none.

A with ThreadPoolExecutor() as pool: block ends, and then pool.submit(print, "hello") is called. What happens?

  • It prints hello
  • It stops with RuntimeError: cannot schedule new futures after shutdown
  • It prints nothing and ends normally
  • A new pool starts and prints hello

Answer: It stops with RuntimeError: cannot schedule new futures after shutdown. Leaving the with block shut the pool down, and a shut-down pool takes no more work.

Continue this course

Frequently asked questions

What happens if a task calls sys.exit()?

The SystemExit waits in the Future like any other error. When result() raises it in the main program, the program ends with that exit status and no message: a task that calls sys.exit(3) ends the program with status 3 at that line. exception() hands it back instead: repr(future.exception()) is SystemExit(3).

Why does my program hang when one task waits for another task's result?

In a pool with one worker, a task that waits for another task's result holds the only worker, and the task it waits for can never start. A timeout in the main program raises TimeoutError, but the program still can't end, because leaving the with block waits for the stuck worker. Give the pool more workers than tasks that wait, or don't make tasks wait on each other.

Is a concurrent.futures Future the same as an asyncio Future?

No. asyncio.Future is concurrent.futures.Future is False, and their CancelledErrors differ too: concurrent.futures.CancelledError is an Exception, while asyncio's isn't. Inside async code, await asyncio.wrap_future(future) waits for a concurrent.futures Future.

Can async code hand blocking work to a pool?

Yes: inside a coroutine, await loop.run_in_executor(pool, add, 2, 3), where loop is asyncio.get_running_loop(), gives 5. asyncio.to_thread(), from Advanced Async & Await Patterns, is the shorter way to use a thread. This site's Run button ignores the pool and runs the function in its only thread.

How do I stop a task that's already running?

You can't from outside: cancel() returns False for a running task. The task has to stop itself, for example by checking a threading.Event that the main program sets. Threading & the GIL covers events.

Why are the lines my worker processes print jumbled?

Each worker process prints when it gets there, and two of them can write at the same moment. Four prints from two workers gave between 4 and 10 different outputs in 20 runs on each of Python 3.10–3.13, some with two lines run together. Return values from the tasks, and print them in the main program.

Related lessons