Add PyMutex wrappers

newsfragments/4523.added.md

@@ -0,0 +1 @@
+* Added a Rust wrapper for `PyMutex`, available on Python 3.13 and newer.

pyo3-ffi/src/cpython/lock.rs

@@ -8,6 +8,15 @@ pub struct PyMutex {
     pub(crate) _pin: PhantomPinned,
 }
 
+impl PyMutex {
+    pub const fn new() -> PyMutex {
+        PyMutex {
+            _bits: AtomicU8::new(0),
+            _pin: PhantomPinned,
+        }
+    }
+}
+
 extern "C" {
     pub fn PyMutex_Lock(m: *mut PyMutex);
     pub fn PyMutex_Unlock(m: *mut PyMutex);

pyo3-ffi/src/object.rs

@@ -1,13 +1,11 @@
 use crate::pyport::{Py_hash_t, Py_ssize_t};
 #[cfg(Py_GIL_DISABLED)]
 use crate::PyMutex;
-#[cfg(Py_GIL_DISABLED)]
-use std::marker::PhantomPinned;
 use std::mem;
 use std::os::raw::{c_char, c_int, c_uint, c_ulong, c_void};
 use std::ptr;
 #[cfg(Py_GIL_DISABLED)]
-use std::sync::atomic::{AtomicIsize, AtomicU32, AtomicU8, Ordering::Relaxed};
+use std::sync::atomic::{AtomicIsize, AtomicU32, Ordering::Relaxed};
 
 #[cfg(Py_LIMITED_API)]
 opaque_struct!(PyTypeObject);
@@ -39,10 +37,7 @@ pub const PyObject_HEAD_INIT: PyObject = PyObject {
     #[cfg(Py_GIL_DISABLED)]
     _padding: 0,
     #[cfg(Py_GIL_DISABLED)]
-    ob_mutex: PyMutex {
-        _bits: AtomicU8::new(0),
-        _pin: PhantomPinned,
-    },
+    ob_mutex: PyMutex::new(),
     #[cfg(Py_GIL_DISABLED)]
     ob_gc_bits: 0,
     #[cfg(Py_GIL_DISABLED)]

src/types/mod.rs

@@ -30,6 +30,7 @@ pub use self::list::{PyList, PyListMethods};
 pub use self::mapping::{PyMapping, PyMappingMethods};
 pub use self::memoryview::PyMemoryView;
 pub use self::module::{PyModule, PyModuleMethods};
+pub use self::mutex::{PyMutex, PyMutexGuard};
 pub use self::none::PyNone;
 pub use self::notimplemented::PyNotImplemented;
 #[allow(deprecated)]
@@ -251,6 +252,8 @@ pub(crate) mod list;
 pub(crate) mod mapping;
 mod memoryview;
 pub(crate) mod module;
+#[cfg(Py_3_13)]
+mod mutex;
 mod none;
 mod notimplemented;
 mod num;

src/types/mutex.rs

@@ -0,0 +1,98 @@
+use std::cell::UnsafeCell;
+use std::ops::{Deref, DerefMut};
+
+/// Wrapper for [`PyMutex`](https://docs.python.org/3/c-api/init.html#c.PyMutex), exposing an RAII guard interface similar to `std::sync::Mutex`.
+#[derive(Debug)]
+pub struct PyMutex<T> {
+    _mutex: UnsafeCell<crate::ffi::PyMutex>,
+    data: UnsafeCell<T>,
+}
+
+/// RAII guard to handle releasing a PyMutex lock.
+#[derive(Debug)]
+pub struct PyMutexGuard<'a, T> {
+    mutex: &'a mut PyMutex<T>,
+}
+
+impl<T> PyMutex<T> {
+    /// Acquire the mutex, blocking the current thread until it is able to do so.
+    pub fn lock(&mut self) -> PyMutexGuard<'_, T> {
+        unsafe { crate::ffi::PyMutex_Lock(self._mutex.get_mut()) };
+        PyMutexGuard { mutex: &mut *self }
+    }
+
+    /// Create a new mutex in an unlocked state ready for use.
+    pub fn new(value: T) -> Self {
+        Self {
+            _mutex: UnsafeCell::new(crate::ffi::PyMutex::new()),
+            data: UnsafeCell::new(value),
+        }
+    }
+}
+
+impl<'a, T> Drop for PyMutexGuard<'a, T> {
+    fn drop(&mut self) {
+        unsafe { crate::ffi::PyMutex_Unlock(self.mutex._mutex.get_mut()) };
+    }
+}
+
+impl<'a, T> Deref for PyMutexGuard<'a, T> {
+    type Target = T;
+
+    fn deref(&self) -> &T {
+        // safety: cannot be null pointer because PyMutexGuard::new always
+        // creates a valid PyMutex pointer
+        unsafe { &*self.mutex.data.get() }
+    }
+}
+
+impl<'a, T> DerefMut for PyMutexGuard<'a, T> {
+    fn deref_mut(&mut self) -> &mut T {
+        // safety: cannot be null pointer because PyMutexGuard::new always
+        // creates a valid PyMutex pointer
+        self.mutex.data.get_mut()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::sync::GILOnceCell;
+    use crate::types::{PyAnyMethods, PyDict, PyDictMethods, PyNone};
+    use crate::Py;
+    use crate::Python;
+
+    #[test]
+    fn test_pymutex() {
+        let mut mutex = Python::with_gil(|py| -> PyMutex<Py<PyDict>> {
+            let d = PyDict::new(py);
+            PyMutex::new(d.unbind())
+        });
+
+        Python::with_gil(|py| {
+            let mut mutex = py.allow_threads(|| -> PyMutex<Py<PyDict>> {
+                std::thread::spawn(|| {
+                    let dict_guard = mutex.lock();
+                    Python::with_gil(|py| {
+                        let dict = dict_guard.bind(py);
+                        dict.set_item(PyNone::get(py), PyNone::get(py)).unwrap();
+                    });
+                    drop(dict_guard);
+                    mutex
+                })
+                .join()
+                .unwrap()
+            });
+
+            let dict_guard = mutex.lock();
+            let d = dict_guard.bind(py);
+
+            assert!(d
+                .get_item(PyNone::get(py))
+                .unwrap()
+                .unwrap()
+                .eq(PyNone::get(py))
+                .unwrap());
+        });
+    }
+}