aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorKai Huuhko <kai.huuhko@gmail.com>2017-07-09 16:50:24 +0300
committerKai Huuhko <kai.huuhko@gmail.com>2017-07-09 16:50:24 +0300
commit5864a9dd2d5d43461f9098708fbf14cf53a0f116 (patch)
treeee2f208bfe248f68d35a7def25e44f9648461dd3
parentElementary: Add import to efl.edje (diff)
downloadpython-efl-5864a9dd2d5d43461f9098708fbf14cf53a0f116.tar.gz
Documentation: Add better documentation about object lifetime
-rw-r--r--doc/efl.rst20
-rw-r--r--efl/eo/efl.eo.pyx14
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)