gh-119241: Add HOWTO for free-threaded C API extensions by colesbury · Pull Request #119877 · python/cpython (original) (raw)
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.Learn more about bidirectional Unicode characters
[ Show hidden characters]({{ revealButtonHref }})
There is more I'd like to add to the HOWTO, such as information on critical sections or other synchronization primitives if/when those APIs become public, but I think that even in the current form will be useful.
cc @ngoldbaum
Co-authored-by: Jelle Zijlstra jelle.zijlstra@gmail.com
Question that came to mind when reading was whether there is a way to compile a single binary extension that is usable on both free threaded and GIL protected builds (if the latter are still looking for an official name, I offer that as a suggestion).
Also (if that is possible) how to check at runtime whether the GIL is enabled or not.
The content that is there looks good, though!
...whether there is a way to compile a single binary extension that is usable on both free threaded and GIL protected builds
No, that's not currently possible. That's something we hope to address in 3.14 with support for the limited API and stable ABI.
I don't know if this is the right place to document it but it might be:
If you use the Windows installer then you end up with one copy of pyconfig.h that doesn't have Py_GIL_DISABLED set. What that means is that running something like python313t setup.py build_ext --inplace will generate an extension that's named as if it's a free-threading extension (e.g. something.cp313t-win_amd64.pyd) but actually isn't. This will crash on import.
The upshot is that people building extensions on Windows will most likely have to manually define Py_GIL_DISABLED themselves.
| Most of the C API is thread-safe, but there are some exceptions. |
|---|
| * **Struct Fields**: Accessing struct fields directly is not thread-safe if |
| the field may be concurrently modified. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe clarify that you're talking about C structs provided by the CPython C API.
| `setuptools https://setuptools.pypa.io/en/latest/setuptools.html`_ to build |
|---|
| your extension and currently set ``py_limited_api=True`` you can use |
| ``py_limited_api=not sysconfig.get_config_var("Py_GIL_DISABLED")`` to opt out |
| of the limited API when building with the free-threaded build. |
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe worth adding a note that this implies that they'll need to set up wheel builds specifically for the free-threaded build if they want to ship free-threaded binaries and otherwise rely on the limited API to only produce a single wheel per platform.
I've updated the docs with the above feedback and moved some things into a "Building Extensions for the Free-Threaded Build" section.
Looks good to me (but I doubt it's my review that you're waiting on)
Co-authored-by: Itamar Oren itamarost@gmail.com
Thanks @colesbury for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖
miss-islington pushed a commit to miss-islington/cpython that referenced this pull request
colesbury added a commit that referenced this pull request
Note that the HOWTO index was just reorganized (GH-119366); this HOWTO is currently missing from the rendered table of contents. Fix is in GH-120703.
picnixz pushed a commit to picnixz/cpython that referenced this pull request
encukou pushed a commit that referenced this pull request
…3 logical sections (GH-119366, GH-120703) (GH-120646)
Update the documentation howto index page and group docs into 3 logical sections (GH-119366)
(cherry picked from commit a26d27e)
Includes a follow-up fix to properly merge GH-119877:
Co-authored-by: Carol Willing carolcode@willingconsulting.com Co-authored-by: Ned Batchelder ned@nedbatchelder.com
mrahtz pushed a commit to mrahtz/cpython that referenced this pull request
noahbkim pushed a commit to hudson-trading/cpython that referenced this pull request
estyxx pushed a commit to estyxx/cpython that referenced this pull request