Ecore Idle functions
Ecore » Ecore main loop

The idler functionality in Ecore allows for callbacks to be called when the program isn't handling events, timers or fd handlers. More...

## Typedefs

typedef struct _Ecore_Factorized_Idle | Ecore_Idler
| A handle for idlers.
typedef struct _Ecore_Factorized_Idle | Ecore_Idle_Enterer
| A handle for idle enterers.
typedef struct _Ecore_Factorized_Idle | Ecore_Idle_Exiter
| A handle for idle exiters.

## Functions

Ecore_Idler * | ecore_idler_add (Ecore_Task_Cb func, const void *data)
| Adds an idler handler.
void * | ecore_idler_del (Ecore_Idler *idler)
| Deletes an idler callback from the list to be executed.
Ecore_Idle_Enterer * | ecore_idle_enterer_add (Ecore_Task_Cb func, const void *data)
| Adds an idle enterer handler.
Ecore_Idle_Enterer * | ecore_idle_enterer_before_add (Ecore_Task_Cb func, const void *data)
| Adds an idle enterer handler at the start of the list so it gets called earlier than others.
void * | ecore_idle_enterer_del (Ecore_Idle_Enterer *idle_enterer)
| Deletes an idle enterer callback.
Ecore_Idle_Exiter * | ecore_idle_exiter_add (Ecore_Task_Cb func, const void *data)
| Adds an idle exiter handler.
void * | ecore_idle_exiter_del (Ecore_Idle_Exiter *idle_exiter)
| Deletes an idle exiter handler from the list to be run on exiting idle state.

## Detailed Description

The idler functionality in Ecore allows for callbacks to be called when the program isn't handling events, timers or fd handlers.

There are three types of idlers: Enterers, Idlers(proper) and Exiters. They are called, respectively, when the program is about to enter an idle state, when the program is in an idle state and when the program has just left an idle state and will begin processing events, timers or fd handlers.

Enterer callbacks are good for updating your program's state, if it has a state engine. Once all of the enterer handlers are called, the program will enter a "sleeping" state.

Idler callbacks are called when the main loop has called all enterer handlers. They are useful for interfaces that require polling and timers would be too slow to use.

Exiter callbacks are called when the main loop wakes up from an idle state.

If no idler callbacks are specified, then the process literally goes to sleep. Otherwise, the idler callbacks are called continuously while the loop is "idle", using as much CPU as is available to the process.

Note
  Idle state doesn't mean that the program is idle, but that the main loop is idle. It doesn't have any timers, events, fd handlers or anything else to process (which in most event driven programs also means that the program is idle too, but it's not a rule). The program itself may be doing a lot of processing in the idler, or in another thread, for example.

Example with functions that deal with idle state:

- ecore idle state - Idlers, enterers and exiters

## Function Documentation

## ecore_idler_add()

Ecore_Idler * ecore_idler_add | ( | Ecore_Task_Cb | func,
|  | const void * | data )

Adds an idler handler.

Parameters

  func | The function to call when idling.
  data | The data to be passed to this `func` call.

Returns
  A idler handle if successfully added, `NULL` otherwise.

Add an idler handle to the event loop, returning a handle on success and `NULL` otherwise. The function `func` will be called repeatedly while no other events are ready to be processed, as long as it returns `1` (or `ECORE_CALLBACK_RENEW`). A return of `0` (or `ECORE_CALLBACK_CANCEL`) deletes the idler.

Idlers are useful for progressively processing data without blocking.

## ecore_idler_del()

void * ecore_idler_del | ( | Ecore_Idler * | idler | ) |

Deletes an idler callback from the list to be executed.

Parameters

  idler | The handle of the idler callback to delete

Returns
  The data pointer passed to the idler callback on success, `NULL` otherwise.

Referenced by ethumb_free().

## ecore_idle_enterer_add()

Ecore_Idle_Enterer * ecore_idle_enterer_add | ( | Ecore_Task_Cb | func,
|  | const void * | data )

Adds an idle enterer handler.

Parameters

  func | The function to call when entering an idle state.
  data | The data to be passed to the `func` call

Returns
  A handle to the idle enterer callback if successful. Otherwise, `NULL` is returned.

Note
  The function func will be called every time the main loop is entering idle state, as long as it returns `1` (or `ECORE_CALLBACK_RENEW`). A return of `0` (or `ECORE_CALLBACK_CANCEL`) deletes the idle enterer.

Referenced by ecore_evas_init(), ecore_wl_init(), eldbus_name_owner_changed_callback_add(), and eldbus_service_property_changed().

## ecore_idle_enterer_before_add()

Ecore_Idle_Enterer * ecore_idle_enterer_before_add | ( | Ecore_Task_Cb | func,
|  | const void * | data )

Adds an idle enterer handler at the start of the list so it gets called earlier than others.

Parameters

  func | The function to call when entering an idle state.
  data | The data to be passed to the `func` call

Returns
  A handle to the idle enterer callback if successful. Otherwise, `NULL` is returned.

Note
  The function func will be called every time the main loop is entering idle state, as long as it returns `1` (or `ECORE_CALLBACK_RENEW`). A return of `0` (or `ECORE_CALLBACK_CANCEL`) deletes the idle enterer.

## ecore_idle_enterer_del()

void * ecore_idle_enterer_del | ( | Ecore_Idle_Enterer * | idle_enterer | ) |

Deletes an idle enterer callback.

Parameters

  idle_enterer | The idle enterer to delete

Returns
  The data pointer passed to the idler enterer callback on success. `NULL` otherwise.

Referenced by ecore_evas_shutdown(), eldbus_name_owner_changed_callback_del(), and eldbus_service_object_manager_attach().

## ecore_idle_exiter_add()

Ecore_Idle_Exiter * ecore_idle_exiter_add | ( | Ecore_Task_Cb | func,
|  | const void * | data )

Adds an idle exiter handler.

Parameters

  func | The function to call when exiting an idle state.
  data | The data to be passed to the `func` call.

Returns
  A handle to the idle exiter callback on success. `NULL` otherwise.

Note
  The function func will be called every time the main loop is exiting idle state, as long as it returns `1` (or `ECORE_CALLBACK_RENEW`). A return of `0` (or `ECORE_CALLBACK_CANCEL`) deletes the idle exiter.

Referenced by ecore_evas_init().

## ecore_idle_exiter_del()

void * ecore_idle_exiter_del | ( | Ecore_Idle_Exiter * | idle_exiter | ) |

Deletes an idle exiter handler from the list to be run on exiting idle state.

Parameters

  idle_exiter | The idle exiter to delete

Returns
  The data pointer that was being being passed to the handler if successful. `NULL` otherwise.

Referenced by ecore_evas_shutdown().