Declare free-threaded support for PyModule #4588

ngoldbaum · 2024-10-01T22:49:00Z

Adds a supports_free_threaded argument to the pymodule macro and a supports_free_threaded method to PyModule.

Updates the tests and examples to mark that they support free-threading.

Removes UNSAFE_PYO3_BUILD_FREE_THREADED=1 from the build config.

ngoldbaum · 2024-10-19T23:19:39Z

Just a note that this should probably only be merged once all the "RuntimeWarning: The global interpreter lock (GIL) has been enabled to load module foo" warnings in the python tests are fixed in the free-threaded build.

ngoldbaum · 2024-10-21T23:31:16Z

Just a note that this should probably only be merged once all the "RuntimeWarning: The global interpreter lock (GIL) has been enabled to load module foo" warnings in the python tests are fixed in the free-threaded build.

This is done now and I think all the tests are passing so I'm going to move this out of draft phase and update the PR description.

ngoldbaum · 2024-10-21T23:40:00Z

tests/ui/invalid_pymodule_args.stderr

@@ -1,4 +1,4 @@
-error: expected one of: `name`, `crate`, `module`, `submodule`
+error: expected one of: `name`, `crate`, `module`, `submodule`, `supports_free_threaded`


bikeshed opportunity: should I call this supports_free_threaded or something else? supports_free_threading is one more character but also feels less weird grammatically maybe?

I could also use GIL in the name since the relevant C API uses names like GIL_NOT_USED and GIL_USED.

supports_free_threading seems slightly better to me; I think in the long run it will be supports_free_threading = false to opt-out, and the default won't need the argument, so longer but clearer seems the obvious choice to me.

What about just #[pymodule(free_threaded)]?

I guess to me that implies that it's always free-threaded (which wouldn't be true on a GIL-enabled Python).

Maybe #[pymodule(requires_gil = false)] ?

How about pymodule(gil_used), since the names of the Py_mod_gil slots that indicates an extension supports free-threading are Py_MOD_GIL_NOT_USED and Py_MOD_GIL_USED. With gil_used users are maybe somewhat more likely to link this with upstream documentation that is probably also useful for determining what they're supposed to do.

I think using gil in the name is fine since this is a low-level concern directly related to whether or not code is making strong assumptions about the GIL.

In the latest version of this PR I renamed it to gil_used = false. In the long run that means users will do pymodule(gil_used) and otherwise not need to think about it.

ngoldbaum · 2024-10-21T23:40:33Z

This probably needs some discussion in the new guide section on free-threading support.

pyo3-macros-backend/src/module.rs

examples/sequential/src/module.rs

pyo3-ffi/build.rs

examples/decorator/src/lib.rs

ngoldbaum · 2024-10-23T16:43:29Z

woohoo! looks like tests are passing except for the codecov issue affecting all PRs right now.

src/macros.rs

src/types/module.rs

davidhewitt

Thanks, broadly looks great to me, a bunch of various thoughts :)

examples/decorator/src/lib.rs

examples/sequential/src/module.rs

davidhewitt · 2024-10-25T11:30:32Z

examples/string-sum/src/lib.rs

+    let module = PyModule_Create(ptr::addr_of_mut!(MODULE_DEF));
+    if module.is_null() {
+        return module;
+    }
+    #[cfg(Py_GIL_DISABLED)]
+    {
+        if PyUnstable_Module_SetGIL(module, Py_MOD_GIL_NOT_USED) < 0 {
+            return std::ptr::null_mut();
+        }
+    }
+    module


Would it be better to add the declaration to m_slots above, in this "raw ffi" case?

using PyModule_Create implies that we're using single-phase initialization, which means we can't set the slot directly:

PyModuleDef_Slot *m_slots
An array of slot definitions for multi-phase initialization, terminated by a {0, NULL} entry. When using single-phase initialization, m_slots must be NULL.

pyo3-ffi/build.rs

pyo3-ffi/src/moduleobject.rs

guide/src/free-threading.md

davidhewitt · 2024-10-25T11:48:22Z

src/types/module.rs

+
+    /// Declare whether or not this module supports running with the GIL disabled
+    ///
+    /// If the module does not rely on the GIL for thread safety, you can pass True
+    /// to this function to indicate the module does not rely on the GIL for
+    /// thread-safety.
+    ///
+    /// This function sets the [`Py_MOD_GIL`
+    /// slot](https://docs.python.org/3/c-api/module.html#c.Py_mod_gil) on the
+    /// module object. The default is `Py_MOD_GIL_USED`, so passing `false` to
+    /// this function is a no-op unless you have already set `Py_MOD_GIL` to
+    /// `Py_MOD_GIL_NOT_USED` elsewhere.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use pyo3::prelude::*;
+    ///
+    /// #[pymodule(supports_free_threaded = true)]
+    /// fn my_module(py: Python<'_>, module: &Bound<'_, PyModule>) -> PyResult<()> {
+    ///     let submodule = PyModule::new(py, "submodule")?;
+    ///     submodule.supports_free_threaded(true)?;
+    ///     module.add_submodule(&submodule)?;
+    ///     Ok(())
+    /// }
+    /// ```
+    ///
+    /// The resulting module will not print a `RuntimeWarning` and re-enable the
+    /// GIL when Python imports it on the free-threaded build, since all module
+    /// objects defined in the extension have `Py_MOD_GIL` set to
+    /// `Py_MOD_GIL_NOT_USED`.
+    ///
+    /// This is a no-op on the GIL-enabled build.
+    fn supports_free_threaded(&self, supports_free_threaded: bool) -> PyResult<()>;


I'm unsure about this one; I think long term I want to split functions what are to do with "module building" from the PyModuleMethods which I'd think should be for "normal" runtime operations on modules.

Was there a particular use case which needed this?

I need this to set the Py_mod_gil slot on submodules that get created without the proc macro.

davidhewitt · 2024-10-25T12:04:42Z

tests/ui/invalid_pymodule_args.stderr

@@ -1,4 +1,4 @@
-error: expected one of: `name`, `crate`, `module`, `submodule`
+error: expected one of: `name`, `crate`, `module`, `submodule`, `supports_free_threaded`


supports_free_threading seems slightly better to me; I think in the long run it will be supports_free_threading = false to opt-out, and the default won't need the argument, so longer but clearer seems the obvious choice to me.

examples/maturin-starter/src/lib.rs

ngoldbaum · 2024-10-31T15:01:07Z

It occurred to me while working on something else that this PR should remove the UNSAFE_PYO3_BUILD_FREE_THREADED uses in the CI scripts a well.

EDIT: done

ngoldbaum force-pushed the module-support branch from 6834f3f to 1bd1338 Compare October 21, 2024 18:50

ngoldbaum mentioned this pull request Oct 21, 2024

ci: run coverage for the free-threaded build #4638

Merged

ngoldbaum marked this pull request as ready for review October 21, 2024 23:31

ngoldbaum changed the title ~~WIP: declare free-threaded support in pymodule macro~~ Declare free-threaded support for PyModule Oct 21, 2024

ngoldbaum commented Oct 21, 2024

View reviewed changes

pyo3-macros-backend/src/module.rs Outdated Show resolved Hide resolved

ngoldbaum mentioned this pull request Oct 21, 2024

run nox -s clippy-all against free-threaded build in CI #4639

Closed

ngoldbaum force-pushed the module-support branch from 11f2a12 to 3021c46 Compare October 22, 2024 00:41

ngoldbaum commented Oct 22, 2024

View reviewed changes

examples/sequential/src/module.rs Outdated Show resolved Hide resolved

ngoldbaum commented Oct 22, 2024

View reviewed changes

pyo3-ffi/build.rs Outdated Show resolved Hide resolved

ngoldbaum commented Oct 22, 2024

View reviewed changes

examples/decorator/src/lib.rs Outdated Show resolved Hide resolved

ngoldbaum mentioned this pull request Oct 23, 2024

Add example Cargo.toml and build.rs for exposing pyo3 cfgs #4641

Merged

ngoldbaum force-pushed the module-support branch 2 times, most recently from 599a58e to 8f86b9e Compare October 23, 2024 21:57

ngoldbaum commented Oct 23, 2024

View reviewed changes

src/macros.rs Outdated Show resolved Hide resolved

src/types/module.rs Outdated Show resolved Hide resolved

davidhewitt reviewed Oct 25, 2024

View reviewed changes

davidhewitt mentioned this pull request Oct 25, 2024

release: 0.23.0 #4651

Draft

5 tasks

mejrs reviewed Oct 25, 2024

View reviewed changes

examples/maturin-starter/src/lib.rs Outdated Show resolved Hide resolved

davidhewitt mentioned this pull request Oct 25, 2024

Opting out of freethreading support #4652

Open

ngoldbaum mentioned this pull request Oct 28, 2024

Update docs for raw FFI use #4665

Merged

ngoldbaum force-pushed the module-support branch from 28d07c0 to 39ffe29 Compare October 28, 2024 19:50

ngoldbaum added 4 commits October 31, 2024 13:14

WIP: declare free-threaded support in pymodule macro

d1cf4cb

ignore ruff lint about unused import

70abf67

eliminate gil re-enabling in pytests

1ba9806

fix clippy nit

ecac640

ngoldbaum added 29 commits October 31, 2024 13:14

add a way to declare free-threaded support without macros

f837b14

fix ruff

f85e1a2

fix changed ui test answer

9ce99eb

fix build issues on old python versions

cb95dc2

fix runtime warnings in examples

81d467b

ensure that the GIL does not get re-enabled in the pytests

389f28b

add changelog entry

ce14ddb

fix ruff

f579247

fix compiler error on older pythons

26acf56

fix clippy

2cc9093

really fix clippy and expose supports_free_threaded on all builds

1e89108

fix clippy and msrv

a875918

fix examples on gil-disabled python

555421f

fix free-threaded clippy

4d1873c

fix unused import in example

160cee3

Add pyo3-build-config as a build dependency to examples that need it

e3aa6de

add docs

82516bb

add rust tests so coverage picks up the new code

0172bf2

fix some formatting issues

2fdc382

Apply cleanups

ac30f2e

fix cargo fmt --check

ab60aac

revert changes to non-FFI examples

2ef9e16

apply David's suggestion for the guide

19fca46

link to raw FFI examples in the guide

6586935

fix config guards in moduleobject.rs

b8b7a66

rename supports_free_threaded to gil_used

2807330

remove ensure_gil_enabled from pyo3-ffi/build.rs

a195ff0

update docs for PyModule::gil_used

b9f9417

remove UNSAFE_PYO3_BUILD_FREE_THREADED from the CI config

a6f59f3

ngoldbaum force-pushed the module-support branch from 356b2ac to a6f59f3 Compare October 31, 2024 19:16

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Declare free-threaded support for PyModule #4588

Declare free-threaded support for PyModule #4588

ngoldbaum commented Oct 1, 2024 •

edited

Loading

ngoldbaum commented Oct 19, 2024

ngoldbaum commented Oct 21, 2024

ngoldbaum Oct 21, 2024 •

edited

Loading

davidhewitt Oct 25, 2024

mejrs Oct 25, 2024

davidhewitt Oct 25, 2024

davidhewitt Oct 25, 2024

ngoldbaum Oct 25, 2024

ngoldbaum Oct 28, 2024

ngoldbaum commented Oct 21, 2024

ngoldbaum commented Oct 23, 2024

davidhewitt left a comment

davidhewitt Oct 25, 2024

ngoldbaum Oct 25, 2024

davidhewitt Oct 25, 2024

ngoldbaum Oct 25, 2024 •

edited

Loading

davidhewitt Oct 25, 2024

ngoldbaum commented Oct 31, 2024 •

edited

Loading

		@@ -1,4 +1,4 @@
		error: expected one of: `name`, `crate`, `module`, `submodule`
		error: expected one of: `name`, `crate`, `module`, `submodule`, `supports_free_threaded`

Declare free-threaded support for PyModule #4588

Are you sure you want to change the base?

Declare free-threaded support for PyModule #4588

Conversation

ngoldbaum commented Oct 1, 2024 • edited Loading

ngoldbaum commented Oct 19, 2024

ngoldbaum commented Oct 21, 2024

ngoldbaum Oct 21, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ngoldbaum commented Oct 21, 2024

ngoldbaum commented Oct 23, 2024

davidhewitt left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ngoldbaum Oct 25, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ngoldbaum commented Oct 31, 2024 • edited Loading

ngoldbaum commented Oct 1, 2024 •

edited

Loading

ngoldbaum Oct 21, 2024 •

edited

Loading

ngoldbaum Oct 25, 2024 •

edited

Loading

ngoldbaum commented Oct 31, 2024 •

edited

Loading