Creates a new promise. More...
Functions | |
EAPI Eina_Promise * | eina_promise_new (Eina_Future_Scheduler *scheduler, Eina_Promise_Cancel_Cb cancel_cb, const void *data) |
EAPI Eina_Promise * | eina_promise_continue_new (const Eina_Future *dead_future, Eina_Promise_Cancel_Cb cancel_cb, const void *data) |
Creates a new promise from a dead_future. More... | |
EAPI void | eina_promise_resolve (Eina_Promise *p, Eina_Value value) |
Resolves a promise. More... | |
EAPI void | eina_promise_reject (Eina_Promise *p, Eina_Error err) |
Rejects a promise. More... | |
typedef struct _Eina_Future_Desc | Eina_Future_Desc |
typedef struct _Eina_Promise | Eina_Promise |
typedef struct _Eina_Future | Eina_Future |
typedef struct _Eina_Future_Cb_Easy_Desc | Eina_Future_Cb_Easy_Desc |
typedef struct _Eina_Future_Cb_Console_Desc | Eina_Future_Cb_Console_Desc |
typedef struct _Eina_Future_Scheduler | Eina_Future_Scheduler |
typedef struct _Eina_Future_Schedule_Entry | Eina_Future_Schedule_Entry |
typedef struct _Eina_Future_Race_Result | Eina_Future_Race_Result |
typedef struct _Eina_Future_Cb_Log_Desc | Eina_Future_Cb_Log_Desc |
typedef Eina_Value(* | Eina_Future_Cb) (void *data, const Eina_Value value, const Eina_Future *dead_future) |
typedef void(* | Eina_Future_Scheduler_Cb) (Eina_Future *f, Eina_Value value) |
typedef void(* | Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_promise) |
typedef Eina_Value(* | Eina_Future_Success_Cb) (void *data, const Eina_Value value) |
typedef Eina_Value(* | Eina_Future_Error_Cb) (void *data, const Eina_Error error) |
typedef void(* | Eina_Future_Free_Cb) (void *data, const Eina_Future *dead_future) |
Creates a new promise.
This function creates a new promise which can be used to create a future using eina_future_new(). Every time a promise is created a Eina_Promise_Cancel_Cb must be provided which is used to free resources that were created.
A promise may be canceled directly by calling eina_future_cancel
(eina_future_new(eina_promise_new(...))) that is, canceling any future that is chained to receive the results.
However promises can be canceled indirectly by other entities. These other entities will call eina_future_cancel()
themselves, however you may not be aware of that. Some common sources of indirect cancellations:
Since a promise may be canceled indirectly (by code sections that goes beyond your scope) you should always provide a cancel callback, even if you think you'll not need it.
Here's a typical example:
If you already have a value and want to create a future that will resolve to it directly use the eina_future_resolved(), it has the same effect as creating a promise and immediately resolving it.
[in,out] | scheduler | The scheduler. |
[in] | cancel_cb | A callback used to inform that the promise was canceled. Use this callback to free data . cancel_cb must not be NULL ! |
[in] | data | Data to cancel_cb . |
NULL
on error. Eina_Future_Cb Eina_Future_Cb |
A callback used to inform that a future was resolved. Usually this callback is called from a clean context, that is, from the main loop or some platform defined safe context. However there are 2 exceptions:
ECANCELED
as error.EINVAL
or ENOMEM
as errors and dead_future
will be NULL
.[in] | data | The data provided by the user |
[in] | value | An Eina_Value which contains the operation result. Before using the value , its type must be checked in order to avoid errors. This is needed because if an operation fails the Eina_Value type will be EINA_VALUE_TYPE_ERROR which is a different type than the expected operation result. |
[in] | dead_future | A pointer to the future that was completed. |
value
argument. If you need to convert to a different type or generate a new value, use eina_value_setup()
on another Eina_Value and return it. By returning a promise Eina_Value (eina_promise_as_value()) the whole chain will wait until the promise is resolved in order to continue its execution. 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).Eina_Future_Scheduler_Cb |
A callback used by the Eina_Future_Scheduler to deliver the future operation result.
[out] | f | The delivered future. |
[in] | value | The future result |
Eina_Promise_Cancel_Cb Eina_Promise_Cancel_Cb |
A callback used to inform that a promise was canceled.
A promise may be canceled by the user calling eina_future_cancel()
on any Eina_Future that is part of the chain that uses an Eina_Promise, that will cancel the whole chain and then the promise.
It should stop all asynchronous operations or at least mark them to be discarded instead of resolved. Actually it can't be resolved once canceled since the given pointer dead_promise
is now invalid.
NULL
, in this callback. Then prior to resolution check if the pointer is set.[in] | data | The data provided by the user. |
[in] | dead_promise | The canceled promise. |
Eina_Future_Success_Cb Eina_Future_Success_Cb |
A callback used to inform that the future completed with success.
Unlike Eina_Future_Cb this callback only called if the future operation was successful, this is, no errors occurred (value
type differs from EINA_VALUE_TYPE_ERROR) and the value
matches _Eina_Future_Cb_Easy_Desc::success_type (if given). In case _Eina_Future_Cb_Easy_Desc::success_type was not supplied (it's NULL
) the value
type must be checked before using it.
[in] | data | The data provided by the user. |
[in] | value | The operation result |
value
argument. If you need to convert to a different type or generate a new value, use eina_value_setup()
on another Eina_Value and return it. By returning a promise Eina_Value (eina_promise_as_value()) the whole chain will wait until the promise is resolved in order to continue its execution. 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). Eina_Future_Error_Cb Eina_Future_Error_Cb |
A callback used to inform that the future completed with failure.
Unlike Eina_Future_Success_Cb this function is only called when an error occurs during the future process or when _Eina_Future_Cb_Easy_Desc::success_type differs from the future result. On future creation errors and future cancellation this function will be called from the current context with the following errors respectfully: EINVAL
, ENOMEM
and ECANCELED
. Otherwise this function is called from a safe context.
If it was possible to recover from an error this function should return an empty value return EINA_VALUE_EMPTY;
or any other Eina_Value type that differs from EINA_VALUE_TYPE_ERROR. In this case the error will not be reported by the other futures in the chain (if any), otherwise if an Eina_Value type EINA_VALUE_TYPE_ERROR is returned the error will continue to be reported to the other futures in the chain.
[in] | data | The data provided by the user. |
[in] | error | The operation error |
eina_value_setup()
on another Eina_Value and return it. By returning a promise Eina_Value (eina_promise_as_value()) the whole chain will wait until the promise is resolved in order to continue its execution. 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). Eina_Future_Free_Cb Eina_Future_Free_Cb |
A callback used to inform that the future was freed and the user should also free
the data
. This callback may be called from an unsafe context if the future was canceled or an error occurred.
[in] | data | The data provided by the user. |
[in] | dead_future | The future that was freed. |
EAPI Eina_Promise* eina_promise_continue_new | ( | const Eina_Future * | dead_future, |
Eina_Promise_Cancel_Cb | cancel_cb, | ||
const void * | data | ||
) |
Creates a new promise from a dead_future.
This function creates a new promise from a future currently being resolved which can be used to create a Eina_Value with eina_promise_as_value(). Every time a promise is created a Eina_Promise_Cancel_Cb must be provided which is used to free resources that were created.
A promise may be canceled directly by calling eina_future_cancel
(eina_future_new(eina_promise_new(...))) that is, canceling any future that is chained to receive the results.
However promises can be canceled indirectly by other entities. These other entities will call eina_future_cancel()
themselves, however you may not be aware of that. Some common sources of indirect cancellations:
Since a promise may be canceled indirectly (by code sections that goes beyond your scope) you should always provide a cancel callback, even if you think you'll not need it.
Here's a typical example:
If you already have a value and want to create a future that will resolve to it directly use the eina_future_resolved(), it has the same effect as creating a promise and immediately resolving it.
[in] | dead_future | The future being resolved to get a scheduler from. |
[in] | cancel_cb | A callback used to inform that the promise was canceled. Use this callback to free data . cancel_cb must not be NULL ! |
[in] | data | Data to cancel_cb . |
NULL
on error. References DBG, eina_mempool_calloc(), EINA_SAFETY_ON_NULL_RETURN_VAL, and EINA_SAFETY_ON_TRUE_RETURN_VAL.
EAPI void eina_promise_resolve | ( | Eina_Promise * | p, |
Eina_Value | value | ||
) |
Resolves a promise.
This function schedules a resolve event in a safe context (main loop or some platform defined safe context), whenever possible the future callbacks will be dispatched.
[in,out] | p | A promise to resolve. |
[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).
References eina_value_flush().
EAPI void eina_promise_reject | ( | Eina_Promise * | p, |
Eina_Error | err | ||
) |
Rejects a promise.
This function schedules a reject event in a safe context (main loop or some platform defined safe context), whenever possible the future callbacks will be dispatched.
[in,out] | p | A promise to reject. |
[in] | err | An Eina_Error value |
References DBG, eina_error_msg_get(), EINA_SAFETY_ON_FALSE_GOTO, eina_value_flush(), eina_value_set(), eina_value_setup(), and EINA_VALUE_TYPE_ERROR.