SyntaxPilot
Courses/Python/Lesson 31
Video coming soonThis lesson’s video is being made

Start with the notes below; the video appears here as soon as it is on YouTube.

Python · Lesson 31 of 40

Threads and multiprocessing

queued

These are the notes for Python episode 31. Raju's shop app downloads 30 bills every night, one after another, and the laptop spends almost all that time waiting for the server. In this episode you invent threads to overlap the waiting, discover a race condition that silently loses money, fix it with a Lock, use a thread pool, find out why threads don't speed up number crunching (the GIL), and invent processes for that case. Every program below ran for real in the SyntaxPilot compiler (Python 3.13.18, a 2-core machine). Timings depend on your computer, so yours will differ a little; the pattern is what matters.

The problem: a program that waits

import time

def download(bill):
    time.sleep(0.1)          # waiting for the server
    return f"bill{bill}.pdf"

start = time.perf_counter()
for b in range(1, 31):
    download(b)
print(f"30 bills in {time.perf_counter() - start:.1f} s")

Output:

30 bills in 3.0 s
  • time.sleep(0.1) pauses the program for a tenth of a second. Here it stands in for waiting on a network reply.
  • time.perf_counter() is a precise stopwatch: subtract two readings to get the elapsed seconds.

Why a faster laptop doesn't help: the processor isn't working, it's waiting. Work like this, where the time goes into waiting for a network, a disk or a user, is called I/O-bound (I/O = input/output). The fix is to start the next download while the previous one is still waiting.

Threads: start() and join()

Real-life picture: one cook boils milk and stands watching it. Hire helpers, each watching their own pot, and the waits overlap.

  • Every program starts with one line of work, the main thread.
  • A thread is another line of work inside the same program. All threads share the program's memory (its variables).
import threading, time

def download(bill):
    time.sleep(0.1)
    print("got bill", bill)

start = time.perf_counter()
workers = []
for b in range(1, 4):
    t = threading.Thread(target=download, args=(b,))
    t.start()
    workers.append(t)
print("all done?")

Output (the order of the bills can change on every run):

all done?
got bill 2
got bill 1
got bill 3
  • target= is the function the thread runs; args= is a tuple of its arguments. (b,) needs the comma: (b) is just b in brackets.
  • start() launches the thread and returns immediately, so the main thread printed all done? before any bill arrived.
  • Two threads can even print at the same moment, so their text collides on one line (in the video the output was got billgot bill 3 followed by 2). print writes the text and the newline separately, and another thread can slip in between: a first taste of the race condition below.

Add join(), which waits until a thread has finished:

for t in workers:
    t.join()
print(f"3 bills in {time.perf_counter() - start:.1f} s")

Output:

all done?
got bill 1
got bill 2
got bill 3
3 bills in 0.1 s

Three 0.1 s waits took 0.1 s in total: they overlapped.

The next problem: a race condition

Real-life picture: two cashiers share one register book showing ₹500. Both read ₹500 at the same moment. One writes ₹585 (a ₹85 sale), the other writes ₹540 (a ₹40 sale) over it. The book says ₹540 instead of ₹625: a sale vanished.

import threading, time

total = 0

def add_sale(amount):
    global total
    for _ in range(100):
        current = total
        time.sleep(0)          # the thread can pause right here
        total = current + amount

workers = [threading.Thread(target=add_sale, args=(1,)) for _ in range(4)]
for t in workers: t.start()
for t in workers: t.join()
print("Expected: 400")
print("Got:", total)

Output (different on every run):

Expected: 400
Got: 107
  • A race condition is a bug where the result depends on the timing of threads: who reads and writes first.
  • total = total + amount is really three steps: read, add, write. If another thread runs between the read and the write, one update overwrites the other (a lost update).
  • time.sleep(0) invites Python to switch threads at the worst moment, so the bug shows every time. In real programs it happens rarely, which makes it far harder to find.
  • global total lets the function change the module-level variable (episode 14).

The fix: a Lock

Real-life picture: one pen tied to the register. Only the cashier holding the pen may read and write; the other waits.

import threading, time

total = 0
lock = threading.Lock()

def add_sale(amount):
    global total
    for _ in range(100):
        with lock:
            current = total
            time.sleep(0)
            total = current + amount

workers = [threading.Thread(target=add_sale, args=(1,)) for _ in range(4)]
for t in workers: t.start()
for t in workers: t.join()
print("Expected: 400")
print("Got:", total)

Output (every run):

Expected: 400
Got: 400
  • A Lock (also called a mutex, mutual exclusion) can be held by only one thread at a time; others block (wait) until it is released.
  • with lock: acquires the lock at the start of the block and releases it at the end, even if an exception happens, just like with open(...) (episode 26).
  • The code inside is a critical section. Keep it as small as possible: while one thread is inside, the others wait.
  • Without with: lock.acquire() ... lock.release() (put the release in finally).

Thread pools: ThreadPoolExecutor

Making, starting and joining many threads by hand is repetitive. The concurrent.futures module gives you a ready-made team:

from concurrent.futures import ThreadPoolExecutor
import time

def download(bill):
    time.sleep(0.1)
    return f"bill{bill}.pdf"

start = time.perf_counter()
with ThreadPoolExecutor(max_workers=10) as pool:
    files = list(pool.map(download, range(1, 31)))
print(files[:3], "...", len(files), "files")
print(f"30 bills in {time.perf_counter() - start:.1f} s")

Output:

['bill1.pdf', 'bill2.pdf', 'bill3.pdf'] ... 30 files
30 bills in 0.3 s
  • A thread pool keeps a fixed number of worker threads (max_workers) and hands them jobs.
  • pool.map(func, items) works like map (episode 17): it calls func on every item, spread across the workers, and returns the results in input order.
  • Leaving the with block waits for every job (no manual join).
  • pool.submit(func, arg) starts one job and returns a Future (a placeholder for a result that isn't ready yet); future.result() waits for it.

30 jobs on 10 workers = 3 rounds of 0.1 s = 0.3 s, ten times faster than one by one.

The next problem: the GIL

from concurrent.futures import ThreadPoolExecutor
import time

def gst_check(n):          # pure number crunching
    return sum(i * i % 7 for i in range(n))

jobs = [3_000_000] * 4

start = time.perf_counter()
for n in jobs: gst_check(n)
print(f"one by one: {time.perf_counter() - start:.1f} s")

start = time.perf_counter()
with ThreadPoolExecutor(max_workers=4) as pool:
    list(pool.map(gst_check, jobs))
print(f"4 threads:  {time.perf_counter() - start:.1f} s")

Output:

one by one: 0.7 s
4 threads:  0.7 s

Four threads were no faster. Work that keeps the processor busy calculating is called CPU-bound.

Real-life picture: many cooks, one knife. Standard Python (CPython) has the GIL, the Global Interpreter Lock: only one thread can run Python code at any moment.

Needs the knife? Threads help?
Watching pots (I/O-bound: network, files, sleep) No: a waiting thread releases the GIL Yes
Chopping onions (CPU-bound: maths, loops) Yes: all threads queue for it No

(Python 3.13 also ships an optional experimental "free-threaded" build without the GIL; the normal build, used everywhere by default, has it.)

Processes: ProcessPoolExecutor

Real-life picture: open a second kitchen with its own cooks and its own knife.

  • A process is a separate running program with its own memory and its own Python interpreter, so its own GIL. Different processes can run on different CPU cores truly at the same time.
  • A CPU core is one independent calculating unit of the processor; os.cpu_count() tells you how many you have.
from concurrent.futures import ProcessPoolExecutor
import os

def gst_check(n):
    total = sum(i * i % 7 for i in range(n))
    return os.getpid(), total

if __name__ == "__main__":
    print("main process:", os.getpid(), "| CPU cores:", os.cpu_count())
    with ProcessPoolExecutor(max_workers=2) as pool:
        for pid, total in pool.map(gst_check, [3_000_000] * 4):
            print("worker", pid, "->", total)

Output (the ID numbers differ on every run):

main process: 1522 | CPU cores: 2
worker 1523 -> 5999999
worker 1524 -> 5999999
worker 1523 -> 5999999
worker 1524 -> 5999999
  • os.getpid() returns the process ID (PID), the number the operating system gives every running program. Two different worker PIDs = two separate processes doing the work.
  • ProcessPoolExecutor() with no max_workers uses one worker per core.
  • if __name__ == "__main__": is required (episode 30): on Windows and macOS (and on Linux from Python 3.14) each worker imports your file again. Without the guard, every worker would try to start its own pool. Python then stops with RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase.
  • Passing data to a process costs time: arguments and results are pickled (packed into bytes) and sent between processes. Use processes for big jobs, not millions of tiny ones.

Same machine, threads vs processes for bigger jobs ([12_000_000] * 4, shown in the video; the process version has all its code under the __main__ guard):

$ python3 gst_threads.py
one by one: 2.5 s
4 threads:  2.8 s
$ python3 gst_processes.py
one by one:  2.3 s
4 processes: 1.6 s

Threads are no faster (even a little slower: they take turns with the GIL). With two cores, processes are clearly faster, though not quite 2×, because starting processes and pickling data costs time. With eight cores, all four jobs could run at once.

Two more process mistakes

A lambda can't be sent to a process:

from concurrent.futures import ProcessPoolExecutor

if __name__ == "__main__":
    with ProcessPoolExecutor() as pool:
        print(list(pool.map(lambda x: x * 2, [1, 2, 3])))

Output (last line):

_pickle.PicklingError: Can't pickle <function <lambda> at 0x7f4a57937ec0>: attribute lookup <lambda> on __main__ failed

Functions are pickled by name and found again in the worker. A lambda has no name to look up. Use a normal def at the top level of the file.

Processes don't share variables:

from multiprocessing import Process

sales = []

def record(amount):
    sales.append(amount)
    print("in the worker:", sales)

if __name__ == "__main__":
    p = Process(target=record, args=(85,))
    p.start()
    p.join()
    print("in main:", sales)

Output:

in the worker: [85]
in main: []

The worker changed its own copy of sales. Return results from functions instead (as pool.map does), or use multiprocessing.Queue / Manager for shared data.

Common mistakes

Mistake What you see Why Fix
t.start() without join() all done? printed before the work finished start() doesn't wait t.join() for every thread
args=(b) TypeError: __main__.download() argument after * must be an iterable, not int (b) isn't a tuple args=(b,)
total = total + amount in many threads Expected: 400 Got: 107 race condition with lock:
threads for calculations 4 threads: 0.7 s (no faster) the GIL ProcessPoolExecutor
a lambda in a process pool PicklingError: Can't pickle <function <lambda> ...> lambdas can't be pickled by name a top-level def
no __main__ guard (Windows/macOS) RuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase. workers re-import the file if __name__ == "__main__":
sales.append() inside a Process in main: [] separate memory return the result

Which one when

The program is mostly... Use Why
waiting (network, files, APIs) threads: ThreadPoolExecutor waiting threads release the GIL
calculating (maths, images, data) processes: ProcessPoolExecutor each process has its own GIL and core
waiting for thousands of things async/await (next episode) far lighter than thousands of threads

Whenever several threads change the same data, protect it with a Lock.

Mini project: Raju's nightly job in parallel

Download 30 bills on 10 threads (with a lock-protected counter), then check them on a process pool.

from concurrent.futures import ThreadPoolExecutor, ProcessPoolExecutor
import threading, time

checked = 0
lock = threading.Lock()

def download(bill):
    global checked
    time.sleep(0.1)                     # waiting for the supplier's server
    with lock:
        checked += 1
    return f"bill{bill}.pdf"

def gst_check(name):
    total = sum(i * i % 7 for i in range(1_000_000))   # heavy calculation
    return name, total % 2 == 0

if __name__ == "__main__":
    start = time.perf_counter()
    with ThreadPoolExecutor(max_workers=10) as pool:
        files = list(pool.map(download, range(1, 31)))
    print(f"downloaded {checked} bills in {time.perf_counter() - start:.1f} s")

    start = time.perf_counter()
    with ProcessPoolExecutor() as pool:
        results = list(pool.map(gst_check, files))
    ok = sum(1 for _, good in results if good)
    print(f"checked {len(results)} bills ({ok} ok) in {time.perf_counter() - start:.1f} s")

Output (2 cores):

downloaded 30 bills in 0.3 s
checked 30 bills (30 ok) in 1.2 s

Practice

1. Time 30 downloads with 1, 5 and 30 workers.

Solution
from concurrent.futures import ThreadPoolExecutor
import time

def download(bill):
    time.sleep(0.1)
    return bill

for workers in [1, 5, 30]:
    start = time.perf_counter()
    with ThreadPoolExecutor(max_workers=workers) as pool:
        list(pool.map(download, range(30)))
    print(f"{workers:>2} workers: {time.perf_counter() - start:.1f} s")

Output:

 1 workers: 3.0 s
 5 workers: 0.6 s
30 workers: 0.1 s

Time ≈ (jobs ÷ workers, rounded up) × 0.1 s.

2. Break the shared counter, then fix it with a Lock.

Solution

Run the race-condition program above (you'll get a number well below 400), then wrap the read and the write in with lock: as in the Lock section. The result is 400 on every run.

3. Count the primes below 200,000 with a process pool, one chunk per core.

Solution
from concurrent.futures import ProcessPoolExecutor
import os

def count_primes(lo, hi):
    count = 0
    for n in range(max(lo, 2), hi):
        if all(n % d for d in range(2, int(n ** 0.5) + 1)):
            count += 1
    return count

if __name__ == "__main__":
    N, parts = 200_000, os.cpu_count()
    step = N // parts
    ranges = [(i * step, N if i == parts - 1 else (i + 1) * step) for i in range(parts)]
    with ProcessPoolExecutor() as pool:
        print("primes below", N, ":", sum(pool.map(count_primes, *zip(*ranges))))

Output:

primes below 200000 : 17984

pool.map with two iterables passes one item from each: zip(*ranges) turns [(0, 100000), (100000, 200000)] into (0, 100000) and (100000, 200000), the lo values and the hi values.

4. Print os.cpu_count() on your laptop. How many workers will ProcessPoolExecutor() use?

Solution

import os; print(os.cpu_count()). With no max_workers, the pool uses that many workers (on Windows at most 61).

Quick quiz

Resize 500 photos on an 8-core laptop; each resize is pure calculation. Which is fastest? A. a for loop B. ThreadPoolExecutor C. ProcessPoolExecutor D. a Lock

Answer

C. Resizing is CPU-bound, so threads queue for the GIL. Processes use all 8 cores.

Interview questions

  1. Thread vs process? Threads share one process's memory and are cheap to start; processes have separate memory and their own interpreter, cost more to start and communicate by pickling.
  2. What is the GIL? CPython's Global Interpreter Lock: only one thread executes Python bytecode at a time. It makes threads useless for CPU-bound speed-ups but fine for I/O-bound work, because blocking I/O releases it.
  3. What is a race condition? How do you prevent one? A bug whose result depends on thread timing, e.g. a lost update in read-modify-write. Prevent it with a Lock around the critical section, or avoid shared state (queues, returning results).
  4. What does join() do? Blocks the caller until the thread (or process) has finished.
  5. Why is if __name__ == "__main__": needed with multiprocessing? With the spawn/forkserver start methods each worker imports the main module; without the guard the pool-creating code would run again in every worker.
  6. I/O-bound vs CPU-bound? I/O-bound time is spent waiting for input/output; CPU-bound time is spent calculating. Threads/async for the first, processes for the second.
  7. What is a deadlock? Two threads each holding a lock the other needs, so both wait forever. Avoid it by always taking locks in the same order and holding them briefly.

Glossary

Term Meaning
concurrency several jobs in progress at the same time (they may take turns)
parallelism several jobs literally running at the same instant, on different cores
thread a line of work inside a program; threads share its memory
main thread the thread every program starts with
threading.Thread(target=, args=) makes a thread that will run target(*args)
start() launches a thread; returns immediately
join() waits until a thread has finished
I/O-bound slow because of waiting for input/output (network, disk)
CPU-bound slow because of calculation
race condition a bug where the result depends on the timing of threads
lost update one thread's write overwriting another's
global lets a function assign to a module-level variable
Lock (mutex) an object only one thread can hold at a time
acquire / release take / give back a lock
critical section code only one thread may run at a time
deadlock threads waiting for each other's locks forever
thread pool a fixed team of reusable worker threads
ThreadPoolExecutor the standard thread pool in concurrent.futures
pool.map runs a function on every item using the pool; results in input order
Future a placeholder for a result that isn't ready yet (submit() returns one)
GIL Global Interpreter Lock: one thread runs Python code at a time
process a separate running program with its own memory and interpreter
CPU core one independent calculating unit of a processor
os.cpu_count() the number of cores
PID process ID, the operating system's number for a running program
ProcessPoolExecutor a pool of worker processes in concurrent.futures
pickling turning a Python object into bytes so it can be sent or saved
multiprocessing.Process starts one function in a new process

Summary

  • A program that mostly waits can overlap its waits with threads: Thread(target=..., args=(...,)), start(), join().
  • Threads share memory, so read-modify-write on shared data causes race conditions; protect it with with lock:.
  • ThreadPoolExecutor + pool.map is the easy way to run many waiting jobs.
  • The GIL lets only one thread run Python code at a time, so threads don't speed up calculations.
  • Processes (ProcessPoolExecutor, under if __name__ == "__main__":) use every core, but don't share variables and need picklable functions.
  • Rule: waiting → threads; calculating → processes.
  • Next episode: checking 10,000 delivery partners at once, where even threads get heavy. You'll invent async and await.