kuuko pushed a commit to branch master. http://git.enlightenment.org/bindings/python/python-efl.git/commit/?id=5864a9dd2d5d43461f9098708fbf14cf53a0f116
commit 5864a9dd2d5d43461f9098708fbf14cf53a0f116 Author: Kai Huuhko <[email protected]> Date: Sun Jul 9 16:50:24 2017 +0300 Documentation: Add better documentation about object lifetime --- doc/efl.rst | 20 ++++++++++++++++++++ efl/eo/efl.eo.pyx | 14 ++++++++++---- 2 files changed, 30 insertions(+), 4 deletions(-) diff --git a/doc/efl.rst b/doc/efl.rst index 6725dae..b21e87d 100644 --- a/doc/efl.rst +++ b/doc/efl.rst @@ -6,6 +6,26 @@ .. 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 ------- diff --git a/efl/eo/efl.eo.pyx b/efl/eo/efl.eo.pyx index cc0c60a..6985308 100644 --- a/efl/eo/efl.eo.pyx +++ b/efl/eo/efl.eo.pyx @@ -283,11 +283,17 @@ cdef class Eo(object): return EoIterator.create(efl_children_iterator_new(self.obj)) 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 - C one. The python object will be automatically deleted by the - garbage collector when there are no more reference to it. + .. note:: Reference count will be decreased at the del callback, not + instantly when calling this. Same for setting the internal + 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) --
