Python Reference ยท Standard Library: Concurrency, Network and Tools
The threading module
Reference for Python's threading module: Thread, Lock, RLock, Event, Semaphore, Condition, Timer, thread-local data, the GIL and when to use threads.
The threading module runs several flows of control inside one process. Each thread has its own call stack but shares memory with the others, so threads can work on the same data. That makes them a good fit for I/O-bound jobs: while one thread waits for a network reply, a disk read or a database, another one can run.
In the standard CPython build, the global interpreter lock (GIL) lets only one thread execute Python bytecode at a time, so threads do not speed up pure number-crunching. For CPU-bound work use multiprocessing or concurrent.futures.ProcessPoolExecutor. Python 3.13 added an optional free-threaded build without the GIL, but code should still protect shared data with locks.
import threading t = threading.Thread(target=print, args=("hello from a thread",)) t.start() t.join()
The in-browser runner cannot start real threads: Thread.start() raises RuntimeError: can't start new thread. The examples below run here (locks, events and other primitives work, they just have nothing to contend with); code that starts threads is shown read-only.
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.
The same program in a normal Python environment (read-only, do not expect it to run in the browser):
for w in workers: w.start() for w in workers: w.join() print(shared["total"]) # 4000, because every increment held the lock
What is in the module
| Name | Description |
|---|---|
Thread(target=None, args=(), kwargs=None, *, name=None, daemon=None) |
A thread of execution. start() begins it, join(timeout=None) waits for it, is_alive() checks it. |
Lock() |
Mutual exclusion. acquire(blocking=True, timeout=-1), release(), and with lock:. |
RLock() |
Re-entrant lock: the owning thread can acquire it several times. |
Event() |
A flag with set(), clear(), is_set() and wait(timeout=None). |
Condition(lock=None) |
Wait for a condition to become true with wait(), notify() and notify_all(). |
Semaphore(value=1), BoundedSemaphore |
Limit how many threads use a resource at once. |
Barrier(parties) |
Makes a group of threads wait until all of them arrive. |
Timer(interval, function) |
A thread that runs function after a delay; cancel() stops it. |
local() |
Object whose attributes are separate for each thread. |
current_thread(), main_thread(), enumerate(), active_count(), get_ident() |
Inspect running threads. |
excepthook, settrace, setprofile, stack_size() |
Hooks and tuning. |
Thread.start() raises RuntimeError if called twice or if the system cannot create a thread. Lock.release() raises RuntimeError if the lock is not held.
Usage notes
- Always
join()or make the thread a daemon. The interpreter waits for non-daemon threads at exit; daemon threads (daemon=True) are stopped abruptly and may leave work half-done. - Call
target, nottarget().Thread(target=work())runsworkimmediately in the current thread and passes its result. - A single-element tuple needs a comma:
args=(5,), notargs=(5). - The GIL does not make your code thread-safe.
counter += 1is several steps; two threads can interleave and lose updates. Protect compound operations with aLock. - Use
with lock:so the lock is released even when an error occurs. - Exceptions in a thread do not reach the caller. They are printed (via
threading.excepthook) and the thread ends. Catch errors in the target, or useconcurrent.futures, whose futures carry exceptions back. - Threads cannot be killed from outside. Stop them cooperatively: loop on an
Event(while not stop.is_set():) and set it. - Return values:
Threadignores the target's return value. Use aqueue.Queue, a shared structure with a lock, orThreadPoolExecutor. - Prefer
queue.Queueto share work. It is already thread-safe and removes most manual locking. - Deadlocks: if two threads take two locks in opposite orders they can wait forever. Always acquire locks in the same order, or use timeouts.
- Choosing tools: threads for blocking I/O,
asynciofor very many connections, processes for CPU-bound work.
Related
queue,concurrent.futures,multiprocessing,asyncio,contextlibwith,time- Lessons: Concurrency, Context managers