summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorXavi Artigas <xavierartigas@yahoo.es>2020-03-17 19:21:41 +0100
committerXavi Artigas <xavierartigas@yahoo.es>2020-03-17 19:23:56 +0100
commitc4fad77ae3d1e2acbc8d0876edb614d861051dc8 (patch)
treeecfec522176e01eea884b16dcf2ea460aefcd7b7
parentd1c74afc40ef3e4c050c05b47aeefd48d23f42f4 (diff)
doxygen docs: Fix Eina Promises doc structure and links
Man, this was a tough one! The content still needs work, but the structure makes a bit more sense now, and there are no broken links, typos or doxygen warnings anymore.
-rw-r--r--src/lib/eina/eina_promise.c4
-rw-r--r--src/lib/eina/eina_promise.h506
2 files changed, 286 insertions, 224 deletions
diff --git a/src/lib/eina/eina_promise.c b/src/lib/eina/eina_promise.c
index 98ef61e03d..4255f7b41c 100644
--- a/src/lib/eina/eina_promise.c
+++ b/src/lib/eina/eina_promise.c
@@ -139,7 +139,9 @@ static const Eina_Value_Struct_Desc RACE_STRUCT_DESC = {
139 .size = sizeof(Eina_Future_Race_Result) 139 .size = sizeof(Eina_Future_Race_Result)
140}; 140};
141 141
142/** @cond local */
142EAPI const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC = &RACE_STRUCT_DESC; 143EAPI const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC = &RACE_STRUCT_DESC;
144/** @endcond */
143 145
144static inline void 146static inline void
145__eina_promise_value_dbg(const char *msg, 147__eina_promise_value_dbg(const char *msg,
@@ -245,7 +247,7 @@ _promise_convert_to(const Eina_Value_Type *type EINA_UNUSED, const Eina_Value_Ty
245 return EINA_FALSE; 247 return EINA_FALSE;
246} 248}
247 249
248static const Eina_Value_Type EINA_VALUE_TYPE_PROMISE = { 250const Eina_Value_Type EINA_VALUE_TYPE_PROMISE = {
249 .version = EINA_VALUE_TYPE_VERSION, 251 .version = EINA_VALUE_TYPE_VERSION,
250 .value_size = sizeof(Eina_Promise *), 252 .value_size = sizeof(Eina_Promise *),
251 .name = "Eina_Promise", 253 .name = "Eina_Promise",
diff --git a/src/lib/eina/eina_promise.h b/src/lib/eina/eina_promise.h
index 548d162aa0..7bd120ec0f 100644
--- a/src/lib/eina/eina_promise.h
+++ b/src/lib/eina/eina_promise.h
@@ -9,26 +9,64 @@ extern "C" {
9#include "eina_types.h" 9#include "eina_types.h"
10#include "eina_value.h" 10#include "eina_value.h"
11 11
12/** 12/** @file */
13
14/** @struct Eina_Promise
13 * @ingroup Eina_Promise 15 * @ingroup Eina_Promise
14 * 16 * An opaque structure representing a piece of data that will be available at a later point.
15 * @{ 17 * @typedef struct _Eina_Promise Eina_Promise
18 * Convenience wrapper.
16 */ 19 */
17typedef struct _Eina_Future_Desc Eina_Future_Desc;
18typedef struct _Eina_Promise Eina_Promise; 20typedef struct _Eina_Promise Eina_Promise;
21
22/** @struct Eina_Future
23 * @ingroup Eina_Future
24 * An opaque structure representing a callback to be called when a promise is fulfilled.
25 * @typedef struct _Eina_Future Eina_Future
26 * Convenience wrapper.
27 */
19typedef struct _Eina_Future Eina_Future; 28typedef struct _Eina_Future Eina_Future;
29
30/** @typedef struct _Eina_Future_Desc Eina_Future_Desc
31 * @ingroup Eina_Future
32 * Convenience wrapper over #_Eina_Future_Desc. */
33typedef struct _Eina_Future_Desc Eina_Future_Desc;
34
35/** @typedef struct _Eina_Future_Race_Result Eina_Future_Race_Result
36 * @ingroup Eina_Future
37 * Convenience wrapper over #_Eina_Future_Race_Result. */
38typedef struct _Eina_Future_Race_Result Eina_Future_Race_Result;
39
40/**
41 * @defgroup Eina_Future_Callbacks Eina Future Callbacks
42 * @ingroup Eina_Future
43 * @brief Methods and structures dealing with #Eina_Future callbacks
44 * @{
45 */
46
47/** @typedef struct _Eina_Future_Cb_Easy_Desc Eina_Future_Cb_Easy_Desc
48 * Convenience wrapper over #_Eina_Future_Cb_Easy_Desc. */
20typedef struct _Eina_Future_Cb_Easy_Desc Eina_Future_Cb_Easy_Desc; 49typedef struct _Eina_Future_Cb_Easy_Desc Eina_Future_Cb_Easy_Desc;
50
51/** @typedef struct _Eina_Future_Cb_Console_Desc Eina_Future_Cb_Console_Desc
52 * Convenience wrapper over _Eina_Future_Cb_Console_Desc. */
21typedef struct _Eina_Future_Cb_Console_Desc Eina_Future_Cb_Console_Desc; 53typedef struct _Eina_Future_Cb_Console_Desc Eina_Future_Cb_Console_Desc;
54
55/** @typedef struct _Eina_Future_Scheduler Eina_Future_Scheduler
56 * Convenience wrapper over _Eina_Future_Scheduler. */
22typedef struct _Eina_Future_Scheduler Eina_Future_Scheduler; 57typedef struct _Eina_Future_Scheduler Eina_Future_Scheduler;
58
59/** @typedef struct _Eina_Future_Schedule_Entry Eina_Future_Schedule_Entry
60 * Convenience wrapper over _Eina_Future_Schedule_Entry. */
23typedef struct _Eina_Future_Schedule_Entry Eina_Future_Schedule_Entry; 61typedef struct _Eina_Future_Schedule_Entry Eina_Future_Schedule_Entry;
24typedef struct _Eina_Future_Race_Result Eina_Future_Race_Result; 62
63/** @typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc
64 * Convenience wrapper over _Eina_Future_Cb_Log_Desc. */
25typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc; 65typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc;
26 66
27/** 67/**
28 * @defgroup Eina_Future_Callbacks Efl Future Callbacks 68 * @typedef Eina_Future_Cb
29 * @ingroup eina_future 69
30 * @typedef Eina_Future_Cb Eina_Future_Cb
31 *
32 * A callback used to inform that a future was resolved. 70 * A callback used to inform that a future was resolved.
33 * Usually this callback is called from a clean context, that is, from the 71 * Usually this callback is called from a clean context, that is, from the
34 * main loop or some platform defined safe context. However there are 72 * main loop or some platform defined safe context. However there are
@@ -43,18 +81,18 @@ typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc;
43 * 81 *
44 * @param[in] data The data provided by the user 82 * @param[in] data The data provided by the user
45 * 83 *
46 * @param[in] value An Eina_Value which contains the operation result. Before using 84 * @param[in] value An #Eina_Value which contains the operation result. Before using
47 * the @p value, its type must be checked in order to avoid errors. This is needed because 85 * the @p value, its type must be checked in order to avoid errors. This is needed because
48 * if an operation fails the Eina_Value type will be EINA_VALUE_TYPE_ERROR 86 * if an operation fails the #Eina_Value type will be #EINA_VALUE_TYPE_ERROR
49 * which is a different type than the expected operation result. 87 * which is a different type than the expected operation result.
50 * 88 *
51 * @param[in] dead_future A pointer to the future that was completed. 89 * @param[in] dead_future A pointer to the future that was completed.
52 * 90 *
53 * @return An Eina_Value to pass to the next Eina_Future in the chain (if any). 91 * @return An #Eina_Value to pass to the next #Eina_Future in the chain (if any).
54 * If there is no need to convert the received value, it's @b recommended 92 * If there is no need to convert the received value, it's @b recommended
55 * to passthrough @p value argument. If you need to convert to a different type 93 * to passthrough the @p value argument. If you need to convert to a different type
56 * or generate a new value, use @c eina_value_setup() on @b another Eina_Value 94 * or generate a new value, use @c eina_value_setup() on @b another #Eina_Value
57 * and return it. By returning a promise Eina_Value (eina_promise_as_value()) the 95 * and return it. By returning a promise #Eina_Value (eina_promise_as_value()) the
58 * whole chain will wait until the promise is resolved in 96 * whole chain will wait until the promise is resolved in
59 * order to continue its execution. 97 * order to continue its execution.
60 * Note that the value contents must survive this function scope, 98 * Note that the value contents must survive this function scope,
@@ -63,7 +101,7 @@ typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc;
63 * using @c eina_value_flush() once they are unused (no more future or futures 101 * using @c eina_value_flush() once they are unused (no more future or futures
64 * returned a new value). 102 * returned a new value).
65 * 103 *
66 * @note The returned value @b can be an EFL_VALUE_TYPE_PROMISE! (see eina_promise_as_value() and 104 * @note The returned value @b can be an #EINA_VALUE_TYPE_PROMISE! (see eina_promise_as_value() and
67 * eina_future_as_value()) In this case the future chain will wait until the promise is resolved. 105 * eina_future_as_value()) In this case the future chain will wait until the promise is resolved.
68 * 106 *
69 * @see eina_future_cancel() 107 * @see eina_future_cancel()
@@ -74,13 +112,11 @@ typedef struct _Eina_Future_Cb_Log_Desc Eina_Future_Cb_Log_Desc;
74 * @see eina_future_chain_array() 112 * @see eina_future_chain_array()
75 * @see eina_future_as_value() 113 * @see eina_future_as_value()
76 * @see eina_promise_as_value() 114 * @see eina_promise_as_value()
77 * @{
78 */ 115 */
79typedef Eina_Value (*Eina_Future_Cb)(void *data, const Eina_Value value, const Eina_Future *dead_future); 116typedef Eina_Value (*Eina_Future_Cb)(void *data, const Eina_Value value, const Eina_Future *dead_future);
80 117
81/** 118/**
82 * @struct _Eina_Future_Scheduler 119 * @struct _Eina_Future_Schedule_Entry
83 * @ingroup eina_promise
84 * 120 *
85 * A struct that represents an scheduled event. 121 * A struct that represents an scheduled event.
86 * This struct may be used by Eina to cancel 122 * This struct may be used by Eina to cancel
@@ -88,8 +124,8 @@ typedef Eina_Value (*Eina_Future_Cb)(void *data, const Eina_Value value, const E
88 * 124 *
89 * @see eina_promise_new() 125 * @see eina_promise_new()
90 * 126 *
91 * @see #Eina_Future_Scheduler 127 * @see Eina_Future_Scheduler
92 * @see #Eina_Future_Scheduler_Cb 128 * @see Eina_Future_Scheduler_Cb
93 */ 129 */
94struct _Eina_Future_Schedule_Entry { 130struct _Eina_Future_Schedule_Entry {
95 /** 131 /**
@@ -102,8 +138,7 @@ struct _Eina_Future_Schedule_Entry {
102 138
103/** 139/**
104 * @typedef Eina_Future_Scheduler_Cb 140 * @typedef Eina_Future_Scheduler_Cb
105 * @ingroup eina_promise 141 * A callback used by the #Eina_Future_Scheduler to deliver
106 * A callback used by the Eina_Future_Scheduler to deliver
107 * the future operation result. 142 * the future operation result.
108 * 143 *
109 * @param[out] f The delivered future. 144 * @param[out] f The delivered future.
@@ -112,21 +147,20 @@ struct _Eina_Future_Schedule_Entry {
112 * 147 *
113 * @see eina_promise_new() 148 * @see eina_promise_new()
114 * 149 *
115 * @see #Eina_Future_Schedule_Entry 150 * @see Eina_Future_Schedule_Entry
116 * @see #Eina_Future_Scheduler 151 * @see Eina_Future_Scheduler
117 */ 152 */
118typedef void (*Eina_Future_Scheduler_Cb)(Eina_Future *f, Eina_Value value); 153typedef void (*Eina_Future_Scheduler_Cb)(Eina_Future *f, Eina_Value value);
119 154
120/** 155/**
121 * @struct _Eina_Future_Scheduler 156 * @struct _Eina_Future_Scheduler
122 * @ingroup eina_promise
123 * This struct is used as a bridge between Eina and the future scheduler. 157 * This struct is used as a bridge between Eina and the future scheduler.
124 * By using the functions provided by #_Eina_Future_Scheduler Eina can 158 * By using the functions provided by _Eina_Future_Scheduler Eina can
125 * schedule futures resolutions, rejections and cancellations to a safe context. 159 * schedule futures resolutions, rejections and cancellations to a safe context.
126 * 160 *
127 * @see eina_promise_new() 161 * @see eina_promise_new()
128 * @see #Eina_Future_Schedule_Entry 162 * @see Eina_Future_Schedule_Entry
129 * @see #Eina_Future_Scheduler_Cb 163 * @see Eina_Future_Scheduler_Cb
130 */ 164 */
131struct _Eina_Future_Scheduler { 165struct _Eina_Future_Scheduler {
132 /** 166 /**
@@ -137,7 +171,7 @@ struct _Eina_Future_Scheduler {
137 * 171 *
138 * Must call back from a safe context using @p cb(f,value) 172 * Must call back from a safe context using @p cb(f,value)
139 * @param[in,out] scheduler The scheduler to use. 173 * @param[in,out] scheduler The scheduler to use.
140 * @param[in] cb The #Eina_Future_Scheduler_Cb to be called and deliver the @p f and @p value. 174 * @param[in] cb The Eina_Future_Scheduler_Cb to be called and deliver the @p f and @p value.
141 * @param[in] f The future to be delivered to @p cb 175 * @param[in] f The future to be delivered to @p cb
142 * @param[in] value The value to be delivered to @p cb 176 * @param[in] value The value to be delivered to @p cb
143 * @return A scheduled entry or @c NULL on error 177 * @return A scheduled entry or @c NULL on error
@@ -155,26 +189,25 @@ struct _Eina_Future_Scheduler {
155}; 189};
156 190
157/** 191/**
158 * @typedef Eina_Promise_Cancel_Cb Eina_Promise_Cancel_Cb. 192 * @typedef void (*Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_promise)
159 * @ingroup eina_promise
160 * 193 *
161 * A callback used to inform that a promise was canceled. 194 * A callback used to inform that a promise was canceled.
162 * 195 *
163 * A promise may be canceled by the user calling `eina_future_cancel()` 196 * A promise may be canceled by the user calling `eina_future_cancel()`
164 * on any Eina_Future that is part of the chain that uses an Eina_Promise, 197 * on any #Eina_Future that is part of the chain that uses an #Eina_Promise,
165 * that will cancel the whole chain and then the promise. 198 * that will cancel the whole chain and then the promise.
166 * 199 *
167 * It should stop all asynchronous operations or at least mark them to be 200 * It should stop all asynchronous operations or at least mark them to be
168 * discarded instead of resolved. Actually it can't be resolved once 201 * discarded instead of resolved. Actually it can't be resolved once
169 * canceled since the given pointer @c dead_promise is now invalid. 202 * canceled since the given pointer @c dead_promise is now invalid.
170 * 203 *
171 * @note This callback is @b mandatory for a reason, do not provide an empty 204 * @note @li This callback is @b mandatory for a reason, do not provide an empty
172 * callback as it'll likely result in memory corruption and invalid access. 205 * callback as it'll likely result in memory corruption and invalid access.
173 * If impossible to cancel an asynchronous task, then create an 206 * If impossible to cancel an asynchronous task, then create an
174 * intermediate memory to hold Eina_Promise and make it @c NULL, 207 * intermediate memory to hold #Eina_Promise and make it @c NULL,
175 * in this callback. Then prior to resolution check if the pointer is set. 208 * in this callback. Then prior to resolution check if the pointer is set.
176 * 209 *
177 * @note This callback is @b not called if eina_promise_resolve() or 210 * @note @li This callback is @b not called if eina_promise_resolve() or
178 * eina_promise_reject() are used. If any cleanup is needed, then 211 * eina_promise_reject() are used. If any cleanup is needed, then
179 * call yourself. It's only meant as cancellation, not a general 212 * call yourself. It's only meant as cancellation, not a general
180 * "free callback". 213 * "free callback".
@@ -188,15 +221,14 @@ struct _Eina_Future_Scheduler {
188typedef void (*Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_promise); 221typedef void (*Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_promise);
189 222
190/** 223/**
191 * @typedef Eina_Future_Success_Cb Eina_Future_Success_Cb. 224 * @typedef Eina_Future_Success_Cb
192 * @ingroup eina_future
193 * 225 *
194 * A callback used to inform that the future completed with success. 226 * A callback used to inform that the future completed with success.
195 * 227 *
196 * Unlike #Eina_Future_Cb this callback only called if the future operation was successful, this is, 228 * Unlike #Eina_Future_Cb this callback is only called if the future operation was successful, this is,
197 * no errors occurred (@p value type differs from EINA_VALUE_TYPE_ERROR) 229 * no errors occurred (@p value type differs from #EINA_VALUE_TYPE_ERROR)
198 * and the @p value matches #_Eina_Future_Cb_Easy_Desc::success_type (if given). 230 * and the @p value matches _Eina_Future_Cb_Easy_Desc::success_type (if given).
199 * In case #_Eina_Future_Cb_Easy_Desc::success_type was not supplied (it's @c NULL) the @p value type 231 * In case _Eina_Future_Cb_Easy_Desc::success_type was not supplied (it's @c NULL) the @p value type
200 * must be checked before using it. 232 * must be checked before using it.
201 * 233 *
202 * @note This function is always called from a safe context (main loop or some platform defined safe context). 234 * @note This function is always called from a safe context (main loop or some platform defined safe context).
@@ -221,36 +253,35 @@ typedef void (*Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_pro
221typedef Eina_Value (*Eina_Future_Success_Cb)(void *data, const Eina_Value value); 253typedef Eina_Value (*Eina_Future_Success_Cb)(void *data, const Eina_Value value);
222 254
223/** 255/**
224 * @typedef Eina_Future_Error_Cb Eina_Future_Error_Cb. 256 * @typedef Eina_Future_Error_Cb
225 * @ingroup eina_future
226 * 257 *
227 * A callback used to inform that the future completed with failure. 258 * A callback used to inform that the future completed with failure.
228 * 259 *
229 * Unlike #Eina_Future_Success_Cb this function is only called when an error 260 * Unlike #Eina_Future_Success_Cb this function is only called when an error
230 * occurs during the future process or when #_Eina_Future_Cb_Easy_Desc::success_type 261 * occurs during the future process or when _Eina_Future_Cb_Easy_Desc::success_type
231 * differs from the future result. 262 * differs from the future result.
232 * On future creation errors and future cancellation this function will be called 263 * On future creation errors and future cancellation this function will be called
233 * from the current context with the following errors respectfully: `EINVAL`, `ENOMEM` and `ECANCELED`. 264 * from the current context with the following errors: `EINVAL`, `ENOMEM` and `ECANCELED`.
234 * Otherwise this function is called from a safe context. 265 * Otherwise this function is called from a safe context.
235 * 266 *
236 * If it was possible to recover from an error this function should return an empty value 267 * If it was possible to recover from an error this function should return an empty value
237 * `return EINA_VALUE_EMPTY;` or any other Eina_Value type that differs from EINA_VALUE_TYPE_ERROR. 268 * #EINA_VALUE_EMPTY or any other #Eina_Value type that differs from #EINA_VALUE_TYPE_ERROR.
238 * In this case the error will not be reported by the other futures in the chain (if any), otherwise 269 * In this case the error will not be reported by the other futures in the chain (if any), otherwise
239 * if an Eina_Value type EINA_VALUE_TYPE_ERROR is returned the error will continue to be reported 270 * if an #Eina_Value type #EINA_VALUE_TYPE_ERROR is returned the error will continue to be reported
240 * to the other futures in the chain. 271 * to the other futures in the chain.
241 * 272 *
242 * @param[in] data The data provided by the user. 273 * @param[in] data The data provided by the user.
243 * @param[in] error The operation error 274 * @param[in] error The operation error
244 * @return An Eina_Value to pass to the next Eina_Future in the chain (if any). 275 * @return An #Eina_Value to pass to the next #Eina_Future in the chain (if any).
245 * If you need to convert to a different type or generate a new value, 276 * If you need to convert to a different type or generate a new value,
246 * use @c eina_value_setup() on @b another Eina_Value 277 * use eina_value_setup() on @b another Eina_Value
247 * and return it. By returning a promise Eina_Value (eina_promise_as_value()) the 278 * and return it. By returning a promise Eina_Value (eina_promise_as_value()) the
248 * whole chain will wait until the promise is resolved in 279 * whole chain will wait until the promise is resolved in
249 * order to continue its execution. 280 * order to continue its execution.
250 * Note that the value contents must survive this function scope, 281 * Note that the value contents must survive this function scope,
251 * that is, do @b not use stack allocated blobs, arrays, structures or types that 282 * that is, do @b not use stack allocated blobs, arrays, structures or types that
252 * keep references to memory you give. Values will be automatically cleaned up 283 * keep references to memory you give. Values will be automatically cleaned up
253 * using @c eina_value_flush() once they are unused (no more future or futures 284 * using eina_value_flush() once they are unused (no more future or futures
254 * returned a new value). 285 * returned a new value).
255 * @see eina_future_cb_easy_from_desc() 286 * @see eina_future_cb_easy_from_desc()
256 * @see eina_future_cb_easy() 287 * @see eina_future_cb_easy()
@@ -258,8 +289,7 @@ typedef Eina_Value (*Eina_Future_Success_Cb)(void *data, const Eina_Value value)
258typedef Eina_Value (*Eina_Future_Error_Cb)(void *data, const Eina_Error error); 289typedef Eina_Value (*Eina_Future_Error_Cb)(void *data, const Eina_Error error);
259 290
260/** 291/**
261 * @typedef Eina_Future_Free_Cb Eina_Future_Free_Cb. 292 * @typedef Eina_Future_Free_Cb
262 * @ingroup eina_future
263 * 293 *
264 * A callback used to inform that the future was freed and the user should also @c free the @p data. 294 * A callback used to inform that the future was freed and the user should also @c free the @p data.
265 * This callback may be called from an unsafe context if the future was canceled or an error 295 * This callback may be called from an unsafe context if the future was canceled or an error
@@ -278,7 +308,6 @@ typedef void (*Eina_Future_Free_Cb)(void *data, const Eina_Future *dead_future);
278 308
279/** 309/**
280 * @struct _Eina_Future_Cb_Easy_Desc 310 * @struct _Eina_Future_Cb_Easy_Desc
281 * @ingroup eina_future
282 * 311 *
283 * A struct with callbacks to be used by eina_future_cb_easy_from_desc() and eina_future_cb_easy() 312 * A struct with callbacks to be used by eina_future_cb_easy_from_desc() and eina_future_cb_easy()
284 * 313 *
@@ -339,7 +368,6 @@ struct _Eina_Future_Cb_Easy_Desc {
339 368
340/** 369/**
341 * @struct _Eina_Future_Cb_Console_Desc 370 * @struct _Eina_Future_Cb_Console_Desc
342 * @ingroup eina_future
343 * 371 *
344 * A struct used to define the prefix and suffix to be printed 372 * A struct used to define the prefix and suffix to be printed
345 * along side the a future value. This struct is used by 373 * along side the a future value. This struct is used by
@@ -360,7 +388,6 @@ struct _Eina_Future_Cb_Console_Desc {
360 388
361/** 389/**
362 * @struct _Eina_Future_Cb_Log_Desc 390 * @struct _Eina_Future_Cb_Log_Desc
363 * @ingroup eina_future
364 * 391 *
365 * This struct is used by eina_future_cb_log_from_desc() and 392 * This struct is used by eina_future_cb_log_from_desc() and
366 * its contents will be routed to eina_log_print() along side 393 * its contents will be routed to eina_log_print() along side
@@ -400,18 +427,22 @@ struct _Eina_Future_Cb_Log_Desc {
400}; 427};
401 428
402/** 429/**
430 * @}
431 */
432
433/**
403 * @struct _Eina_Future_Desc 434 * @struct _Eina_Future_Desc
404 * @ingroup eina_future 435 * @ingroup Eina_Future
405 * A struct used to define a callback and data for a future. 436 * A struct used to define a callback and data for a future.
406 * 437 *
407 * This struct contains a future completion callback and a data to the future 438 * This struct contains a future completion callback and a data to the future
408 * completion callback which is used by eina_future_then(), eina_future_chain() 439 * completion callback which is used by eina_future_then(), eina_future_chain()
409 * and friends to inform the user about the future result. The #_Eina_Future_Desc::data 440 * and friends to inform the user about the future result. The _Eina_Future_Desc::data
410 * variable should be freed when #_Eina_Future_Desc::cb is called, otherwise it will leak. 441 * variable should be freed when _Eina_Future_Desc::cb is called, otherwise it will leak.
411 * 442 *
412 * @note If eina_future_then(), eina_future_chain() and friends fails to return a valid future 443 * @note If eina_future_then(), eina_future_chain() and friends fails to return a valid future
413 * (in other words: @c NULL is returned) the #_Eina_Future_Desc::cb will be called 444 * (in other words: @c NULL is returned) the _Eina_Future_Desc::cb will be called
414 * report an error like `EINVAL` or `ENOMEM` so #_Eina_Future_Desc::data can be freed. 445 * report an error like `EINVAL` or `ENOMEM` so _Eina_Future_Desc::data can be freed.
415 * 446 *
416 * @see eina_future_then() 447 * @see eina_future_then()
417 * @see eina_future_chain_array() 448 * @see eina_future_chain_array()
@@ -452,36 +483,26 @@ struct _Eina_Future_Desc {
452}; 483};
453 484
454/** 485/**
455 * @} 486 * @defgroup Eina_Promise Eina Promises
456 */ 487 * @ingroup Eina
457
458/**
459 * @defgroup Eina_Promise Eina_Promise
460 * Creates a new promise.
461 *
462 * This function creates a new promise which can be used to create a future
463 * using eina_future_new(). Every time a promise is created a #Eina_Promise_Cancel_Cb
464 * must be provided which is used to free resources that were created.
465 * 488 *
466 * A promise may be canceled directly by calling 489 * @brief Promises are a programming paradigm that simplifies synchronization when concurrent execution is present.
467 * @c eina_future_cancel(eina_future_new(eina_promise_new(...)))
468 * that is, canceling any future that is chained to receive the results.
469 * 490 *
470 * However promises can be canceled indirectly by other entities. 491 * Since C does not natively support Promises the Eina library provides the Eina_Promise and Eina_Future objects.
471 * These other entities will call `eina_future_cancel()` themselves,
472 * however you may not be aware of that. Some common sources
473 * of indirect cancellations:
474 * 492 *
475 * @li A subsystem was shutdown, canceling all pending futures (i.e.: ecore_shutdown()) 493 * In procedural languages like C if you need a value which is not yet available, for instance because
494 * it takes a long time to calculate or has to be fetched from a remote server, you typically have to wait.
476 * 495 *
477 * @li An EO object was linked to the promise or future, then if the object dies (last reference 496 * Other languages however can return a Promise and continue execution immediately. A promise acts as a placeholder
478 * is gone), then the pending promises and futures will be canceled. 497 * for the requested value: the value is not available yet but will be at some point in the future.
479 * 498 *
480 * @li Some other entity (library provider or library user) chained and canceled his future, 499 * With a promise in hand you can attach callbacks to be triggered when the value becomes available (i.e. when
481 * which will result in your future being canceled. 500 * the promise is fulfilled) and then continue your calculations. You can even pass the promise to other methods
501 * which will then be executed as values become available, forming complex chains.
482 * 502 *
483 * Since a promise may be canceled indirectly (by code sections that goes beyond your scope) 503 * An Eina_Promise can be considered as an object with the sole purpose of emitting the "Promise Resolved" event.
484 * you should always provide a cancel callback, even if you think you'll not need it. 504 * Eina_Future are callbacks attached to this object to be called when the event is emitted. The promised value is
505 * passed to the callbacks whenever it's available.
485 * 506 *
486 * Here's a typical example: 507 * Here's a typical example:
487 * 508 *
@@ -521,6 +542,43 @@ struct _Eina_Future_Desc {
521 * } 542 * }
522 * @endcode 543 * @endcode
523 * 544 *
545 * @{
546 */
547
548/**
549 * Value type for #Eina_Value's containing an #Eina_Promise
550 */
551EAPI extern const Eina_Value_Type EINA_VALUE_TYPE_PROMISE;
552
553/**
554 * Creates a new promise.
555 *
556 * This function creates a new promise which can be used to create a future
557 * using eina_future_new(). Every time a promise is created an #Eina_Promise_Cancel_Cb
558 * must be provided which is used to free resources that were created.
559 *
560 * A promise may be canceled directly by calling:
561 * @code
562 * eina_future_cancel(eina_future_new(eina_promise_new(...)))
563 * @endcode
564 * That is, canceling any future that is chained to receive the results.
565 *
566 * However promises can be canceled indirectly by other entities.
567 * These other entities will call eina_future_cancel() themselves,
568 * however you may not be aware of that. Some common sources
569 * of indirect cancellations:
570 *
571 * @li A subsystem was shutdown, canceling all pending futures (i.e.: ecore_shutdown())
572 *
573 * @li An EO object was linked to the promise or future, then if the object dies (last reference
574 * is gone), then the pending promises and futures will be canceled.
575 *
576 * @li Some other entity (library provider or library user) chained and canceled his future,
577 * which will result in your future being canceled.
578 *
579 * Since a promise may be canceled indirectly (by code sections that goes beyond your scope)
580 * you should always provide a cancel callback, even if you think you'll not need it.
581 *
524 * If you already have a value and want to create a future that will 582 * If you already have a value and want to create a future that will
525 * resolve to it directly use the eina_future_resolved(), it has the 583 * resolve to it directly use the eina_future_resolved(), it has the
526 * same effect as creating a promise and immediately resolving it. 584 * same effect as creating a promise and immediately resolving it.
@@ -536,10 +594,9 @@ struct _Eina_Future_Desc {
536 * @see eina_promise_resolve() 594 * @see eina_promise_resolve()
537 * @see eina_promise_reject() 595 * @see eina_promise_reject()
538 * @see eina_promise_as_value() 596 * @see eina_promise_as_value()
539 * @see #Eina_Future_Scheduler 597 * @see Eina_Future_Scheduler
540 * @see #Eina_Future_Scheduler_Entry 598 * @see Eina_Future_Schedule_Entry
541 * @see #Eina_Future_Scheduler_Cb 599 * @see Eina_Future_Scheduler_Cb
542 * @{
543 */ 600 */
544EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promise_Cancel_Cb cancel_cb, const void *data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 601EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promise_Cancel_Cb cancel_cb, const void *data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
545 602
@@ -548,15 +605,17 @@ EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promi
548 * 605 *
549 * This function creates a new promise from a future currently being resolved which can be 606 * This function creates a new promise from a future currently being resolved which can be
550 * used to create a #Eina_Value with eina_promise_as_value(). Every time a promise is 607 * used to create a #Eina_Value with eina_promise_as_value(). Every time a promise is
551 * created a #Eina_Promise_Cancel_Cb must be provided which is used to free resources 608 * created an #Eina_Promise_Cancel_Cb must be provided which is used to free resources
552 * that were created. 609 * that were created.
553 * 610 *
554 * A promise may be canceled directly by calling 611 * A promise may be canceled directly by calling:
555 * @c eina_future_cancel(eina_future_new(eina_promise_new(...))) 612 * @code
556 * that is, canceling any future that is chained to receive the results. 613 * eina_future_cancel(eina_future_new(eina_promise_new(...)))
614 * @endcode
615 * That is, canceling any future that is chained to receive the results.
557 * 616 *
558 * However promises can be canceled indirectly by other entities. 617 * However promises can be canceled indirectly by other entities.
559 * These other entities will call `eina_future_cancel()` themselves, 618 * These other entities will call eina_future_cancel() themselves,
560 * however you may not be aware of that. Some common sources 619 * however you may not be aware of that. Some common sources
561 * of indirect cancellations: 620 * of indirect cancellations:
562 * 621 *
@@ -574,7 +633,6 @@ EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promi
574 * Here's a typical example: 633 * Here's a typical example:
575 * 634 *
576 * @code 635 * @code
577 *
578 * Eina_Value 636 * Eina_Value
579 * _future_resolve(void *data, const Eina_Value v, const Eina_Future *dead_future) 637 * _future_resolve(void *data, const Eina_Value v, const Eina_Future *dead_future)
580 * { 638 * {
@@ -589,11 +647,11 @@ EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promi
589 * same effect as creating a promise and immediately resolving it. 647 * same effect as creating a promise and immediately resolving it.
590 * 648 *
591 * @note This function is to be used solely inside of a future resolve callback with 649 * @note This function is to be used solely inside of a future resolve callback with
592 * the Eina_Value being returned from it. 650 * the #Eina_Value being returned from it.
593 * 651 *
594 * @param[in] dead_future The future being resolved to get a scheduler from. 652 * @param[in] dead_future The future being resolved to get a scheduler from.
595 * @param[in] cancel_cb A callback used to inform that the promise was canceled. Use 653 * @param[in] cancel_cb A callback used to inform that the promise was canceled. Use
596 * this callback to @c free @p data. @p cancel_cb must not be @c NULL ! 654 * this callback to @c free @p data. @p cancel_cb must not be @c NULL.
597 * @param[in] data Data to @p cancel_cb. 655 * @param[in] data Data to @p cancel_cb.
598 * @return A promise or @c NULL on error. 656 * @return A promise or @c NULL on error.
599 * @see eina_future_cancel() 657 * @see eina_future_cancel()
@@ -602,9 +660,9 @@ EAPI Eina_Promise *eina_promise_new(Eina_Future_Scheduler *scheduler, Eina_Promi
602 * @see eina_promise_resolve() 660 * @see eina_promise_resolve()
603 * @see eina_promise_reject() 661 * @see eina_promise_reject()
604 * @see eina_promise_as_value() 662 * @see eina_promise_as_value()
605 * @see #Eina_Future_Scheduler 663 * @see Eina_Future_Scheduler
606 * @see #Eina_Future_Scheduler_Entry 664 * @see Eina_Future_Schedule_Entry
607 * @see #Eina_Future_Scheduler_Cb 665 * @see Eina_Future_Scheduler_Cb
608 */ 666 */
609EAPI Eina_Promise *eina_promise_continue_new(const Eina_Future *dead_future, Eina_Promise_Cancel_Cb cancel_cb, const void *data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT; 667EAPI Eina_Promise *eina_promise_continue_new(const Eina_Future *dead_future, Eina_Promise_Cancel_Cb cancel_cb, const void *data) EINA_ARG_NONNULL(1, 2) EINA_WARN_UNUSED_RESULT;
610 668
@@ -639,7 +697,7 @@ EAPI void eina_promise_resolve(Eina_Promise *p, Eina_Value value) EINA_ARG_NONNU
639 * 697 *
640 * @param[in,out] p A promise to reject. 698 * @param[in,out] p A promise to reject.
641 * @param[in] err An Eina_Error value 699 * @param[in] err An Eina_Error value
642 * @note Internally this function will create an Eina_Value with type #EINA_VALUE_TYPE_ERROR. 700 * @note Internally this function will create an #Eina_Value with type #EINA_VALUE_TYPE_ERROR.
643 * 701 *
644 * @see eina_promise_new() 702 * @see eina_promise_new()
645 * @see eina_promise_resolve() 703 * @see eina_promise_resolve()
@@ -653,23 +711,27 @@ EAPI void eina_promise_reject(Eina_Promise *p, Eina_Error err) EINA_ARG_NONNULL(
653 */ 711 */
654 712
655/** 713/**
656 * @defgroup Eina_Future Eina_Future 714 * @defgroup Eina_Future Eina Futures
715 * @ingroup Eina_Promise
716 * @brief Methods and structures dealing with #Eina_Future
717 * @{
718 */
719
720/**
657 * Cancels a future. 721 * Cancels a future.
658 * 722 *
659 * This function will cancel the whole future chain immediately (it will not be schedule to the next mainloop pass) 723 * This function will cancel the whole future chain immediately (it will not be schedule to the next mainloop pass)
660 * and it will also cancel the promise linked against it. The Eina_Future_Cb will be called 724 * and it will also cancel the promise linked against it. The #Eina_Future_Cb will be called
661 * with an Eina_Value typed as #EINA_VALUE_TYPE_ERROR, which its value will be 725 * with an #Eina_Value typed as #EINA_VALUE_TYPE_ERROR, with its value set to @c ECANCELED
662 * ECANCELED
663 * @param[in,out] f The future to cancel. 726 * @param[in,out] f The future to cancel.
664 * @{
665 */ 727 */
666EAPI void eina_future_cancel(Eina_Future *f) EINA_ARG_NONNULL(1); 728EAPI void eina_future_cancel(Eina_Future *f) EINA_ARG_NONNULL(1);
667 729
668/** 730/**
669 * Flushes an #Eina_Future_Desc 731 * Flushes an #Eina_Future_Desc
670 * 732 *
671 * This function is mainly used by bindings to flush a #Eina_Future_Desc. 733 * This function is mainly used by bindings to flush an #Eina_Future_Desc.
672 * It will call the #Eina_Future_Cb with `ENOMEM` and zero the @p desc contents. 734 * It will call the #Eina_Future_Cb with @c ENOMEM and zero the @p desc contents.
673 * 735 *
674 * @param[in,out] desc The #Eina_Future_Desc to flush, if @c NULL this is a noop. 736 * @param[in,out] desc The #Eina_Future_Desc to flush, if @c NULL this is a noop.
675 */ 737 */
@@ -678,8 +740,8 @@ EAPI void eina_future_desc_flush(Eina_Future_Desc *desc);
678/** 740/**
679 * Flushes an #Eina_Future_Cb_Easy_Desc 741 * Flushes an #Eina_Future_Cb_Easy_Desc
680 * 742 *
681 * This function is mainly used by bindings to flush a #Eina_Future_Cb_Easy_Desc. 743 * This function is mainly used by bindings to flush an #Eina_Future_Cb_Easy_Desc.
682 * It will call the #Eina_Future_Error_Cb with `ENOMEM`, the #Eina_Future_Free_Cb and 744 * It will call the #Eina_Future_Error_Cb with @c ENOMEM, the #Eina_Future_Free_Cb and
683 * zero the @p desc contents. 745 * zero the @p desc contents.
684 * 746 *
685 * @param[in,out] desc The #Eina_Future_Cb_Easy_Desc to flush, if @c NULL this is a noop. 747 * @param[in,out] desc The #Eina_Future_Cb_Easy_Desc to flush, if @c NULL this is a noop.
@@ -687,11 +749,11 @@ EAPI void eina_future_desc_flush(Eina_Future_Desc *desc);
687EAPI void eina_future_cb_easy_desc_flush(Eina_Future_Cb_Easy_Desc *desc); 749EAPI void eina_future_cb_easy_desc_flush(Eina_Future_Cb_Easy_Desc *desc);
688 750
689/** 751/**
690 * Creates a new Eina_Value from a promise. 752 * Creates a new #Eina_Value from a promise.
691 * 753 *
692 * This function creates a new Eina_Value that will store a promise 754 * This function creates a new #Eina_Value that will store an #Eina_Promise
693 * in it. This function is useful for dealing with promises inside 755 * in it. This function is useful for dealing with promises inside
694 * a #Eina_Future_Cb. By returning a Promise Eina_Value the 756 * an #Eina_Future_Cb. By returning a promise inside the #Eina_Value the
695 * whole chain will wait until the promise is resolved in 757 * whole chain will wait until the promise is resolved in
696 * order to continue its execution. Example: 758 * order to continue its execution. Example:
697 * 759 *
@@ -756,8 +818,8 @@ EAPI void eina_future_cb_easy_desc_flush(Eina_Future_Cb_Easy_Desc *desc);
756 * } 818 * }
757 * @endcode 819 * @endcode
758 * 820 *
759 * @param[in,out] p The promise obect to create the value from. 821 * @param[in,out] p The promise object to wrap in a value.
760 * @return An Eina_Value. On error the value's type will be @c NULL. 822 * @return An #Eina_Value. On error the value's type will be @c NULL.
761 * 823 *
762 * @note If an error happens the promise will be CANCELED. 824 * @note If an error happens the promise will be CANCELED.
763 * @see eina_future_as_value() 825 * @see eina_future_as_value()
@@ -767,10 +829,10 @@ EAPI void eina_future_cb_easy_desc_flush(Eina_Future_Cb_Easy_Desc *desc);
767EAPI Eina_Value eina_promise_as_value(Eina_Promise *p) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 829EAPI Eina_Value eina_promise_as_value(Eina_Promise *p) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
768 830
769/** 831/**
770 * Creates an Eina_Value from a future. 832 * Creates an #Eina_Value from a future.
771 * 833 *
772 * This function is used for the same purposes as eina_promise_as_value(), 834 * This function is used for the same purposes as eina_promise_as_value(),
773 * but receives an Eina_Future instead. 835 * but receives an #Eina_Future instead.
774 * 836 *
775 * @param[in,out] f A future to create a Eina_Value from. 837 * @param[in,out] f A future to create a Eina_Value from.
776 * @return An Eina_Value. On error the value's type will be @c NULL. 838 * @return An Eina_Value. On error the value's type will be @c NULL.
@@ -808,7 +870,7 @@ EAPI Eina_Future *eina_future_new(Eina_Promise *p) EINA_ARG_NONNULL(1) EINA_WARN
808 * Creates a new future that is already resolved to a value. 870 * Creates a new future that is already resolved to a value.
809 * 871 *
810 * This function creates a new future with an already known value, 872 * This function creates a new future with an already known value,
811 * that will be resolved and dispatched by the given @a scheduler as 873 * that will be resolved and dispatched by the given @p scheduler as
812 * usual. 874 * usual.
813 * 875 *
814 * This is a helper that behaves the same as eina_promise_new() 876 * This is a helper that behaves the same as eina_promise_new()
@@ -840,18 +902,18 @@ EAPI Eina_Future *eina_future_resolved(Eina_Future_Scheduler *scheduler, Eina_Va
840 * Creates a new future that is already rejected to a specified error. 902 * Creates a new future that is already rejected to a specified error.
841 * 903 *
842 * This function creates a new future with an already known error, 904 * This function creates a new future with an already known error,
843 * that will be resolved and dispatched by the given @a scheduler as 905 * that will be resolved and dispatched by the given @p scheduler as
844 * usual. 906 * usual.
845 * 907 *
846 * This is a helper that behaves the same as eina_promise_new() 908 * This is a helper that behaves the same as eina_promise_new()
847 * followed by eina_future_new() and then eina_promise_rejected(). 909 * followed by eina_future_new() and then eina_promise_reject().
848 * 910 *
849 * Futures can also be canceled using eina_future_cancel(), which will 911 * Futures can also be canceled using eina_future_cancel(), which will
850 * cause the whole chain to be canceled alongside with any pending 912 * cause the whole chain to be canceled alongside with any pending
851 * promise. 913 * promise.
852 * 914 *
853 * @param[in,out] scheduler The scheduler to use. 915 * @param[in,out] scheduler The scheduler to use.
854 * @param[in] err An Eina_Error value 916 * @param[in] err An #Eina_Error value
855 * 917 *
856 * @return The future or @c NULL on error. 918 * @return The future or @c NULL on error.
857 * 919 *
@@ -864,17 +926,17 @@ EAPI Eina_Future *eina_future_resolved(Eina_Future_Scheduler *scheduler, Eina_Va
864EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Error err); 926EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Error err);
865 927
866/** 928/**
867 * Register an Eina_Future_Desc to be used when the future is resolve/rejected. 929 * Register an #Eina_Future_Desc to be used when the future is resolved/rejected.
868 * 930 *
869 * With this function a callback and data is attached to the future and then 931 * With this function a callback and data is attached to the future and then
870 * once it's resolved or rejected the callback will be informed. 932 * once it's resolved or rejected the callback will be informed.
871 * 933 *
872 * If during the future creation an error happens this function will return @c NULL, 934 * If during the future creation an error happens this function will return @c NULL,
873 * and the #Eina_Future_Desc::cb will be called reporting an error (`EINVAL` or `ENOMEM`), 935 * and the Eina_Future_Desc::cb will be called reporting an error (@c EINVAL or @c ENOMEM),
874 * so the user has a chance to free #Eina_Future_Desc::data. 936 * so the user has a chance to free Eina_Future_Desc::data.
875 * 937 *
876 * In case a future in the chain is canceled, the whole chain will be canceled immediately 938 * In case a future in the chain is canceled, the whole chain will be canceled immediately
877 * and the error `ECANCELED` will be reported. 939 * and the error @c ECANCELED will be reported.
878 * 940 *
879 * Here's a simple usage of this function. 941 * Here's a simple usage of this function.
880 * 942 *
@@ -915,17 +977,18 @@ EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Er
915 * @endcode 977 * @endcode
916 * 978 *
917 * Although the code presented at `_size_ready()` is very simple, most of it 979 * Although the code presented at `_size_ready()` is very simple, most of it
918 * is just used to check the Eina_Value type. In order 980 * is just used to check the #Eina_Value type. In order
919 * to avoid this type of code the function eina_future_cb_easy_from_desc() 981 * to avoid this type of code the function eina_future_cb_easy_from_desc()
920 * was created. Please, check its documentation for more information. 982 * was created. Please, check its documentation for more information.
921 * 983 *
922 * This function can also be used to create a future chain, making 984 * This function can also be used to create a future chain, making
923 * it possible to execute the future result in a cascade order. When 985 * it possible to execute the future result in a cascade order. When
924 * using a future chain the Eina_Value returned by a #Eina_Future_Desc::cb 986 * using a future chain the #Eina_Value returned by a Eina_Future_Desc::cb
925 * will be delivered to the next #Eina_Future_Desc::cb in the chain. 987 * will be delivered to the next Eina_Future_Desc::cb in the chain.
926 * 988 *
927 * Here's an example: 989 * Here's an example:
928 * 990 *
991 * @code
929 * static Eina_Value 992 * static Eina_Value
930 * _future_cb1(const *data EINA_UNUSED, const Eina_Value v) 993 * _future_cb1(const *data EINA_UNUSED, const Eina_Value v)
931 * { 994 * {
@@ -978,7 +1041,6 @@ EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Er
978 * return new_v; 1041 * return new_v;
979 * } 1042 * }
980 * 1043 *
981 * @code
982 * void chain(void) 1044 * void chain(void)
983 * { 1045 * {
984 * Eina_Future *f = get_file_size_async("/MyFile.txt"); 1046 * Eina_Future *f = get_file_size_async("/MyFile.txt");
@@ -992,11 +1054,11 @@ EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Er
992 * } 1054 * }
993 * @endcode 1055 * @endcode
994 * 1056 *
995 * Although it's possible to create a future chain using eina_future_then()/eina_future_then_from_desc() 1057 * Although it's possible to create a future chain using eina_future_then() and eina_future_then_from_desc()
996 * there's a function that makes this task much easier, please check eina_future_chain_array() for more 1058 * there's a function that makes this task much easier, please check eina_future_chain_array() for more
997 * information. 1059 * information.
998 * @note This example does manual conversion and print, however we offer 1060 * @note This example does manual conversion and print, however Eina offers
999 * eina_future_cb_convert_to() and eina_future_cb_console_from_desc() and to make those common case easier. 1061 * eina_future_cb_convert_to() and eina_future_cb_console_from_desc() to make those common case easier.
1000 * 1062 *
1001 * @param[in,out] prev A future to link against 1063 * @param[in,out] prev A future to link against
1002 * @param[in] desc A description struct containing the callback and data. 1064 * @param[in] desc A description struct containing the callback and data.
@@ -1005,7 +1067,7 @@ EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Er
1005 * desc.cb will be called in order to free desc.data. 1067 * desc.cb will be called in order to free desc.data.
1006 * @see eina_future_new() 1068 * @see eina_future_new()
1007 * @see eina_future_then() 1069 * @see eina_future_then()
1008 * @see #Eina_Future_Desc 1070 * @see Eina_Future_Desc
1009 * @see eina_future_chain_array() 1071 * @see eina_future_chain_array()
1010 * @see eina_future_chain() 1072 * @see eina_future_chain()
1011 * @see eina_future_cb_console_from_desc() 1073 * @see eina_future_cb_console_from_desc()
@@ -1018,30 +1080,28 @@ EAPI Eina_Future *eina_future_rejected(Eina_Future_Scheduler *scheduler, Eina_Er
1018 */ 1080 */
1019EAPI Eina_Future *eina_future_then_from_desc(Eina_Future *prev, const Eina_Future_Desc desc) EINA_ARG_NONNULL(1); 1081EAPI Eina_Future *eina_future_then_from_desc(Eina_Future *prev, const Eina_Future_Desc desc) EINA_ARG_NONNULL(1);
1020 1082
1021
1022/** 1083/**
1023 * Creates an Eina_Future_Desc that will log the previous future resolved value. 1084 * Creates an Eina_Future_Desc that will log the previous future resolved value.
1024 * 1085 *
1025 * This function can be used to quickly log the value that an #Eina_Future_Desc::cb 1086 * This function can be used to quickly log the value that an Eina_Future_Desc::cb
1026 * is returning. The returned value will be passed to the next future in the chain without 1087 * is returning. The returned value will be passed to the next future in the chain without
1027 * modifications. 1088 * modifications.
1028 * 1089 *
1029 * There are some helper macros like eina_future_cb_log_dbg() which will automatically 1090 * There are some helper macros like eina_future_cb_log_dbg() which will automatically
1030 * fill the following fields: 1091 * fill the following fields:
1031 * 1092 *
1032 * @li #Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used. 1093 * @li Eina_Future_Cb_Log_Desc::file: The `__FILE__` function will be used.
1033 * @li #Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used. 1094 * @li Eina_Future_Cb_Log_Desc::func: The `__FUNCTION__` macro will be used.
1034 * @li #Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_DBG will be used. 1095 * @li Eina_Future_Cb_Log_Desc::level: `EINA_LOG_LEVEL_DBG` will be used.
1035 * @li #Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used. 1096 * @li Eina_Future_Cb_Log_Desc::domain: `EINA_LOG_DOMAIN_DEFAULT` will be used.
1036 * @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used. 1097 * @li Eina_Future_Cb_Log_Desc::line: The `__LINE__` macro will be used.
1037 *
1038 * 1098 *
1039 * @param[in] desc The description data to be used. 1099 * @param[in] desc The description data to be used.
1040 * @return An #Eina_Future_Desc 1100 * @return An #Eina_Future_Desc
1041 * 1101 *
1042 * @see #Eina_Future_Cb_Log_Desc 1102 * @see Eina_Future_Cb_Log_Desc
1043 * @see efl_future_then() 1103 * @see eina_future_then()
1044 * @see efl_future_chain() 1104 * @see eina_future_chain()
1045 * @see eina_future_cb_log_dbg() 1105 * @see eina_future_cb_log_dbg()
1046 * @see eina_future_cb_log_crit() 1106 * @see eina_future_cb_log_crit()
1047 * @see eina_future_cb_log_err() 1107 * @see eina_future_cb_log_err()
@@ -1057,11 +1117,11 @@ EAPI Eina_Future_Desc eina_future_cb_log_from_desc(const Eina_Future_Cb_Log_Desc
1057 * This behaves exactly like eina_future_then_from_desc(), but makes it easier to create future chains. 1117 * This behaves exactly like eina_future_then_from_desc(), but makes it easier to create future chains.
1058 * 1118 *
1059 * If during the future chain creation an error happens this function will return @c NULL, 1119 * If during the future chain creation an error happens this function will return @c NULL,
1060 * and the #Eina_Future_Desc::cb from the @p descs array will be called reporting an error (`EINVAL` or `ENOMEM`), 1120 * and the Eina_Future_Desc::cb from the @p descs array will be called reporting an error (`EINVAL` or `ENOMEM`),
1061 * so the user has a chance to free #Eina_Future_Desc::data. 1121 * so the user has a chance to free Eina_Future_Desc::data.
1062 * 1122 *
1063 * Just like eina_future_then_from_desc(), the value returned by a #Eina_Future_Desc::cb callback will 1123 * Just like eina_future_then_from_desc(), the value returned by a Eina_Future_Desc::cb callback will
1064 * be delivered to the next #Eina_Future_Desc::cb in the chain. 1124 * be delivered to the next Eina_Future_Desc::cb in the chain.
1065 * 1125 *
1066 * In case a future in the chain is canceled, the whole chain will be canceled immediately 1126 * In case a future in the chain is canceled, the whole chain will be canceled immediately
1067 * and the error `ECANCELED` will be reported. 1127 * and the error `ECANCELED` will be reported.
@@ -1069,7 +1129,6 @@ EAPI Eina_Future_Desc eina_future_cb_log_from_desc(const Eina_Future_Cb_Log_Desc
1069 * Here's an example: 1129 * Here's an example:
1070 * 1130 *
1071 * @code 1131 * @code
1072 *
1073 * // callbacks code.... 1132 * // callbacks code....
1074 * 1133 *
1075 * Eina_Future* chain(void) 1134 * Eina_Future* chain(void)
@@ -1083,13 +1142,14 @@ EAPI Eina_Future_Desc eina_future_cb_log_from_desc(const Eina_Future_Cb_Log_Desc
1083 * @endcode 1142 * @endcode
1084 * 1143 *
1085 * @param[in,out] prev The previous future 1144 * @param[in,out] prev The previous future
1086 * @param[in] descs An array of descriptions. The last element of the array must have the #Eina_Future_Desc::cb set to @c NULL 1145 * @param[in] descs An array of descriptions.
1146 The last element of the array must have the Eina_Future_Desc::cb set to @c NULL
1087 * @return A future or @c NULL on error. 1147 * @return A future or @c NULL on error.
1088 * @note If an error happens the whole future chain will CANCELED and 1148 * @note If an error happens the whole future chain will CANCELED and
1089 * desc.cb will be called in order to free desc.data. 1149 * desc.cb will be called in order to free desc.data.
1090 * @see eina_future_new() 1150 * @see eina_future_new()
1091 * @see eina_future_then() 1151 * @see eina_future_then()
1092 * @see #Eina_Future_Desc 1152 * @see Eina_Future_Desc
1093 * @see eina_future_chain() 1153 * @see eina_future_chain()
1094 * @see eina_future_cb_ignore_error() 1154 * @see eina_future_cb_ignore_error()
1095 * @see eina_future_cb_console_from_desc() 1155 * @see eina_future_cb_console_from_desc()
@@ -1111,7 +1171,7 @@ EAPI Eina_Future *eina_future_chain_array(Eina_Future *prev, const Eina_Future_D
1111 * 1171 *
1112 * 1172 *
1113 * @param[in,out] prev The previous future 1173 * @param[in,out] prev The previous future
1114 * @param[in] descs An array of descriptions. The last element of the array must have the #Eina_Future_Desc::cb set to @c NULL 1174 * @param[in] descs An array of descriptions. The last element of the array must have the Eina_Future_Desc::cb set to @c NULL
1115 * @return A future or @c NULL on error. 1175 * @return A future or @c NULL on error.
1116 * @note If an error happens the whole future chain will CANCELED and 1176 * @note If an error happens the whole future chain will CANCELED and
1117 * desc.cb will be called in order to free desc.data. 1177 * desc.cb will be called in order to free desc.data.
@@ -1124,9 +1184,9 @@ EAPI Eina_Future *eina_future_chain_array(Eina_Future *prev, const Eina_Future_D
1124EAPI Eina_Future *eina_future_chain_easy_array(Eina_Future *prev, const Eina_Future_Cb_Easy_Desc descs[]) EINA_ARG_NONNULL(1, 2); 1184EAPI Eina_Future *eina_future_chain_easy_array(Eina_Future *prev, const Eina_Future_Cb_Easy_Desc descs[]) EINA_ARG_NONNULL(1, 2);
1125 1185
1126/** 1186/**
1127 * Creates an Eina_Future_Desc that will print the previous future resolved value. 1187 * Creates an #Eina_Future_Desc that will print the previous future's resolved value.
1128 * 1188 *
1129 * This function can be used to quickly inspect the value that an #Eina_Future_Desc::cb 1189 * This function can be used to quickly inspect the value that an Eina_Future_Desc::cb
1130 * is returning. The returned value will be passed to the next future in the chain without 1190 * is returning. The returned value will be passed to the next future in the chain without
1131 * modifications. 1191 * modifications.
1132 * 1192 *
@@ -1149,12 +1209,12 @@ EAPI Eina_Future *eina_future_chain_easy_array(Eina_Future *prev, const Eina_Fut
1149 * @return An #Eina_Future_Desc 1209 * @return An #Eina_Future_Desc
1150 * 1210 *
1151 * The description object, @p desc, can (optionally) include a prefix, suffix, 1211 * The description object, @p desc, can (optionally) include a prefix, suffix,
1152 * filename and function name. If these are @c NULL, empty strings ("") are used 1212 * filename and function name. If these are @c NULL, empty strings ("") are used
1153 * instead. If @p desc->suffix is provided, the '\n' should be provided to ensure 1213 * instead. If @p desc->suffix is provided, the '\\n' should be provided to ensure
1154 * the printed string ends with a line feed. 1214 * the printed string ends with a line feed.
1155 * 1215 *
1156 * @see eina_future_then() 1216 * @see eina_future_then()
1157 * @see #Eina_Future_Desc 1217 * @see Eina_Future_Desc
1158 * @see eina_future_chain() 1218 * @see eina_future_chain()
1159 * @see eina_future_cb_easy_from_desc() 1219 * @see eina_future_cb_easy_from_desc()
1160 * @see eina_future_cb_easy() 1220 * @see eina_future_cb_easy()
@@ -1167,10 +1227,10 @@ EAPI Eina_Future *eina_future_chain_easy_array(Eina_Future *prev, const Eina_Fut
1167EAPI Eina_Future_Desc eina_future_cb_console_from_desc(const Eina_Future_Cb_Console_Desc desc) EINA_WARN_UNUSED_RESULT; 1227EAPI Eina_Future_Desc eina_future_cb_console_from_desc(const Eina_Future_Cb_Console_Desc desc) EINA_WARN_UNUSED_RESULT;
1168 1228
1169/** 1229/**
1170 * Returns a #Eina_Future_Desc that ignores an error. 1230 * Returns an #Eina_Future_Desc that ignores an error.
1171 * 1231 *
1172 * This function may be used if one wants to ignore an error. If the 1232 * This function may be used if one wants to ignore an error. If the
1173 * specified error happens an EINA_VALUE_EMPTY will be delivered to the 1233 * specified error happens an #EINA_VALUE_EMPTY will be delivered to the
1174 * next future in the chain. 1234 * next future in the chain.
1175 * 1235 *
1176 * @param[in] err The error to be ignored. 1236 * @param[in] err The error to be ignored.
@@ -1179,12 +1239,12 @@ EAPI Eina_Future_Desc eina_future_cb_console_from_desc(const Eina_Future_Cb_Cons
1179EAPI Eina_Future_Desc eina_future_cb_ignore_error(Eina_Error err); 1239EAPI Eina_Future_Desc eina_future_cb_ignore_error(Eina_Error err);
1180 1240
1181/** 1241/**
1182 * Creates an #Eina_Future_Desc which will convert the the received eina value to a given type. 1242 * Creates an #Eina_Future_Desc which will convert the received eina value to a given type.
1183 * 1243 *
1184 * @param[in] type The Eina_Value_Type to convert to. 1244 * @param[in] type The #Eina_Value_Type to convert to.
1185 * @return An #Eina_Future_Desc 1245 * @return An #Eina_Future_Desc
1186 * @see eina_future_then() 1246 * @see eina_future_then()
1187 * @see #Eina_Future_Desc 1247 * @see Eina_Future_Desc
1188 * @see eina_future_chain() 1248 * @see eina_future_chain()
1189 * @see eina_future_cb_easy_from_desc() 1249 * @see eina_future_cb_easy_from_desc()
1190 * @see eina_future_cb_easy() 1250 * @see eina_future_cb_easy()
@@ -1194,27 +1254,27 @@ EAPI Eina_Future_Desc eina_future_cb_ignore_error(Eina_Error err);
1194EAPI Eina_Future_Desc eina_future_cb_convert_to(const Eina_Value_Type *type); 1254EAPI Eina_Future_Desc eina_future_cb_convert_to(const Eina_Value_Type *type);
1195 1255
1196/** 1256/**
1197 * Creates an #Eina_Future_Desc based on a #Eina_Future_Cb_Easy_Desc 1257 * Creates an #Eina_Future_Desc based on an #Eina_Future_Cb_Easy_Desc.
1198 * 1258 *
1199 * This function aims to be used in conjunction with eina_future_chain(), 1259 * This function aims to be used in conjunction with eina_future_chain(),
1200 * eina_future_then_from_desc() and friends and its main objective is to simplify 1260 * eina_future_then_from_desc() and friends and its main objective is to simplify
1201 * error handling and Eina_Value type checks. 1261 * error handling and #Eina_Value type checks.
1202 * It uses three callbacks to inform the user about the future's 1262 * It uses three callbacks to inform the user about the future's
1203 * result and life cycle. They are: 1263 * result and life cycle. They are:
1204 * 1264 *
1205 * @li #Eina_Future_Cb_Easy_Desc::success: This callback is called when 1265 * @li Eina_Future_Cb_Easy_Desc::success: This callback is called when
1206 * the future execution was successful, that is, no errors occurred and 1266 * the future execution was successful, that is, no errors occurred and
1207 * the result type matches #Eina_Future_Cb_Easy_Desc::success_type. In case 1267 * the result type matches Eina_Future_Cb_Easy_Desc::success_type. In case
1208 * #Eina_Future_Cb_Easy_Desc::success_type is @c NULL, this function will 1268 * Eina_Future_Cb_Easy_Desc::success_type is @c NULL, this function will
1209 * only be called if the future did not report an error. The value returned 1269 * only be called if the future did not report an error. The value returned
1210 * by this function will be propagated to the next future in the chain (if any). 1270 * by this function will be propagated to the next future in the chain (if any).
1211 * 1271 *
1212 * @li #Eina_Future_Cb_Easy_Desc::error: This callback is called when 1272 * @li Eina_Future_Cb_Easy_Desc::error: This callback is called when
1213 * the future result is an error or #Eina_Future_Cb_Easy_Desc::success_type 1273 * the future result is an error or Eina_Future_Cb_Easy_Desc::success_type
1214 * does not match the future result type. The value returned 1274 * does not match the future result type. The value returned
1215 * by this function will be propagated to the next future in the chain (if any). 1275 * by this function will be propagated to the next future in the chain (if any).
1216 * 1276 *
1217 * @li #Eina_Future_Cb_Easy_Desc::free: Called after the future was freed and any resources 1277 * @li Eina_Future_Cb_Easy_Desc::free: Called after the future was freed and any resources
1218 * allocated must be freed at this point. This callback is always called. 1278 * allocated must be freed at this point. This callback is always called.
1219 * 1279 *
1220 * Check the example below for a sample usage: 1280 * Check the example below for a sample usage:
@@ -1249,7 +1309,6 @@ EAPI Eina_Future_Desc eina_future_cb_convert_to(const Eina_Value_Type *type);
1249 * free(ctx); 1309 * free(ctx);
1250 * } 1310 * }
1251 * 1311 *
1252 * @code
1253 * void do_work(File_Size_Handler_Cb cb) 1312 * void do_work(File_Size_Handler_Cb cb)
1254 * { 1313 * {
1255 * Ctx *ctx = malloc(sizeof(Ctx)); 1314 * Ctx *ctx = malloc(sizeof(Ctx));
@@ -1274,12 +1333,11 @@ EAPI Eina_Future_Desc eina_future_cb_easy_from_desc(const Eina_Future_Cb_Easy_De
1274 * 1333 *
1275 * Creates a promise that is resolved once all the futures 1334 * Creates a promise that is resolved once all the futures
1276 * from the @p array are resolved. 1335 * from the @p array are resolved.
1277 * The promise is resolved with an Eina_Value type array which 1336 * The promise is resolved with an #Eina_Value type array which
1278 * contains EINA_VALUE_TYPE_VALUE elements. The result array is 1337 * contains #EINA_VALUE_TYPE_VALUE elements. The result array is
1279 * ordered according to the @p array argument. Example: 1338 * ordered according to the @p array argument. Example:
1280 * 1339 *
1281 * @code 1340 * @code
1282 *
1283 * static const char * 1341 * static const char *
1284 * _get_operation_name_by_index(int idx) 1342 * _get_operation_name_by_index(int idx)
1285 * { 1343 * {
@@ -1364,7 +1422,7 @@ EAPI Eina_Future_Desc eina_future_cb_easy_from_desc(const Eina_Future_Cb_Easy_De
1364 * } 1422 * }
1365 * @endcode 1423 * @endcode
1366 * 1424 *
1367 * @param[in,out] array An array of futures, @c #EINA_FUTURE_SENTINEL terminated. 1425 * @param[in,out] array An array of futures, terminated with #EINA_FUTURE_SENTINEL.
1368 * @return A promise or @c NULL on error. 1426 * @return A promise or @c NULL on error.
1369 * @note On error all the futures will be CANCELED. 1427 * @note On error all the futures will be CANCELED.
1370 * @see eina_future_all_array() 1428 * @see eina_future_all_array()
@@ -1376,8 +1434,8 @@ EAPI Eina_Promise *eina_promise_all_array(Eina_Future *array[]) EINA_ARG_NONNULL
1376 * 1434 *
1377 * Creates a promise that is resolved once all the futures 1435 * Creates a promise that is resolved once all the futures
1378 * from the @p iterator are resolved. 1436 * from the @p iterator are resolved.
1379 * The promise is resolved with an Eina_Value type array which 1437 * The promise is resolved with an #Eina_Value type array which
1380 * contains EINA_VALUE_TYPE_VALUE elements. The result array is 1438 * contains #EINA_VALUE_TYPE_VALUE elements. The result array is
1381 * ordered according to the @p iterator order. 1439 * ordered according to the @p iterator order.
1382 * 1440 *
1383 * @param[in] iterator An iterator of futures. Will be destroyed after the call. 1441 * @param[in] iterator An iterator of futures. Will be destroyed after the call.
@@ -1394,16 +1452,15 @@ EAPI Eina_Promise *eina_promise_all_iterator(Eina_Iterator *iterator) EINA_ARG_N
1394 * is completed. The remaining futures will be canceled with the 1452 * is completed. The remaining futures will be canceled with the
1395 * error code `ECANCELED` 1453 * error code `ECANCELED`
1396 * 1454 *
1397 * The resulting value is an EINA_VALUE_TYPE_STRUCT with two fields: 1455 * The resulting value is an #EINA_VALUE_TYPE_STRUCT with two fields:
1398 * 1456 *
1399 * @li A field named "value" which contains an Eina_Value with the result itself. 1457 * @li A field named @c value containing an #Eina_Value with the result itself.
1400 * @li A field named "index" which is an int that contains the index of the completed 1458 * @li A field named @c index containing the index of the completed
1401 * function relative to the @p array; 1459 * function relative to the @p array.
1402 * 1460 *
1403 * Example. 1461 * Example:
1404 * 1462 *
1405 * @code 1463 * @code
1406 *
1407 * static const char * 1464 * static const char *
1408 * _get_operation_name_by_index(int idx) 1465 * _get_operation_name_by_index(int idx)
1409 * { 1466 * {
@@ -1492,11 +1549,11 @@ EAPI Eina_Promise *eina_promise_all_iterator(Eina_Iterator *iterator) EINA_ARG_N
1492 * } 1549 * }
1493 * @endcode 1550 * @endcode
1494 * 1551 *
1495 * @param[in,out] array An array of futures, @c #EINA_FUTURE_SENTINEL terminated. 1552 * @param[in,out] array An array of futures, terminated by #EINA_FUTURE_SENTINEL.
1496 * @return A promise or @c NULL on error. 1553 * @return A promise or @c NULL on error.
1497 * @note On error all the futures will be CANCELED. 1554 * @note On error all the futures will be CANCELED.
1498 * @see eina_future_race_array() 1555 * @see eina_future_race_array()
1499 * @see #_Eina_Future_Race_Result 1556 * @see _Eina_Future_Race_Result
1500 */ 1557 */
1501EAPI Eina_Promise *eina_promise_race_array(Eina_Future *array[]) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT; 1558EAPI Eina_Promise *eina_promise_race_array(Eina_Future *array[]) EINA_ARG_NONNULL(1) EINA_WARN_UNUSED_RESULT;
1502 1559
@@ -1528,7 +1585,7 @@ EAPI Eina_Promise *eina_promise_race_array(Eina_Future *array[]) EINA_ARG_NONNUL
1528 * @see eina_future_race_array() 1585 * @see eina_future_race_array()
1529 * @see eina_promise_race() 1586 * @see eina_promise_race()
1530 * @see eina_future_race() 1587 * @see eina_future_race()
1531 * @see #EINA_PROMISE_RACE_STRUCT_DESC 1588 * @see EINA_PROMISE_RACE_STRUCT_DESC
1532 */ 1589 */
1533struct _Eina_Future_Race_Result { 1590struct _Eina_Future_Race_Result {
1534 /** 1591 /**
@@ -1542,17 +1599,17 @@ struct _Eina_Future_Race_Result {
1542}; 1599};
1543 1600
1544/** 1601/**
1545 * @var EINA_PROMISE_RACE_STRUCT_DESC 1602 * @var const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC
1546 * 1603 *
1547 * A pointer to the race struct description, which 1604 * A pointer to the race struct description, which
1548 * is used by eina_promise_race_array(); 1605 * is used by eina_promise_race_array().
1549 * 1606 *
1550 * This struct contains two members: 1607 * This struct contains two members:
1551 * @li value An EINA_VALUE_TYPE_VALUE that contains the future result that wont the race. 1608 * @li @c value: An #EINA_VALUE_TYPE_VALUE that contains the future result that won the race.
1552 * @li index An EINA_VALUE_TYPE_UINT that contains the future index that won the race. 1609 * @li @c index: An #EINA_VALUE_TYPE_UINT that contains the future index that won the race.
1553 * 1610 *
1554 * @see eina_promise_race_array() 1611 * @see eina_promise_race_array()
1555 * @see #_Eina_Future_Race_Result 1612 * @see _Eina_Future_Race_Result
1556 */ 1613 */
1557EAPI extern const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC; 1614EAPI extern const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC;
1558 1615
@@ -1560,10 +1617,10 @@ EAPI extern const Eina_Value_Struct_Desc *EINA_PROMISE_RACE_STRUCT_DESC;
1560 * Creates a future that will be resolved once all futures from @p array is resolved. 1617 * Creates a future that will be resolved once all futures from @p array is resolved.
1561 * This is a helper over eina_promise_all_array() 1618 * This is a helper over eina_promise_all_array()
1562 * 1619 *
1563 * @param[in,out] array A future array, must be terminated with #EINA_FUTURE_SENTINEL 1620 * @param[in,out] array A future array, must be terminated with #EINA_FUTURE_SENTINEL.
1564 * @return A future. 1621 * @return A future.
1565 * @see eina_promise_all_array() 1622 * @see eina_promise_all_array()
1566 * @see #EINA_FUTURE_SENTINEL 1623 * @see EINA_FUTURE_SENTINEL
1567 */ 1624 */
1568static inline Eina_Future * 1625static inline Eina_Future *
1569eina_future_all_array(Eina_Future *array[]) 1626eina_future_all_array(Eina_Future *array[])
@@ -1596,7 +1653,7 @@ eina_future_all_iterator(Eina_Iterator *iterator)
1596 * @param[in,out] array A future array, must be terminated with #EINA_FUTURE_SENTINEL 1653 * @param[in,out] array A future array, must be terminated with #EINA_FUTURE_SENTINEL
1597 * @return A future. 1654 * @return A future.
1598 * @see eina_promise_race_array() 1655 * @see eina_promise_race_array()
1599 * @see #EINA_FUTURE_SENTINEL 1656 * @see EINA_FUTURE_SENTINEL
1600 */ 1657 */
1601static inline Eina_Future * 1658static inline Eina_Future *
1602eina_future_race_array(Eina_Future *array[]) 1659eina_future_race_array(Eina_Future *array[])
@@ -1694,11 +1751,11 @@ eina_future_race_array(Eina_Future *array[])
1694 * 1751 *
1695 * This macro will set the following fields of the #Eina_Future_Cb_Log_Desc: 1752 * This macro will set the following fields of the #Eina_Future_Cb_Log_Desc:
1696 * 1753 *
1697 * @li #Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used. 1754 * @li Eina_Future_Cb_Log_Desc::file: The `__FILE__` function will be used.
1698 * @li #Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used. 1755 * @li Eina_Future_Cb_Log_Desc::func: The `__FUNCTION__` macro will be used.
1699 * @li #Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_DBG will be used. 1756 * @li Eina_Future_Cb_Log_Desc::level: `EINA_LOG_LEVEL_DBG` will be used.
1700 * @li #Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used. 1757 * @li Eina_Future_Cb_Log_Desc::domain: `EINA_LOG_DOMAIN_DEFAULT` will be used.
1701 * @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used. 1758 * @li Eina_Future_Cb_Log_Desc::line: The `__LINE__` macro will be used.
1702 * 1759 *
1703 * Usage: 1760 * Usage:
1704 * @code 1761 * @code
@@ -1713,13 +1770,13 @@ eina_future_race_array(Eina_Future *array[])
1713/** 1770/**
1714 * A syntactic sugar over eina_future_cb_log_from_desc(). 1771 * A syntactic sugar over eina_future_cb_log_from_desc().
1715 * 1772 *
1716 * This macro will set the following fields of the #Eina_Future_Cb_Log_Desc: 1773 * This macro will set the following fields of the Eina_Future_Cb_Log_Desc:
1717 * 1774 *
1718 * @li #Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used. 1775 * @li Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used.
1719 * @li #Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used. 1776 * @li Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used.
1720 * @li #Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_CRITICAL will be used. 1777 * @li Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_CRITICAL will be used.
1721 * @li #Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used. 1778 * @li Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
1722 * @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used. 1779 * @li Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used.
1723 * 1780 *
1724 * Usage: 1781 * Usage:
1725 * @code 1782 * @code
@@ -1734,13 +1791,13 @@ eina_future_race_array(Eina_Future *array[])
1734/** 1791/**
1735 * A syntactic sugar over eina_future_cb_log_from_desc(). 1792 * A syntactic sugar over eina_future_cb_log_from_desc().
1736 * 1793 *
1737 * This macro will set the following fields of the #Eina_Future_Cb_Log_Desc: 1794 * This macro will set the following fields of the Eina_Future_Cb_Log_Desc:
1738 * 1795 *
1739 * @li #Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used. 1796 * @li Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used.
1740 * @li #Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used. 1797 * @li Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used.
1741 * @li #Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_ERR will be used. 1798 * @li Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_ERR will be used.
1742 * @li #Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used. 1799 * @li Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
1743 * @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used. 1800 * @li Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used.
1744 * 1801 *
1745 * Usage: 1802 * Usage:
1746 * @code 1803 * @code
@@ -1755,13 +1812,13 @@ eina_future_race_array(Eina_Future *array[])
1755/** 1812/**
1756 * A syntactic sugar over eina_future_cb_log_from_desc(). 1813 * A syntactic sugar over eina_future_cb_log_from_desc().
1757 * 1814 *
1758 * This macro will set the following fields of the #Eina_Future_Cb_Log_Desc: 1815 * This macro will set the following fields of the Eina_Future_Cb_Log_Desc:
1759 * 1816 *
1760 * @li #Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used. 1817 * @li Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used.
1761 * @li #Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used. 1818 * @li Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used.
1762 * @li #Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_INFO will be used. 1819 * @li Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_INFO will be used.
1763 * @li #Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used. 1820 * @li Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
1764 * @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used. 1821 * @li Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used.
1765 * 1822 *
1766 * Usage: 1823 * Usage:
1767 * @code 1824 * @code
@@ -1776,18 +1833,21 @@ eina_future_race_array(Eina_Future *array[])
1776/** 1833/**
1777 * A syntactic sugar over eina_future_cb_log_from_desc(). 1834 * A syntactic sugar over eina_future_cb_log_from_desc().
1778 * 1835 *
1779 * This macro will set the following fields of the #Eina_Future_Cb_Log_Desc: 1836 * This macro will set the following fields of the Eina_Future_Cb_Log_Desc:
1780 * 1837 *
1781 * @li #Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used. 1838 * @li Eina_Future_Cb_Log_Desc::file: The __FILE__ function will be used.
1782 * @li #Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used. 1839 * @li Eina_Future_Cb_Log_Desc::func: The __FUNCTION__ macro will be used.
1783 * @li #Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_WARN will be used. 1840 * @li Eina_Future_Cb_Log_Desc::level: EINA_LOG_LEVEL_WARN will be used.
1784 * @li #Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used. 1841 * @li Eina_Future_Cb_Log_Desc::domain: EINA_LOG_DOMAIN_DEFAULT will be used.
1785 * @li #Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used. 1842 * @li Eina_Future_Cb_Log_Desc::line: The __LINE__ macro will be used.
1786 * 1843 *
1787 * Usage: 1844 * Usage:
1788 * @code 1845 * @code
1789 * desc = eina_future_cb_log_warn(.prefix = "prefix", .suffix = "suffix"); 1846 * desc = eina_future_cb_log_warn(.prefix = "prefix", .suffix = "suffix");
1790 * @endcode 1847 * @endcode
1848 * @param _prefix PREFIX
1849 * @param _suffix SUFFIX
1850 * @returns SOMETHING
1791 * @see eina_future_cb_log_from_desc() 1851 * @see eina_future_cb_log_from_desc()
1792 */ 1852 */
1793#define eina_future_cb_log_warn(_prefix, _suffix) \ 1853#define eina_future_cb_log_warn(_prefix, _suffix) \