[PySide] [shiboken2] Object Ownership

[icfwm at gmx.net]

Hi Cristián,

thank you very much for the detailed answer. Indeed it was very
enlightening, even if I still have troubles to imagine the consequences
of class attribute. Probably this needs some more experimenting.

I'm going to try to come up with a doc enhancement as requested, but it
may take some time.

Best Regards
Christoph

On 27.02.20 10:59, Cristián Maureira-Fredes wrote:
> 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
>
>
>