Cancels a future. More...
Data Structures | |
struct | _Eina_Future_Race_Result |
Functions | |
void | eina_future_cancel (Eina_Future *f) |
void | eina_future_desc_flush (Eina_Future_Desc *desc) |
Flushes an #Eina_Future_Desc. More... | |
void | eina_future_cb_easy_desc_flush (Eina_Future_Cb_Easy_Desc *desc) |
Flushes an #Eina_Future_Cb_Easy_Desc. More... | |
Eina_Value | eina_promise_as_value (Eina_Promise *p) |
Creates a new Eina_Value from a promise. More... | |
Eina_Value | eina_future_as_value (Eina_Future *f) |
Creates an Eina_Value from a future. More... | |
Eina_Future * | eina_future_new (Eina_Promise *p) |
Creates a new future. More... | |
Eina_Future * | eina_future_resolved (Eina_Future_Scheduler *scheduler, Eina_Value value) |
Creates a new future that is already resolved to a value. More... | |
Eina_Future * | eina_future_rejected (Eina_Future_Scheduler *scheduler, Eina_Error err) |
Creates a new future that is already rejected to a specified error. More... | |
Eina_Future * | eina_future_then_from_desc (Eina_Future *prev, const Eina_Future_Desc desc) |
Register an Eina_Future_Desc to be used when the future is resolve/rejected. More... | |
Eina_Future_Desc | eina_future_cb_log_from_desc (const Eina_Future_Cb_Log_Desc desc) |
Creates an Eina_Future_Desc that will log the previous future resolved value. More... | |
Eina_Future * | eina_future_chain_array (Eina_Future *prev, const Eina_Future_Desc descs[]) |
Creates a future chain. More... | |
Eina_Future * | eina_future_chain_easy_array (Eina_Future *prev, const Eina_Future_Cb_Easy_Desc descs[]) |
Wrapper around eina_future_chain_array() and eina_future_cb_easy_from_desc() More... | |
Eina_Future_Desc | eina_future_cb_console_from_desc (const Eina_Future_Cb_Console_Desc desc) |
Creates an Eina_Future_Desc that will print the previous future resolved value. More... | |
Eina_Future_Desc | eina_future_cb_ignore_error (Eina_Error err) |
Returns a #Eina_Future_Desc that ignores an error. More... | |
Eina_Future_Desc | eina_future_cb_convert_to (const Eina_Value_Type *type) |
Creates an #Eina_Future_Desc which will convert the the received eina value to a given type. More... | |
Eina_Future_Desc | eina_future_cb_easy_from_desc (const Eina_Future_Cb_Easy_Desc desc) |
Creates an #Eina_Future_Desc based on a #Eina_Future_Cb_Easy_Desc. More... | |
Eina_Promise * | eina_promise_all_array (Eina_Future *array[]) |
Creates an all promise. More... | |
Eina_Promise * | eina_promise_race_array (Eina_Future *array[]) |
Creates a race promise. More... | |
static Eina_Future * | eina_future_all_array (Eina_Future *array[]) |
Creates a future that will be resolved once all futures from array is resolved. More... | |
static Eina_Future * | eina_future_race_array (Eina_Future *array[]) |
Creates a future that will be resolved once a future array is resolved. More... | |
Variables | |
const Eina_Value_Struct_Desc * | EINA_PROMISE_RACE_STRUCT_DESC |
const EAPI Eina_Value_Struct_Desc * | EINA_PROMISE_RACE_STRUCT_DESC = &RACE_STRUCT_DESC |
Cancels a future.
This function will cancel the whole future chain immediately (it will not be schedule to the next mainloop pass) and it will also cancel the promise linked against it. The Eina_Future_Cb will be called with an Eina_Value typed as EINA_VALUE_TYPE_ERROR, which its value will be ECANCELED
[in,out] | f | The future to cancel. |
#define EINA_FUTURE_SENTINEL ((void *)(unsigned long)-1) |
Used by eina_promise_race_array() and eina_promise_all_array() and friends to flag the end of the array.
#define eina_promise_race | ( | ... | ) | eina_promise_race_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL}) |
A syntactic sugar over eina_promise_race_array().
Usage:
#define eina_future_race | ( | ... | ) | eina_future_race_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL}) |
A syntactic sugar over eina_future_race_array().
Usage:
#define eina_future_all | ( | ... | ) | eina_future_all_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL}) |
A syntactic sugar over eina_future_all_array().
Usage:
#define eina_promise_all | ( | ... | ) | eina_promise_all_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL}) |
A syntactic sugar over eina_promise_all_array().
Usage:
#define eina_future_cb_easy | ( | ... | ) | eina_future_cb_easy_from_desc((Eina_Future_Cb_Easy_Desc){__VA_ARGS__}) |
A syntactic sugar over eina_future_cb_easy_from_desc().
Usage:
#define eina_future_chain | ( | _prev, | |
... | |||
) | eina_future_chain_array(_prev, (Eina_Future_Desc[]){__VA_ARGS__, {.cb = NULL, .data = NULL}}) |
A syntactic sugar over eina_future_chain_array().
Usage:
#define eina_future_then | ( | _prev, | |
... | |||
) | eina_future_then_from_desc(_prev, (Eina_Future_Desc){__VA_ARGS__}) |
A syntactic sugar over eina_future_then_from_desc().
Usage:
#define eina_future_cb_console | ( | ... | ) | eina_future_cb_console_from_desc((Eina_Future_Cb_Console_Desc){__VA_ARGS__}) |
#define eina_future_cb_log_dbg | ( | _prefix, | |
_suffix | |||
) |
A syntactic sugar over eina_future_cb_log_from_desc().
This macro will set the following fields of the #Eina_Future_Cb_Log_Desc:
Usage:
#define eina_future_cb_log_crit | ( | _prefix, | |
_suffix | |||
) |
A syntactic sugar over eina_future_cb_log_from_desc().
This macro will set the following fields of the #Eina_Future_Cb_Log_Desc:
Usage:
#define eina_future_cb_log_err | ( | _prefix, | |
_suffix | |||
) |
A syntactic sugar over eina_future_cb_log_from_desc().
This macro will set the following fields of the #Eina_Future_Cb_Log_Desc:
Usage:
#define eina_future_cb_log_info | ( | _prefix, | |
_suffix | |||
) |
A syntactic sugar over eina_future_cb_log_from_desc().
This macro will set the following fields of the #Eina_Future_Cb_Log_Desc:
Usage:
#define eina_future_cb_log_warn | ( | _prefix, | |
_suffix | |||
) |
A syntactic sugar over eina_future_cb_log_from_desc().
This macro will set the following fields of the #Eina_Future_Cb_Log_Desc:
Usage:
#define eina_future_then_easy | ( | _prev, | |
... | |||
) | eina_future_then_from_desc(_prev, eina_future_cb_easy(__VA_ARGS__)) |
A syntactic sugar over eina_future_then() and eina_future_cb_easy().
Usage:
#define eina_future_chain_easy | ( | _prev, | |
... | |||
) | eina_future_chain_easy_array(_prev, (Eina_Future_Cb_Easy_Desc[]) {__VA_ARGS__, {NULL, NULL, NULL, NULL, NULL}}) |
A syntactic sugar over eina_future_chain() and eina_future_cb_easy().
Usage:
void eina_future_desc_flush | ( | Eina_Future_Desc * | desc | ) |
Flushes an #Eina_Future_Desc.
This function is mainly used by bindings to flush a #Eina_Future_Desc. It will call the Eina_Future_Cb with ENOMEM
and zero the desc
contents.
[in,out] | desc | The #Eina_Future_Desc to flush, if NULL this is a noop. |
void eina_future_cb_easy_desc_flush | ( | Eina_Future_Cb_Easy_Desc * | desc | ) |
Flushes an #Eina_Future_Cb_Easy_Desc.
This function is mainly used by bindings to flush a #Eina_Future_Cb_Easy_Desc. It will call the Eina_Future_Error_Cb with ENOMEM
, the Eina_Future_Free_Cb and zero the desc
contents.
[in,out] | desc | The #Eina_Future_Cb_Easy_Desc to flush, if NULL this is a noop. |
References _Eina_Future_Cb_Easy_Desc::data, eina_value_flush(), _Eina_Future_Cb_Easy_Desc::error, and _Eina_Future_Cb_Easy_Desc::free.
Eina_Value eina_promise_as_value | ( | Eina_Promise * | p | ) |
Creates a new Eina_Value from a promise.
This function creates a new Eina_Value that will store a promise in it. This function is useful for dealing with promises inside a Eina_Future_Cb. By returning a Promise Eina_Value the whole chain will wait until the promise is resolved in order to continue its execution. Example:
[in,out] | p | The promise obect to create the value from. |
NULL
.References DBG, EINA_SAFETY_ON_FALSE_GOTO, EINA_VALUE_EMPTY, eina_value_flush(), eina_value_pset(), and eina_value_setup().
Eina_Value eina_future_as_value | ( | Eina_Future * | f | ) |
Creates an Eina_Value from a future.
This function is used for the same purposes as eina_promise_as_value(), but receives an Eina_Future instead.
[in,out] | f | A future to create a Eina_Value from. |
NULL
. f
will be CANCELED References EINA_VALUE_EMPTY.
Eina_Future* eina_future_new | ( | Eina_Promise * | p | ) |
Creates a new future.
This function creates a new future and can be used to report that an operation has succeeded or failed using eina_promise_resolve() or eina_promise_reject().
Futures can also be canceled using eina_future_cancel(), which will cause the whole chain to be canceled alongside with any pending promise.
NULL
is returned) and the future attached to the promise will be canceled![in,out] | p | A promise used to attach a future. May not be NULL . |
NULL
on error. References _Eina_Future_Desc::cb, and EINA_SAFETY_ON_TRUE_GOTO.
Referenced by eina_future_all_array(), and eina_future_race_array().
Eina_Future* eina_future_resolved | ( | Eina_Future_Scheduler * | scheduler, |
Eina_Value | value | ||
) |
Creates a new future that is already resolved to a value.
This function creates a new future with an already known value, that will be resolved and dispatched by the given scheduler as usual.
This is a helper that behaves the same as eina_promise_new() followed by eina_future_new() and then eina_promise_resolve().
Futures can also be canceled using eina_future_cancel(), which will cause the whole chain to be canceled alongside with any pending promise.
[in,out] | scheduler | The scheduler to use. |
[in] | value | The value to be delivered. Note that the value contents must survive this function scope, that is, do not use stack allocated blobs, arrays, structures or types that keep references to memory you give. Values will be automatically cleaned up using eina_value_flush() once they are unused (no more future or futures returned a new value). |
NULL
on error.References EINA_SAFETY_ON_NULL_GOTO.
Eina_Future* eina_future_rejected | ( | Eina_Future_Scheduler * | scheduler, |
Eina_Error | err | ||
) |
Creates a new future that is already rejected to a specified error.
This function creates a new future with an already known error, that will be resolved and dispatched by the given scheduler as usual.
This is a helper that behaves the same as eina_promise_new() followed by eina_future_new() and then eina_promise_rejected().
Futures can also be canceled using eina_future_cancel(), which will cause the whole chain to be canceled alongside with any pending promise.
[in,out] | scheduler | The scheduler to use. |
[in] | err | An Eina_Error value |
NULL
on error.References EINA_SAFETY_ON_NULL_GOTO.
Eina_Future* eina_future_then_from_desc | ( | Eina_Future * | prev, |
const Eina_Future_Desc | desc | ||
) |
Register an Eina_Future_Desc to be used when the future is resolve/rejected.
With this function a callback and data is attached to the future and then once it's resolved or rejected the callback will be informed.
If during the future creation an error happens this function will return NULL
, and the Eina_Future_Desc::cb will be called reporting an error (EINVAL
or ENOMEM
), so the user has a chance to free Eina_Future_Desc::data.
In case a future in the chain is canceled, the whole chain will be canceled immediately and the error ECANCELED
will be reported.
Here's a simple usage of this function.
Although the code presented at _size_ready()
is very simple, most of it is just used to check the Eina_Value type. In order to avoid this type of code the function eina_future_cb_easy_from_desc() was created. Please, check its documentation for more information.
This function can also be used to create a future chain, making it possible to execute the future result in a cascade order. When using a future chain the Eina_Value returned by a Eina_Future_Desc::cb will be delivered to the next Eina_Future_Desc::cb in the chain.
Here's an example:
static Eina_Value _future_cb1(const *data EINA_UNUSED, const Eina_Value v) { Eina_Value new_v; int i;
// There's no need to check the Eina_Value type since we're using eina_future_cb_easy() eina_value_get(&v, &i); printf("File size as int: %d\n", i); eina_value_setup(&new_v, EINA_VALUE_TYPE_STRING); // Convert the file size to string eina_value_convert(&v, &new_v); return new_v; }
static Eina_Value _future_cb2(const *data EINA_UNUSED, const Eina_Value v) { Eina_Value new_v; const char *file_size_str;
// There's no need to check the Eina_Value type since we're using eina_future_cb_easy() eina_value_get(&v, &file_size_str); printf("File size as string: %s\n", file_size_str); eina_value_setup(&new_v, EINA_VALUE_TYPE_DOUBLE); eina_value_convert(&v, &new_v); return new_v; }
static Eina_Value _future_cb3(const *data EINA_UNUSED, const Eina_Value v) { double d;
// There's no need to check the Eina_Value type since we're using eina_future_cb_easy() eina_value_get(&v, &d); printf("File size as double: %g\n", d); return v; }
static Eina_Value _future_err(void *data EINA_UNUSED, Eina_Error err) { // This function is called if future result type does not match or another error occurred Eina_Value new_v; eina_value_setup(&new_v, EINA_VALUE_TYPE_ERROR); eina_value_set(&new_v, err); fprintf(stderr, "Error during future process. Reason: %s\n", eina_error_msg_get(err)); // Pass the error to the next future in the chain.. return new_v; }
Although it's possible to create a future chain using eina_future_then()/eina_future_then_from_desc() there's a function that makes this task much easier, please check eina_future_chain_array() for more information.
[in,out] | prev | A future to link against |
[in] | desc | A description struct containing the callback and data. |
NULL
on error. References EINA_SAFETY_ON_TRUE_GOTO.
Referenced by efl_future_chain_array().
Eina_Future_Desc eina_future_cb_log_from_desc | ( | const Eina_Future_Cb_Log_Desc | desc | ) |
Creates an Eina_Future_Desc that will log the previous future resolved value.
This function can be used to quickly log the value that an Eina_Future_Desc::cb is returning. The returned value will be passed to the next future in the chain without modifications.
There are some helper macros like eina_future_cb_log_dbg() which will automatically fill the following fields:
[in] | desc | The description data to be used. |
References _Eina_Future_Cb_Log_Desc::domain, EINA_SAFETY_ON_NULL_GOTO, _Eina_Future_Cb_Log_Desc::file, _Eina_Future_Cb_Log_Desc::func, _Eina_Future_Cb_Log_Desc::level, _Eina_Future_Cb_Log_Desc::line, _Eina_Future_Cb_Log_Desc::prefix, and _Eina_Future_Cb_Log_Desc::suffix.
Eina_Future* eina_future_chain_array | ( | Eina_Future * | prev, |
const Eina_Future_Desc | descs[] | ||
) |
Creates a future chain.
This behaves exactly like eina_future_then_from_desc(), but makes it easier to create future chains.
If during the future chain creation an error happens this function will return NULL
, and the Eina_Future_Desc::cb from the descs
array will be called reporting an error (EINVAL
or ENOMEM
), so the user has a chance to free Eina_Future_Desc::data.
Just like eina_future_then_from_desc(), the value returned by a Eina_Future_Desc::cb callback will be delivered to the next Eina_Future_Desc::cb in the chain.
In case a future in the chain is canceled, the whole chain will be canceled immediately and the error ECANCELED
will be reported.
Here's an example:
[in,out] | prev | The previous future |
[in] | descs | An array of descriptions. The last element of the array must have the Eina_Future_Desc::cb set to NULL |
NULL
on error. References _Eina_Future_Desc::cb, EINA_SAFETY_ON_NULL_GOTO, and EINA_SAFETY_ON_TRUE_GOTO.
Eina_Future* eina_future_chain_easy_array | ( | Eina_Future * | prev, |
const Eina_Future_Cb_Easy_Desc | descs[] | ||
) |
Wrapper around eina_future_chain_array() and eina_future_cb_easy_from_desc()
This functions makes it easier to use eina_future_chain_array() with eina_future_cb_easy_from_desc(), check the macro eina_future_chain_easy() for a syntax sugar.
[in,out] | prev | The previous future |
[in] | descs | An array of descriptions. The last element of the array must have the Eina_Future_Desc::cb set to NULL |
NULL
on error. References eina_future_cb_easy_from_desc(), EINA_SAFETY_ON_NULL_GOTO, EINA_SAFETY_ON_TRUE_GOTO, eina_value_flush(), _Eina_Future_Cb_Easy_Desc::error, _Eina_Future_Cb_Easy_Desc::free, _Eina_Future_Cb_Easy_Desc::success, and _Eina_Future_Cb_Easy_Desc::success_type.
Eina_Future_Desc eina_future_cb_console_from_desc | ( | const Eina_Future_Cb_Console_Desc | desc | ) |
Creates an Eina_Future_Desc that will print the previous future resolved value.
This function can be used to quickly inspect the value that an Eina_Future_Desc::cb is returning. The returned value will be passed to the next future in the chain without modifications.
There's also a helper macro called eina_future_cb_console() which makes this function easier to use.
Example:
[in] | desc | Description object with contextual information. |
The description object, desc
, can (optionally) include a prefix, suffix, filename and function name. If these are NULL
, empty strings ("") are used instead. If desc->suffix
is provided, the '
' should be provided to ensure the printed string ends with a line feed.
References _Eina_Future_Desc::cb, _Eina_Future_Desc::data, EINA_SAFETY_ON_NULL_GOTO, _Eina_Future_Cb_Console_Desc::prefix, and _Eina_Future_Cb_Console_Desc::suffix.
Eina_Future_Desc eina_future_cb_ignore_error | ( | Eina_Error | err | ) |
Returns a #Eina_Future_Desc that ignores an error.
This function may be used if one wants to ignore an error. If the specified error happens an EINA_VALUE_EMPTY will be delivered to the next future in the chain.
[in] | err | The error to be ignored. |
Eina_Future_Desc eina_future_cb_convert_to | ( | const Eina_Value_Type * | type | ) |
Creates an #Eina_Future_Desc which will convert the the received eina value to a given type.
[in] | type | The Eina_Value_Type to convert to. |
References _Eina_Future_Desc::cb.
Eina_Future_Desc eina_future_cb_easy_from_desc | ( | const Eina_Future_Cb_Easy_Desc | desc | ) |
Creates an #Eina_Future_Desc based on a #Eina_Future_Cb_Easy_Desc.
This function aims to be used in conjunction with eina_future_chain(), eina_future_then_from_desc() and friends and its main objective is to simplify error handling and Eina_Value type checks. It uses three callbacks to inform the user about the future's result and life cycle. They are:
NULL
, this function will only be called if the future did not report an error. The value returned by this function will be propagated to the next future in the chain (if any).Check the example below for a sample usage:
[in] | desc | The easy callback's description. |
References EINA_SAFETY_ON_NULL_GOTO.
Referenced by eina_future_chain_easy_array().
Eina_Promise* eina_promise_all_array | ( | Eina_Future * | array[] | ) |
Creates an all promise.
Creates a promise that is resolved once all the futures from the array
are resolved. The promise is resolved with an Eina_Value type array which contains EINA_VALUE_TYPE_VALUE elements. The result array is ordered according to the array
argument. Example:
[in,out] | array | An array of futures, EINA_FUTURE_SENTINEL terminated. |
NULL
on error. References eina_mempool_free(), EINA_SAFETY_ON_FALSE_GOTO, EINA_SAFETY_ON_NULL_GOTO, EINA_SAFETY_ON_NULL_RETURN_VAL, eina_value_array_append(), eina_value_array_setup(), eina_value_flush(), eina_value_setup(), EINA_VALUE_TYPE_INT, and EINA_VALUE_TYPE_VALUE.
Referenced by eina_future_all_array().
Eina_Promise* eina_promise_race_array | ( | Eina_Future * | array[] | ) |
Creates a race promise.
Creates a promise that resolves when a future from the array
is completed. The remaining futures will be canceled with the error code ECANCELED
The resulting value is an EINA_VALUE_TYPE_STRUCT with two fields:
array
;Example.
[in,out] | array | An array of futures, EINA_FUTURE_SENTINEL terminated. |
NULL
on error. References EINA_SAFETY_ON_FALSE_GOTO, EINA_SAFETY_ON_NULL_GOTO, and EINA_SAFETY_ON_NULL_RETURN_VAL.
Referenced by eina_future_race_array().
|
inlinestatic |
Creates a future that will be resolved once all futures from array
is resolved.
This is a helper over eina_promise_all_array()
[in,out] | array | A future array, must be terminated with EINA_FUTURE_SENTINEL |
References eina_future_new(), and eina_promise_all_array().
|
inlinestatic |
Creates a future that will be resolved once a future array
is resolved.
This is a helper over eina_promise_race_array()
[in,out] | array | A future array, must be terminated with EINA_FUTURE_SENTINEL |
References eina_future_new(), and eina_promise_race_array().
const Eina_Value_Struct_Desc* EINA_PROMISE_RACE_STRUCT_DESC |
A pointer to the race struct description, which is used by eina_promise_race_array();
This struct contains two members:
EINA_PROMISE_RACE_STRUCT_DESC = &RACE_STRUCT_DESC |
A pointer to the race struct description, which is used by eina_promise_race_array();
This struct contains two members: