Eina Futures

Modules | Data Structures | Macros | Typedefs | Functions | Variables
Eina Futures
Eina » Eina Promises

Methods and structures dealing with Eina_Future. More...

## Modules
| Eina Future Callbacks
| Methods and structures dealing with Eina_Future callbacks.

## Data Structures
struct | _Eina_Future_Race_Result
| The struct that is used to store the race result. More...
struct | Eina_Future
| An opaque structure representing a callback to be called when a promise is fulfilled. More...
struct | _Eina_Future_Desc
| A struct used to define a callback and data for a future. More...

## Macros
#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. More...
#define | eina_promise_race(...) eina_promise_race_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})
| A syntactic sugar over eina_promise_race_array(). More...
#define | eina_future_race(...) eina_future_race_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})
| A syntactic sugar over eina_future_race_array(). More...
#define | eina_future_all(...) eina_future_all_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})
| A syntactic sugar over eina_future_all_array(). More...
#define | eina_promise_all(...) eina_promise_all_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})
| A syntactic sugar over eina_promise_all_array(). More...
#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(). More...
#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(). More...
#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(). More...
#define | eina_future_cb_console(...) eina_future_cb_console_from_desc((Eina_Future_Cb_Console_Desc){__VA_ARGS__})
| A syntactic sugar over eina_future_cb_console_from_desc(). More...
#define | eina_future_cb_log_dbg(_prefix, _suffix)
| A syntactic sugar over eina_future_cb_log_from_desc(). More...
#define | eina_future_cb_log_crit(_prefix, _suffix)
| A syntactic sugar over eina_future_cb_log_from_desc(). More...
#define | eina_future_cb_log_err(_prefix, _suffix)
| A syntactic sugar over eina_future_cb_log_from_desc(). More...
#define | eina_future_cb_log_info(_prefix, _suffix)
| A syntactic sugar over eina_future_cb_log_from_desc(). More...
#define | eina_future_cb_log_warn(_prefix, _suffix)
| A syntactic sugar over eina_future_cb_log_from_desc(). More...
#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(). More...
#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(). More...

## Typedefs
typedef struct _Eina_Future_Desc | Eina_Future_Desc
| Convenience wrapper over _Eina_Future_Desc.
typedef struct _Eina_Future_Race_Result | Eina_Future_Race_Result
| Convenience wrapper over _Eina_Future_Race_Result.

## Functions
EINA_API void | eina_future_cancel (Eina_Future *f)
| Cancels a future. More...
EINA_API void | eina_future_desc_flush (Eina_Future_Desc *desc)
| Flushes an Eina_Future_Desc. More...
EINA_API void | eina_future_cb_easy_desc_flush (Eina_Future_Cb_Easy_Desc *desc)
| Flushes an Eina_Future_Cb_Easy_Desc. More...
EINA_API Eina_Value | eina_promise_as_value (Eina_Promise *p)
| Creates a new Eina_Value from a promise. More...
EINA_API Eina_Value | eina_future_as_value (Eina_Future *f)
| Creates an Eina_Value from a future. More...
EINA_API Eina_Future * | eina_future_new (Eina_Promise *p)
| Creates a new future. More...
EINA_API 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_API 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_API 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 resolved/rejected. More...
EINA_API 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_API Eina_Future * | eina_future_chain_array (Eina_Future *prev, const Eina_Future_Desc descs[])
| Creates a future chain. More...
EINA_API 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_API 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's resolved value. More...
EINA_API Eina_Future_Desc | eina_future_cb_ignore_error (Eina_Error err)
| Returns an Eina_Future_Desc that ignores an error. More...
EINA_API Eina_Future_Desc | eina_future_cb_convert_to (const Eina_Value_Type *type)
| Creates an Eina_Future_Desc which will convert the received eina value to a given type. More...
EINA_API Eina_Future_Desc | eina_future_cb_easy_from_desc (const Eina_Future_Cb_Easy_Desc desc)
| Creates an Eina_Future_Desc based on an Eina_Future_Cb_Easy_Desc. More...
EINA_API Eina_Promise * | eina_promise_all_array (Eina_Future *array[])
| Creates an all promise. More...
EINA_API Eina_Promise * | eina_promise_all_iterator (Eina_Iterator *iterator)
| Creates an all promise from an iterator. More...
EINA_API 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_all_iterator (Eina_Iterator *iterator)
| Creates a future that will be resolved once all futures from `iterator` are 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
EINA_API 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(). More...

## Detailed Description

Methods and structures dealing with Eina_Future.

## Macro Definition Documentation

## ◆ EINA_FUTURE_SENTINEL

#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.

See also
  eina_promise_race_array()
  eina_promise_all_array()

## ◆ eina_promise_race

#define eina_promise_race | ( |  | ... | ) | eina_promise_race_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})

A syntactic sugar over eina_promise_race_array().

Usage:

promise = eina_promise_race(future1, future2, future3, future4);
eina_promise_race
#define eina_promise_race(...)
A syntactic sugar over eina_promise_race_array().
Definition: eina_promise.h:1683

See also
  eina_promise_race_array()

## ◆ eina_future_race

#define eina_future_race | ( |  | ... | ) | eina_future_race_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})

A syntactic sugar over eina_future_race_array().

Usage:

future = eina_future_race(future1, future2, future3, future4);
eina_future_race
#define eina_future_race(...)
A syntactic sugar over eina_future_race_array().
Definition: eina_promise.h:1692

See also
  eina_future_race_array()

## ◆ eina_future_all

#define eina_future_all | ( |  | ... | ) | eina_future_all_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})

A syntactic sugar over eina_future_all_array().

Usage:

future = eina_future_all(future1, future2, future3, future4);
eina_future_all
#define eina_future_all(...)
A syntactic sugar over eina_future_all_array().
Definition: eina_promise.h:1701

See also
  eina_future_all_array()

## ◆ eina_promise_all

#define eina_promise_all | ( |  | ... | ) | eina_promise_all_array((Eina_Future *[]){__VA_ARGS__, EINA_FUTURE_SENTINEL})

A syntactic sugar over eina_promise_all_array().

Usage:

promise = eina_promise_all(future1, future2, future3, future4);
eina_promise_all
#define eina_promise_all(...)
A syntactic sugar over eina_promise_all_array().
Definition: eina_promise.h:1710

See also
  eina_promise_all_array()

## ◆ eina_future_cb_easy

#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:

future_desc = eina_future_cb_easy(_success_cb, _error_cb, _free_cb, EINA_VALUE_TYPE_INT, my_data);
eina_future_cb_easy
#define eina_future_cb_easy(...)
A syntactic sugar over eina_future_cb_easy_from_desc().
Definition: eina_promise.h:1719
EINA_VALUE_TYPE_INT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_INT
manages int type.
Definition: eina_value.c:5602

See also
  eina_future_cb_easy_from_desc()

## ◆ eina_future_chain

#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:

future = eina_future_chain(future, {.cb = _my_cb, .data = my_data}, {.cb = _my_another_cb, .data = NULL});
eina_future_chain
#define eina_future_chain(_prev,...)
A syntactic sugar over eina_future_chain_array().
Definition: eina_promise.h:1728

See also
  eina_future_chain_array()

## ◆ eina_future_then

#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:

future = eina_future_then(future, _my_cb, my_data);
eina_future_then
#define eina_future_then(_prev,...)
A syntactic sugar over eina_future_then_from_desc().
Definition: eina_promise.h:1738

See also
  eina_future_then_from_desc()
  eina_future_then_easy()

## ◆ eina_future_cb_console

#define eina_future_cb_console | ( |  | ... | ) | eina_future_cb_console_from_desc((Eina_Future_Cb_Console_Desc){__VA_ARGS__})

A syntactic sugar over eina_future_cb_console_from_desc().

Usage:

desc = eina_future_cb_console(.prefix = "prefix", .suffix = "suffix");
eina_future_cb_console
#define eina_future_cb_console(...)
A syntactic sugar over eina_future_cb_console_from_desc().
Definition: eina_promise.h:1747

See also
  eina_future_cb_console_from_desc()

## ◆ eina_future_cb_log_dbg

#define eina_future_cb_log_dbg | ( |  | _prefix,
|  |  | _suffix
| ) |  |

Value:
eina_future_cb_log_from_desc((Eina_Future_Cb_Log_Desc){_prefix, _suffix, __FILE__, \
__func__, EINA_LOG_LEVEL_DBG, EINA_LOG_DOMAIN_DEFAULT, __LINE__})
eina_future_cb_log_from_desc
EINA_API 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.
Definition: eina_promise.c:1558
EINA_LOG_DOMAIN_DEFAULT
#define EINA_LOG_DOMAIN_DEFAULT
This macro defines the domain to use with the macros EINA_LOG_DOM_DBG(), EINA_LOG_DOM_INFO(),...
Definition: eina_log.h:284
EINA_LOG_LEVEL_DBG
@ EINA_LOG_LEVEL_DBG
Debug log level.
Definition: eina_log.h:461
_Eina_Future_Cb_Log_Desc
This struct is used by eina_future_cb_log_from_desc() and its contents will be routed to eina_log_pri...
Definition: eina_promise.h:398

A syntactic sugar over eina_future_cb_log_from_desc().

This macro will set the following fields of the Eina_Future_Cb_Log_Desc:

- Eina_Future_Cb_Log_Desc::file: The `__FILE__` function will be used.
- Eina_Future_Cb_Log_Desc::func: The `__func__` macro will be used.
- Eina_Future_Cb_Log_Desc::level: `EINA_LOG_LEVEL_DBG` will be used.
- Eina_Future_Cb_Log_Desc::domain: `EINA_LOG_DOMAIN_DEFAULT` will be used.
- Eina_Future_Cb_Log_Desc::line: The `__LINE__` macro will be used.

Usage:

desc = eina_future_cb_log_dbg(.prefix = "prefix", .suffix = "suffix");
eina_future_cb_log_dbg
#define eina_future_cb_log_dbg(_prefix, _suffix)
A syntactic sugar over eina_future_cb_log_from_desc().
Definition: eina_promise.h:1766

See also
  eina_future_cb_log_from_desc()

## ◆ eina_future_cb_log_crit

#define eina_future_cb_log_crit | ( |  | _prefix,
|  |  | _suffix
| ) |  |

Value:
eina_future_cb_log_from_desc((Eina_Future_Cb_Log_Desc){_prefix, _suffix, __FILE__, \
__func__, EINA_LOG_LEVEL_CRITICAL, EINA_LOG_DOMAIN_DEFAULT, __LINE__})
EINA_LOG_LEVEL_CRITICAL
@ EINA_LOG_LEVEL_CRITICAL
Critical log level.
Definition: eina_log.h:457

A syntactic sugar over eina_future_cb_log_from_desc().

This macro will set the following fields of the Eina_Future_Cb_Log_Desc:

- Eina_Future_Cb_Log_Desc::file: The FILE function will be used.
- Eina_Future_Cb_Log_Desc::func: The func macro will be used.
- Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_CRITICAL will be used.
- Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
- Eina_Future_Cb_Log_Desc::line: The LINE macro will be used.

Usage:

desc = eina_future_cb_log_crit(.prefix = "prefix", .suffix = "suffix");
eina_future_cb_log_crit
#define eina_future_cb_log_crit(_prefix, _suffix)
A syntactic sugar over eina_future_cb_log_from_desc().
Definition: eina_promise.h:1787

See also
  eina_future_cb_log_from_desc()

## ◆ eina_future_cb_log_err

#define eina_future_cb_log_err | ( |  | _prefix,
|  |  | _suffix
| ) |  |

Value:
eina_future_cb_log_from_desc((Eina_Future_Cb_Log_Desc){_prefix, _suffix, __FILE__, \
__func__, EINA_LOG_LEVEL_ERR, EINA_LOG_DOMAIN_DEFAULT, __LINE__})
EINA_LOG_LEVEL_ERR
@ EINA_LOG_LEVEL_ERR
Error log level.
Definition: eina_log.h:458

A syntactic sugar over eina_future_cb_log_from_desc().

This macro will set the following fields of the Eina_Future_Cb_Log_Desc:

- Eina_Future_Cb_Log_Desc::file: The FILE function will be used.
- Eina_Future_Cb_Log_Desc::func: The func macro will be used.
- Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_ERR will be used.
- Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
- Eina_Future_Cb_Log_Desc::line: The LINE macro will be used.

Usage:

desc = eina_future_cb_log_err(.prefix = "prefix", .suffix = "suffix");
eina_future_cb_log_err
#define eina_future_cb_log_err(_prefix, _suffix)
A syntactic sugar over eina_future_cb_log_from_desc().
Definition: eina_promise.h:1808

See also
  eina_future_cb_log_from_desc()

## ◆ eina_future_cb_log_info

#define eina_future_cb_log_info | ( |  | _prefix,
|  |  | _suffix
| ) |  |

Value:
eina_future_cb_log_from_desc((Eina_Future_Cb_Log_Desc){_prefix, _suffix, __FILE__, \
__func__, EINA_LOG_LEVEL_INFO, EINA_LOG_DOMAIN_DEFAULT, __LINE__})
EINA_LOG_LEVEL_INFO
@ EINA_LOG_LEVEL_INFO
Information log level.
Definition: eina_log.h:460

A syntactic sugar over eina_future_cb_log_from_desc().

This macro will set the following fields of the Eina_Future_Cb_Log_Desc:

- Eina_Future_Cb_Log_Desc::file: The FILE function will be used.
- Eina_Future_Cb_Log_Desc::func: The func macro will be used.
- Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_INFO will be used.
- Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
- Eina_Future_Cb_Log_Desc::line: The LINE macro will be used.

Usage:

desc = eina_future_cb_log_info(.prefix = "prefix", .suffix = "suffix");
eina_future_cb_log_info
#define eina_future_cb_log_info(_prefix, _suffix)
A syntactic sugar over eina_future_cb_log_from_desc().
Definition: eina_promise.h:1829

See also
  eina_future_cb_log_from_desc()

## ◆ eina_future_cb_log_warn

#define eina_future_cb_log_warn | ( |  | _prefix,
|  |  | _suffix
| ) |  |

Value:
eina_future_cb_log_from_desc((Eina_Future_Cb_Log_Desc){_prefix, _suffix, __FILE__, \
__func__, EINA_LOG_LEVEL_WARN, EINA_LOG_DOMAIN_DEFAULT, __LINE__})
EINA_LOG_LEVEL_WARN
@ EINA_LOG_LEVEL_WARN
Warning log level.
Definition: eina_log.h:459

A syntactic sugar over eina_future_cb_log_from_desc().

This macro will set the following fields of the Eina_Future_Cb_Log_Desc:

- Eina_Future_Cb_Log_Desc::file: The FILE function will be used.
- Eina_Future_Cb_Log_Desc::func: The func macro will be used.
- Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_WARN will be used.
- Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
- Eina_Future_Cb_Log_Desc::line: The LINE macro will be used.

Usage:

desc = eina_future_cb_log_warn(.prefix = "prefix", .suffix = "suffix");
eina_future_cb_log_warn
#define eina_future_cb_log_warn(_prefix, _suffix)
A syntactic sugar over eina_future_cb_log_from_desc().
Definition: eina_promise.h:1853

Parameters

  _prefix | PREFIX
  _suffix | SUFFIX

Returns
  SOMETHING

See also
  eina_future_cb_log_from_desc()

## ◆ eina_future_then_easy

#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:

f = eina_future_then_easy(f, .success = _success_cb, .success_type = EINA_VALUE_TYPE_DOUBLE, .data = NULL, );
eina_future_then_easy
#define eina_future_then_easy(_prev,...)
A syntactic sugar over eina_future_then() and eina_future_cb_easy().
Definition: eina_promise.h:1869
EINA_VALUE_TYPE_DOUBLE
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_DOUBLE
manages double type.
Definition: eina_value.c:5606

See also
  eina_future_then_from_desc()
  eina_future_easy()
  eina_future_then()
  eina_future_cb_easy_from_desc()

## ◆ eina_future_chain_easy

#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:

f = eina_future_chain_easy(f, {.success = _success_cb, .success_type = EINA_VALUE_TYPE_DOUBLE, .data = NULL},
{ .success = _success2_cb }, {.error = error_cb});
eina_future_chain_easy
#define eina_future_chain_easy(_prev,...)
A syntactic sugar over eina_future_chain() and eina_future_cb_easy().
Definition: eina_promise.h:1884

See also
  eina_future_chain_array()
  eina_future_easy()
  eina_future_chain_easy_array()
  eina_future_cb_easy_from_desc()

## Function Documentation

## ◆ eina_future_cancel()

EINA_API void eina_future_cancel | ( | Eina_Future * | f | ) |

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, with its value set to `ECANCELED`

Parameters

  [in,out] | f | The future to cancel.

## ◆ eina_future_desc_flush()

EINA_API void eina_future_desc_flush | ( | Eina_Future_Desc * | desc | ) |

Flushes an Eina_Future_Desc.

This function is mainly used by bindings to flush an Eina_Future_Desc. It will call the Eina_Future_Cb with `ENOMEM` and zero the `desc` contents.

Parameters

  [in,out] | desc | The Eina_Future_Desc to flush, if `NULL` this is a noop.

## ◆ eina_future_cb_easy_desc_flush()

EINA_API 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 an 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.

Parameters

  [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_promise_as_value()

EINA_API 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 an Eina_Promise in it. This function is useful for dealing with promises inside an Eina_Future_Cb. By returning a promise inside the Eina_Value the whole chain will wait until the promise is resolved in order to continue its execution. Example:

static Eina_Value
_file_data_ready(const *data EINA_UNUSED, const Eina_Value v, const Eina_Future *dead EINA_UNUSED)
{
const char *file_data;
Eina_Promise *p;
// It was not possible to fetch the file size.
if (v.type == EINA_VALUE_TYPE_ERROR)
{
Eina_Error err;
eina_value_get(&v, &err);
fprintf(stderr, "Could not get the file data. Reason: %s\n", eina_error_msg_get(err));
ecore_main_loop_quit();
return v;
}
else if (v.type != EINA_VALUE_TYPE_STRING)
{
fprintf(stderr, "Expecting type '%s' - received '%s'\n", EINA_VALUE_TYPE_STRING->name, v.type->name);
ecore_main_loop_quit();
return v;
}
eina_value_get(&v, &file_data);
// count_words will count the words in the background and resolve the promise once it is over...
p = count_words(file_data);
return eina_promise_as_value(p);
}
static Eina_Value
_word_count_ready(const *data EINA_UNUSED, const Eina_Value v, const Eina_Future *dead EINA_UNUSED)
{
// The _word_count_ready will only be called once count_words() resolves/rejects the promise returned by _file_data_ready()
int count;
if (v.type == EINA_VALUE_TYPE_ERROR)
{
Eina_Error err;
eina_value_get(&v, &err);
fprintf(stderr, "Could not count the file words. Reason: %s\n", eina_error_msg_get(err));
ecore_main_loop_quit();
return v;
}
else if (v.type != EINA_VALUE_TYPE_INT)
{
fprintf(stderr, "Expecting type '%s' - received '%s'\n", EINA_VALUE_TYPE_INT->name, v.type->name);
ecore_main_loop_quit();
return v;
}
eina_value_get(&v, &count);
printf("File word count %d\n", count);
return v;
}
void
file_operation(void)
{
Eina_Future *f = get_file_data("/MyFile.txt");
eina_future_chain(f, {.cb = _file_data_ready, .data = NULL},
{.cb = _word_count_ready, .data = NULL});
}
ecore_main_loop_quit
void ecore_main_loop_quit(void)
Quits the main loop once all the events currently on the queue have been processed.
Definition: ecore_main.c:1321
Eina_Error
int Eina_Error
The integer type containing the error type.
Definition: eina_error.h:90
eina_error_msg_get
EINA_API const char * eina_error_msg_get(Eina_Error error)
Returns the description of the given error number.
Definition: eina_error.c:295
eina_promise_as_value
EINA_API Eina_Value eina_promise_as_value(Eina_Promise *p)
Creates a new Eina_Value from a promise.
Definition: eina_promise.c:622
EINA_UNUSED
#define EINA_UNUSED
Used to indicate that a function parameter is purposely unused.
Definition: eina_types.h:339
EINA_VALUE_TYPE_ERROR
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_ERROR
manages Eina_Error values.
Definition: eina_value.c:5592
EINA_VALUE_TYPE_STRING
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_STRING
manages string type.
Definition: eina_value.c:5608
eina_value_get
static Eina_Bool eina_value_get(const Eina_Value *value,...)
Gets the generic value.
Eina_Future
An opaque structure representing a callback to be called when a promise is fulfilled.
Eina_Promise
An opaque structure representing a piece of data that will be available at a later point.
_Eina_Value_Type::name
const char * name
name for debug and introspection
Definition: eina_value.h:3681
_Eina_Value
defines the contents of a value
Definition: eina_value.h:662

Parameters

  [in,out] | p | The promise object to wrap in a value.

Returns
  An Eina_Value. On error the value's type will be `NULL`.

Note
  If an error happens the promise will be CANCELED.

See also
  eina_future_as_value()
  eina_promise_reject()
  eina_promise_resolve()

References DBG, EINA_SAFETY_ON_FALSE_GOTO, EINA_VALUE_EMPTY, eina_value_flush(), eina_value_pset(), eina_value_setup(), and EINA_VALUE_TYPE_PROMISE.

Referenced by eina_future_as_value().

## ◆ eina_future_as_value()

EINA_API 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.

Parameters

  [in,out] | f | A future to create a Eina_Value from.

Returns
  An Eina_Value. On error the value's type will be `NULL`.

Note
  If an error happens the future `f` will be CANCELED

See also
  eina_promise_as_value()

References DBG, eina_future_then, eina_promise_as_value(), eina_promise_new(), EINA_SAFETY_ON_NULL_GOTO, EINA_VALUE_EMPTY, EINA_VALUE_TYPE_PROMISE, and ERR.

## ◆ eina_future_new()

EINA_API 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.

Note
  A promise can only have one future attached to it, calling eina_future_new() on the same promise twice will result in an error (`NULL` is returned) and the future attached to the promise will be canceled!

Parameters

  [in,out] | p | A promise used to attach a future. May not be `NULL`.

Returns
  The future or `NULL` on error.

Note
  If an error happens this function will CANCEL the promise.

See also
  eina_promise_new()
  eina_promise_reject()
  eina_promise_resolve()
  eina_future_cancel()

References _Eina_Future_Desc::cb, and EINA_SAFETY_ON_TRUE_GOTO.

Referenced by eina_future_all_array(), eina_future_all_iterator(), eina_future_race_array(), eina_future_rejected(), and eina_future_resolved().

## ◆ eina_future_resolved()

EINA_API 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.

Parameters

  [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).

Returns
  The future or `NULL` on error.

See also
  eina_promise_new()
  eina_future_new()
  eina_promise_reject()
  eina_promise_resolve()
  eina_future_cancel()

References eina_future_new(), eina_promise_new(), eina_promise_resolve(), EINA_SAFETY_ON_NULL_GOTO, and eina_value_flush().

## ◆ eina_future_rejected()

EINA_API 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_reject().

Futures can also be canceled using eina_future_cancel(), which will cause the whole chain to be canceled alongside with any pending promise.

Parameters

  [in,out] | scheduler | The scheduler to use.
  [in] | err | An Eina_Error value

Returns
  The future or `NULL` on error.

See also
  eina_promise_new()
  eina_future_new()
  eina_promise_reject()
  eina_promise_resolve()
  eina_future_cancel()

References eina_future_new(), eina_promise_new(), eina_promise_reject(), and EINA_SAFETY_ON_NULL_GOTO.

## ◆ eina_future_then_from_desc()

EINA_API 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 resolved/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.

static Eina_Value
_file_ready(const *data, const Eina_Value v, const Eina_Future *dead EINA_UNUSED)
{
Ctx *ctx = data;
// It was not possible to fetch the file size.
if (v.type == EINA_VALUE_TYPE_ERROR)
{
Eina_Error err;
eina_value_get(&v, &err);
fprintf(stderr, "Could not read the file size. Reason: %s\n", eina_error_msg_get(err));
ecore_main_loop_quit();
return v;
}
else if (v.type != EINA_VALUE_TYPE_INT)
{
fprintf(stderr, "Expecting type '%s' - received '%s'\n", EINA_VALUE_TYPE_INT->name, v.type->name);
ecore_main_loop_quit();
return v;
}
eina_value_get(&v, &ctx->size);
printf("File size is %d bytes\n", ctx->size);
return v;
}
void
file_operation(void)
{
Eina_Future *f = get_file_size_async("/MyFile.txt");
eina_future_then_from_desc(f, (const Eina_Future_Desc){.cb = _size_ready, .data = NULL});
// There's a helper macro called eina_future_then() which simplifies the usage.
// The code below has the same effect.
// eina_future_then(f, _size_ready, NULL);
}
eina_future_then_from_desc
EINA_API 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 resolved/rejected.
Definition: eina_promise.c:945
_Eina_Future_Desc
A struct used to define a callback and data for a future.
Definition: eina_promise.h:455

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;
}
void chain(void)
{
Eina_Future *f = get_file_size_async("/MyFile.txt");
f = eina_future_then_easy(f, .success = _future_cb1, .success_type = EINA_VALUE_TYPE_INT);
// _future_cb2 will be executed after _future_cb1()
f = eina_future_then_easy(f, .success = _future_cb2, .success_type = EINA_VALUE_TYPE_STRING);
// _future_cb3 will be executed after _future_cb2()
f = eina_future_then_easy(f, .success = _future_cb3, .success_type = EINA_VALUE_TYPE_DOUBLE);
// If an error happens _future_err will be called
eina_future_then_easy(f, .error = _future_err);
}
eina_value_set
static Eina_Bool eina_value_set(Eina_Value *value,...)
Sets the generic value.
eina_value_setup
static Eina_Bool eina_value_setup(Eina_Value *value, const Eina_Value_Type *type)
Initializes generic value storage.
eina_value_convert
EINA_API Eina_Bool eina_value_convert(const Eina_Value *value, Eina_Value *convert)
Converts one value to another type.
Definition: eina_value.c:5688

Although it's possible to create a future chain using eina_future_then() and eina_future_then_from_desc() there's a function that makes this task much easier, please check eina_future_chain_array() for more information.

Note
  This example does manual conversion and print, however Eina offers eina_future_cb_convert_to() and eina_future_cb_console_from_desc() to make those common case easier.

Parameters

  [in,out] | prev | A future to link against
  [in] | desc | A description struct containing the callback and data.

Returns
  A new future or `NULL` on error.

Note
  If an error happens the whole future chain will CANCELED and desc.cb will be called in order to free desc.data.

See also
  eina_future_new()
  eina_future_then()
  Eina_Future_Desc
  eina_future_chain_array()
  eina_future_chain()
  eina_future_cb_console_from_desc()
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()
  eina_future_cb_convert_to()
  eina_future_cancel()
  eina_future_then_easy()
  eina_future_cb_log_from_desc()

References EINA_SAFETY_ON_TRUE_GOTO.

## ◆ eina_future_cb_log_from_desc()

EINA_API 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:

- Eina_Future_Cb_Log_Desc::file: The `__FILE__` function will be used.
- Eina_Future_Cb_Log_Desc::func: The `__func__` macro will be used.
- Eina_Future_Cb_Log_Desc::level: `EINA_LOG_LEVEL_DBG` will be used.
- Eina_Future_Cb_Log_Desc::domain: `EINA_LOG_DOMAIN_DEFAULT` will be used.
- Eina_Future_Cb_Log_Desc::line: The `__LINE__` macro will be used.

Parameters

  [in] | desc | The description data to be used.

Returns
  An Eina_Future_Desc

See also
  Eina_Future_Cb_Log_Desc
  eina_future_then()
  eina_future_chain()
  eina_future_cb_log_dbg()
  eina_future_cb_log_crit()
  eina_future_cb_log_err()
  eina_future_cb_log_info()
  eina_future_cb_log_warn()
  eina_future_cb_console_from_desc()

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_chain_array()

EINA_API 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:

// callbacks code....
Eina_Future* chain(void)
{
Eina_Future *f = get_file_size_async("/MyFile.txt");
return eina_future_chain(f, eina_future_cb_easy(_future_cb1, _future_err, NULL, EINA_VALUE_TYPE_INT, NULL),
eina_future_cb_easy(_future_cb2, _future_err, NULL, EINA_VALUE_TYPE_STRING, NULL),
eina_future_cb_easy(_future_cb3, _future_err, NULL, EINA_VALUE_TYPE_DOUBLE, NULL),
{.cb = _future_cb4, .data = NULL });
}

Parameters

  [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`

Returns
  A future or `NULL` on error.

Note
  If an error happens the whole future chain will CANCELED and desc.cb will be called in order to free desc.data.

See also
  eina_future_new()
  eina_future_then()
  Eina_Future_Desc
  eina_future_chain()
  eina_future_cb_ignore_error()
  eina_future_cb_console_from_desc()
  eina_future_cb_log_from_desc()
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()
  eina_future_then_from_desc()
  eina_future_then_easy()
  eina_future_cb_convert_to()

References _Eina_Future_Desc::cb, EINA_SAFETY_ON_NULL_GOTO, and EINA_SAFETY_ON_TRUE_GOTO.

## ◆ eina_future_chain_easy_array()

EINA_API 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.

Parameters

  [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`

Returns
  A future or `NULL` on error.

Note
  If an error happens the whole future chain will CANCELED and desc.cb will be called in order to free desc.data.

See also
  eina_future_chain_easy()
  eina_future_chain()
  eina_future_cb_easy()
  eina_future_chain_array()
  eina_future_cb_easy_from_desc()

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_cb_console_from_desc()

EINA_API 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's 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:

eina_future_chain(a_future, {.cb = cb1, .data = NULL},
//Inspect the cb1 value and pass to cb2 without modifications
eina_future_cb_console("cb1 value:"),
{.cb = cb2, .data = NULL},
//Inspect the cb2 value
eina_future_cb_console("cb2 value:", " cb2 value suffix\n"))

Parameters

  [in] | desc | Description object with contextual information.

Returns
  An Eina_Future_Desc

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 '\n' should be provided to ensure the printed string ends with a line feed.

See also
  eina_future_then()
  Eina_Future_Desc
  eina_future_chain()
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()
  eina_future_then_from_desc()
  eina_future_then_easy()
  eina_future_cb_console()
  eina_future_cb_ignore_error()
  eina_future_cb_log_from_desc()

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_cb_ignore_error()

EINA_API Eina_Future_Desc eina_future_cb_ignore_error | ( | Eina_Error | err | ) |

Returns an 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.

Parameters

  [in] | err | The error to be ignored.

Returns
  A future descriptor to be used with eina_future_then() or eina_future_chain()

## ◆ eina_future_cb_convert_to()

EINA_API Eina_Future_Desc eina_future_cb_convert_to | ( | const Eina_Value_Type * | type | ) |

Creates an Eina_Future_Desc which will convert the received eina value to a given type.

Parameters

  [in] | type | The Eina_Value_Type to convert to.

Returns
  An Eina_Future_Desc

See also
  eina_future_then()
  Eina_Future_Desc
  eina_future_chain()
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()
  eina_future_then_from_desc()
  eina_future_then_easy()

References _Eina_Future_Desc::cb.

## ◆ eina_future_cb_easy_from_desc()

EINA_API Eina_Future_Desc eina_future_cb_easy_from_desc | ( | const Eina_Future_Cb_Easy_Desc | desc | ) |

Creates an Eina_Future_Desc based on an 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:

- Eina_Future_Cb_Easy_Desc::success: This callback is called when the future execution was successful, that is, no errors occurred and the result type matches Eina_Future_Cb_Easy_Desc::success_type. In case Eina_Future_Cb_Easy_Desc::success_type is `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).

- Eina_Future_Cb_Easy_Desc::error: This callback is called when the future result is an error or Eina_Future_Cb_Easy_Desc::success_type does not match the future result type. The value returned by this function will be propagated to the next future in the chain (if any).

- Eina_Future_Cb_Easy_Desc::free: Called after the future was freed and any resources allocated must be freed at this point. This callback is always called.

Check the example below for a sample usage:

static Eina_Value
_file_size_ok(void *data, Eina_Value v)
{
Ctx *ctx = data;
// Since an Eina_Future_Cb_Easy_Desc::success_type was provided, there's no need to check the value type
int s;
eina_value_get(&v, &s);
printf("File size is %d bytes\n", s);
ctx->file_size = s;
return v;
}
static Eina_Value
_file_size_err(void *data, Eina_Error err)
{
fprintf(stderr, "Could not read the file size. Reason: %s\n", eina_error_msg_get(err));
// Stop propagating the error.
return EINA_VALUE_EMPTY;
}
static void
_future_freed(void *data, const Eina_Future dead)
{
Ctx *ctx = data;
printf("Future %p deleted\n", dead);
ctx->file_size_handler_cb(ctx->file_size);
free(ctx);
}
void do_work(File_Size_Handler_Cb cb)
{
Ctx *ctx = malloc(sizeof(Ctx));
ctx->f = get_file_size("/tmp/todo.txt");
ctx->file_size = -1;
ctx->file_size_handler_cb = cb;
eina_future_then_easy(f, _file_size_ok, _file_size_err, _future_freed, EINA_VALUE_TYPE_INT, ctx);
}
EINA_VALUE_EMPTY
#define EINA_VALUE_EMPTY
This is simply a value with all memory zeroed.
Definition: eina_value.h:317

Parameters

  [in] | desc | The easy callback's description.

Returns
  An Eina_Future_Desc

See also
  eina_future_chain()
  eina_future_then()
  eina_future_cb_easy()

References EINA_SAFETY_ON_NULL_GOTO.

Referenced by eina_future_chain_easy_array().

## ◆ eina_promise_all_array()

EINA_API 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:

static const char *
_get_operation_name_by_index(int idx)
{
switch (idx)
{
case 0: return "Get file data";
case 1: return "Get file size";
default: return "sum";
}
}
static Eina_Value
_all_cb(const void *data EINA_UNUSED, const Eina_Value array, const Eina_Future *dead EINA_UNUSED)
{
Eina_Error err;
unsigned int i, len;
if (array.type == EINA_VALUE_TYPE_ERROR)
{
eina_value_get(&array, &err);
fprintf(stderr, "Could not complete all operations. Reason: %s\n", eina_error_msg_get(err));
return array;
}
len = eina_value_array_count(&array);
for (i = 0; i < len; i++)
{
Eina_Value v;
eina_value_array_get(&array, i, &v);
if (v.type == EINA_VALUE_TYPE_ERROR)
{
eina_value_get(&v, &err);
fprintf(stderr, "Could not complete operation '%s'. Reason: %s\n", _get_operation_name_by_index(i), eina_error_msg_get(err));
continue;
}
if (!i)
{
const char *msg;
if (v.type != EINA_VALUE_TYPE_STRING)
{
fprintf(stderr, "Operation %s expects '%s' - received '%s'\n", _get_operation_name_by_index(i), EINA_VALUE_TYPE_STRING->name, v.type->name);
continue;
}
eina_value_get(&v, &msg);
printf("File content:%s\n", msg);
}
else if (i == 1)
{
int i;
if (v.type != EINA_VALUE_TYPE_INT)
{
fprintf(stderr, "Operation %s expects '%s' - received '%s'\n", _get_operation_name_by_index(i), EINA_VALUE_TYPE_INT->name, v.type->name);
continue;
}
eina_value_get(&v, &i);
printf("File size: %d\n", i);
}
else
{
double p;
if (v.type != EINA_VALUE_TYPE_DOUBLE)
{
fprintf(stderr, "Operation %s expects '%s' - received '%s'\n", _get_operation_name_by_index(i), EINA_VALUE_TYPE_DOUBLE->name, v.type->name);
continue;
}
eina_value_get(&v, &p);
printf("50 places of PI: %f\n", p);
}
}
return array;
}
void func(void)
{
Eina_Future *f1, *f2, *f3, f_all;
f1 = read_file("/tmp/todo.txt");
f2 = get_file_size("/tmp/file.txt");
// calculates 50 places of PI
f3 = calc_pi(50);
f_all = eina_future_all(f1, f2, f3);
eina_future_then(f_all, _all_cb, NULL);
}
eina_value_array_count
static unsigned int eina_value_array_count(const Eina_Value *value)
Queries number of elements in value of array type.
eina_value_array_get
static Eina_Bool eina_value_array_get(const Eina_Value *value, unsigned int position,...)
Gets the generic value from an array member.
_Eina_Value::type
const Eina_Value_Type * type
how to access values
Definition: eina_value.h:663

Parameters

  [in,out] | array | An array of futures, terminated with EINA_FUTURE_SENTINEL.

Returns
  A promise or `NULL` on error.

Note
  On error all the futures will be CANCELED.

See also
  eina_future_all_array()

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_all_iterator()

EINA_API Eina_Promise* eina_promise_all_iterator | ( | Eina_Iterator * | iterator | ) |

Creates an all promise from an iterator.

Creates a promise that is resolved once all the futures from the `iterator` 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 `iterator` order.

Parameters

  [in] | iterator | An iterator of futures. Will be destroyed after the call.

Returns
  A promise or `NULL` on error.

Note
  On error all the futures will be CANCELED.

See also
  eina_future_all_iterator()

References eina_future_then, EINA_ITERATOR_FOREACH, eina_iterator_free(), eina_iterator_next(), eina_mempool_free(), eina_promise_new(), 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_iterator().

## ◆ eina_promise_race_array()

EINA_API 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:

- A field named `value` containing an Eina_Value with the result itself.
- A field named `index` containing the index of the completed function relative to the `array`.

Example:

static const char *
_get_operation_name_by_index(int idx)
{
switch (idx)
{
case 0: return "Get file data";
case 1: return "Get file size";
default: return "sum";
}
}
static Eina_Value
_race_cb(const void *data EINA_UNUSED, const Eina_Value v)
{
unsigned int i;
Eina_Value result;
Eina_Error err;
Eina_Value_Struct *st;
// No need to check for the 'v' type. eina_future_cb_easy() did that for us.
// However we should check if the struct has the correct description
st = eina_value_memory_get(&v);
if (st->desc != EINA_PROMISE_RACE_STRUCT_DESC)
{
fprintf(stderr, "Eina_Value is not a race struct\n");
return v;
}
eina_value_struct_get(&v, "index", &i);
// Get the operation result
eina_value_struct_get(&v, "value", &result);
if (!i)
{
const char *msg;
if (result.type != EINA_VALUE_TYPE_STRING)
fprintf(stderr, "Operation %s expects '%s' - received '%s'\n", _get_operation_name_by_index(i), EINA_VALUE_TYPE_STRING->name, result.type->name);
else
{
eina_value_get(&result, &msg);
printf("File content:%s\n", msg);
}
}
else if (i == 1)
{
int i;
if (result.type != EINA_VALUE_TYPE_INT)
fprintf(stderr, "Operation %s expects '%s' - received '%s'\n", _get_operation_name_by_index(i), EINA_VALUE_TYPE_INT->name, v.type->name);
else
{
eina_value_get(&result, &i);
printf("File size: %d\n", i);
}
}
else
{
double p;
if (result.type != EINA_VALUE_TYPE_DOUBLE)
fprintf(stderr, "Operation %s expects '%s' - received '%s'\n", _get_operation_name_by_index(i), EINA_VALUE_TYPE_DOUBLE->name, result.type->name);
else
{
eina_value_get(&result, &p);
printf("50 places of PI: %f\n", p);
}
}
eina_value_flush(&result);
return v;
}
static Eina_Value
_race_err(void *data, Eina_Error err)
{
fprintf(stderr, "Could not complete the race future. Reason: %s\n", eina_error_msg_get(err));
return EINA_VALUE_EMPTY;
}
void func(void)
{
static const *Eina_Future[] = {NULL, NULL, NULL, NULL};
Eina_List *l = NULL;
futures[0] = read_file("/tmp/todo.txt");
futures[1] = get_file_size("/tmp/file.txt");
// calculates 50 places of PI
futures[2] = calc_pi(50);
f_race = eina_future_race_array(futures);
eina_future_then_easy(f_race, _race_cb, _race_err, NULL, EINA_VALUE_TYPE_STRUCT, NULL);
}
eina_future_race_array
static Eina_Future * eina_future_race_array(Eina_Future *array[])
Creates a future that will be resolved once a future array is resolved.
Definition: eina_promise.h:1659
EINA_PROMISE_RACE_STRUCT_DESC
EINA_API 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().
EINA_VALUE_TYPE_STRUCT
EINA_API const Eina_Value_Type * EINA_VALUE_TYPE_STRUCT
manages struct type.
Definition: eina_value.c:5614
eina_value_struct_get
static Eina_Bool eina_value_struct_get(const Eina_Value *value, const char *name,...)
Gets the generic value from a struct member.
eina_value_flush
static void eina_value_flush(Eina_Value *value)
Empties a generic value storage.
_Eina_List
Type for a generic double linked list.
Definition: eina_list.h:318
_Eina_Value_Struct
Used to store the memory and its description.
Definition: eina_value.h:3180
_Eina_Value_Struct::desc
const Eina_Value_Struct_Desc * desc
How to manage the structure.
Definition: eina_value.h:3181

Parameters

  [in,out] | array | An array of futures, terminated by EINA_FUTURE_SENTINEL.

Returns
  A promise or `NULL` on error.

Note
  On error all the futures will be CANCELED.

See also
  eina_future_race_array()
  _Eina_Future_Race_Result

References EINA_SAFETY_ON_FALSE_GOTO, EINA_SAFETY_ON_NULL_GOTO, and EINA_SAFETY_ON_NULL_RETURN_VAL.

Referenced by eina_future_race_array().

## ◆ eina_future_all_array()

static Eina_Future* eina_future_all_array | ( | Eina_Future * | 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()

Parameters

  [in,out] | array | A future array, must be terminated with EINA_FUTURE_SENTINEL.

Returns
  A future.

See also
  eina_promise_all_array()
  EINA_FUTURE_SENTINEL

References eina_future_new(), and eina_promise_all_array().

## ◆ eina_future_all_iterator()

static Eina_Future* eina_future_all_iterator | ( | Eina_Iterator * | iterator | ) |
| inlinestatic

Creates a future that will be resolved once all futures from `iterator` are resolved.

This is a helper over eina_promise_all_iterator()

Parameters

  [in] | iterator | An iterator containing futures. Will be destroyed on exit of the function.

Returns
  A future.

See also
  eina_promise_all_iterator()

References eina_future_new(), and eina_promise_all_iterator().

## ◆ eina_future_race_array()

static Eina_Future* eina_future_race_array | ( | Eina_Future * | array[] | ) |
| inlinestatic

Creates a future that will be resolved once a future `array` is resolved.

This is a helper over eina_promise_race_array()

Parameters

  [in,out] | array | A future array, must be terminated with EINA_FUTURE_SENTINEL

Returns
  A future.

See also
  eina_promise_race_array()
  EINA_FUTURE_SENTINEL

References eina_future_new(), and eina_promise_race_array().

## Variable Documentation

## ◆ EINA_PROMISE_RACE_STRUCT_DESC

const Eina_Value_Struct_Desc * EINA_PROMISE_RACE_STRUCT_DESC
| extern

A pointer to the race struct description, which is used by eina_promise_race_array().

This struct contains two members:

- `value:` An EINA_VALUE_TYPE_VALUE that contains the future result that won the race.
- `index:` An EINA_VALUE_TYPE_UINT that contains the future index that won the race.

See also
  eina_promise_race_array()
  _Eina_Future_Race_Result