This group discusses functions that are acting on Ecore's main loop itself or on events and infrastructure directly linked to it. More...
Modules | |
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 | |
Functions that deal with and send signals to spawned processes. | |
File Descriptor Handling Functions | |
Functions that deal with file descriptor handlers. | |
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 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 Job functions | |
You can queue jobs that are to be done by the main loop when the current event is dealt with. | |
Ecore Throttle functions | |
Macros | |
#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 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 | |
EAPI void | ecore_main_loop_iterate (void) |
Runs a single iteration of the main loop to process everything on the queue. More... | |
EAPI 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 before ready for some class of I/O operation. More... | |
EAPI 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. | |
EAPI Eina_Bool | ecore_main_loop_glib_integrate (void) |
Request ecore to integrate GLib's main loop. More... | |
EAPI void | ecore_main_loop_glib_always_integrate_disable (void) |
Disable always integrating glib. More... | |
EAPI void | ecore_main_loop_begin (void) |
Runs the application main loop. More... | |
EAPI void | ecore_main_loop_quit (void) |
Quits the main loop once all the events currently on the queue have been processed. More... | |
EAPI void | ecore_main_loop_thread_safe_call_async (Ecore_Cb callback, void *data) |
Call callback asynchronously in the main loop. More... | |
EAPI void * | ecore_main_loop_thread_safe_call_sync (Ecore_Data_Cb callback, void *data) |
Call callback synchronously in the main loop. More... | |
EAPI int | ecore_thread_main_loop_begin (void) |
This function suspend the main loop in a know state. More... | |
EAPI int | ecore_thread_main_loop_end (void) |
Unlock the main loop. More... | |
EAPI 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 block/non-blocking status. More... | |
EAPI Ecore_Fd_Handler * | ecore_main_fd_handler_add (int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data) |
Adds a callback for activity on the given file descriptor. More... | |
EAPI void * | ecore_main_fd_handler_del (Ecore_Fd_Handler *fd_handler) |
Marks an FD handler for deletion. More... | |
EAPI void | ecore_main_fd_handler_prepare_callback_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data) |
Set the prepare callback with data for a given Ecore_Fd_Handler. More... | |
EAPI int | ecore_main_fd_handler_fd_get (Ecore_Fd_Handler *fd_handler) |
Retrieves the file descriptor that the given handler is handling. More... | |
EAPI Eina_Bool | ecore_main_fd_handler_active_get (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags) |
Gets which flags are active on an FD handler. More... | |
EAPI void | ecore_main_fd_handler_active_set (Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags) |
Set what active streams the given FD handler should be monitoring. More... | |
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 function 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.
Function Documentation
EAPI Eina_Bool ecore_main_fd_handler_active_get | ( | Ecore_Fd_Handler * | fd_handler, |
Ecore_Fd_Handler_Flags | flags | ||
) |
Gets which flags are active on an FD handler.
- Parameters
-
fd_handler The given FD handler. flags The flags, ECORE_FD_READ
,ECORE_FD_WRITE
orECORE_FD_ERROR
to query.
- Returns
EINA_TRUE
if any of the given flags are active,EINA_FALSE
otherwise.
References ECORE_FD_ERROR, ECORE_FD_READ, and ECORE_FD_WRITE.
EAPI void ecore_main_fd_handler_active_set | ( | Ecore_Fd_Handler * | fd_handler, |
Ecore_Fd_Handler_Flags | flags | ||
) |
Set what active streams the given FD handler should be monitoring.
- Parameters
-
fd_handler The given FD handler. flags The flags to be watching.
Referenced by ecore_con_client_send(), ecore_con_server_send(), ecore_exe_pipe_run(), and ecore_exe_send().
EAPI Ecore_Fd_Handler* ecore_main_fd_handler_add | ( | int | fd, |
Ecore_Fd_Handler_Flags | flags, | ||
Ecore_Fd_Cb | func, | ||
const void * | data, | ||
Ecore_Fd_Cb | buf_func, | ||
const void * | buf_data | ||
) |
Adds a callback for activity on the given file descriptor.
- Parameters
-
fd The file descriptor to watch. flags To monitor it for reading use ECORE_FD_READ
, for writingECORE_FD_WRITE
, and for errorECORE_FD_ERROR
. Values bay |(ored).func The callback function. data The data to pass to the callback. buf_func The function to call to check if any data has been buffered and already read from the fd. May be NULL
.buf_data The data to pass to the buf_func
function.
- Returns
- A fd handler handle on success,
NULL
otherwise.
func will be called during the execution of The Ecore Main Loop when the file descriptor is available for reading, writing, or there has been an error(depending on the given flags).
When func returns ECORE_CALLBACK_CANCEL, it indicates that the handler should be marked for deletion (identical to calling ecore_main_fd_handler_del).
- Warning
- buf_func is meant for internal use only and should be avoided.
The return value of buf_func has a different meaning, when it returns ECORE_CALLBACK_CANCEL, it indicates that func shouldn't be called, and when it returns ECORE_CALLBACK_RENEW it indicates func should be called. The return value of buf_func will not cause the FD handler to be deleted.
buf_func is called during event loop handling to check if data that has been read from the file descriptor is in a buffer and is available to read. Some systems, notably xlib, handle their own buffering, and would otherwise not work with select(). These systems should use a buf_func. This is a most annoying hack, only ecore_x uses it, so refer to that for an example.
Referenced by ecore_evas_init(), ecore_exe_pipe_run(), ecore_fb_input_device_listen(), ecore_pipe_add(), ecore_pipe_thaw(), ecore_wl_init(), and ecore_x_init().
EAPI void* ecore_main_fd_handler_del | ( | Ecore_Fd_Handler * | fd_handler | ) |
Marks an FD handler for deletion.
- Parameters
-
fd_handler The FD handler.
- Returns
- The data pointer set using ecore_main_fd_handler_add, for fd_handler on success,
NULL
otherwise. This function marks an fd handler to be deleted during an iteration of the main loop. It does NOT close the associated fd!
- Warning
- If the underlying fd is already closed ecore may complain if the main loop is using epoll internally, and also in some rare cases this may cause crashes and instability. Remember to delete your fd handlers before the fds they listen to are closed.
Referenced by ecore_con_server_add(), ecore_con_server_connect(), ecore_con_url_shutdown(), ecore_evas_shutdown(), and ecore_exe_free().
EAPI int ecore_main_fd_handler_fd_get | ( | Ecore_Fd_Handler * | fd_handler | ) |
Retrieves the file descriptor that the given handler is handling.
- Parameters
-
fd_handler The given FD handler.
- Returns
- The file descriptor the handler is watching.
Referenced by ecore_con_client_fd_get(), and ecore_con_server_fd_get().
EAPI void ecore_main_fd_handler_prepare_callback_set | ( | Ecore_Fd_Handler * | fd_handler, |
Ecore_Fd_Prep_Cb | func, | ||
const void * | data | ||
) |
Set the prepare callback with data for a given Ecore_Fd_Handler.
- Parameters
-
fd_handler The fd handler func The prep function data The data to pass to the prep function
This function will be called prior to any fd handler's callback function (even the other fd handlers), before entering the main loop select function.
- Note
- Once a prepare callback is set for a fd handler, it cannot be changed. You need to delete the fd handler and create a new one, to set another callback.
- You probably don't need this function. It is only necessary for very uncommon cases that need special behavior.
EAPI 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.
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:
- ecore_con_client_example.c, and ecore_con_server_example.c.
EAPI void ecore_main_loop_glib_always_integrate_disable | ( | void | ) |
Disable always integrating glib.
If ecore is compiled with –enable-glib-integration-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.
EAPI Eina_Bool ecore_main_loop_glib_integrate | ( | void | ) |
Request 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:
- 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 –enable-glib-integration-always.
- Returns
EINA_TRUE
on success ofEINA_FALSE
if it failed, likely no GLib support in Ecore.
References ecore_main_loop_select_func_get(), and ecore_main_loop_select_func_set().
Referenced by ecore_init().
EAPI 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 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.
EAPI 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 block/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.
- See Also
- ecore_main_loop_iterate()
EAPI 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 will mark the ecore_main_loop_begin() function to return at the end of the current main loop iteration.
- Examples:
- ecore_con_client_example.c, and ecore_con_server_example.c.
EAPI 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 before ready for some class of I/O operation.
This function will be used instead of the system call select and could possible 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.
Referenced by ecore_main_loop_glib_integrate().
EAPI void ecore_main_loop_thread_safe_call_async | ( | Ecore_Cb | callback, |
void * | data | ||
) |
Call 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.
Referenced by ecore_thread_feedback().
EAPI void* ecore_main_loop_thread_safe_call_sync | ( | Ecore_Data_Cb | callback, |
void * | data | ||
) |
Call 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.
EAPI int ecore_thread_main_loop_begin | ( | void | ) |
This function suspend 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.
EAPI int ecore_thread_main_loop_end | ( | void | ) |
Unlock 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.