https://github.com/python/cpython/commit/0784a2b986437897b026e538486f0338dab2fa20
commit: 0784a2b986437897b026e538486f0338dab2fa20
branch: 3.15
author: Inada Naoki <[email protected]>
committer: methane <[email protected]>
date: 2026-11-09T04:01:10Z
summary:
Doc: Update threading FAQ and use local tables of contents (GH-161554)
(cherry picked from commit 0aec939d7d1e9728a0d4a55f280d08771f598388)
files:
M Doc/faq/design.rst
M Doc/faq/extending.rst
M Doc/faq/general.rst
M Doc/faq/gui.rst
M Doc/faq/library.rst
M Doc/faq/programming.rst
M Doc/faq/windows.rst
M Doc/tools/removed-ids.txt
diff --git a/Doc/faq/design.rst b/Doc/faq/design.rst
index 02a3a3a22070dae..3a3e16b3bcf3db4 100644
--- a/Doc/faq/design.rst
+++ b/Doc/faq/design.rst
@@ -5,6 +5,7 @@ Design and History FAQ
.. only:: html
.. contents::
+ :local:
Why does Python use indentation for grouping of statements?
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst
index 1d5abed2317b0ce..e0e6ddd04af76df 100644
--- a/Doc/faq/extending.rst
+++ b/Doc/faq/extending.rst
@@ -5,6 +5,7 @@ Extending/Embedding FAQ
.. only:: html
.. contents::
+ :local:
.. highlight:: c
diff --git a/Doc/faq/general.rst b/Doc/faq/general.rst
index ff38ba395fba22c..ba4fb89713c66d2 100644
--- a/Doc/faq/general.rst
+++ b/Doc/faq/general.rst
@@ -7,6 +7,7 @@ General Python FAQ
.. only:: html
.. contents::
+ :local:
General Information
diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst
index cfa60feceb31b77..37e77ee08fc8ec9 100644
--- a/Doc/faq/gui.rst
+++ b/Doc/faq/gui.rst
@@ -7,6 +7,7 @@ Graphic User Interface FAQ
.. only:: html
.. contents::
+ :local:
.. XXX need review for Python 3.
diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst
index d8d75ca6f2ec96c..abfd35ea8846418 100644
--- a/Doc/faq/library.rst
+++ b/Doc/faq/library.rst
@@ -7,6 +7,7 @@ Library and Extension FAQ
.. only:: html
.. contents::
+ :local:
General Library Questions
=========================
@@ -241,51 +242,6 @@ The :mod:`threading` module builds convenient abstractions
on top of the
low-level primitives provided by the :mod:`_thread` module.
-None of my threads seem to run: why?
-------------------------------------
-
-As soon as the main thread exits, all threads are killed. Your main thread is
-running too quickly, giving the threads no time to do any work.
-
-A simple fix is to add a sleep to the end of the program that's long enough for
-all the threads to finish::
-
- import threading, time
-
- def thread_task(name, n):
- for i in range(n):
- print(name, i)
-
- for i in range(10):
- T = threading.Thread(target=thread_task, args=(str(i), i))
- T.start()
-
- time.sleep(10) # <---------------------------!
-
-But now (on many platforms) the threads don't run in parallel, but appear to
run
-sequentially, one at a time! The reason is that the OS thread scheduler
doesn't
-start a new thread until the previous thread is blocked.
-
-A simple fix is to add a tiny sleep to the start of the run function::
-
- def thread_task(name, n):
- time.sleep(0.001) # <--------------------!
- for i in range(n):
- print(name, i)
-
- for i in range(10):
- T = threading.Thread(target=thread_task, args=(str(i), i))
- T.start()
-
- time.sleep(10)
-
-Instead of trying to guess a good delay value for :func:`time.sleep`,
-it's better to use some kind of semaphore mechanism. One idea is to use the
-:mod:`queue` module to create a queue object, let each thread append a token to
-the queue when it finishes, and let the main thread read as many tokens from
the
-queue as there are threads.
-
-
How do I parcel out work among a bunch of worker threads?
---------------------------------------------------------
@@ -410,35 +366,17 @@ deployment on high-end multiprocessor server machines,
because a multi-threaded
Python program effectively only uses one CPU, due to the insistence that
(almost) all Python code can only run while the GIL is held.
-With the approval of :pep:`703` work is now underway to remove the GIL from the
-CPython implementation of Python. Initially it will be implemented as an
-optional compiler flag when building the interpreter, and so separate
-builds will be available with and without the GIL. Long-term, the hope is
-to settle on a single build, once the performance implications of removing the
-GIL are fully understood. Python 3.13 is likely to be the first release
-containing this work, although it may not be completely functional in this
-release.
-
-The current work to remove the GIL is based on a
-`fork of Python 3.9 with the GIL removed <https://github.com/colesbury/nogil>`_
-by Sam Gross.
-Prior to that,
-in the days of Python 1.5, Greg Stein actually implemented a comprehensive
-patch set (the "free threading" patches) that removed the GIL and replaced it
-with fine-grained locking. Adam Olsen did a similar experiment
-in his `python-safethread
<https://code.google.com/archive/p/python-safethread>`_
-project. Unfortunately, both of these earlier experiments exhibited a sharp
-drop in single-thread
-performance (at least 30% slower), due to the amount of fine-grained locking
-necessary to compensate for the removal of the GIL. The Python 3.9 fork
-is the first attempt at removing the GIL with an acceptable performance
-impact.
+Since Python 3.13, CPython provides an optional free-threaded build that can
run
+with the GIL disabled, allowing Python threads to run in parallel on multiple
+CPU cores (see :pep:`703`). Free-threaded Python is officially supported as of
+Python 3.14 (see :pep:`779`), but is not the default build. See
+:doc:`/howto/free-threading-python` for details.
The presence of the GIL in current Python releases
doesn't mean that you can't make good use of Python on multi-CPU machines!
You just have to be creative with dividing the work up between multiple
*processes* rather than multiple *threads*. The
-:class:`~concurrent.futures.ProcessPoolExecutor` class in the new
+:class:`~concurrent.futures.ProcessPoolExecutor` class in the
:mod:`concurrent.futures` module provides an easy way of doing so; the
:mod:`multiprocessing` module provides a lower-level API in case you want
more control over dispatching of tasks.
@@ -452,7 +390,9 @@ already do this.
An alternative approach to reducing the impact of the GIL is
to make the GIL a per-interpreter-state lock rather than truly global.
This was :ref:`first implemented in Python 3.12 <whatsnew312-pep684>` and is
-available in the C API. A Python interface to it is expected in Python 3.13.
+available in the C API. Python interfaces were added in Python 3.14 through the
+:mod:`concurrent.interpreters` module and the
+:class:`~concurrent.futures.InterpreterPoolExecutor` class.
The main limitation to it at the moment is likely to be 3rd party extension
modules, since these must be written with multiple interpreters in mind in
order to be usable, so many older extension modules will not be usable.
diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst
index 4e1157e6ebe7296..5eb8dff1ee8052b 100644
--- a/Doc/faq/programming.rst
+++ b/Doc/faq/programming.rst
@@ -7,6 +7,7 @@ Programming FAQ
.. only:: html
.. contents::
+ :local:
General questions
=================
diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst
index c0c92fdbbc84d12..7f6170f8ade99e9 100644
--- a/Doc/faq/windows.rst
+++ b/Doc/faq/windows.rst
@@ -11,6 +11,7 @@ Python on Windows FAQ
.. only:: html
.. contents::
+ :local:
.. XXX need review for Python 3.
XXX need review for Windows Vista/Seven?
diff --git a/Doc/tools/removed-ids.txt b/Doc/tools/removed-ids.txt
index 16d91e16832fd6f..795de0e3e2324c7 100644
--- a/Doc/tools/removed-ids.txt
+++ b/Doc/tools/removed-ids.txt
@@ -4,6 +4,8 @@
c-api/allocation.html: deprecated-aliases
c-api/file.html: deprecated-api
+# Removed sections
+faq/library.html: none-of-my-threads-seem-to-run-why
library/asyncio-task.html: terminating-a-task-group
tutorial/modules.html: packages-in-multiple-directories
_______________________________________________
Python-checkins mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: [email protected]
