Grokking Concurrency in Python
Vote

0% completed

​

Thread Lifecycle

Creating and Starting a Thread

Names and Join Timeouts

When a Thread Raises an Exception

Daemon Threads and Exit

In Production

Key Takeaways

Practice Questions

Thread Lifecycle
Thread Lifecycle

Harvest crawled eight pages with eight threads and printed crawl finished: 7 of 8 pages, missing [5]. The process ended with exit status 0, so the job scheduler recorded a success. Above that line, the log held a 30-line traceback that started with Exception in thread fetch-5:.

The thread that fetched page 5 had failed, and nothing in the code that started it noticed. That is how a thread ends when the starting code makes no plan for its result, its errors, and its last piece of work.

Creating and Starting a Thread

Concurrency and Parallelism in Python used a pool that created threads for Harvest. This lesson uses the threading.Thread class directly, because a pool hides the steps that matter here. A Thread object describes a function to run in a new thread, and it does nothing until you call its start() method.

pages = {} def fetch_into(n): pages[n] = fetch(n) # ... t = threading.Thread(target=fetch_into, args=(0,)) t.start() t.join()

Calling start() asks the operating system for a new thread, which then calls the target function, and the call returns at once. Calling join() blocks the calling thread until the other thread has finished, that is, until its target returns or raises an exception.

The demos ran with Python 3.15.2 on a Linux virtual machine with 2 virtual CPUs (one physical core). They use a copy of the Harvest test site with 40 pages of 20,000 words each, a delay of 250 milliseconds per request, and a missing page 5 that returns an HTTP 404 error.

Output:

$ python3.15 lifecycle.py this code runs in: MainThread created: name='Thread-1 (fetch_into)', alive=False, ident=None started: alive=True, threads in the process=2 joined: alive=False, page 0 has 20004 words start again: RuntimeError: threads can only be started once

Every program starts with one thread, named MainThread. Before start(), the new thread does not exist: is_alive() returns False, and its ident, the number that identifies a running thread, is None. The last line shows that a Thread object can run only once, so running the work again needs a new object.

A thread from start to exit
A thread from start to exit

Names and Join Timeouts

Python named the first thread Thread-1 (fetch_into): a counter and the target's name. The name appears in tracebacks, in log lines, and in thread dumps, so Harvest passes a name that says what the thread does:

workers = [threading.Thread(target=fetch_into, args=(n,), name=f"fetch-{n}") for n in range(1, 4)] # ... workers[0].join(timeout=0.1)

join() also takes a timeout in seconds, which limits how long the caller waits:

Output:

named: fetch-1, fetch-2, fetch-3 join(timeout=0.1) returned after 0.10 s, alive=True all joined after 0.25 s, pages fetched: [0, 1, 2, 3]

The request takes 250 milliseconds, so the thread was still running when the join returned. join() returns None whether the thread finished or the time ran out. After join(timeout=...), only is_alive() tells you whether the thread actually finished. A shutdown with a time limit uses this check to log the names of workers that are still alive.

When a Thread Raises an Exception

In the crawl at the top of this page, the request for page 5 raised HTTPError, and nothing inside fetch_into caught it. The output began like this:

Output:

Exception in thread fetch-5: Traceback (most recent call last): File "<python>/lib/python3.15/threading.py", line 1219, in _bootstrap_inner self._context.run(self.run) ~~~~~~~~~~~~~~~~~^^^^^^^^^^

Twenty-four more lines followed, and then:

Output:

urllib.error.HTTPError: HTTP Error 404: Not Found crawl finished: 7 of 8 pages, missing [5] exit status: 0

An exception ends only the thread that raised it. The other seven threads finished, join() returned normally for all eight, and the exception never reached the main thread. threading.excepthook is the function Python calls with an uncaught exception from a thread, and by default it prints the traceback to standard error.

You can replace the hook. Harvest's version records which threads failed:

def record_failure(args): failed.append(args.thread.name) print(f"{args.thread.name} failed: {args.exc_type.__name__}: {args.exc_value}") # ... threading.excepthook = record_failure # ... if failed: sys.exit(f"failed threads: {failed}")

The hook runs in the thread that failed and receives one argument with the fields exc_type, exc_value, exc_traceback, and thread:

Output:

$ python3.15 failures.py --hook fetch-5 failed: HTTPError: HTTP Error 404: Not Found crawl finished: 7 of 8 pages, missing [5] failed threads: ['fetch-5'] exit status: 1

A hook is a safety measure for unexpected errors. For expected errors, such as a missing page, catch the exception inside the target function and store it with the results. A ThreadPoolExecutor does this for you: it keeps each call's exception and raises it again in the thread that reads that call's result.

Daemon Threads and Exit

At the end of the program, Python waits for every thread that is still running, unless that thread is a daemon. A daemon thread is a thread that Python stops without warning when the program exits, instead of waiting for it to finish. You choose this with daemon=True when you create the thread.

The demo starts a thread that spends one second saving Harvest's index:

def save_index(): try: time.sleep(1.0) # stands in for writing the index to disk print("index saved") finally: print("save_index cleanup ran")

An atexit handler, a function that Python runs as the program exits, prints when the exit began:

Output:

$ python3.15 daemon.py main thread done, saver.daemon=False index saved save_index cleanup ran atexit handlers run after 1.00 s $ python3.15 daemon.py --daemon main thread done, saver.daemon=True atexit handlers run after 0.00 s

The ordinary thread delayed the exit by one second and ran its cleanup. The daemon thread was stopped partway: the index was never saved, and its finally block never ran. Daemon threads suit work that can be lost, such as printing progress. Work that writes data must run in an ordinary thread that the program joins before it exits.

In Production

What you seeWhat it meansHow to check
A batch job reports success but some results are missingA worker raised an exception that only the default hook sawSearch standard error for Exception in thread; install a hook that logs and counts failures
A service takes a long time to stop, or never stopsPython is waiting at exit for a non-daemon threadPrint threading.enumerate() during shutdown; name every thread so the list is readable
Files are cut short after a restartThe work ran in a daemon thread that was stopped at exitUse an ordinary thread and join it before the program ends
Code reads a result that is not there yetA join(timeout=...) ran out and nobody checked is_alive()Look for joins with a timeout and no is_alive() check

Key Takeaways

  • A Thread runs nothing until start(), and each Thread object can be started only once.
  • After join(timeout=...), only is_alive() says whether the thread finished.
  • An uncaught exception ends only its own thread, never reaches join(), and by default is only printed.
  • Python waits for ordinary threads at exit and stops daemon threads without running their finally blocks.
  • Name every thread after its job, so tracebacks and thread lists say which work failed.

Every thread in these demos wrote to its own key in pages, so no two threads touched the same data. Harvest's crawler threads share a set of visited pages and a word counter. The next lesson, Race Conditions in Python Code, shows what goes wrong when they do.

Practice Questions

Try each question first, then open the answer.

1. A teammate calls worker.join(timeout=5) and then reads the worker's result. On slow days the result is missing. What is wrong?

<details> <summary>Show answer</summary>

join() returns None whether or not the thread finished, so the code reads the result even after a timeout. The code must call worker.is_alive() after the join and handle the case where it returns True.

</details>

2. One of eight fetch threads raises HTTPError, and the program still exits with status 0. Why?

<details> <summary>Show answer</summary>

An uncaught exception ends only the thread that raised it. The default threading.excepthook prints the traceback, join() returns normally, and the main thread continues to the end.

</details>

3. A service writes its cache to disk in a thread created with daemon=True. After restarts, the file is sometimes incomplete. Why, and what is the fix?

<details> <summary>Show answer</summary>

Python stops daemon threads at exit without running their finally blocks, so a write can stop partway. Make the writer an ordinary thread and join it before the program ends.

</details>

4. During a slow shutdown, threading.enumerate() shows Thread-7 (run) and Thread-12 (run) still alive. Why is this hard to act on, and what would help?

<details> <summary>Show answer</summary>

The default names give only a counter and the target's name, not the job. Names such as fetch-12 or index-writer show at once which job is delaying the shutdown.

</details>

Reading Progress

0%


Vote for new content

On This Page

Creating and Starting a Thread

Names and Join Timeouts

When a Thread Raises an Exception

Daemon Threads and Exit

In Production

Key Takeaways

Practice Questions