143 lines
4.6 KiB
C
143 lines
4.6 KiB
C
#ifndef EFL_FUTURE_H_
|
|
# define EFL_FUTURE_H_
|
|
|
|
/**
|
|
* @addtogroup Efl_Future Efl future and promise.
|
|
* @{
|
|
*/
|
|
|
|
/**
|
|
* @typedef Efl_Promise
|
|
* The type of Efl Promise used in asynchronous operation, the write side of a promise.
|
|
*/
|
|
typedef Eo Efl_Promise;
|
|
#define _EFL_PROMISE_EO_CLASS_TYPE
|
|
|
|
#define EFL_FUTURE_CLASS efl_future_class_get()
|
|
EWAPI const Efl_Class *efl_future_class_get(void); /**< @since 1.19 */
|
|
|
|
/**
|
|
* @var EINA_ERROR_FUTURE_CANCEL
|
|
* @brief The error identifier corresponding to a future being canceled.
|
|
*/
|
|
EAPI extern Eina_Error EINA_ERROR_FUTURE_CANCEL; /**< @since 1.19 */
|
|
|
|
/** Parameter passed in event callbacks in case of future failure to proceed.
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
typedef struct _Efl_Future_Event_Failure Efl_Future_Event_Failure;
|
|
struct _Efl_Future_Event_Failure
|
|
{
|
|
Efl_Promise *next; /** The promise to the next future. Allowing to send a processed value down the chain. */
|
|
Eina_Error error; /** The error generated trying to process the request. */
|
|
};
|
|
|
|
/** Parameter passed in event callbacks in case of future succeeding to proceed.
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
typedef struct _Efl_Future_Event_Success Efl_Future_Event_Success;
|
|
struct _Efl_Future_Event_Success
|
|
{
|
|
Efl_Promise *next; /** The promise to the next future. Allowing to send a processed value down the chain. */
|
|
void *value; /** The value return by the processed request. The type is defined by the function executing the request. */
|
|
};
|
|
|
|
/** Parameter passed in event callbacks while a future is progressing a request.
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
typedef struct _Efl_Future_Event_Progress Efl_Future_Event_Progress;
|
|
struct _Efl_Future_Event_Progress
|
|
{
|
|
Efl_Promise *next; /** The promise to the next future. Allowing to send a processed progress down the chain. */
|
|
const void *progress; /** The progress status updated by the processed request. The type is defined by the function executing the request. */
|
|
};
|
|
|
|
EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_FAILURE;
|
|
EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_SUCCESS;
|
|
EOAPI extern const Efl_Event_Description _EFL_FUTURE_EVENT_PROGRESS;
|
|
|
|
/** A future failed
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
#define EFL_FUTURE_EVENT_FAILURE (&(_EFL_FUTURE_EVENT_FAILURE))
|
|
|
|
/** A future succeeded
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
#define EFL_FUTURE_EVENT_SUCCESS (&(_EFL_FUTURE_EVENT_SUCCESS))
|
|
|
|
/** A future progressed
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
#define EFL_FUTURE_EVENT_PROGRESS (&(_EFL_FUTURE_EVENT_PROGRESS))
|
|
|
|
/**
|
|
* @brief Add sets of callbacks to handle the progress and the result of a future.
|
|
*
|
|
* callbacks are called depending on the outcome of the promise related to the future.
|
|
*
|
|
* @param[in] success the callback to call in case of a succesful computation from the promise
|
|
* @param[in] failure the callback to call in case of a failure to deliver from the promise
|
|
* @param[in] progress the callback to call during the progression of the the promise, this is optional
|
|
* @param[in] data additional data to pass to the callback
|
|
*
|
|
* @return Return a new future when the callback has been successfully added pointing to the next request
|
|
* being processed during the future success, failure or progress callback (You can reference count the next
|
|
* promise to defer the result and make it asynchronous too. This future can be ignored.
|
|
*
|
|
* @note except if you do reference count the Efl.Future object, you can only call once this function.
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
EOAPI Efl_Future *efl_future_then(Eo *obj, Efl_Event_Cb success, Efl_Event_Cb failure, Efl_Event_Cb progress, const void *data);
|
|
|
|
/**
|
|
* @brief Cancel the need for that specific future.
|
|
*
|
|
* This will trigger the failure of the future and may result in the promise stopping its computation as
|
|
* it will be notified when there is no more need for computing the request.
|
|
*
|
|
* @see efl_future_use
|
|
*
|
|
* @ingroup Efl_Future
|
|
*
|
|
* @since 1.19
|
|
*/
|
|
EOAPI void efl_future_cancel(Eo *obj);
|
|
|
|
/**
|
|
* @brief To be used in conjunction with when you plan to use efl_future_cancel
|
|
*
|
|
* This function will store in *wref, obj and make sure that on failure or success of the future, it
|
|
* will be reset to NULL. This guarantee that the pointer you are using will always be correct and
|
|
* that you do not have to worry about passing a dead pointer to efl_future_cancel.
|
|
*
|
|
* @param[out] storage Will be set to obj and tracked during all the lifetime of the future.
|
|
* @param[in] future The future to remember about.
|
|
*
|
|
* @see efl_future_cancel
|
|
*
|
|
* @ingroup Efl_Future
|
|
*/
|
|
static inline void
|
|
efl_future_use(Efl_Future **storage, Eo *future)
|
|
{
|
|
efl_wref_add(future, storage);
|
|
}
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
/**
|
|
* @}
|
|
*/
|
|
|
|
#endif
|