gh-119241: Add HOWTO for free-threaded C API extensions #119877
Conversation
Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. Co-authored-by: Nathan Goldbaum <[email protected]>
colesbury
added
docs
|
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 <[email protected]>
|
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! |
|
Direct link to the preview: https://cpython-previews--119877.org.readthedocs.build/en/119877/howto/free-threading-extensions.html |
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 The upshot is that people building extensions on Windows will most likely have to manually define |
| 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. |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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 <[email protected]>
|
Thanks @colesbury for the PR 🌮🎉.. I'm working now to backport this PR to: 3.13. |
…GH-119877) Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. (cherry picked from commit 02b272b) Co-authored-by: Sam Gross <[email protected]> Co-authored-by: Nathan Goldbaum <[email protected]>
|
GH-120693 is a backport of this pull request to the 3.13 branch. |
…9877) (#120693) Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. (cherry picked from commit 02b272b) Co-authored-by: Sam Gross <[email protected]> Co-authored-by: Nathan Goldbaum <[email protected]>
…#119877) Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. Co-authored-by: Nathan Goldbaum <[email protected]>
…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: * Add a link to free-threading HOWTO to the index (GH-120703) (cherry picked from commit 45d5cab) Co-authored-by: Carol Willing <[email protected]> Co-authored-by: Ned Batchelder <[email protected]>
…#119877) Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. Co-authored-by: Nathan Goldbaum <[email protected]>
…#119877) Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. Co-authored-by: Nathan Goldbaum <[email protected]>
…#119877) Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum. Co-authored-by: Nathan Goldbaum <[email protected]>
Some sections adapted from https://github.com/Quansight-Labs/free-threaded-compatibility/ written by Nathan Goldbaum.
📚 Documentation preview 📚: https://cpython-previews--119877.org.readthedocs.build/
📚 HOWTO link 📚: https://cpython-previews--119877.org.readthedocs.build/en/119877/howto/free-threading-extensions.html