[PySide] [shiboken2] Object Ownership

[Cristián Maureira-Fredes]

Hello,

I will answer inline:


On 2/25/20 12:05 AM, icfwm at gmx.net wrote:
> Hi,
> (snip)
> One of the biggest unknowns here is the default ownership assumptions of
> shiboken2. It is mentioned that there are some heuristics, but
> unfortunately the documentation seems to be spread around the
> aforementioned places, and so I'm not sure if I understood everything
> correctly. I would like to give some examples in C++ code (assuming "A"
> is a wrapped C++ class which is wrapped as <object-type>) and the
> question is whether or not my assumptions are correct?
> 
> 1.  A* createA(); // default ownership of return value: target language,
> unless --enable-return-value-heuristic is given

yes

> 2.  void doSomething(A* arg); // default ownership of argument: target
> language

yes

> 3.  void doSomething(A& arg); // default ownership of argument: target
> language

yes

> 4.  const A& getReference(); // what happens here? a copy of the result
> is transferred to target ownership?

yes,
for example look at the generated code for the function "font()"
from QWidget:


// font()const 

const QFont & cppResult = const_cast<const ::QWidget *>(
   cppSelf)->font();

pyResult = Shiboken::Conversions::copyToPython(
   reinterpret_cast<SbkObjectType *>(
     SbkPySide2_QtGuiTypes[SBK_QFONT_IDX]), &cppResult);

the value is just copied to target (python).


> It seems that the default is that the target language owns all objects
> passed around and transfer to c++ has to be made explicit in
> typesystem.xml?

yes

> In the <define-ownership> tag documentation, for me it is completely
> unclear what the class attribute means? I think the default is "target",
> but what happens when you specify "native"?

The class attribute will specify if you want to modify
the native or target functions.
- The native being the one called e.g.:
     QMimeData * QTreeWidgetWrapper::mimeData(...)
     in qtreewidget_wrapper.cpp
- or the target function:
     static PyObject *Sbk_QTreeWidgetFunc_mimeData(...)
     in qtreewidget_wrapper.cpp


Since the default is target,
using class="native" will allow the python object
to keep the ownership of it:
- the variable called pyResult (in the native function)

But when you specify:
<define-ownership class="native" owner="c++" ...>
you are telling shiboken, don't allow the python object
to keep ownership of the object, so then in the generated code
you get something like:

Shiboken::Object::releaseOwnership(pyResult)

Another case is:

<define-ownership class="target" owner="default",

in that case nothing is done in the target function,
the variable will just exists in that scope,
However when using:

<define-ownership class="target" owner="target",

you will explicitly get the ownership of the object,
and the following line will be added to the target function:

Shiboken::Object::getOwnership(pyResult);

and you have yet another case of:

<define-ownership class="target" owner="c++",

that will release the ownership (from target)
so it will leave it to C++:

Shiboken::Object::releaseOwnership(pyArg)

as you can see, this is the same case as the first with the 
class="native" owner="c++", but this happens in the
target function and not in the native.


> In the object ownership documentation, it is mentioned that there is the
> invalidate-after-use attribute, but this seems to be missing in the type
> system reference. The given use case is completely unclear to me and it
> would be good to have an example when this might be useful.

Maybe the test case for this situation can clarify the situation better:
https://code.qt.io/cgit/pyside/pyside-setup.git/tree/sources/shiboken2/ApiExtractor/tests/testmodifyfunction.cpp#n102

> All in all, the object ownership documentation could be improved greatly
> by giving some examples for the mentioned cases, not only in the xml
> domain, but also in C++ domain.

Sure, I'm totally with you on this,
but it's always a matter of people available to do so,
and priorities :(

I really hope you can help us improving the documentation too,
even if you find a small mistake you want to submit,
please do, I will happily review it :)

Cheers



-- 
Dr. Cristian Maureira-Fredes
R&D Manager

The Qt Company GmbH
Erich-Thilo-Str. 10
D-12489 Berlin

Geschäftsführer: Mika Pälsi,
Juha Varelius, Mika Harjuaho
Sitz der Gesellschaft: Berlin,
Registergericht: Amtsgericht
Charlottenburg, HRB 144331 B
--