Struct PyMutex 

pub struct PyMutex<T: ?Sized> { /* private fields */ }

Wrapper for PyMutex, exposing an RAII guard interface.

Compared with std::sync::Mutex or parking_lot::Mutex, this is a very stripped-down locking primitive that only supports blocking lock and unlock operations and does not support try_lock or APIs that depend on try_lock. For this reason, it is not possible to avoid the possibility of possibly blocking when calling lock and extreme care must be taken to avoid introducing a deadlock.

This type is most useful when arbitrary Python code might execute while the lock is held. On the GIL-enabled build, PyMutex will release the GIL if the thread is blocked on acquiring the lock. On the free-threaded build, threads blocked on acquiring a PyMutex will not prevent the garbage collector from running.

Implementations

impl<T> PyMutex<T>

pub fn lock(&self) -> PyMutexGuard<'_, T>

Acquire the mutex, blocking the current thread until it is able to do so.

pub const fn new(value: T) -> Self

Create a new mutex in an unlocked state ready for use.

pub fn is_locked(&self) -> bool

Check if the mutex is locked.

Note that this is only useful for debugging or test purposes and should not be used to make concurrency control decisions, as the lock state may change immediately after the check.

pub fn into_inner(self) -> T

where T: Sized,

Consumes this mutex, returning the underlying data.

Trait Implementations

impl<'a, T: ?Sized + 'a> PyMutexTrait<'a, T> for PyMutex<T>

Available on Py_3_13 and non-Py_LIMITED_API only.

impl<T: ?Sized + Send> Send for PyMutex<T>

SAFETY: T must be Send for a PyMutex to be Send because it is possible to acquire the owned T from the PyMutex via into_inner.

impl<T: ?Sized + Send> Sync for PyMutex<T>

SAFETY: T must be Send for PyMutex to be Sync. This ensures that the protected data can be accessed safely from multiple threads without causing data races or other unsafe behavior.

PyMutex<T> provides mutable access to T to one thread at a time. However, it’s essential for T to be Send because it’s not safe for non-Send structures to be accessed in this manner. For instance, consider Rc, a non-atomic reference counted smart pointer, which is not Send. With Rc, we can have multiple copies pointing to the same heap allocation with a non-atomic reference count. If we were to use Mutex<Rc<_>>, it would only protect one instance of Rc from shared access, leaving other copies vulnerable to potential data races.

Also note that it is not necessary for T to be Sync as &T is only made available to one thread at a time if T is not Sync.