Object ownership#
One of the main things a binding developer should have in mind is how the C++ instances lives will cope with Python’s reference count. The last thing you want is to crash a program due to a segfault when your C++ instance was deleted and the wrapper object tries to access the invalid memory there.
In this section we’ll show how Qt for Python deals with object ownership and parentship, taking advantage of the information provided by the APIExtractor.
Ownership basics#
As any python binding, Qt for Python-based bindings uses reference counting to handle the life of the wrapper object (the Python object that contains the C++ object, do not confuse with the wrapped C++ object). When a reference count reaches zero, the wrapper is deleted by Python garbage collector and tries to delete the wrapped instance, but sometimes the wrapped C++ object is already deleted, or maybe the C++ object should not be freed after the Python wrapper go out of scope and die, because C++ is already taking care of the wrapped instance.
This is not a concern for value types specified by value-type, which can be freely created, copied and destroyed, however object types specified by object-type pointing to C++ instances with life cycle constraints may require attention.
In order to handle this, you should tell the generator whether the instance’s ownership belongs to the binding or to the C++ Library. When belonging to the binding, we are sure that the C++ object won’t be deleted by C++ code and we can call the C++ destructor when the refcount reaches 0. Otherwise, instances owned by C++ code can be destroyed arbitrarily, without notifying the Python wrapper of its destruction.
By default, objects created in Python have ownership. A relevant case are
return values of virtual factory methods reimplemented in Python
(C++ Wrapper Code) which pass the bindings code. Objects obtained from C++
(for example, QGuiApplication::clipoard()) do not have ownership.
The Shiboken module module provides the dump() utility function,
which prints the relevant information for an object.
Invalidating objects#
To prevent segfaults and double frees, the wrapper objects are invalidated. An invalidated can’t be passed as argument or have an attribute or method accessed. Trying to do this will raise RuntimeError.
The following situations can invalidate an object:
C++ taking ownership#
When an object is passed to a function or method that takes ownership of it, the wrapper is invalidated as we can’t be sure of when the object is destroyed, unless it has a virtual destructor or the transfer is due to the special case of parent ownership.
Besides being passed as argument, the called object can have its ownership changed, like the setParent method in Qt’s QObject.
Invalidate after use#
Objects marked with invalidate-after-use in the type system description always are virtual method arguments provided by a C++ originated call. They should be invalidated right after the Python function returns (see Invalidation after use).
Objects with virtual methods#
A little bit of implementation details (see also Code Generation Terminology): virtual methods are supported by creating a C++ class, the shell, that inherits from the class with virtual methods, the native one, and override those methods to check if any derived class in Python also override it.
If the class has a virtual destructor (and C++ classes with virtual methods should have), this C++ instance invalidates the wrapper only when the overridden destructor is called.
An instance of the shell is created when created in Python. However,
when the object is created in C++, like in a factory method or a parameter
to a virtual function like QObject::event(QEvent *), the wrapped object
is a C++ instance of the native class, not the shell one, and we cannot
know when it is destroyed.
Parent-child relationship#
One special type of ownership is the parent-child relationship. Being a child of an object means that when the object’s parent dies, the C++ instance also dies, so the Python references will be invalidated. Qt’s QObject system, for example, implements this behavior, but this is valid for any C++ library with similar behavior.
Parentship heuristics#
As the parent-child relationship is very common, Qt for Python tries to automatically infer what methods falls into the parent-child scheme, adding the extra directives related to ownership.
This heuristic will be triggered when generating code for a method and:
The function is a constructor.
The argument name is parent.
The argument type is a pointer to an object.
When triggered, the heuristic will set the argument named “parent” as the parent of the object being created by the constructor.
The main focus of this process was to remove a lot of hand written code from type system when binding Qt libraries. For Qt, this heuristic works in all cases, but be aware that it might not when binding your own libraries.
To activate this heuristic, use the –enable-parent-ctor-heuristic command line switch.
Return value heuristics#
When enabled, object returned as pointer in C++ will become child of the object on which the method was called.
To activate this heuristic, use the command line switch –enable-return-value-heuristic.
To disable this heuristic for specific cases, specify default as
ownership:
<modify-argument index="0">
<define-ownership class="target" owner="default" />
</modify-argument>
Common pitfalls#
Not saving unowned objects references#
Sometimes when you pass an instance as argument to a method and the receiving instance will need that object to live indefinitely, but will not take ownership of the argument instance. In this case, you should hold a reference to the argument instance.
For example, let’s say that you have a renderer class that will use a source class in a setSource method but will not take ownership of it. The following code is wrong, because when render is called the Source object created during the call to setSource is already destroyed.
renderer.setModel(Source())
renderer.render()
To solve this, you should hold a reference to the source object, like in
source = Source()
renderer.setSource(source)
renderer.render()
Ownership Management in the Typesystem#
Python Wrapper Code#
For this code, the class attribute takes the value target
(see Code Generation Terminology).
Ownership transfer from C++ to target#
When an object currently owned by C++ has its ownership transferred back to the target language, the binding can know for sure when the object will be deleted and tie the C++ instance existence to the wrapper, calling the C++ destructor normally when the wrapper is deleted.
<modify-argument index="1">
<define-ownership class="target" owner="target" />
</modify-argument>
A typical use case would be returning an object allocated in C++, for
example from clone() or other factory methods.
Ownership transfer from target to C++#
In the opposite direction, when an object ownership is transferred from the target language to C++, the native code takes full control of the object life and you don’t know when that object will be deleted, rendering the wrapper object invalid, unless you’re wrapping an object with a virtual destructor, so you can override it and be notified of its destruction.
By default it’s safer to just render the wrapper object invalid and raise some error if the user tries to access one of this objects members or pass it as argument to some function, to avoid unpleasant segfaults. Also you should avoid calling the C++ destructor when deleting the wrapper.
<modify-argument index="1">
<define-ownership class="target" owner="c++" />
</modify-argument>
Use cases would be an returning a member object by pointer
or passing an object by pointer into a function where the class
takes ownership, for example
QNetworkAccessManager::setCookieJar(QNetworkCookieJar *).
Parent-child relationship#
One special type of relationship is the parent-child. When an object is called the parent of another object (the child), the former is in charge of deleting its child when deleted and the target language can trust that the child will be alive as long as the parent is, unless some other method can take the C++ ownership away from the parent.
One of the main uses of this scheme is Qt’s object system, with ownership among QObject-derived classes, creating “trees” of instances.
<modify-argument index="this">
<parent index="1" action="add"/>
</modify-argument>
In this example, the instance with the method that is being invoked (indicated by ‘index=”this”’ on modify-argument) will be marked as a child of the first argument using the parent tag. To remove ownership, just use “remove” in the action attribute. Removing parentship also transfers the ownership back to python.
C++ Wrapper Code#
For this code, the class attribute takes the value native. The
modifications affect code called from within C++, typically when calling
virtual C++ methods reimplemented in Python
(see Code Generation Terminology).
Return values of virtual functions#
The ownership of C++ objects returned by pointer should be set to c++ to
prevent them from being deleted by Python, since objects created
in Python have ownership by default.
Ownership transfers specified for other arguments do not have any effect.
Invalidation after use#
Sometimes an object is created in C++ and passed as a virtual method call
argument and destroyed after the call returned
(see Objects with virtual methods).
In this case, you should use the invalidate-after-use attribute in the
modify-argument tag to mark the wrapper as invalid right after the
virtual method returns.
<modify-argument index="2" invalidate-after-use="yes"/>
In this example the second argument will be invalidated after this method call.