Documentation: Add better documentation about object lifetime
This commit is contained in:
parent
a475ecba44
commit
5864a9dd2d
20
doc/efl.rst
20
doc/efl.rst
|
@ -6,6 +6,26 @@
|
||||||
.. versionadded:: 1.8
|
.. versionadded:: 1.8
|
||||||
|
|
||||||
|
|
||||||
|
Object lifetime
|
||||||
|
---------------
|
||||||
|
|
||||||
|
Eo objects (and any which have the delete() method) get their reference count
|
||||||
|
internally increased by one at object creation. This means that these objects
|
||||||
|
will not get freed when you release all references to them in your application.
|
||||||
|
You must call the objects' delete() method to decrease the internal reference
|
||||||
|
count. This will usually also trigger some kind of action to destroy
|
||||||
|
the object gracefully, i.e. hiding the graphical object etc, and will set the
|
||||||
|
C object pointer to NULL, which will prevent you from calling methods on the
|
||||||
|
object.
|
||||||
|
|
||||||
|
If you can't keep track of when your application calls the delete method, you
|
||||||
|
can check that your object is still valid with either the is_deleted() method,
|
||||||
|
or with a non-zero check::
|
||||||
|
|
||||||
|
if eo_obj:
|
||||||
|
print(repr(eo_obj))
|
||||||
|
|
||||||
|
|
||||||
Logging
|
Logging
|
||||||
-------
|
-------
|
||||||
|
|
||||||
|
|
|
@ -283,11 +283,17 @@ cdef class Eo(object):
|
||||||
return EoIterator.create(efl_children_iterator_new(self.obj))
|
return EoIterator.create(efl_children_iterator_new(self.obj))
|
||||||
|
|
||||||
def delete(self):
|
def delete(self):
|
||||||
"""Delete the object and free internal resources.
|
"""Decrease internal reference count and delete the object gracefully
|
||||||
|
|
||||||
.. note:: This will not delete the python object, but only the internal
|
.. note:: Reference count will be decreased at the del callback, not
|
||||||
C one. The python object will be automatically deleted by the
|
instantly when calling this. Same for setting the internal
|
||||||
garbage collector when there are no more reference to it.
|
object pointer to NULL and freeing any internal resources.
|
||||||
|
|
||||||
|
.. note:: This will not automatically free the Python object, only
|
||||||
|
the wrapped C object. This will prevent you from calling methods
|
||||||
|
other than :meth:`is_deleted` and accessing properties on the
|
||||||
|
object. The Python object will be automatically freed by Python
|
||||||
|
when there are no more references to it.
|
||||||
|
|
||||||
"""
|
"""
|
||||||
efl_del(self.obj)
|
efl_del(self.obj)
|
||||||
|
|
Loading…
Reference in New Issue