Ecore main loop
Ecore

This group discusses functions that are acting on Ecore's main loop itself or on events and infrastructure directly linked to it. More...

## Topics

| Ecore Event functions
| Ecore events provide two main features that are of use to those using ecore: creating events and being notified of events.
| Process Spawning Functions
| This module is responsible for managing portable processes using Ecore.
| File Descriptor Handling Functions
| Definition for functions that deal with file descriptor handlers.
| Ecore Thread functions
| Facilities to run heavy tasks in different threads to avoid blocking the main loop.
| Pipe wrapper
| These functions wrap the pipe / write / read functions to easily integrate its use into ecore's main loop.
| Ecore Throttle functions
| Ecore Poll functions
| Ecore poller provides infrastructure for the creation of pollers.
| Ecore Animator functions
| Ecore animators are a helper to simplify creating animations.
| Ecore Timer functions
| Ecore provides very flexible timer functionality.
| 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.
| Ecore Job functions
| You can queue jobs that are to be done by the main loop when the current event is dealt with.

## Data Structures

struct | _Ecore_Version

## Macros

#define | ECORE_VERSION_MAJOR EFL_VERSION_MAJOR
| Ecore version major number.
#define | ECORE_VERSION_MINOR EFL_VERSION_MINOR
| Ecore version minor number.
#define | ECORE_CALLBACK_CANCEL EINA_FALSE
| Return value to remove a callback.
#define | ECORE_CALLBACK_RENEW EINA_TRUE
| Return value to keep a callback.
#define | ECORE_CALLBACK_PASS_ON EINA_TRUE
| Return value to pass event to next handler.
#define | ECORE_CALLBACK_DONE EINA_FALSE
| Return value to stop event handling.

## Typedefs

typedef struct _Ecore_Version | Ecore_Version
| This is the Ecore version information structure that can be used at runtime to detect which version of ecore is being used and adapt appropriately as follows for example:
typedef Eina_Bool(* | Ecore_Task_Cb) (void *data)
| A callback run for a task (timer, idler, poller, animator, etc).
typedef int(* | Ecore_Select_Function) (int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout)
| A function which can be used to replace select() in the main loop.
typedef void(* | Ecore_Cb) (void *data)
| A generic callback called as a hook when a certain point in execution is reached.
typedef void *(* | Ecore_Data_Cb) (void *data)
| A callback which is used to return data to the main function.

## Functions

void | ecore_main_loop_iterate (void)
| Runs a single iteration of the main loop to process everything on the queue.
int | ecore_main_loop_iterate_may_block (int may_block)
| Runs a single iteration of the main loop to process everything on the queue with blocking/non-blocking status.
void | ecore_main_loop_select_func_set (Ecore_Select_Function func)
| Sets the function to use when monitoring multiple file descriptors, and waiting until one of more of the file descriptors are ready for some class of I/O operation.
Ecore_Select_Function | ecore_main_loop_select_func_get (void)
| Gets the select function set by ecore_select_func_set(), or the native select function if none was set.
Eina_Bool | ecore_main_loop_glib_integrate (void)
| Requests ecore to integrate GLib's main loop.
void | ecore_main_loop_glib_always_integrate_disable (void)
| Disables always integrating GLib.
void | ecore_main_loop_begin (void)
| Runs the application main loop.
void | ecore_main_loop_quit (void)
| Quits the main loop once all the events currently on the queue have been processed.
Eina_Bool | ecore_main_loop_animator_ticked_get (void)
| Returns if an animator has ticked off during this loop iteration.
int | ecore_main_loop_nested_get (void)
| Returns if the ecore_main_loop is running.
Eina_Bool | ecore_fork_reset_callback_add (Ecore_Cb func, const void *data)
| Adds a function to be called by ecore_fork_reset().
Eina_Bool | ecore_fork_reset_callback_del (Ecore_Cb func, const void *data)
| This removes the callback specified.
void | ecore_fork_reset (void)
| Resets the ecore internal state after a fork.
void | ecore_main_loop_thread_safe_call_async (Ecore_Cb callback, void *data)
| Calls callback asynchronously in the main loop.
void * | ecore_main_loop_thread_safe_call_sync (Ecore_Data_Cb callback, void *data)
| Calls callback synchronously in the main loop.
void | ecore_main_loop_thread_safe_call_wait (double wait)
| Waits for the next thread call in the main loop.
int | ecore_thread_main_loop_begin (void)
| This function suspends the main loop in a know state.
int | ecore_thread_main_loop_end (void)
| Unlocks the main loop.
Eina_Bool | efl_loop_register (Efl_Loop *obj, const Efl_Class *klass, const Efl_Object *provider)
| Please use efl_provider_register instead.
Eina_Bool | efl_loop_unregister (Efl_Loop *obj, const Efl_Class *klass, const Efl_Object *provider)
| Please use efl_provider_unregister instead.
void | efl_exit (int exit_code)
| Quits the main loop once all the events currently on the queue have been processed.
int | efl_loop_exit_code_process (Eina_Value *value)
Eina_Future_Scheduler * | efl_loop_future_scheduler_get (const Eo *obj)
| Get the future scheduler for the current loop.
Eo * | efl_main_loop_get (void)

## Variables

Ecore_Version * | ecore_version

## Detailed Description

This group discusses functions that are acting on Ecore's main loop itself or on events and infrastructure directly linked to it.

Most programs only need to start and end the main loop, the rest of the functions discussed here are meant to be used in special situations, and with great care.

For details on the usage of ecore's main loop and how it interacts with other ecore facilities see: The Ecore Main Loop.

## Typedef Documentation

## Ecore_Version

typedef struct _Ecore_Version Ecore_Version

This is the Ecore version information structure that can be used at runtime to detect which version of ecore is being used and adapt appropriately as follows for example:

#if defined(ECORE_VERSION_MAJOR) && (ECORE_VERSION_MAJOR >= 1) && defined(ECORE_VERSION_MINOR) && (ECORE_VERSION_MINOR > 0)
printf("Ecore version: %i.%i.%i\n",
ecore_version->major,
ecore_version->minor,
ecore_version->micro);
if (ecore_version->revision > 0)
{
printf(" Built from Git revision # %i\n", ecore_version->revision);
}
#endif

## Function Documentation

## ecore_main_loop_iterate()

void ecore_main_loop_iterate | ( | void |  | ) |

Runs a single iteration of the main loop to process everything on the queue.

It does everything that is already done inside an `Ecore` main loop, like checking for expired timers, idlers, etc. But it will do it only once and return, instead of keeping watch for new events.

DO NOT use this function unless you are the person God comes to ask for advice when He has trouble managing the Universe.

See also
  ecore_main_loop_iterate_may_block()

References EINA_MAIN_LOOP_CHECK_RETURN.

Referenced by ecore_con_server_flush(), ecore_ipc_server_flush(), elm_quicklaunch_seed(), elm_quicklaunch_sub_shutdown(), elm_shutdown(), and emotion_shutdown().

## ecore_main_loop_iterate_may_block()

int ecore_main_loop_iterate_may_block | ( | int | may_block | ) |

Runs a single iteration of the main loop to process everything on the queue with blocking/non-blocking status.

Parameters

  may_block | A flag if the main loop has a possibility of blocking. (`EINA_TRUE` = may block/`EINA_FALSE` = non block)

This is an extension API for ecore_main_loop_iterate() with additional parameter. It does everything that is already done inside an `Ecore` main loop, like checking for expired timers, idlers, etc. But it will do it only once and return, instead of keep watching for new events.

DO NOT use this function unless you are the person God comes to ask for advice when He has trouble managing the Universe.

Returns
  `1` if event exists, else `0`.

See also
  ecore_main_loop_iterate()

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

## ecore_main_loop_select_func_set()

void ecore_main_loop_select_func_set | ( | Ecore_Select_Function | func | ) |

Sets the function to use when monitoring multiple file descriptors, and waiting until one of more of the file descriptors are ready for some class of I/O operation.

This function will be used instead of the system call select and could possibly be used to integrate the Ecore event loop with an external event loop.

Warning
  you don't know how to use, don't even try to use it.

Parameters

  func | The function to be used.

References EINA_MAIN_LOOP_CHECK_RETURN.

Referenced by ecore_main_loop_glib_integrate().

## ecore_main_loop_select_func_get()

Ecore_Select_Function ecore_main_loop_select_func_get | ( | void |  | ) |

Gets the select function set by ecore_select_func_set(), or the native select function if none was set.

Returns
  A function which can be used to replace select() in the main loop.

References EINA_MAIN_LOOP_CHECK_RETURN_VAL.

Referenced by ecore_main_loop_glib_integrate().

## ecore_main_loop_glib_integrate()

Eina_Bool ecore_main_loop_glib_integrate | ( | void |  | ) |

Requests ecore to integrate GLib's main loop.

This will add a small overhead during every main loop interaction by checking GLib's default main context (used by its main loop). If it have events to be checked (timers, file descriptors or idlers), then these will be polled alongside with Ecore's own events, then dispatched before Ecore's. This is done by calling ecore_main_loop_select_func_set().

This will cooperate with previously set ecore_main_loop_select_func_set() by calling the old function. Similarly, if you want to override ecore_main_loop_select_func_set() after main loop is integrated, call the new select function set by this call (get it by calling ecore_main_loop_select_func_get() right after ecore_main_loop_glib_integrate()).

This is useful to use GMainLoop libraries, like GTK, GUPnP, LibSoup, GConf and more. Adobe Flash plugin and other plugins systems depend on this as well.

Once initialized/integrated, it will be valid until Ecore is completely shut down.

Example of use:

int main(void)
{
ecore_init();
ecore_main_loop_glib_integrate();
// some code here
ecore_main_loop_begin();
ecore_shutdown();
return 0;
}
ecore_shutdown
EAPI int ecore_shutdown(void)
Shuts down connections, signal handlers sockets etc.
Definition ecore.c:371
ecore_init
EAPI int ecore_init(void)
Sets up connections, signal handlers, sockets etc.
Definition ecore.c:230
ecore_main_loop_glib_integrate
Eina_Bool ecore_main_loop_glib_integrate(void)
Requests ecore to integrate GLib's main loop.
Definition ecore_glib.c:290
ecore_main_loop_begin
void ecore_main_loop_begin(void)
Runs the application main loop.
Definition ecore_main.c:1311

Returns
  `EINA_TRUE` on success of, `EINA_FALSE` if it failed likely due to no GLib support in Ecore.

Note
  This is only available if Ecore was compiled with GLib support.
  You don't need to call this function if Ecore was compiled with. –with-glib=always.

References ecore_main_loop_select_func_get(), ecore_main_loop_select_func_set(), EINA_FALSE, EINA_TRUE, and ERR.

Referenced by ecore_init().

## ecore_main_loop_glib_always_integrate_disable()

void ecore_main_loop_glib_always_integrate_disable | ( | void |  | ) |

Disables always integrating GLib.

If ecore is compiled with –with-glib=always (to always call ecore_main_loop_glib_integrate() when ecore_init() is called), then calling this before calling ecore_init() will disable the integration. This is for apps that explicitly do not want this to happen for whatever reasons they may have.

## ecore_main_loop_begin()

void ecore_main_loop_begin | ( | void |  | ) |

Runs the application main loop.

This function will not return until ecore_main_loop_quit is called. It will check for expired timers, idlers, file descriptors being watched by fd handlers, etc. Once everything is done, before entering again on idle state, any callback set as `Idle_Enterer` will be called.

This function should be called once only from the same thread that initted ecore, eina etc. (ecore_init(), eina_init(), ...) and should never be nested. Never call it from within an instance of itself.

Each main loop iteration is done by calling ecore_main_loop_iterate() internally.

The polling (select) function used can be changed with ecore_main_loop_select_func_set().

The function used to check for file descriptors, events, and that has a timeout for the timers can be changed using ecore_main_loop_select_func_set().

Examples
  banshee.c, client.c, complex-types-client-eina-value.c, complex-types-server.c, complex-types.c, connman-list-services.c, ecore_animator_example.c, ecore_con_client_example.c, ecore_con_client_simple_example.c, ecore_con_lookup_example.c, ecore_con_server_example.c, ecore_con_server_simple_example.c, ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, ecore_con_url_headers_example.c, ecore_evas_basics_example.c, ecore_evas_buffer_example_02.c, ecore_evas_callbacks.c, ecore_evas_object_example.c, ecore_evas_window_sizes_example.c, ecore_event_example_01.c, ecore_event_example_02.c, ecore_exe_example.c, ecore_exe_example_child.c, ecore_fd_handler_example.c, ecore_idler_example.c, ecore_imf_example.c, ecore_job_example.c, ecore_pipe_gstreamer_example.c, ecore_pipe_simple_example.c, ecore_poller_example.c, ecore_thread_example.c, ecore_time_functions_example.c, ecore_timer_example.c, edje-basic.c, edje-box.c, edje-box2.c, edje-color-class.c, edje-drag.c, edje-perspective.c, edje-signals-messages.c, edje-swallow.c, edje-table.c, edje-text.c, eina_tiler_01.c, eio_file_ls.c, emotion_basic_example.c, emotion_signals_example.c, emotion_test_main.c, evas-aspect-hints.c, evas-box.c, evas-events.c, evas-hints.c, evas-images.c, evas-images2.c, evas-map-utils.c, evas-object-manipulation.c, evas-smart-interface.c, evas-smart-object.c, evas-stacking.c, evas-table.c, evas-text.c, ofono-dial.c, and server.c.

References DBG, eina_evlog(), and EINA_MAIN_LOOP_CHECK_RETURN.

Referenced by elm_run().

## ecore_main_loop_quit()

void ecore_main_loop_quit | ( | void |  | ) |

Quits the main loop once all the events currently on the queue have been processed.

This function returns immediately, but if called inside the main loop it will mark the ecore_main_loop_begin() function to return at the end of the current main loop iteration.

Examples
  banshee.c, client.c, complex-types.c, ecore_con_client_example.c, ecore_con_client_simple_example.c, ecore_con_lookup_example.c, ecore_con_url_cookies_example.c, ecore_con_url_download_example.c, ecore_con_url_headers_example.c, ecore_evas_basics_example.c, ecore_evas_buffer_example_02.c, ecore_evas_callbacks.c, ecore_evas_window_sizes_example.c, ecore_event_example_01.c, ecore_event_example_02.c, ecore_exe_example.c, ecore_exe_example_child.c, ecore_fd_handler_example.c, ecore_idler_example.c, ecore_job_example.c, ecore_pipe_simple_example.c, ecore_poller_example.c, ecore_thread_example.c, ecore_time_functions_example.c, edje-basic.c, edje-box.c, edje-box2.c, edje-color-class.c, edje-drag.c, edje-perspective.c, edje-signals-messages.c, edje-swallow.c, edje-table.c, edje-text.c, eio_file_ls.c, emotion_test_main.c, evas-box.c, evas-hints.c, evas-images.c, evas-images2.c, evas-map-utils.c, evas-smart-interface.c, evas-smart-object.c, evas-stacking.c, evas-table.c, evas-text.c, and server.c.

References EINA_MAIN_LOOP_CHECK_RETURN, EINA_VALUE_EMPTY, and EINA_VALUE_TYPE_INT.

Referenced by ecore_sdl_feed_events().

## ecore_main_loop_animator_ticked_get()

Eina_Bool ecore_main_loop_animator_ticked_get | ( | void |  | ) |

Returns if an animator has ticked off during this loop iteration.

Returns
  `EINA_TRUE` if an animator has been called, `EINA_FALSE` otherwise.

There should be little need for anyone to use this - ever.

Since
  1.9

References DBG.

## ecore_main_loop_nested_get()

int ecore_main_loop_nested_get | ( | void |  | ) |

Returns if the ecore_main_loop is running.

Returns
  An integer specifying if the ecore_main_loop is running, `0` if not running, > `0` if running

Since
  1.13

## ecore_fork_reset_callback_add()

Eina_Bool ecore_fork_reset_callback_add | ( | Ecore_Cb | func,
|  | const void * | data )

Adds a function to be called by ecore_fork_reset().

Parameters

  func | The function to add.
  data | The data to pass to this function.

This queues `func` to be called (and passed `data` as its argument) when ecore_fork_reset() is called. This allows other libraries and subsystems to also reset their internal state after a fork.

Returns
  `EINA_TRUE` on success, else `EINA_FALSE`.

Since
  1.7

References EINA_FALSE, eina_list_append(), and EINA_TRUE.

Referenced by eeze_udev_watch_add(), and eldbus_init().

## ecore_fork_reset_callback_del()

Eina_Bool ecore_fork_reset_callback_del | ( | Ecore_Cb | func,
|  | const void * | data )

This removes the callback specified.

Parameters

  func | The function to delete.
  data | The data passed to this function.

This deletes the callback added by ecore_fork_reset_callback_add() using the function and data pointer to specify which to remove.

Returns
  `EINA_TRUE` on success, else `EINA_FALSE`.

Since
  1.7

References EINA_FALSE, EINA_LIST_FOREACH, eina_list_remove_list(), and EINA_TRUE.

Referenced by eeze_udev_watch_del(), and eldbus_shutdown().

## ecore_fork_reset()

void ecore_fork_reset | ( | void |  | ) |

Resets the ecore internal state after a fork.

Ecore maintains internal data that can be affected by the fork() system call which creates a duplicate of the current process. This also duplicates file descriptors which is problematic in that these file descriptors still point to their original sources. This function makes ecore reset internal state (e.g. pipes used for signalling between threads) so they function correctly afterwards.

It is highly suggested that you call this function after any fork() system call inside the child process if you intend to use ecore features after this point and not call any exec() family functions. Not doing so will cause possible misbehaviour.

Since
  1.7

References ecore_pipe_add(), ecore_pipe_del(), ecore_pipe_write(), eina_debug_fork_reset(), EINA_LIST_FOREACH, EINA_LIST_FOREACH_SAFE, eina_list_remove_list(), eina_main_loop_define(), and unsetenv().

Referenced by elm_quicklaunch_fork().

## ecore_main_loop_thread_safe_call_async()

void ecore_main_loop_thread_safe_call_async | ( | Ecore_Cb | callback,
|  | void * | data )

Calls callback asynchronously in the main loop.

Since
  1.1.0

Parameters

  callback | The callback to call in the main loop
  data | The data to give to that call back

For all calls that need to happen in the main loop (most EFL functions do), this helper function provides the infrastructure needed to do it safely by avoiding dead lock, race condition and properly wake up the main loop.

Remember after that function call, you should never touch again the `data` in the thread, it is owned by the main loop and your callback should take care of freeing it if necessary.

References EINA_FALSE, and eina_main_loop_is().

Referenced by ecore_drm2_fb_flip_complete(), and ecore_thread_feedback().

## ecore_main_loop_thread_safe_call_sync()

void * ecore_main_loop_thread_safe_call_sync | ( | Ecore_Data_Cb | callback,
|  | void * | data )

Calls callback synchronously in the main loop.

Since
  1.1.0

Parameters

  callback | The callback to call in the main loop
  data | The data to give to that call back

Returns
  The value returned by the callback in the main loop.

For all calls that need to happen in the main loop (most EFL functions do), this helper function provides the infrastructure needed to do it safely by avoiding dead lock, race condition and properly wake up the main loop.

Remember this function will block until the callback is executed in the main loop. It can take time and you have no guaranty about the timeline.

References EINA_FALSE, eina_main_loop_is(), and EINA_TRUE.

## ecore_main_loop_thread_safe_call_wait()

void ecore_main_loop_thread_safe_call_wait | ( | double | wait | ) |

Waits for the next thread call in the main loop.

Since
  1.13.0

Parameters

  wait | How long to wait for this callback to be called.

Note: This function should only be called in the main loop and will actually block the main loop until either a call is triggered from a thread or the time specified by wait has passed.

References ecore_pipe_wait().

Referenced by ecore_thread_wait().

## ecore_thread_main_loop_begin()

int ecore_thread_main_loop_begin | ( | void |  | ) |

This function suspends the main loop in a know state.

Since
  1.1.0

Returns
  The number of time ecore_thread_main_loop_begin() has been called in this thread, if the main loop was suspended correctly. If not, it return `-1`.

This function suspend the main loop in a know state, this let you use any EFL call you want after it return. Be carefully, the main loop is blocked until you call ecore_thread_main_loop_end(). This is the only sane way to achieve pseudo thread safety.

Notice that until the main loop is blocked, the thread is blocked and their is noway around that.

We still advise you, when possible, to use ecore_main_loop_thread_safe_call_async() as it will not block the thread nor the main loop.

References eina_main_loop_define(), eina_main_loop_is(), EINA_TRUE, and ERR.

## ecore_thread_main_loop_end()

int ecore_thread_main_loop_end | ( | void |  | ) |

Unlocks the main loop.

Since
  1.1.0

Returns
  The number of time ecore_thread_main_loop_end() need to be called before the main loop is unlocked again. `-1` will be returned if you are trying to unlock when there wasn't enough call to ecore_thread_main_loop_begin().

After a call to ecore_thread_main_loop_begin(), you need to absolutely call ecore_thread_main_loop_end(), or you application will stay frozen.

References eina_main_loop_is(), and ERR.

## efl_exit()

void efl_exit | ( | int | exit_code | ) |

Quits the main loop once all the events currently on the queue have been processed.

Parameters

  [in] | exit_code | Returned value by begin()

Note
  This function can only be called from the main loop.

References EINA_VALUE_EMPTY, and EINA_VALUE_TYPE_INT.

Referenced by elm_exit().

## efl_loop_future_scheduler_get()

Eina_Future_Scheduler * efl_loop_future_scheduler_get | ( | const Eo * | obj | ) |

Get the future scheduler for the current loop.

Parameters

  [in] | obj | An object which is either a loop or a loop consumer

Returns
  The current loop's future scheduler.

References efl_loop_future_scheduler_get().

Referenced by efl_loop_future_scheduler_get().