Expose unsafe wrappers for Py_BEGIN_CRITICAL_SECTION_MUTEX API (#5642)

* WIP: attempt to add with_critical_section_mutex

* WIP: use an UnsafeCell

* finish UnsafeCell rewrite

* finish and tweak docs

* fix limited API builds

* fix deadlocks and abi3 compilation errors

* remove unnecessary comparisons with true

* add two more tests

* add changelog entry

* add missing conditional compilation for new tests

* add missing conditional compilation for new tests

* fix conditional compilation in pyo3::sync

* fix Python 3.13 clippy

* Update newsfragments/5642.added.md

* refactor so to use EnteredCriticalSection struct

* tweak docstrings

* Add SAFETY comments in tests

* fix include guards

* remove unnecessary returns

* fix whitespace formatting

* Move note about minimum Python version

* Fix reference leak by adjusting lifetimes

* Apply suggestions for test tweaks from code review

* refactor into a new module and rewrite docs

* adjust imports to satisfy clippy

* Fix EnteredCriticalSection conditinal compilation

* fix wasm clippy

* add changelog for the moved functions

* actually deprecate the old export

* refer to locking mutexes and acquiring critical sections consistently

* remove unnecessary availability note

* simplify wasm conditional compilation

Author: ngoldbaum

newsfragments/5642.added.md

@@ -0,0 +1 @@
+added FFI definitions and an unsafe Rust API wrapping `Py_BEGIN_CRITICAL_SECTION_MUTEX` and `Py_BEGIN_CRITICAL_SECTION_MUTEX2`.

newsfragments/5642.changed.md

@@ -0,0 +1 @@
+The `with_critical_section` and `with_critical_section2` functions are now available in `pyo3::sync::critical_section`. Aliases that generate deprecation warnings are available in `pyo3::sync`.

pyo3-ffi/src/cpython/critical_section.rs

@@ -1,4 +1,4 @@
-#[cfg(Py_GIL_DISABLED)]
+#[cfg(any(Py_3_14, Py_GIL_DISABLED))]
 use crate::PyMutex;
 use crate::PyObject;
 
@@ -24,7 +24,15 @@ opaque_struct!(pub PyCriticalSection2);
 
 extern "C" {
     pub fn PyCriticalSection_Begin(c: *mut PyCriticalSection, op: *mut PyObject);
+    #[cfg(Py_3_14)]
+    pub fn PyCriticalSection_BeginMutex(c: *mut PyCriticalSection, m: *mut PyMutex);
     pub fn PyCriticalSection_End(c: *mut PyCriticalSection);
     pub fn PyCriticalSection2_Begin(c: *mut PyCriticalSection2, a: *mut PyObject, b: *mut PyObject);
+    #[cfg(Py_3_14)]
+    pub fn PyCriticalSection2_BeginMutex(
+        c: *mut PyCriticalSection2,
+        m1: *mut PyMutex,
+        m2: *mut PyMutex,
+    );
     pub fn PyCriticalSection2_End(c: *mut PyCriticalSection2);
 }

src/conversions/std/num.rs

@@ -342,10 +342,12 @@ impl BytesSequenceExtractor<'_, '_> {
 
         match self {
             BytesSequenceExtractor::Bytes(b) => copy_slice(b.as_bytes()),
-            BytesSequenceExtractor::ByteArray(b) => crate::sync::with_critical_section(b, || {
-                // Safety: b is protected by a critical section
-                copy_slice(unsafe { b.as_bytes() })
-            }),
+            BytesSequenceExtractor::ByteArray(b) => {
+                crate::sync::critical_section::with_critical_section(b, || {
+                    // Safety: b is protected by a critical section
+                    copy_slice(unsafe { b.as_bytes() })
+                })
+            }
         }
     }
 }