|author||Kai Huuhko <email@example.com>||2017-07-09 16:50:24 +0300|
|committer||Kai Huuhko <firstname.lastname@example.org>||2017-07-09 16:50:24 +0300|
|parent||Elementary: Add import to efl.edje (diff)|
Documentation: Add better documentation about object lifetime
2 files changed, 30 insertions, 4 deletions
diff --git a/doc/efl.rst b/doc/efl.rst
index 6725dae..b21e87d 100644
@@ -6,6 +6,26 @@
.. versionadded:: 1.8
+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
+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:
diff --git a/efl/eo/efl.eo.pyx b/efl/eo/efl.eo.pyx
index cc0c60a..6985308 100644
@@ -283,11 +283,17 @@ cdef class Eo(object):
- """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.