Struct PyClassGuardMut

Source

pub struct PyClassGuardMut<'a, T: PyClass<Frozen = False>> { /* private fields */ }

Expand description

A wrapper type for a mutably borrowed value from a PyClass

§When not to use `PyClassGuardMut`

Usually you can use &mut references as method and function receivers and arguments, and you won’t need to use PyClassGuardMut directly:

use pyo3::prelude::*;

#[pyclass]
struct Number {
    inner: u32,
}

#[pymethods]
impl Number {
    fn increment(&mut self) {
        self.inner += 1;
    }
}

The #[pymethods] proc macro will generate this wrapper function (and more), using PyClassGuardMut under the hood:

// The function which is exported to Python looks roughly like the following
unsafe extern "C" fn __pymethod_increment__(
    _slf: *mut ::pyo3::ffi::PyObject,
    _args: *mut ::pyo3::ffi::PyObject,
) -> *mut ::pyo3::ffi::PyObject {
    unsafe fn inner<'py>(
        py: ::pyo3::Python<'py>,
        _slf: *mut ::pyo3::ffi::PyObject,
    ) -> ::pyo3::PyResult<*mut ::pyo3::ffi::PyObject> {
        let function = Number::increment;
        let mut holder_0 = ::pyo3::impl_::extract_argument::FunctionArgumentHolder::INIT;
        let result = {
            let ret = function(::pyo3::impl_::extract_argument::extract_pyclass_ref_mut::<Number>(
                unsafe { ::pyo3::impl_::pymethods::BoundRef::ref_from_ptr(py, &_slf) }.0,
                &mut holder_0,
            )?);
            {
                let result = {
                    let obj = ret;
                    ::pyo3::impl_::wrap::converter(&obj)
                        .wrap(obj)
                        .map_err(::core::convert::Into::<::pyo3::PyErr>::into)
                };
                ::pyo3::impl_::wrap::converter(&result).map_into_ptr(py, result)
            }
        };
        result
    }

    unsafe {
        ::pyo3::impl_::trampoline::noargs(
            _slf,
            _args,
            inner,
        )
    }
}

§When to use `PyClassGuardMut`

§Using PyClasses from Rust

However, we do need PyClassGuardMut if we want to call its methods from Rust:

Python::attach(|py| {
    let n = Py::new(py, Number { inner: 0 })?;

    // We borrow the guard and then dereference
    // it to get a mutable reference to Number
    let mut guard: PyClassGuardMut<'_, Number> = n.extract(py)?;
    let n_mutable: &mut Number = &mut *guard;

    n_mutable.increment();

    // To avoid panics we must dispose of the
    // `PyClassGuardMut` before borrowing again.
    drop(guard);

    let n_immutable: &Number = &*n.extract::<PyClassGuard<'_, Number>>(py)?;
    assert_eq!(n_immutable.inner, 1);

    Ok(())
})

§Dealing with possibly overlapping mutable references

It is also necessary to use PyClassGuardMut if you can receive mutable arguments that may overlap. Suppose the following function that swaps the values of two Numbers:

#[pyfunction]
fn swap_numbers(a: &mut Number, b: &mut Number) {
    std::mem::swap(&mut a.inner, &mut b.inner);
}

When users pass in the same Number as both arguments, one of the mutable borrows will fail and raise a RuntimeError:

>>> a = Number()
>>> swap_numbers(a, a)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  RuntimeError: Already borrowed

It is better to write that function like this:

#[pyfunction]
fn swap_numbers(a: &Bound<'_, Number>, b: &Bound<'_, Number>) -> PyResult<()> {
    // Check that the pointers are unequal
    if !a.is(b) {
        let mut a: PyClassGuardMut<'_, Number> = a.extract()?;
        let mut b: PyClassGuardMut<'_, Number> = b.extract()?;
        std::mem::swap(&mut a.inner, &mut b.inner);
    } else {
        // Do nothing - they are the same object, so don't need swapping.
    }
    Ok(())
}

See PyClassGuard and the guide for more information.

Implementations§

Source §

impl<'a, T: PyClass<Frozen = False>> PyClassGuardMut<'a, T>

Source

pub fn map<F, U: ?Sized>(self, f: F) -> PyClassGuardMap<'a, U, true>
where F: FnOnce(&mut T) -> &mut U,

Consumes the PyClassGuardMut and returns a PyClassGuardMap for a component of the borrowed data

§Examples


#[pyclass]
pub struct MyClass {
    data: [i32; 100],
}

let obj = Bound::new(py, MyClass { data: [0; 100] })?;
let mut data = obj.extract::<PyClassGuardMut<'_, MyClass>>()?.map(|c| c.data.as_mut_slice());
data[0] = 42;

Source §

impl<'a, T, U> PyClassGuardMut<'a, T>
where T: PyClass<BaseType = U, Frozen = False>, U: PyClass<Frozen = False>,

Source

pub fn as_super(&mut self) -> &mut PyClassGuardMut<'a, U>

Borrows a mutable reference to PyClassGuardMut<T::BaseType>.

With the help of this method, you can mutate attributes and call mutating methods on the superclass without consuming the PyClassGuardMut<T>. This method can also be chained to access the super-superclass (and so on).

See PyClassGuard::as_super for more.

Source