cedric pushed a commit to branch master.
http://git.enlightenment.org/core/efl.git/commit/?id=bd362b13d656e779f4851d57257bf04883b34ba8
commit bd362b13d656e779f4851d57257bf04883b34ba8
Author: Cedric BAIL <ced...@osg.samsung.com>
Date: Thu Sep 8 14:51:13 2016 -0700
efl: add documentation and last cleanup of the API.
---
src/lib/ecore/efl_promise.c | 10 ++++----
src/lib/ecore/efl_promise.eo | 45 +++++++++++++++++++++++---------
src/lib/eio/efl_io_manager.c | 6 ++---
src/lib/eo/efl_future.h | 50 +++++++++++++++++++++++++++++-------
src/tests/ecore/ecore_test_promise.c | 2 +-
5 files changed, 83 insertions(+), 30 deletions(-)
diff --git a/src/lib/ecore/efl_promise.c b/src/lib/ecore/efl_promise.c
index 6ef7691..53c79ed 100644
--- a/src/lib/ecore/efl_promise.c
+++ b/src/lib/ecore/efl_promise.c
@@ -535,7 +535,7 @@ _efl_promise_value_set(Eo *obj, Efl_Promise_Data *pd, void
*v, Eina_Free_Cb free
}
static void
-_efl_promise_failed(Eo *obj, Efl_Promise_Data *pd, Eina_Error err)
+_efl_promise_failed_set(Eo *obj, Efl_Promise_Data *pd, Eina_Error err)
{
Efl_Promise_Msg *message;
Efl_Loop_Future_Data *f;
@@ -576,7 +576,7 @@ _efl_promise_failed(Eo *obj, Efl_Promise_Data *pd,
Eina_Error err)
}
static void
-_efl_promise_progress_set(Eo *obj, Efl_Promise_Data *pd, void *p)
+_efl_promise_progress_set(Eo *obj, Efl_Promise_Data *pd, const void *p)
{
Efl_Loop_Future_Data *f;
Eina_List *l, *ln;
@@ -620,7 +620,7 @@ _efl_promise_efl_object_destructor(Eo *obj,
Efl_Promise_Data *pd)
if (!pd->message && pd->futures)
{
if (!pd->optional) ERR("This promise has not been fulfilled.
Forcefully cancelling %p.", obj);
- efl_promise_failed(obj, EINA_ERROR_FUTURE_CANCEL);
+ efl_promise_failed_set(obj, EINA_ERROR_FUTURE_CANCEL);
}
if (pd->message)
@@ -916,7 +916,7 @@ _fail_all(void *data, const Efl_Event *ev)
}
}
- efl_promise_failed(all->promise, fail->error);
+ efl_promise_failed_set(all->promise, fail->error);
_efl_promise_all_free(all);
efl_unref(all->promise);
}
@@ -1128,7 +1128,7 @@ _fail_race(void *data, const Efl_Event *ev)
}
}
- efl_promise_failed(race->promise, fail->error);
+ efl_promise_failed_set(race->promise, fail->error);
_efl_promise_all_free(race);
efl_unref(race->promise);
}
diff --git a/src/lib/ecore/efl_promise.eo b/src/lib/ecore/efl_promise.eo
index 7d3b348..e78cad8 100644
--- a/src/lib/ecore/efl_promise.eo
+++ b/src/lib/ecore/efl_promise.eo
@@ -3,32 +3,53 @@ import eina_types;
class Efl.Promise (Efl.Loop_User)
{
methods {
- @property progress {
- set {
- }
- values {
- p: void_ptr;
+ progress_set {
+ [[Update the progress and send it immediately to all connected
Efl_Future.
+
+ The progress is not kept and when the function return it will not
be accessed
+ anymore. The pointer is owned by the caller and will remain so
after the return
+ of the function call.
+ ]]
+ params {
+ @in p: const(void_ptr);
}
}
@property future {
+ [[Request a new future linked to this promise.
+
+ Efl_Future are optional and will be automatically deleted if no then
callback have
+ been set before the next iteration of the main loop.
+ ]]
get {
- [[The returned future is optional and if no then/chain_then are
registered before it goes back to run in the main loop, it will be destroyed.]]
+ [[The returned new future.]]
}
values {
- f: future<void_ptr>;
+ f: future<void_ptr, void_ptr>; [[Return a future where the value
will be set by calling value_set while the progress will be updated by
progress_set.]]
}
}
@property value {
+ [[The value expected by all connected future.]]
set {
+ [[
+ This function can be called only once and you can not call
#failed.set after that.
+ The value will be owned by the promise until it is destroyed.
The value will be cleaned
+ when the promise and all the future depending on it are
destroyed.
+ ]]
}
values {
- v: void_ptr;
- free_cb: __builtin_free_cb;
+ v: void_ptr; [[The pointer to the value.]]
+ free_cb: __builtin_free_cb; [[The function to call to free the
value.]]
}
}
- failed {
- params {
- @in err: Eina.Error;
+ @property failed {
+ [[Define the failure state of this promise.]]
+ set {
+ [[
+ This function can be called only once and you can not call
#value.set after that.
+ ]]
+ }
+ values {
+ err: Eina.Error; [[The reason for failure of this promise.]]
}
}
}
diff --git a/src/lib/eio/efl_io_manager.c b/src/lib/eio/efl_io_manager.c
index fba276c..1d6d3fb 100644
--- a/src/lib/eio/efl_io_manager.c
+++ b/src/lib/eio/efl_io_manager.c
@@ -111,7 +111,7 @@ _file_error_cb(void *data, Eio_File *handler, int error)
efl_event_callback_array_del(p, promise_handling(), handler);
- efl_promise_failed(p, error);
+ efl_promise_failed_set(p, error);
efl_del(p);
}
@@ -126,7 +126,7 @@ _file_done_cb(void *data, Eio_File *handler)
if (!v)
{
- efl_promise_failed(p, ENOMEM);
+ efl_promise_failed_set(p, ENOMEM);
goto end;
}
@@ -365,7 +365,7 @@ _file_stat_done_cb(void *data, Eio_File *handle
EINA_UNUSED, const Eina_Stat *st
c = calloc(1, sizeof (Eina_Stat));
if (!c)
{
- efl_promise_failed(p, ENOMEM);
+ efl_promise_failed_set(p, ENOMEM);
goto end;
}
diff --git a/src/lib/eo/efl_future.h b/src/lib/eo/efl_future.h
index 243d660..78dc273 100644
--- a/src/lib/eo/efl_future.h
+++ b/src/lib/eo/efl_future.h
@@ -15,36 +15,65 @@ typedef Eo Efl_Promise;
#define EFL_FUTURE_CLASS efl_future_class_get()
EWAPI const Efl_Class *efl_future_class_get(void);
+/**
+ * @var EINA_ERROR_FUTURE_CANCEL
+ * @brief The error identifier corresponding to a future being canceled.
+ */
EAPI extern Eina_Error EINA_ERROR_FUTURE_CANCEL;
+/** Parameter passed in event callbacks in case of future failure to proceed.
+ *
+ * @ingroup Efl_Future
+ */
typedef struct _Efl_Future_Event_Failure Efl_Future_Event_Failure;
struct _Efl_Future_Event_Failure
{
- Efl_Promise *next;
- Eina_Error error;
+ Efl_Promise *next; /** The promise to the next future. Allowing to send a
processed value down the chain. */
+ Eina_Error error; /** The error generated trying to process the request. */
};
+/** Parameter passed in event callbacks in case of future succeeding to
proceed.
+ *
+ * @ingroup Efl_Future
+ */
typedef struct _Efl_Future_Event_Success Efl_Future_Event_Success;
struct _Efl_Future_Event_Success
{
- Efl_Promise *next;
- void *value;
+ Efl_Promise *next; /** The promise to the next future. Allowing to send a
processed value down the chain. */
+ void *value; /** The value return by the processed request. The type is
defined by the function executing the request. */
};
+/** Parameter passed in event callbacks while a future is progressing a
request.
+ *
+ * @ingroup Efl_Future
+ */
typedef struct _Efl_Future_Event_Progress Efl_Future_Event_Progress;
struct _Efl_Future_Event_Progress
{
- Efl_Promise *next;
- void *progress;
+ Efl_Promise *next; /** The promise to the next future. Allowing to send a
processed progress down the chain. */
+ const void *progress; /** The progress status updated by the processed
request. The type is defined by the function executing the request. */
};
EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_FAILURE;
EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_SUCCESS;
EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_PROGRESS;
- // FIXME: documentation
+/** A future failed
+ *
+ * @ingroup Efl_Future
+ */
#define EFL_FUTURE_EVENT_FAILURE (&(_EFL_FUTURE_EVENT_FAILURE))
+
+/** A future succeeded
+ *
+ * @ingroup Efl_Future
+ */
#define EFL_FUTURE_EVENT_SUCCESS (&(_EFL_FUTURE_EVENT_SUCCESS))
+
+/** A future progressed
+ *
+ * @ingroup Efl_Future
+ */
#define EFL_FUTURE_EVENT_PROGRESS (&(_EFL_FUTURE_EVENT_PROGRESS))
/**
@@ -57,7 +86,9 @@ EOAPI extern const Efl_Event_Description
_EFL_FUTURE_EVENT_PROGRESS;
* @param[in] progress the callback to call during the progression of the the
promise, this is optional
* @param[in] data additional data to pass to the callback
*
- * @return Return a new future when the callback has been successfully added.
This future can be ignored.
+ * @return Return a new future when the callback has been successfully added
pointing to the next request
+ * being processed during the future success, failure or progress callback
(You can reference count the next
+ * promise to defer the result and make it asynchronous too. This future can
be ignored.
*
* @note except if you do reference count the Efl.Future object, you can only
call once this function.
*
@@ -68,7 +99,8 @@ EOAPI Efl_Future *efl_future_then(Eo *obj, Efl_Event_Cb
success, Efl_Event_Cb fa
/**
* @brief Cancel the need for that specific future.
*
- * This will trigger the failure of the future and may result in the promise
stopping its computation.
+ * This will trigger the failure of the future and may result in the promise
stopping its computation as
+ * it will be notified when there is no more need for computing the request.
*
* @see efl_future_use
*
diff --git a/src/tests/ecore/ecore_test_promise.c
b/src/tests/ecore/ecore_test_promise.c
index 0f35ac0..16c100a 100644
--- a/src/tests/ecore/ecore_test_promise.c
+++ b/src/tests/ecore/ecore_test_promise.c
@@ -605,7 +605,7 @@ _chain_fail(void *data, const Efl_Event *ev)
fo->cancel = EINA_TRUE;
- efl_promise_failed(f->next, f->error);
+ efl_promise_failed_set(f->next, f->error);
}
static void
--
