Skip to content

Commit

Permalink
Free-threaded build config fixes (#4719)
Browse files Browse the repository at this point in the history
* update build config logic and library name generation

* fix free-threaded windows clippy with --features=abi3

* use constant

* add release note

* apply my self-review comments

* use ensure and error handling instead of panicking

* skip abi3 fixup on free-threaded build

* don't support PYO3_USE_ABI3_FORWARD_COMPATIBILITY on free-threaded build

* don't panic in pyo3-ffi in abi3 check

* document lack of limited API support

* add is_free_threaded() method to InterpreterConfig

* implement David's code review suggestions

* remove unused imports
  • Loading branch information
ngoldbaum authored and davidhewitt committed Nov 25, 2024
1 parent 02eb2a1 commit 07093e9
Show file tree
Hide file tree
Showing 4 changed files with 245 additions and 79 deletions.
28 changes: 27 additions & 1 deletion guide/src/free-threading.md
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,15 @@ using single-phase initialization and the
[`sequential`](https://github.com/PyO3/pyo3/tree/main/pyo3-ffi/examples/sequential)
example for modules using multi-phase initialization.

If you would like to use conditional compilation to trigger different code paths
under the free-threaded build, you can use the `Py_GIL_DISABLED` attribute once
you have configured your crate to generate the necessary build configuration
data. See [the guide
section](./building-and-distribution/multiple-python-versions.md) for more
details about supporting multiple different Python versions, including the
free-threaded build.


## Special considerations for the free-threaded build

The free-threaded interpreter does not have a GIL, and this can make interacting
Expand Down Expand Up @@ -234,7 +243,24 @@ needed. For now you should explicitly add locking, possibly using conditional
compilation or using the critical section API to avoid creating deadlocks with
the GIL.

## Thread-safe single initialization
### Cannot build extensions using the limited API

The free-threaded build uses a completely new ABI and there is not yet an
equivalent to the limited API for the free-threaded ABI. That means if your
crate depends on PyO3 using the `abi3` feature or an an `abi3-pyxx` feature,
PyO3 will print a warning and ignore that setting when building extensions using
the free-threaded interpreter.

This means that if your package makes use of the ABI forward compatibility
provided by the limited API to uploads only one wheel for each release of your
package, you will need to update and tooling or instructions to also upload a
version-specific free-threaded wheel.

See [the guide section](./building-and-distribution/multiple-python-versions.md)
for more details about supporting multiple different Python versions, including
the free-threaded build.

### Thread-safe single initialization

Until version 0.23, PyO3 provided only [`GILOnceCell`] to enable deadlock-free
single initialization of data in contexts that might execute arbitrary Python
Expand Down
2 changes: 2 additions & 0 deletions newsfragments/4719.fixed.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
* Fixed an issue that prevented building free-threaded extensions for crates
that request a specific minimum limited API version.
Loading

0 comments on commit 07093e9

Please sign in to comment.