Threading & the GIL
Published by Brayan K
A thread is a separate flow of execution inside one program, letting your code do several things at once — and Python's threading module lets you start, coordinate, and join those threads.
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.
Start work once, then join its lifetime explicitly
A Thread object describes a function call that can run in another thread. start launches that work; join waits for it to finish. A function’s return value is not returned by join. Arrange an explicit result or error channel, then read it after the worker has completed.
from threading import Thread
result = {}
def calculate(values):
result["total"] = sum(values)
worker = Thread(target=calculate, args=([2, 3, 5],))
worker.start()
joined = worker.join()
print(result["total"])
print(joined is None)
print(worker.is_alive())
# ✅ Expected output:
# 10
# True
# FalseOnly the worker writes this result, and the main thread reads it after join. Printing from the main thread also avoids making the displayed order depend on worker scheduling. Pass the callable as target rather than calling it while constructing the thread. Model selection and that call-versus-callable mistake are covered in Concurrency in Python: Threads vs Processes.
from threading import Thread
worker = Thread(target=lambda: None)
worker.join()
# ✅ Expected error:
# RuntimeError: cannot join thread before it is startedfrom threading import Thread
worker = Thread(target=lambda: None)
worker.start()
worker.join()
worker.start()
# ✅ Expected error:
# RuntimeError: threads can only be started onceCreate a new Thread for another execution. Calling worker.run directly is a normal function call in the current thread; it does not create another execution thread. Keep that distinction in mind when a demonstration seems to work in an environment that cannot start threads. These actual worker examples require local Python.
Protect the complete shared invariant, not just the final assignment
On conventional CPython builds, the GIL limits execution of Python bytecode to one thread at a time. It is not a transaction around your application’s read/check/update sequence. Optional free-threaded CPython builds, available from Python 3.13, change the execution model further. Correct synchronization should not depend on a convenient scheduling result from one build.
from threading import Lock, Thread
state = {"total": 0}
lock = Lock()
def add_many(amount):
for _ in range(100):
with lock:
state["total"] = state["total"] + amount
workers = [Thread(target=add_many, args=(amount,)) for amount in (1, 2)]
for worker in workers:
worker.start()
for worker in workers:
worker.join()
print(state["total"])
# ✅ Expected output:
# 300Both workers use the same lock around the whole update. A lock used by only one writer does not establish the intended agreement. Keep unrelated slow work outside the critical section so the lock protects a small, clearly named invariant. Do not hold it while waiting for another thread that needs the same lock to finish.
Threads can overlap waiting for I/O, and some native extensions release the GIL while computing. Pure-Python CPU work on a conventional GIL-enabled build does not automatically gain multicore execution from Thread. Parallelism with concurrent.futures owns executor use; performance claims require measuring the real workload, not printing a fixed speedup.
A regular lock does not allow the same thread to acquire it twice
from threading import Lock, RLock
regular = Lock()
with regular:
print(regular.acquire(blocking=False))
reentrant = RLock()
with reentrant:
acquired = reentrant.acquire(blocking=False)
print(acquired)
if acquired:
reentrant.release()
# ✅ Expected output:
# False
# TrueBlocking a second acquisition of the regular lock here would deadlock this thread. RLock tracks its owning thread and acquisition depth, allowing nested code on that thread to acquire it again. Every successful acquisition still needs a matching release. A with block handles its own acquisition; the explicit successful acquire above needs its own release.
from threading import Lock
Lock().release()
# ✅ Expected error:
# RuntimeError: release unlocked lockUse a regular Lock when nested acquisition is unnecessary. Choosing RLock does not solve an inconsistent lock order between different threads. If two locks are needed, establish one acquisition order throughout the program or redesign the operation around one owner.
Use an Event for a persistent signal and a Condition for a predicate
from threading import Event, Thread
ready = Event()
result = []
def receive_signal():
ready.wait()
result.append("released")
ready.set()
worker = Thread(target=receive_signal)
worker.start()
worker.join()
print(result)
print(ready.is_set())
# ✅ Expected output:
# ['released']
# TrueAn Event stores a flag. set wakes waiters and leaves the flag set until clear, so a later waiter can proceed too. It does not carry a stream of separate jobs; repeated set calls do not create a count of messages. Thread-Safe Queues (queue) owns handing off distinct work items.
from threading import Condition, Thread
condition = Condition()
state = {"ready": False, "value": None}
result = []
def consume():
with condition:
condition.wait_for(lambda: state["ready"])
result.append(state["value"])
worker = Thread(target=consume)
worker.start()
with condition:
state["value"] = "approved"
state["ready"] = True
condition.notify_all()
worker.join()
print(result)
# ✅ Expected output:
# ['approved']The producer changes the state and notifies while holding the condition’s lock. wait_for checks the predicate and waits as needed; waiting releases the lock and reacquires it before continuing. If the producer finishes before the consumer begins waiting, the true predicate still lets the consumer proceed. A notification alone would not store that fact.
Cancellation and worker failure need a communication policy
from threading import Thread
result = {}
def work():
try:
int("many")
except ValueError as error:
result["error"] = type(error).__name__
worker = Thread(target=work)
worker.start()
worker.join()
print(result["error"])
# ✅ Expected output:
# ValueErrorAn uncaught exception in a plain thread does not become an exception raised by join in the main thread. This worker deliberately records its expected conversion failure. Futures offer automatic error retrieval through result, covered in the executor lesson. Do not let a missing result silently look like success.
Python provides no general safe operation that forcibly stops an arbitrary running thread. Use a cooperative stop signal and make the worker check it at sensible boundaries. A worker blocked indefinitely on an unrelated operation will not notice the signal until that operation returns; use a suitable timeout or wake-up mechanism for that operation.
Daemon threads do not provide reliable cleanup: the interpreter can stop them abruptly when only daemon threads remain. For work that must finish or release resources, request shutdown explicitly and join non-daemon workers. A timeout passed to join limits how long the caller waits; it does not cancel the worker. Check is_alive afterward if that distinction matters.
Complete a signal-and-join handoff
The worker waits for permission before recording a result. Fill the signal type, the operation that grants permission and the operation that waits for worker completion.
from threading import Event, Thread
ready = ___()
result = []
def work():
ready.wait()
result.append("done")
worker = Thread(target=work)
worker.start()
ready.___()
worker.___()
print(result)
# 👉 replace ___ with Event
# 👉 replace ___ with set
# 👉 replace ___ with join
# ✅ Expected output:
# ['done']Cancel before a controlled work boundary
Create a worker that first signals entered, then waits on proceed. After proceed is set, it checks a stop Event: if requested, record cancelled; otherwise record completed. In the main thread, start the worker, wait until it reaches the boundary, request stop, release proceed and join. Print the single status and whether the worker is still alive. Do not use sleep or assume that starting a thread means it has already reached a particular line.
from threading import Event, Thread
entered = Event()
proceed = Event()
stop = Event()
result = {}
def work():
entered.set()
proceed.wait()
if stop.is_set():
result["status"] = "cancelled"
return
result["status"] = "completed"
worker = Thread(target=work)
worker.start()
entered.wait()
stop.set()
proceed.set()
worker.join()
print(result["status"])
print(worker.is_alive())
# ✅ Expected output:
# cancelled
# FalseThe handshake makes the exercise deterministic. A real long-running task needs cancellation checks at boundaries appropriate to its work; this example does not imply that Event can interrupt any blocking operation.
Practice quiz
What does this program print? from threading import Thread result = [] t = Thread(target=lambda: result.append(3)) t.start() print(t.join() is None) print(result)
- True [3]
- False [3]
- True []
- 3 [3]
Answer: True [3]. join waits but does not return the target function’s result.
What must a lock cover to protect a read/check/update invariant?
- Only the final print
- Only the first reader
- The entire related operation, with every participant using the same lock
- Any unrelated line before the update
Answer: The entire related operation, with every participant using the same lock. The protected operation must stay indivisible relative to cooperating participants.
What does this program print? from threading import Lock lock = Lock() with lock: print(lock.acquire(blocking=False))
- True
- None
- RuntimeError
- False
Answer: False. A regular lock is not reentrant, even for its current thread.
What does Event.set preserve for a waiter that starts later?
- One queued job per call
- A set flag until clear is called
- The setter’s return value
- The thread’s local variables
Answer: A set flag until clear is called. An Event is a persistent flag, not a message counter.
Why use Condition.wait_for with a predicate?
- To avoid acquiring any lock
- To check the actual shared state before and after waiting
- To store notifications forever
- To start a new process
Answer: To check the actual shared state before and after waiting. Correctness depends on state under the condition’s lock, not notification timing alone.
What does this program print? from threading import Thread, current_thread, main_thread result = [] t = Thread(target=lambda: result.append(current_thread() is main_thread())) t.run() print(result)
- [False]
- []
- RuntimeError
- [True]
Answer: [True]. run called directly executes in the calling thread.
Which error ends this program? from threading import Thread Thread(target=lambda: None).join()
- RuntimeError: cannot join thread before it is started
- None
- False
- ValueError: thread has no result
Answer: RuntimeError: cannot join thread before it is started. A thread must be started before it can be joined.
What does join(timeout=...) do when the timeout expires first?
- Terminates the worker
- Converts it to a daemon
- Returns control without cancelling the worker
- Raises the worker’s exception automatically
Answer: Returns control without cancelling the worker. The caller must inspect is_alive if it needs to distinguish timeout from completion.
Continue this course
- Previous: Checkpoint: OOP & Standard Library
- Next: multiprocessing: True Parallelism — Use multiple processes to bypass the GIL for CPU-bound work
- Quick reference: Python cheat sheet