How to understand Python::with_gil and Py<Myclass>?

[sun-rs]

Q1. With code below I found somthing that if I want to call a python method in Rust, I don't need to add Python::with_gil. But in some official examples like https://pyo3.rs/v0.16.2/class/call.html or https://pyo3.rs/v0.16.2/python_from_rust.html, some use Python::with_gil while some not. What's the difference?

I think maybe because I call the method from python side which means I already got the gil, so I do not need to add Python::with_gil in Rust?

#[pyclass]
pub struct Myclass {
    pycls: Py<PyAny>,
}

#[pymethods]
impl Myclass {
    #[new]
    pub fn new(pycls: Py<PyAny>) -> Self {
        Myclass { pycls }
    }

    pub fn on_calculation(&mut self, py:Python) {
        let py_model = self.pycls.as_ref(py);
        py_model
            .call_method("on_calculation", (), None)
            .unwrap();

        // This also work!!!!!!
        // Python::with_gil(|py| {
        //     let py_model = self.pycls.as_ref(py);
        //     py_model
        //         .call_method("on_calculation", (), None)
        //         .unwrap();           
        // });
    }

#[pyclass]
pub struct Player {
    
    cls: Myclass,
}

#[pymethods]
impl Player {
    #[new]
    pub fn new(cls: Myclass) -> Self {
        Player { cls: cls}
    }

    pub fn run(&mut self, num:i64, py: Python) {
        for _i in 0..num {
            self.cls.on_calculation(py); 
        }
    }
}

class TestContext:
    def __init__(self, num: int):
        self.x = num
    def on_calculation(self):
        self.x += 3

if __name__=="__main__":
    pycls = TestContext(9)
    rcls = Myclass(pycls)
  
    x = Player(rcls)
    x.run(10)

Q2. I found if replace the member cls: Myclass of rust struct Player to cls: Py<Myclass>, and change the way to call it use as_ref(py), code in python side doesn't need to change any and will also work. It seems in python ,after pycls = TestContext(9) rcls = Myclass(pycls), the rcls could be recognize as Py<Myclass> and Myclass??

#[pymethods]
impl Player {
    #[new]
    pub fn new(cls: Py<Myclass>) -> Self {
        Player { cls:cls }
    }

    pub fn run(&mut self, num:i64, py: Python) {
        for _i in 0..num {
            self.cls.as_ref(py).call_method("on_calculation", (), None).unwrap();
        }
    }
}

How to understand this and what's the difference in these two call method?

[adamreichold]

A value py: Python<'a> is a proof that the GIL is held, i.e. all functions which require you to have the GIL express this by requiring you to pass such a py: Python<'a> token as an argument. One example is Py::as_ref which produces a reference into the Python heap which is valid as long as the GIL is held, i.e. its lifetime 'a is bound to that of the token.

Python::with_gil is a function to acquire the GIL, i.e. it will check whether the GIL is already held, lock it if not and depending on that also release it before returning. In this way, it is a safe method to produce such a py: Python<'a> token.

Methods exposed as #[pymethods] are supposed to be called from Python meaning that the GIL is definitely held when they are invoked. Hence they can request PyO3 to make a py: Python<'a> token available to them. This value is then produced by the wrapper code for the method which is automatically generated by PyO3. If you were to call that method manually from Rust, you would need to use e.g. Python::with_gil to produce it.

Finally, Py<T> is basically a safe wrapper for *mut T expressing that the pointer is into the Python heap and the life time of the object is managed via reference counting which is always the case for objects in CPython. Hence passing Myclass(pycls) is passing such a reference counted pointer to pycls to the constructor of Myclass even on the Python side, the signature fn new(cls: Py<Myclass>) just makes that explicit.

Additionally, a constructor like

    #[new]
    pub fn new(cls: Myclass) -> Self {
        Player { cls: cls}
    }

should not be callable from Python at all if Myclass is not Clone as Python does not support destructive move semantics and can only produce a value of type Myclass after being invoked (from Python) with a value of type Py<Myclass> by cloning the interior.

[adamreichold]

Still confused about rcls = Myclass(pycls),x = Player(rcls) because it both works for pub fn new(cls: Myclass) and pub fn new(cls: Py). So i don't know what it really is.

I am not sure what you doing exactly, but it does not work without cloning the value (i.e. the rcls is copied, not moved into x), i.e.

#[pyclass]
struct MyInnerClass {
    value: i32,
}

#[pymethods]
impl MyInnerClass {
    #[new]
    fn new(value: i32) -> Self {
        Self { value }
    }
}

#[pyclass]
struct MyOuterClass {
    inner: MyInnerClass,
}

#[pymethods]
impl MyOuterClass {
    #[new]
    fn new(inner: MyInnerClass) -> Self {
        Self { inner }
    }
}

leads to the compiler error

error[E0277]: the trait bound `MyInnerClass: Clone` is not satisfied
  --> examples/simple/src/lib.rs:34:19
   |
34 |     fn new(inner: MyInnerClass) -> Self {
   |                   ^^^^^^^^^^^^ the trait `Clone` is not implemented for `MyInnerClass`
   |
   = note: required because of the requirements on the impl of `FromPyObject<'_>` for `MyInnerClass`
note: required by a bound in `extract_argument`
  --> /home/adam/.cargo/registry/src/github.com-1ecc6299db9ec823/pyo3-0.16.2/src/impl_/extract_argument.rs:14:8
   |
14 |     T: FromPyObject<'py>,
   |        ^^^^^^^^^^^^^^^^^ required by this bound in `extract_argument`

For more information about this error, try `rustc --explain E0277`.
error: could not compile `rust-ext` due to previous error

whereas

#[pyclass]
struct MyInnerClass {
    value: i32,
}

#[pymethods]
impl MyInnerClass {
    #[new]
    fn new(value: i32) -> Self {
        Self { value }
    }
}

#[pyclass]
struct MyOuterClass {
    inner: Py<MyInnerClass>,
}

#[pymethods]
impl MyOuterClass {
    #[new]
    fn new(inner: Py<MyInnerClass>) -> Self {
        Self { inner }
    }
}

works. (Py<T> can always be cloned as cloning it means incrementing the reference count.)

Does it means we can get a pure rust struct in python? Py is a pointer while argument type Myclass is the instance itself?

No, #[pyclass] instances are always placed on the Python heap and have to conform to the PyObject protocol thereby, e.g. for providing reference counting. But PyO3 takes care of this behind the scenes and adds another layer of dynamic borrow checking which is necessary to go from Py<PyCell<T>> (which is how a #[pyclass] looks like explicitly) to &T/&mut T.

Does this mean that when I do Myclass(pycls) in python it actually returns a Py for Rust ?

Somewhat. As written above, Py<T> is really just a wrapper for the way Python managesall object references (which always have shared ownership).

[sun-rs]

it does not work without cloning the value

@adamreichold Thanks for reply! I re-checked my code , I found it's because I add #[derive(Debug, Clone)] which make it works. Please pardon my Ignorance.

What I want to do is I have a class write in rust(for query and execute performance) with a lot of data, I need to use same one instance on both Python and Rust side and avoid copy data while remain perfomance of Rust.

According to your amazing reply, It seems fn new(inner: Py<MyInnerClass>) -> Self is appropriate for my scene while avoiding copy data?

Another question is that if MyInnerClass do not has lot of data, it is very small(few small vector as class variables) and barely just methods in it. Would fn new(inner: MyInnerClass) -> Self { wilt #[derive(Debug, Clone)] perform better than fn new(inner: Py<MyInnerClass>) -> Self when call its methods (like quick and simple use self.inner.method() rather than use .as_ref(py).call_method("method")) ? As I far as I know heap maybe slower?

[adamreichold]

According to your amazing reply, It seems fn new(inner: Py) -> Self is appropriate for my scene while avoiding copy data?

Yes.

Another question is that if MyInnerClass do not has lot of data, it is very small(few small vector as class variables) and barely just methods in it. Would fn new(inner: MyInnerClass) -> Self { wilt #[derive(Debug, Clone)] perform better than fn new(inner: Py) -> Self when call its methods (like quick and simple use self.inner.method() rather than use .as_ref(py).call_method("method")) ? As I far as I know heap maybe slower?

The object will placed on the Python heap in both cases. With Py<...> it will just copy the contents from the heap into your newly created struct.

And while self.inner.method() will probably be faster than self.inner.as_ref(py).call_method("method"), this has likely less to do with where inner is allocated (inline or on the heap), but rather with the borrow checking and most importantly dispatch overhead.

But the question is probably moot if self.inner, needs to be exposed to Python code and that code should be able to modify its content. In that case you have to use Py<...> to be able to hand a reference to the Python code.

[sun-rs]

Thanks for reply! Now I know if I want to expose a struct for using in Python, it must be a Py<Myclass>. I found there are two way to call a method in it, self.inner.as_ref(py).call_method("method") and self.inner.borrow_mut(py).method() , are they equal to each other? Which is a better?

Also I noticed that in many official examples which return some data to Python, it should do a clone first. Can I make this conclusion that if a data need send to Python, it must be copy first? We couldn't do Zero-copy transfer? It seems Arrow can be send to Rust from Python with zero-copy.

[adamreichold]

I found there are two way to call a method in it, self.inner.as_ref(py).call_method("method") and self.inner.borrow_mut(py).method() , are they equal to each other? Which is a better?

The second one as it does not dispatch via Python.