eo del interceptor: add the ability to intercept deletions of eo objects

Imagine this. You have an object. You pass this object handle as a
message to another thread. Let's say it's not a UI object, so
something you might expect to be able to be accessed from multiple
threads. In order to keep the object alive you eo_ref() it when
placing the message on a queue and eo_unref() it once the message is
"done" in the other thread. If the original sender unref()ed the
object before the message is done, then the object will be destroyed
in the reciever thread. This is bad for objects "expecting" not to be
destroyed outside their owning thread.

This allows thius situation to be fixed. A constructor in a class of
an object can set up a delete interceptor. For example if we have a
"loop ownership" class you multi-ple-inherit from/use as a mixin. This
class will set up the interceptor to ensure that on destruction if
pthread_self() != owning loop thread id, then add object to "delete
me" queue on the owning loop and wake it up. the owning loop thread
will wake up and then process this queue and delete the queued objects
nicely and safely within the "owning context".

This can also be used in this same manner to defer deletion within a
loop "until later" in the same delete_me queue.

You can even use this as a caching mechanism for objects to prevernt
their actual destruction and instead place them in a cached area to be
picked from at a later date.

The uses are many for this and this is a basic building block for
future EFL features like generic messages where a message payload
could be an eo object and thus the above loop onwership issue can
happen and needs fixing.

This adds APIs, implementation, documentation (doxy reference) and tests.

@feature

src/lib/eo/Eo.h

@@ -166,6 +166,16 @@ typedef struct _Eo_Event Eo_Event;
  */
 typedef Eina_Bool (*Eo_Event_Cb)(void *data, const Eo_Event *event);
 
+/**
+ * @typedef Eo_Del_Intercept
+ *
+ * A function to be called on object deletion/destruction instead of normal
+ * destruction taking place.
+ *
+ * @param obj_id The object needing destruction
+ */
+typedef void (*Eo_Del_Intercept) (Eo *obj_id);
+
 #include "eo_base.eo.h"
 #define EO_CLASS EO_BASE_CLASS
 
@@ -786,6 +796,54 @@ EAPI void eo_unref(const Eo *obj);
  */
 EAPI int eo_ref_get(const Eo *obj);
 
+/**
+ * @brief Set a deletion interceptor function
+ * @param obj The object to set the interceptor on
+ * @param del_intercept_func The interceptor function to call
+ *
+ * This sets the function @p del_intercept_func to be called when an object
+ * is about to go from a reference count of 1 to 0, thus triggering actual
+ * destruction of the object. Instead of going to a reference count of 0 and
+ * being destroyed, the object will stay alive with a reference count of 1
+ * and this intercept function will be called instead. It is the job of
+ * this interceptor function to handle any further deletion of of the object
+ * from here.
+ *
+ * Note that by default objects have no interceptor function set, and thus
+ * will be destroyed as normal. To return an object to this state, simply
+ * set the @p del_intercept_func to NULL which is the default.
+ *
+ * A good use for this feature is to ensure an object is destroyed by its
+ * owning main loop and not in a foreign loop. This makes it possible to
+ * safely unrefor delete objects from any loop as an interceptor can be set
+ * on an object that will abort destruction and instead queue the object
+ * on its owning loop to be destroyed at some time in the future and now
+ * set the intercept function to NULL so it is not called again on the next
+ * "real deletion".
+ * 
+ * @see eo_del_intercept_get()
+ * @see eo_unref()
+ * @see eo_del()
+ */
+EAPI void eo_del_intercept_set(Eo *obj, Eo_Del_Intercept del_intercept_func);
+
+/**
+ * @brief Get the deletion interceptor function
+ * @param obj The object to get the interceptor of
+ * @return The intercept function or NULL if none is set.
+ *
+ * This returns the interceptor function set by eo_del_intercept_set(). Note
+ * that objects by default have no interceptor (NULL) set, but certain
+ * classes may set one up in a constructor, so it is important to be able
+ * to get the interceptor function to know if this has happend and
+ * if you want to override this interceptor, be sure to call it after your
+ * own interceptor function has finished. It would generally be a bad idea
+ * though to override these functions.
+ * 
+ * @see eo_del_intercept_set()
+ */
+EAPI Eo_Del_Intercept eo_del_intercept_get(const Eo *obj);
+
 /**
  * @brief Unrefs the object and reparents it to NULL.
  * @param obj the object to work on.

src/lib/eo/eo.c

@@ -1332,6 +1332,22 @@ eo_ref_get(const Eo *obj_id)
    return obj->refcount;
 }
 
+EAPI void
+eo_del_intercept_set(Eo *obj_id, Eo_Del_Intercept del_intercept_func)
+{
+   EO_OBJ_POINTER_RETURN(obj_id, obj);
+
+   obj->del_intercept = del_intercept_func;
+}
+
+EAPI Eo_Del_Intercept
+eo_del_intercept_get(const Eo *obj_id)
+{
+   EO_OBJ_POINTER_RETURN_VAL(obj_id, obj, NULL);
+
+   return obj->del_intercept;
+}
+
 void
 _eo_condtor_done(Eo *obj_id)
 {

src/lib/eo/eo_private.h

@@ -95,6 +95,7 @@ struct _Eo_Object
 #endif
 
      Eina_List *composite_objects;
+     Eo_Del_Intercept del_intercept;
 
      int refcount;
      int datarefcount;
@@ -295,6 +296,14 @@ _eo_unref(_Eo_Object *obj)
              ERR("Object %p deletion already triggered. You wrongly call eo_unref() within a destructor.", _eo_id_get(obj));
              return;
           }
+
+        if (obj->del_intercept)
+          {
+             (obj->refcount)++;
+             obj->del_intercept(_eo_id_get(obj));
+             return;
+          }
+
         obj->del_triggered = EINA_TRUE;
 
         _eo_del_internal(__FILE__, __LINE__, obj);

src/tests/eo/suite/eo_test_general.c

@@ -950,6 +950,60 @@ START_TEST(eo_add_failures)
 }
 END_TEST
 
+static Eina_Bool intercepted = EINA_FALSE;
+
+static void
+_del_intercept(Eo *obj)
+{
+   intercepted = EINA_TRUE;
+   eo_del_intercept_set(obj, NULL);
+   eo_unref(obj);
+}
+
+START_TEST(eo_del_intercept)
+{
+#ifdef HAVE_EO_ID
+   eo_init();
+
+   static const Eo_Class_Description class_desc = {
+        EO_VERSION,
+        "Simple",
+        EO_CLASS_TYPE_REGULAR,
+        EO_CLASS_DESCRIPTION_NOOPS(),
+        NULL,
+        0,
+        NULL,
+        NULL
+   };
+
+   const Eo_Class *klass = eo_class_new(&class_desc, EO_CLASS, NULL);
+   fail_if(!klass);
+
+   /* Check unref interception */
+   intercepted = EINA_FALSE;
+   Eo *obj = eo_add(klass, NULL);
+   fail_if(!obj);
+   fail_if(!eo_isa(obj, klass));
+   eo_del_intercept_set(obj, _del_intercept);
+   eo_unref(obj);
+   fail_if(!intercepted);
+   fail_if(eo_isa(obj, klass));
+
+   /* Check del interception */
+   intercepted = EINA_FALSE;
+   obj = eo_add(klass, NULL);
+   fail_if(!obj);
+   fail_if(!eo_isa(obj, klass));
+   eo_del_intercept_set(obj, _del_intercept);
+   eo_del(obj);
+   fail_if(!intercepted);
+   fail_if(eo_isa(obj, klass));
+
+   eo_shutdown();
+#endif
+}
+END_TEST
+
 void eo_test_general(TCase *tc)
 {
    tcase_add_test(tc, eo_simple);
@@ -967,4 +1021,5 @@ void eo_test_general(TCase *tc)
    tcase_add_test(tc, eo_add_do_and_custom);
    tcase_add_test(tc, eo_pointers_indirection);
    tcase_add_test(tc, eo_add_failures);
+   tcase_add_test(tc, eo_del_intercept);
 }