forked from enlightenment/efl
efl: add documentation and last cleanup of the API.
This commit is contained in:
parent
0c067fb62f
commit
bd362b13d6
|
@ -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);
|
||||
}
|
||||
|
|
|
@ -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.]]
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
@ -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;
|
||||
}
|
||||
|
||||
|
|
|
@ -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
|
||||
*
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue