Eina Future Callbacks
Eina » Eina Promises » Eina Futures

Methods and structures dealing with Eina_Future callbacks. More...

## Data Structures

struct | _Eina_Future_Schedule_Entry
| A struct that represents an scheduled event. More...
struct | _Eina_Future_Scheduler
| This struct is used as a bridge between Eina and the future scheduler. More...
struct | _Eina_Future_Cb_Easy_Desc
| A struct with callbacks to be used by eina_future_cb_easy_from_desc() and eina_future_cb_easy(). More...
struct | _Eina_Future_Cb_Console_Desc
| A struct used to define the prefix and suffix to be printed along side the a future value. More...
struct | _Eina_Future_Cb_Log_Desc
| This struct is used by eina_future_cb_log_from_desc() and its contents will be routed to eina_log_print() along side the future value. More...

## Typedefs

typedef struct _Eina_Future_Cb_Easy_Desc | Eina_Future_Cb_Easy_Desc
| Convenience wrapper over _Eina_Future_Cb_Easy_Desc.
typedef struct _Eina_Future_Cb_Console_Desc | Eina_Future_Cb_Console_Desc
| Convenience wrapper over _Eina_Future_Cb_Console_Desc.
typedef struct _Eina_Future_Scheduler | Eina_Future_Scheduler
| Convenience wrapper over _Eina_Future_Scheduler.
typedef struct _Eina_Future_Schedule_Entry | Eina_Future_Schedule_Entry
| Convenience wrapper over _Eina_Future_Schedule_Entry.
typedef struct _Eina_Future_Cb_Log_Desc | Eina_Future_Cb_Log_Desc
| Convenience wrapper over _Eina_Future_Cb_Log_Desc.
typedef Eina_Value(* | Eina_Future_Cb) (void *data, const Eina_Value value, const Eina_Future *dead_future)
| A callback used to inform that a future was resolved.
typedef void(* | Eina_Future_Scheduler_Cb) (Eina_Future *f, Eina_Value value)
| A callback used by the Eina_Future_Scheduler to deliver the future operation result.
typedef void(* | Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_promise)
| A callback used to inform that a promise was canceled.
typedef Eina_Value(* | Eina_Future_Success_Cb) (void *data, const Eina_Value value)
| A callback used to inform that the future completed with success.
typedef Eina_Value(* | Eina_Future_Error_Cb) (void *data, const Eina_Error error)
| A callback used to inform that the future completed with failure.
typedef void(* | Eina_Future_Free_Cb) (void *data, const Eina_Future *dead_future)
| A callback used to inform that the future was freed and the user should also `free` the `data`.

## Detailed Description

Methods and structures dealing with Eina_Future callbacks.

## Typedef Documentation

## Eina_Future_Cb

typedef Eina_Value(* Eina_Future_Cb) (void *data, const Eina_Value value, const Eina_Future *dead_future)

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:

- eina_future_cancel() was used, it's called immediately in the context that called cancel using ECANCELED as error.

- eina_future_then(), eina_future_then_from_desc(), eina_future_chain(), eina_future_chain_array() or similar failed due to invalid pointer or memory allocation. Then the callback is called from the failed context using EINVAL or ENOMEM as errors and `dead_future` will be `NULL`.

Parameters

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

Returns
  An Eina_Value to pass to the next Eina_Future in the chain (if any). If there is no need to convert the received value, it's recommended to passthrough the `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).

Note
  The returned value can be an EINA_VALUE_TYPE_PROMISE! (see eina_promise_as_value() and eina_future_as_value()) In this case the future chain will wait until the promise is resolved.

See also
  eina_future_cancel()
  eina_future_then()
  eina_future_then_from_desc()
  eina_future_then_easy()
  eina_future_chain()
  eina_future_chain_array()
  eina_future_as_value()
  eina_promise_as_value()

## Eina_Future_Scheduler_Cb

typedef void(* Eina_Future_Scheduler_Cb) (Eina_Future *f, Eina_Value value)

A callback used by the Eina_Future_Scheduler to deliver the future operation result.

Parameters

  [out] | f | The delivered future.
  [in] | value | The future result

See also
  eina_promise_new()
  Eina_Future_Schedule_Entry
  Eina_Future_Scheduler

## Eina_Promise_Cancel_Cb

typedef void(* Eina_Promise_Cancel_Cb) (void *data, const Eina_Promise *dead_promise)

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.

Note
  - This callback is mandatory for a reason, do not provide an empty callback as it'll likely result in memory corruption and invalid access. If impossible to cancel an asynchronous task, then create an intermediate memory to hold Eina_Promise and make it `NULL`, in this callback. Then prior to resolution check if the pointer is set.
  - This callback is not called if eina_promise_resolve() or eina_promise_reject() are used. If any cleanup is needed, then call yourself. It's only meant as cancellation, not a general "free callback".

Parameters

  [in] | data | The data provided by the user.
  [in] | dead_promise | The canceled promise.

See also
  eina_promise_reject()
  eina_promise_resolve()
  eina_future_cancel()

## Eina_Future_Success_Cb

typedef Eina_Value(* Eina_Future_Success_Cb) (void *data, const Eina_Value value)

A callback used to inform that the future completed with success.

Unlike Eina_Future_Cb this callback is 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.

Note
  This function is always called from a safe context (main loop or some platform defined safe context).

Parameters

  [in] | data | The data provided by the user.
  [in] | value | The operation result

Returns
  An Eina_Value to pass to the next Eina_Future in the chain (if any). If there is no need to convert the received value, it's recommended to passthrough `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).

See also
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()

## Eina_Future_Error_Cb

typedef Eina_Value(* Eina_Future_Error_Cb) (void *data, const Eina_Error error)

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

Parameters

  [in] | data | The data provided by the user.
  [in] | error | The operation error

Returns
  An Eina_Value to pass to the next Eina_Future in the chain (if any). 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).

See also
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()

## Eina_Future_Free_Cb

typedef void(* Eina_Future_Free_Cb) (void *data, const Eina_Future *dead_future)

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.

Note
  This callback is always called, even if Eina_Future_Error_Cb and/or Eina_Future_Success_Cb were not provided, which can also be used to monitor when a future ends.

Parameters

  [in] | data | The data provided by the user.
  [in] | dead_future | The future that was freed.

See also
  eina_future_cb_easy_from_desc()
  eina_future_cb_easy()