From 08f150677e2d6134b019a84ba4a830873f32a064 Mon Sep 17 00:00:00 2001
From: Semyon Moroz <donbarbos@proton.me>
Date: Fri, 16 May 2025 12:17:29 +0000
Subject: [PATCH] gh-124210: Add introduction to `threading` docs (GH-127046)
(cherry picked from commit 62f66caa8c963bdf45d1e22456aea985e74fa2d5)
Co-authored-by: Semyon Moroz <donbarbos@proton.me>
Co-authored-by: Peter Bierma <zintensitydev@gmail.com>
---
Doc/library/threading.rst | 114 +++++++++++++++++++++++++++++---------
1 file changed, 89 insertions(+), 25 deletions(-)
diff --git a/Doc/library/threading.rst b/Doc/library/threading.rst
index 192e84302f92f3..7471f9bf507efd 100644
--- a/Doc/library/threading.rst
+++ b/Doc/library/threading.rst
@@ -11,6 +11,52 @@
This module constructs higher-level threading interfaces on top of the lower
level :mod:`_thread` module.
+.. include:: ../includes/wasm-notavail.rst
+
+Introduction
+------------
+
+The :mod:`!threading` module provides a way to run multiple `threads
+<https://en.wikipedia.org/wiki/Thread_(computing)>`_ (smaller
+units of a process) concurrently within a single process. It allows for the
+creation and management of threads, making it possible to execute tasks in
+parallel, sharing memory space. Threads are particularly useful when tasks are
+I/O bound, such as file operations or making network requests,
+where much of the time is spent waiting for external resources.
+
+A typical use case for :mod:`!threading` includes managing a pool of worker
+threads that can process multiple tasks concurrently. Here's a basic example of
+creating and starting threads using :class:`~threading.Thread`::
+
+ import threading
+ import time
+
+ def crawl(link, delay=3):
+ print(f"crawl started for {link}")
+ time.sleep(delay) # Blocking I/O (simulating a network request)
+ print(f"crawl ended for {link}")
+
+ links = [
+ "https://python.org",
+ "https://docs.python.org",
+ "https://peps.python.org",
+ ]
+
+ # Start threads for each link
+ threads = []
+ for link in links:
+ # Using `args` to pass positional arguments and `kwargs` for keyword arguments
+ t = threading.Thread(target=crawl, args=(link,), kwargs={"delay": 2})
+ threads.append(t)
+
+ # Start each thread
+ for t in threads:
+ t.start()
+
+ # Wait for all threads to finish
+ for t in threads:
+ t.join()
+
.. versionchanged:: 3.7
This module used to be optional, it is now always available.
@@ -45,7 +91,25 @@ level :mod:`_thread` module.
However, threading is still an appropriate model if you want to run
multiple I/O-bound tasks simultaneously.
-.. include:: ../includes/wasm-notavail.rst
+GIL and performance considerations
+----------------------------------
+
+Unlike the :mod:`multiprocessing` module, which uses separate processes to
+bypass the :term:`global interpreter lock` (GIL), the threading module operates
+within a single process, meaning that all threads share the same memory space.
+However, the GIL limits the performance gains of threading when it comes to
+CPU-bound tasks, as only one thread can execute Python bytecode at a time.
+Despite this, threads remain a useful tool for achieving concurrency in many
+scenarios.
+
+As of Python 3.13, experimental :term:`free-threaded <free threading>` builds
+can disable the GIL, enabling true parallel execution of threads, but this
+feature is not available by default (see :pep:`703`).
+
+.. TODO: At some point this feature will become available by default.
+
+Reference
+---------
This module defines the following functions:
@@ -62,7 +126,7 @@ This module defines the following functions:
Return the current :class:`Thread` object, corresponding to the caller's thread
of control. If the caller's thread of control was not created through the
- :mod:`threading` module, a dummy thread object with limited functionality is
+ :mod:`!threading` module, a dummy thread object with limited functionality is
returned.
The function ``currentThread`` is a deprecated alias for this function.
@@ -157,13 +221,13 @@ This module defines the following functions:
.. index:: single: trace function
- Set a trace function for all threads started from the :mod:`threading` module.
+ Set a trace function for all threads started from the :mod:`!threading` module.
The *func* will be passed to :func:`sys.settrace` for each thread, before its
:meth:`~Thread.run` method is called.
.. function:: settrace_all_threads(func)
- Set a trace function for all threads started from the :mod:`threading` module
+ Set a trace function for all threads started from the :mod:`!threading` module
and all Python threads that are currently executing.
The *func* will be passed to :func:`sys.settrace` for each thread, before its
@@ -186,13 +250,13 @@ This module defines the following functions:
.. index:: single: profile function
- Set a profile function for all threads started from the :mod:`threading` module.
+ Set a profile function for all threads started from the :mod:`!threading` module.
The *func* will be passed to :func:`sys.setprofile` for each thread, before its
:meth:`~Thread.run` method is called.
.. function:: setprofile_all_threads(func)
- Set a profile function for all threads started from the :mod:`threading` module
+ Set a profile function for all threads started from the :mod:`!threading` module
and all Python threads that are currently executing.
The *func* will be passed to :func:`sys.setprofile` for each thread, before its
@@ -257,8 +321,8 @@ when implemented, are mapped to module-level functions.
All of the methods described below are executed atomically.
-Thread-Local Data
------------------
+Thread-local data
+^^^^^^^^^^^^^^^^^
Thread-local data is data whose values are thread specific. If you
have data that you want to be local to a thread, create a
@@ -389,8 +453,8 @@ affects what we see::
.. _thread-objects:
-Thread Objects
---------------
+Thread objects
+^^^^^^^^^^^^^^
The :class:`Thread` class represents an activity that is run in a separate
thread of control. There are two ways to specify the activity: by passing a
@@ -608,8 +672,8 @@ since it is impossible to detect the termination of alien threads.
.. _lock-objects:
-Lock Objects
-------------
+Lock objects
+^^^^^^^^^^^^
A primitive lock is a synchronization primitive that is not owned by a
particular thread when locked. In Python, it is currently the lowest level
@@ -698,8 +762,8 @@ All methods are executed atomically.
.. _rlock-objects:
-RLock Objects
--------------
+RLock objects
+^^^^^^^^^^^^^
A reentrant lock is a synchronization primitive that may be acquired multiple
times by the same thread. Internally, it uses the concepts of "owning thread"
@@ -801,8 +865,8 @@ call release as many times the lock has been acquired can lead to deadlock.
.. _condition-objects:
-Condition Objects
------------------
+Condition objects
+^^^^^^^^^^^^^^^^^
A condition variable is always associated with some kind of lock; this can be
passed in or one will be created by default. Passing one in is useful when
@@ -973,8 +1037,8 @@ item to the buffer only needs to wake up one consumer thread.
.. _semaphore-objects:
-Semaphore Objects
------------------
+Semaphore objects
+^^^^^^^^^^^^^^^^^
This is one of the oldest synchronization primitives in the history of computer
science, invented by the early Dutch computer scientist Edsger W. Dijkstra (he
@@ -1054,7 +1118,7 @@ Semaphores also support the :ref:`context management protocol <with-locks>`.
.. _semaphore-examples:
-:class:`Semaphore` Example
+:class:`Semaphore` example
^^^^^^^^^^^^^^^^^^^^^^^^^^
Semaphores are often used to guard resources with limited capacity, for example,
@@ -1082,8 +1146,8 @@ causes the semaphore to be released more than it's acquired will go undetected.
.. _event-objects:
-Event Objects
--------------
+Event objects
+^^^^^^^^^^^^^
This is one of the simplest mechanisms for communication between threads: one
thread signals an event and other threads wait for it.
@@ -1139,8 +1203,8 @@ method. The :meth:`~Event.wait` method blocks until the flag is true.
.. _timer-objects:
-Timer Objects
--------------
+Timer objects
+^^^^^^^^^^^^^
This class represents an action that should be run only after a certain amount
of time has passed --- a timer. :class:`Timer` is a subclass of :class:`Thread`
@@ -1177,8 +1241,8 @@ For example::
only work if the timer is still in its waiting stage.
-Barrier Objects
----------------
+Barrier objects
+^^^^^^^^^^^^^^^
.. versionadded:: 3.2