eolian: start to express ownership transfere

before @owned was not even expressed in the api definitions of the
generated APIs, this adds support for it.

@owned is now expressed with EFL_TRANSFER_OWNERSHIP in a arguments. And
that preprocessor directive is documented.

Reviewed-by: Daniel Kolesa <daniel@octaforge.org>
Differential Revision: https://phab.enlightenment.org/D9369

src/bin/eolian/headers.c

@@ -35,6 +35,8 @@ _gen_param(Eina_Strbuf *buf, Eolian_Function_Parameter *pr,
    eina_strbuf_append(buf, _get_add_star(ftype, eolian_parameter_direction_get(pr)));
    eina_strbuf_append(buf, prn);
    eina_stringshare_del(prtn);
+   if (eolian_type_is_owned(eolian_parameter_type_get(pr)))
+     eina_strbuf_append(buf, " EFL_TRANSFER_OWNERSHIP");
    *rpid = 0;
    return 1;
 }
@@ -166,6 +168,8 @@ _gen_func(const Eolian_State *state, const Eolian_Function *fid,
           flagbuf = eina_strbuf_new();
         eina_strbuf_prepend(flagbuf, " EINA_WARN_UNUSED_RESULT");
      }
+   if (rtp && eolian_type_is_owned(rtp))
+     eina_strbuf_append(buf, " EFL_TRANSFER_OWNERSHIP");
    if (flagbuf)
      {
         eina_strbuf_append(buf, eina_strbuf_string_get(flagbuf));

src/lib/eo/Eo.h

@@ -212,6 +212,19 @@ EAPI extern unsigned int _efl_object_init_generation;
  */
 typedef void (*Efl_Del_Intercept) (Eo *obj_id);
 
+/**
+ * This is a no-operation. Its presence behind a function parameter indicates that
+ * ownership of the parameter is transferred to the callee.
+ * When present after a method, it indicates that the return value of the method is
+ * transferred to the caller.
+ * For objects, ownership transfer means that exactly one reference is transferred.
+ * If you transfer ownership without owning a reference in the first place, you will
+ * get unexpected behavior.
+ * For non-Objects, ownership transfer means that the responsibility of freeing a
+ * segment of memory is passed on.
+ */
+#define EFL_TRANSFER_OWNERSHIP
+
 #include "efl_object_override.eo.h"
 #include "efl_object.eo.h"
 
@@ -2369,6 +2382,7 @@ EAPI Eina_Iterator *eo_objects_iterator_new(void);
  * @return EINA_TRUE if the object is ownable. EINA_FALSE if not.
  */
 EAPI Eina_Bool efl_ownable_get(const Eo *obj);
+
 /**
  * @}
  */

src/tests/eolian/data/function_as_argument_ref.h

@@ -19,6 +19,6 @@ EWAPI const Efl_Class *function_as_argument_class_get(void);
 
 EOAPI void function_as_argument_set_cb(Eo *obj, void *cb_data, SimpleFunc cb, Eina_Free_Cb cb_free_cb);
 
-EOAPI char *function_as_argument_call_cb(Eo *obj, int a, double b);
+EOAPI char *function_as_argument_call_cb(Eo *obj, int a, double b) EFL_TRANSFER_OWNERSHIP;
 
 #endif

src/tests/eolian/data/function_types_ref.h

@@ -8,7 +8,7 @@ typedef void (*VoidFunc)(void *data);
 
 typedef const char * (*SimpleFunc)(void *data, int a, double b);
 
-typedef double (*ComplexFunc)(void *data, const char *c, char **d);
+typedef double (*ComplexFunc)(void *data, const char *c, char **d EFL_TRANSFER_OWNERSHIP);
 
 typedef void (*FuncAsArgFunc)(void *data, void *cb_data, VoidFunc cb, Eina_Free_Cb cb_free_cb, void *another_cb_data, SimpleFunc another_cb, Eina_Free_Cb another_cb_free_cb);
 

src/tests/eolian/data/struct_ref.h

@@ -38,7 +38,7 @@ EWAPI const Efl_Class *struct_class_get(void);
  *
  * @ingroup Struct
  */
-EOAPI char *struct_foo(Eo *obj, int idx);
+EOAPI char *struct_foo(Eo *obj, int idx) EFL_TRANSFER_OWNERSHIP;
 
 EOAPI Named *struct_bar(Eo *obj);
 

src/tests/eolian/data/typedef_ref.h

@@ -43,6 +43,6 @@ typedef enum
 
 EWAPI const Efl_Class *typedef_class_get(void);
 
-EOAPI char *typedef_foo(Eo *obj, int idx);
+EOAPI char *typedef_foo(Eo *obj, int idx) EFL_TRANSFER_OWNERSHIP;
 
 #endif