gh-124370: Add "howto" for free-threaded Python #124371
Conversation
This is a guide aimed at people writing Python code, as oppposed to the existing guide for C API extension authors.
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
| * :ref:`function <user-defined-funcs>` objects declared at the module level | ||
| * :ref:`method <instance-methods>` descriptors | ||
| * :ref:`code <code-objects>` objects | ||
| * :term:`module` objects and their dictionaries | ||
| * :ref:`classes <classes>` (type objects) |
There was a problem hiding this comment.
It's probably worth noting somewhere in here that these objects (and immortalization itself) are implementation details, and very much subject to change.
Doc/howto/free-threading-python.rst
Outdated
| mechanism for decisions related to the build configuration. | ||
|
|
||
|
|
||
| Thread Safety |
There was a problem hiding this comment.
I feel like this section is probably among the most important for most users. As I understand it, the general rule is that you write thread-safe code under free-threading the same way that you'd write thread-safe code under previous versions of Python; the rules have not really changed. That could be made more explicit.
There was a problem hiding this comment.
I think that's our goal for the implementation, but I'm a bit hesitant to promise too much here, especially because it's not always clear what was thread-safe under the GIL.
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
There was a problem hiding this comment.
High level comments:
- Overall, great! I'm not reading it with an eye for what has been left out. But its a doc, I consider those "living" and future updates would deal with that.
- Perhaps include the word "experimental" in the top level title to help temper expectations?
- Consider adding a reference to PEP 703 to the doc for context for those interested in how this came to be and what the initial long term plan and expectations are.
- In the final Single-threaded performance section, I predict someone not aware of larger long term plans and PEP 703 and the earlier proof of concept work you built on top of a couple releases to freak out at the thought of a 40% slower interpreter. I'd go beyond the "This overhead is expected to be reduced in the Python 3.14." statement and indicate what level of free-threaded build performance delta we're ultimately aiming for in the future (without promising which version it happens in).
|
LGTM. +1 for @gpshead's comment about including some detail about what single-threaded performance delta we're ultimately shooting for. |
| --------- | ||
|
|
||
| Sharing the same iterator object between multiple threads is generally not | ||
| safe and threads may see duplicate or missing elements when iterating or crash |
There was a problem hiding this comment.
Is the possible crashing of the interpreter expected to be addressed in 3.14?
As a consequence of iterators not being thread safe, some modules are not safe either (e g. json, itertools). Should this be mentioned somewhere?
Doc/howto/free-threading-python.rst
Outdated
| ********************************* | ||
|
|
||
| Starting with the 3.13 release, CPython has experimental support for running | ||
| with the :term:`global interpreter lock` (GIL) disabled in a configuration |
There was a problem hiding this comment.
"configuration" makes me think of a configuration file I might need to create. Can we say "build of Python"? Or at least "build configuration".
Doc/howto/free-threading-python.rst
Outdated
| with the :term:`global interpreter lock` (GIL) disabled in a configuration | ||
| called :term:`free threading`. This document describes the implications of | ||
| free threading for Python code. See :ref:`freethreading-extensions-howto` for | ||
| information on how to write C extensions that support the free-threaded build. |
There was a problem hiding this comment.
We seem to switch between "free threading" and "free-threaded" kind of randomly. I can't decide if this is OK or if we should choose one and stick with it.
There was a problem hiding this comment.
I think it's fine. We also say both "multithreaded" and "multithreading" depending on the context.
Doc/howto/free-threading-python.rst
Outdated
|
|
||
| The free-threaded build of CPython can optionally run with the global | ||
| interpreter lock enabled, such as when :envvar:`PYTHON_GIL` is set to ``1``, | ||
| or when importing an extension module that requires the GIL. |
There was a problem hiding this comment.
This could use more explanation. When might I want to set this environment variable? "an extension module that requires the GIL": is this something I have to figure out, or does Python know this itself somehow?
There was a problem hiding this comment.
I don't want to get into the details of the environment variable here. The important point here is that the free-threaded build can run with the GIL enabled -- that's not obvious to most people. The environment variable is mentioned here just as an example of that.
Doc/howto/free-threading-python.rst
Outdated
| The free-threaded build of the 3.13 release makes some objects :term:`immortal` | ||
| in order to avoid reference count contention that would prevent efficient | ||
| multi-threaded scaling. This means that these objects are never deallocated. | ||
| This is expected to be addressed in Python 3.14 with |
There was a problem hiding this comment.
"addressed" how? That makes it sound like immortal objects are a problem. Are they?
Doc/howto/free-threading-python.rst
Outdated
| * :ref:`classes <classes>` (type objects) | ||
|
|
||
| The immortalization of these objects happens the first time a thread is started | ||
| after the main thread. |
There was a problem hiding this comment.
After reading about immortalization, I don't understand the implications for me as a Python programmer. Why do I care that they are now immortal? These all sound like things that would have never been deallocated anyway. Are there unusual circumstances that I should be considering?
There was a problem hiding this comment.
Hopefully most people won't care, but some programs create these sorts of things in a loop.
| Frame objects | ||
| ------------- | ||
|
|
||
| It is not safe to access :ref:`frame <frame-objects>` objects from other |
There was a problem hiding this comment.
Can you elaborate on how it is not safe? What might happen?
There was a problem hiding this comment.
Your program may crash. I'll add it to the guide.
|
|
||
| The free-threaded build has additional overhead when executing Python code | ||
| compared to the default GIL-enabled build. In 3.13, this overhead is about | ||
| 40% on the `pyperformance <https://pyperformance.readthedocs.io/>`_ suite. |
There was a problem hiding this comment.
This is surprising: the lore around removing the GIL has always been that it was easy, the hard part was doing it without affecting single-threaded performance. This seems like a significant hit. I understand it's a work in progress, and performance will be improved, but maybe we could elaborate on that a bit here.
| called :term:`free threading`. This document describes the implications of | ||
| free threading for Python code. See :ref:`freethreading-extensions-howto` for | ||
| information on how to write C extensions that support the free-threaded build. | ||
|
|
There was a problem hiding this comment.
I wonder if we could add a quick snapshot of the overall plan: if everything works out, eventually free threading will be the only build, etc. Also, maybe a statement about how most programmer won't need to be concerned with this, we're doing a lot to keep everyday Python programs behaving the same, etc.
There was a problem hiding this comment.
I would perhaps add a note in the seealso block that refers to the PEP and adds 1 or 2 highlights:
- performance conscious users may wish to try the free threaded version
- most users can safely continue to use the default CPython version
- when free threading is no longer experimental, the versions will converge into one version for all.
Doc/howto/free-threading-python.rst
Outdated
|
|
||
| The :func:`sys._is_gil_enabled` function will return ``False`` if the global | ||
| interpreter lock is currently disabled. This is the recommended mechanism for | ||
| decisions like whether to use multithreading or multiprocessing. |
There was a problem hiding this comment.
Is it likely that people will write code that examines this variable and chooses between multithreading and multiprocessing? It seems unlikely to me, but maybe library authors will? When should it be used?
There was a problem hiding this comment.
"How do I distinguish between the free-threaded and GIL-enabled build?" is a fairly common question, although I don't think people make much use of it other than for quick debugging and sanity checks.
There was a problem hiding this comment.
I would break this section into two sections:
- Identifying free threading builds (with the last paragraph)
- Reenabling the GIL with a free threading build (first two paragraphs)
|
When you're done making the requested changes, leave the comment: |
Co-authored-by: mpage <mpage@cs.stanford.edu>
There was a problem hiding this comment.
Looking good @colesbury. I made some wording suggestions that should add clarity for Ned and others.
| called :term:`free threading`. This document describes the implications of | ||
| free threading for Python code. See :ref:`freethreading-extensions-howto` for | ||
| information on how to write C extensions that support the free-threaded build. | ||
|
|
There was a problem hiding this comment.
I would perhaps add a note in the seealso block that refers to the PEP and adds 1 or 2 highlights:
- performance conscious users may wish to try the free threaded version
- most users can safely continue to use the default CPython version
- when free threading is no longer experimental, the versions will converge into one version for all.
| Installation | ||
| ============ | ||
|
|
||
| Starting with Python 3.13, the official macOS and Windows installers |
There was a problem hiding this comment.
We don't provide Linux installers.
There was a problem hiding this comment.
Right, but we could mention here that people building their own CPython such as on Linux need to useconfigure --disable-gil to create such an installation.
There was a problem hiding this comment.
Mostly I want to direct people to https://py-free-threading.github.io/installing_cpython/. That's going to be a lot more comprehensive. There are a lot of ways people install Python!
I can make that part of the body of the text instead of a "see also" section
Doc/howto/free-threading-python.rst
Outdated
|
|
||
| The :func:`sys._is_gil_enabled` function will return ``False`` if the global | ||
| interpreter lock is currently disabled. This is the recommended mechanism for | ||
| decisions like whether to use multithreading or multiprocessing. |
There was a problem hiding this comment.
I would break this section into two sections:
- Identifying free threading builds (with the last paragraph)
- Reenabling the GIL with a free threading build (first two paragraphs)
Doc/howto/free-threading-python.rst
Outdated
| --------------- | ||
|
|
||
| The free-threaded build of the 3.13 release makes some objects :term:`immortal` | ||
| in order to avoid reference count contention that would prevent efficient |
There was a problem hiding this comment.
| in order to avoid reference count contention that would prevent efficient | |
| which have reference counts that are never modified. Since the immortal object is guaranteed not to be | |
| deallocated, efficient multi-threading scaling is possible by avoiding reference count contention between | |
| threads. |
There was a problem hiding this comment.
I've reworked this a bit. Would you please take another look at it? As you wrote, immortalization means reference counts are not modified and objects are not guaranteed not to be deallocated. I wanted to get across that:
- Reference counts not being modified enables efficient multi-threaded scaling.
- Objects not being deallocated is a potential problem because some applications may leak memory. That's being addressed in 3.14. We don't expect this to be a problem for most applications, but it's something to watch out for if you run your application with refleak checks.
Doc/howto/free-threading-python.rst
Outdated
| less of an impact. This overhead is expected to be reduced in Python | ||
| 3.14. We are aiming for an overhead of 10% or less on the pyperformance |
There was a problem hiding this comment.
| less of an impact. This overhead is expected to be reduced in Python | |
| 3.14. We are aiming for an overhead of 10% or less on the pyperformance | |
| less of an impact. This overhead is expected to be reduced in Python | |
| 3.14 by implementing more efficient reference counting and garbage collection. We are aiming for an overhead of 10% or less on the pyperformance |
There was a problem hiding this comment.
We expect that the biggest source of improvement will be reenabling the specializing adaptive interpreter in 3.14. It's currently disabled in the 3.13 free-threaded build. Is that worth mentioning here?
I don't expect any big performance impact for reference counting and garbage collection changes in 3.14
Co-authored-by: Carol Willing <carolcode@willingconsulting.com>
There was a problem hiding this comment.
Love the updates @colesbury. This how to is a nice addition 😄
This is a guide aimed at people writing Python code, as oppposed to the existing guide for C API extension authors.
📚 Documentation preview 📚: https://cpython-previews--124371.org.readthedocs.build/en/124371/howto/free-threading-python.html