Threads: threading and ThreadPoolExecutor

A thread is a second line of execution inside the same program: it runs a function while the rest of the program carries on, and it sees the same objects. threading.Thread(target=f, args=(x,)) creates one, start() sets it running and join() waits until it has finished. For I/O-bound work such as downloads, a concurrent.futures.ThreadPoolExecutor is usually the better tool: it keeps a fixed set of threads, hands them your function calls and gives the results back in order. Because threads share memory, passing data between them costs nothing, and that is also their danger: two threads that change the same number without coordinating can lose an update. This lesson starts threads by hand, then runs a pool of them, then makes a lost update happen.

Starting a thread and waiting for it

Thread takes the function to run as target and its arguments as a tuple in args. A name is optional: without one, Python calls the thread “Thread-1 (download)”, a number and the function’s name, but a name of your own makes logs and debuggers far easier to read. Inside the thread, threading.current_thread().name tells the code which thread it runs in:

import threading
import time

finished = []  # list.append is safe to call from several threads


def download(page, seconds):
    time.sleep(seconds)  # stands in for waiting on the network
    finished.append(f"{page} (in {threading.current_thread().name})")


jobs = {"home": 0.3, "news": 0.1, "cart": 0.2}
threads = [
    threading.Thread(target=download, args=(page, seconds), name=f"get-{page}")
    for page, seconds in jobs.items()
]

start = time.perf_counter()
for thread in threads:
    thread.start()  # returns at once: the thread runs on its own
print(f"started {len(threads)} threads; alive now: {sum(t.is_alive() for t in threads)}")
for thread in threads:
    thread.join()  # waits until that thread has finished
took = time.perf_counter() - start

print("finished in this order:", ", ".join(finished))
print(f"all done after about {took:.1f} s, alive now: {sum(t.is_alive() for t in threads)}")

started 3 threads; alive now: 3
finished in this order: news (in get-news), cart (in get-cart), home (in get-home)
all done after about 0.3 s, alive now: 0

• start() returned at once: right after the loop all three threads were alive and sleeping.
• They finished in the order of their waits, 0.1, 0.2 and 0.3 seconds, not in the order they started, and the whole job took about as long as the slowest download.
• join() blocked until each thread had finished, so the final count of living threads is zero.

A thread created with daemon=True is stopped abruptly when the program exits, without running its clean-up, so give that flag only to work that may be cut off at any moment. An ordinary thread keeps the program alive: Python waits for every one of them to finish before it exits.

A pool of threads with ThreadPoolExecutor

Creating one thread per task stops scaling once there are thousands of tasks. A ThreadPoolExecutor starts at most max_workers threads and feeds them the calls one at a time:

import time
from concurrent.futures import ThreadPoolExecutor

PAGES = [f"/results/class-{n}" for n in range(1, 11)]  # ten pages to download


def download(path):
    time.sleep(0.2)  # each page takes 0.2 s to arrive
    return f"{path}: {len(path) * 120} bytes"


start = time.perf_counter()
one_by_one = [download(path) for path in PAGES]
sequential = time.perf_counter() - start

start = time.perf_counter()
with ThreadPoolExecutor(max_workers=5) as pool:
    pooled = list(pool.map(download, PAGES))  # results come back in the order of PAGES
threaded = time.perf_counter() - start

print(f"one after another: {sequential:.1f} s")
print(f"5 worker threads:  {threaded:.1f} s")
print(f"same results, same order: {one_by_one == pooled}")
print(pooled[0])

one after another: 2.0 s
5 worker threads:  0.4 s
same results, same order: True
/results/class-1: 1920 bytes

Ten waits of 0.2 seconds took 2 seconds in turn and about 0.4 seconds on five threads: two rounds of five downloads in parallel. pool.map() returned the results in the order of PAGES, so the list compares equal to the one built in turn. pool.submit(download, path) is the other way in: it returns a Future at once, a placeholder for a result that does not exist yet, and future.result() waits for that one call. The with block waits for every call before it shuts the pool down, so no thread is left running when the block ends. Leave out max_workers and the pool chooses a size meant for waiting work, which is a sensible start for downloads like these.

When threads share data: a lost update

balance = balance + amount looks like one step, but it is three: read the balance, add, write it back. Python’s documentation lists i = i+1 among the operations that are not atomic. If another thread runs between the read and the write, one of the two updates disappears. The scheduler does that only now and then, so this example uses a threading.Barrier to make it happen every time: each thread waits at the barrier, after its read, until the other thread has read too.

import threading


class Wallet:
    def __init__(self, balance):
        self.balance = balance


wallet = Wallet(0)
both_have_read = threading.Barrier(2)  # makes the unlucky timing happen every time


def deposit(amount):
    current = wallet.balance  # 1. read
    both_have_read.wait()  # wait until the other thread has read too
    wallet.balance = current + amount  # 2. add and 3. write


threads = [threading.Thread(target=deposit, args=(500,)) for _ in range(2)]
for thread in threads:
    thread.start()
for thread in threads:
    thread.join()

print("two deposits of 500 each")
print(f"expected balance: 1000, actual balance: {wallet.balance}")

two deposits of 500 each
expected balance: 1000, actual balance: 500

Both threads read 0, both computed 500, and the second write replaced the first. The program raised no error and gave no warning: the bug shows up only as a wrong number, and only when the timing is unlucky. Python’s glossary calls this a race condition: the result depends on the order in which the threads happen to run. There are three ways out. A lock makes the read, the add and the write one step that only one thread at a time may take. A queue lets one thread own the data while the others send it requests. And returning results instead of sharing them, as pool.map() does above, avoids shared state altogether. The next lesson builds the first two.

Check yourself

Lost updates counted, and a check-then-act race reproduced Pro: opens with a Pro, Premium or Ultimate pass

Errors, timeouts and pool sizes in real thread code Pro: opens with a Pro, Premium or Ultimate pass

Interview questions

Key takeaways

• Thread(target=f, args=(x,)).start() runs f(x) alongside the rest of the program; join() waits for it.
• A ThreadPoolExecutor reuses a fixed set of threads; map() returns results in input order, submit() returns a Future.
• Waiting work, such as downloads, overlaps on threads: ten waits of 0.2 s took about 0.4 s on five threads.
• x = x + 1 is a read, an add and a write; two threads can both read the old value, and one update is lost without any error.