Ecore Idle functions

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 Eo Ecore_Idler
 A handle for idlers.
 
typedef Eo Ecore_Idle_Enterer
 A handle for idle enterers.
 
typedef Eo Ecore_Idle_Exiter
 A handle for idle exiters.
 

Functions

static Eina_Bool _ecore_idle_enterer_add (Ecore_Idle_Enterer *obj, Ecore_Idle_Enterer_Private_Data *ie, Ecore_Task_Cb func, const void *data)
 
EAPI Ecore_Idle_Entererecore_idle_enterer_add (Ecore_Task_Cb func, const void *data)
 Add an idle enterer handler. More...
 
static void _idle_enterer_after_constructor (Eo *obj, void *_pd, va_list *list)
 
EAPI Ecore_Idle_Entererecore_idle_enterer_before_add (Ecore_Task_Cb func, const void *data)
 Add an idle enterer handler at the start of the list so it gets called earlier than others. More...
 
static void _idle_enterer_before_constructor (Eo *obj, void *_pd, va_list *list)
 
static void _constructor (Eo *obj, void *_pd, va_list *list)
 
EAPI void * ecore_idle_enterer_del (Ecore_Idle_Enterer *idle_enterer)
 Delete an idle enterer callback. More...
 
EAPI Ecore_Idle_Exiterecore_idle_exiter_add (Ecore_Task_Cb func, const void *data)
 Add an idle exiter handler. More...
 
static void _idle_exiter_constructor (Eo *obj, void *_pd, va_list *list)
 
EAPI void * ecore_idle_exiter_del (Ecore_Idle_Exiter *idle_exiter)
 Delete an idle exiter handler from the list to be run on exiting idle state. More...
 
const Eo_Classecore_idler_class_get (void)
 
const Eo_Classecore_idle_enterer_class_get (void)
 
const Eo_Classecore_idle_exiter_class_get (void)
 
#define ECORE_IDLER_CLASS   ecore_idler_class_get()
 
#define ECORE_IDLER_ID(sub_id)   (ECORE_IDLER_BASE_ID + sub_id)
 
#define ecore_idler_constructor(func, data)   ECORE_IDLER_ID(ECORE_IDLER_SUB_ID_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
 
#define ECORE_IDLE_ENTERER_CLASS   ecore_idle_enterer_class_get()
 
#define ECORE_IDLE_ENTERER_ID(sub_id)   (ECORE_IDLE_ENTERER_BASE_ID + sub_id)
 
#define ecore_idle_enterer_after_constructor(func, data)   ECORE_IDLE_ENTERER_ID(ECORE_IDLE_ENTERER_SUB_ID_AFTER_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
 
#define ecore_idle_enterer_before_constructor(func, data)   ECORE_IDLE_ENTERER_ID(ECORE_IDLE_ENTERER_SUB_ID_BEFORE_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
 
#define ECORE_IDLE_EXITER_CLASS   ecore_idle_exiter_class_get()
 
#define ECORE_IDLE_EXITER_ID(sub_id)   (ECORE_IDLE_EXITER_BASE_ID + sub_id)
 
#define ecore_idle_exiter_constructor(func, data)   ECORE_IDLE_EXITER_ID(ECORE_IDLE_EXITER_SUB_ID_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
 
enum  {
  ECORE_IDLER_SUB_ID_CONSTRUCTOR,
  ECORE_IDLER_SUB_ID_LAST
}
 
enum  {
  ECORE_IDLE_ENTERER_SUB_ID_AFTER_CONSTRUCTOR,
  ECORE_IDLE_ENTERER_SUB_ID_BEFORE_CONSTRUCTOR,
  ECORE_IDLE_ENTERER_SUB_ID_LAST
}
 
enum  {
  ECORE_IDLE_EXITER_SUB_ID_CONSTRUCTOR,
  ECORE_IDLE_EXITER_SUB_ID_LAST
}
 
Eo_Op ECORE_IDLER_BASE_ID
 
Eo_Op ECORE_IDLE_ENTERER_BASE_ID
 
Eo_Op ECORE_IDLE_EXITER_BASE_ID
 
Ecore_Idlerecore_idler_add (Ecore_Task_Cb func, const void *data)
 Add an idler handler. More...
 
void * ecore_idler_del (Ecore_Idler *idler)
 Delete an idler callback from the list to be executed. More...
 

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:

Macro Definition Documentation

#define ecore_idler_constructor (   func,
  data 
)    ECORE_IDLER_ID(ECORE_IDLER_SUB_ID_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
Since
1.8

Contructor.

Parameters
[in]func
[in]data

Referenced by ecore_idler_add().

#define ecore_idle_enterer_after_constructor (   func,
  data 
)    ECORE_IDLE_ENTERER_ID(ECORE_IDLE_ENTERER_SUB_ID_AFTER_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
Since
1.8

Contructor. Will insert the handler at the end of the list.

Parameters
[in]func
[in]data

Referenced by ecore_idle_enterer_add().

#define ecore_idle_enterer_before_constructor (   func,
  data 
)    ECORE_IDLE_ENTERER_ID(ECORE_IDLE_ENTERER_SUB_ID_BEFORE_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
Since
1.8

Contructor. Will insert the handler at the beginning of the list.

Parameters
[in]func
[in]data

Referenced by ecore_idle_enterer_before_add().

#define ecore_idle_exiter_constructor (   func,
  data 
)    ECORE_IDLE_EXITER_ID(ECORE_IDLE_EXITER_SUB_ID_CONSTRUCTOR), EO_TYPECHECK(Ecore_Task_Cb, func), EO_TYPECHECK(const void *, data)
Since
1.8

Contructor.

Parameters
[in]func
[in]data

Referenced by ecore_idle_exiter_add().

Function Documentation

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

Add an idle enterer handler.

Parameters
funcThe function to call when entering an idle state.
dataThe 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.
Examples:
ecore_idler_example.c.

References EAPI, ecore_idle_enterer_after_constructor, eina_inlist_append(), and EINA_INLIST_GET.

Referenced by ecore_evas_init(), ecore_wl_init(), and ecore_x_init().

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

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

Parameters
funcThe function to call when entering an idle state.
dataThe 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.

References EAPI, ecore_idle_enterer_before_constructor, EINA_INLIST_GET, eina_inlist_prepend(), and EINA_UNUSED.

EAPI void* ecore_idle_enterer_del ( Ecore_Idle_Enterer idle_enterer)

Delete an idle enterer callback.

Parameters
idle_entererThe idle enterer to delete
Returns
The data pointer passed to the idler enterer callback on success. NULL otherwise.
Examples:
ecore_idler_example.c.

References EINA_FALSE, EINA_INLIST_GET, eina_inlist_remove(), and EINA_MAIN_LOOP_CHECK_RETURN_VAL.

Referenced by ecore_evas_shutdown(), ecore_wl_server_mode_set(), and ecore_x_double_click_time_get().

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

Add an idle exiter handler.

Parameters
funcThe function to call when exiting an idle state.
dataThe 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.
Examples:
ecore_idler_example.c.

References EAPI, ecore_idle_exiter_constructor, eina_inlist_append(), EINA_INLIST_GET, EINA_MAIN_LOOP_CHECK_RETURN, eina_main_loop_is(), EINA_TRUE, EINA_UNLIKELY, and EINA_UNUSED.

EAPI void* ecore_idle_exiter_del ( Ecore_Idle_Exiter idle_exiter)

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

Parameters
idle_exiterThe idle exiter to delete
Returns
The data pointer that was being being passed to the handler if successful. NULL otherwise.
Examples:
ecore_idler_example.c.

References EINA_FALSE, EINA_INLIST_GET, eina_inlist_remove(), EINA_MAIN_LOOP_CHECK_RETURN_VAL, and EINA_UNUSED.

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

Add an idler handler.

Parameters
funcThe function to call when idling.
dataThe 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 prossessing data without blocking.

References EAPI, ecore_idler_constructor, eina_inlist_append(), EINA_INLIST_GET, EINA_MAIN_LOOP_CHECK_RETURN, eina_main_loop_is(), EINA_TRUE, EINA_UNLIKELY, and EINA_UNUSED.

Referenced by ecore_con_url_proxy_password_set(), ecore_wl_dnd_drag_types_get(), eldbus_name_owner_changed_callback_add(), eldbus_service_interface_register(), eldbus_service_property_changed(), eldbus_shutdown(), and ethumb_client_generate().

void* ecore_idler_del ( Ecore_Idler idler)

Delete an idler callback from the list to be executed.

Parameters
idlerThe handle of the idler callback to delete
Returns
The data pointer passed to the idler callback on success, NULL otherwise.

References EINA_FALSE, EINA_INLIST_GET, eina_inlist_remove(), EINA_MAIN_LOOP_CHECK_RETURN_VAL, and EINA_UNUSED.

Referenced by ecore_con_url_proxy_password_set(), ecore_con_url_shutdown(), eldbus_connection_ref(), eldbus_name_owner_changed_callback_del(), eldbus_service_interface_register(), eldbus_service_object_manager_attach(), and eldbus_shutdown().