2011-05-24 04:31:32 -07:00
/**
@ brief Ecore Library Public API Calls
These routines are used for Ecore Library interaction
*/
/**
@ mainpage Ecore
2011-07-06 21:58:34 -07:00
@ version 1.1
2011-05-24 04:31:32 -07:00
@ date 2000 - 2011
2011-08-03 14:00:09 -07:00
Please see the @ ref authors page for contact details .
2011-05-24 04:31:32 -07:00
@ section intro Introduction
2011-06-22 08:00:44 -07:00
Ecore is a library of convenience functions . A brief explanation of how to use
it can be found in @ ref Ecore_Main_Loop_Page .
2011-05-24 04:31:32 -07:00
The Ecore library provides the following modules :
2011-09-14 07:20:13 -07:00
@ li @ ref Ecore_Main_Loop_Group
2011-05-24 04:31:32 -07:00
@ li @ ref Ecore_File_Group
@ li @ ref Ecore_Con_Group
@ li @ link Ecore_Evas . h Ecore_Evas - Evas convenience functions . @ endlink
@ li @ ref Ecore_FB_Group
@ li @ link Ecore_Ipc . h Ecore_IPC - Inter Process Communication functions . @ endlink
@ li @ link Ecore_X . h Ecore_X - X Windows System wrapper . @ endlink
@ li @ ref Ecore_Win32_Group
@ li @ ref Ecore_WinCE_Group
2011-06-22 08:01:55 -07:00
For more info on Ecore usage , there are these @ ref Examples .
2011-05-24 04:31:32 -07:00
@ section compiling How to compile using Ecore ?
pkgconfig ( . pc ) files are installed for every ecore module .
Thus , to compile using any of them , you can use something like the following :
@ verbatim
gcc * . c $ ( pkg - config ecore ecore - $ x ecore - $ y [ . . . ] - - cflags - - libs )
@ endverbatim
@ section install How is it installed ?
Suggested configure options for evas for a Linux desktop X display :
@ verbatim
. / configure \
2011-08-08 04:29:05 -07:00
make
su -
. . .
make install
2011-05-24 04:31:32 -07:00
@ endverbatim
*/
2011-08-03 14:00:09 -07:00
/**
@ page authors Authors
@ author Carsten Haitzler < raster @ rasterman . com >
@ author Tom Gilbert < tom @ linuxbrit . co . uk >
@ author Burra < burra @ colorado . edu >
@ author Chris Ross < chris @ darkrock . co . uk >
@ author Term < term @ twistedpath . org >
@ author Tilman Sauerbeck < tilman @ code - monkey . de >
@ author Ibukun Olumuyiwa < ibukun @ computer . org >
@ author Yuri < da2001 @ hotmail . ru >
@ author Nicholas Curran < quasar @ bigblue . net . au >
@ author Howell Tam < pigeon @ pigeond . net >
@ author Nathan Ingersoll < rbdpngn @ users . sourceforge . net >
@ author Andrew Elcock < andy @ elcock . org >
@ author Kim Woelders < kim @ woelders . dk >
@ author Sebastian Dransfeld < sebastid @ tango . flipp . net >
@ author Simon Poole < simon . armlinux @ themalago . net >
@ author Jorge Luis Zapata Muga < jorgeluis . zapata @ gmail . com >
@ author dan sinclair < zero @ everburning . com >
@ author Michael ' Mickey ' Lauer < mickey @ tm . informatik . uni - frankfurt . de >
@ author David ' onefang ' Seikel < onefang @ gmail . com >
@ author Hisham ' CodeWarrior ' Mardam Bey < hisham @ hisham . cc >
@ author Brian ' rephorm ' Mattern < rephorm @ rephorm . com >
@ author Tim Horton < hortont424 @ gmail . com >
@ author Arnaud de Turckheim ' quarium ' < quarium @ gmail . com >
@ author Matt Barclay < mbarclay @ gmail . com >
@ author Peter Wehrfritz < peter . wehrfritz @ web . de >
@ author Albin " Lutin " Tonnerre < albin . tonnerre @ gmail . com >
@ author Vincent Torri < vincent . torri @ gmail . com >
@ author Lars Munch < lars @ segv . dk >
@ author Andre Dieb < andre . dieb @ gmail . com >
@ author Mathieu Taillefumier < mathieu . taillefumier @ free . fr >
@ author Rui Miguel Silva Seabra < rms @ 1407. org >
@ author Samsung Electronics
@ author Samsung SAIT
@ author Nicolas Aguirre < aguirre . nicolas @ gmail . com >
@ author Brett Nash < nash @ nash . id . au >
@ author Mike Blumenkrantz < mike @ zentific . com >
@ author Leif Middelschulte < leif . middelschulte @ gmail . com >
@ author Mike McCormack < mj . mccormack @ samsung . com >
@ author Sangho Park < gouache95 @ gmail . com >
@ author Jihoon Kim < jihoon48 . kim @ samsung . com > < imfine98 @ gmail . com >
@ author Daniel Juyung Seo < seojuyung2 @ gmail . com > < juyung . seo @ samsung . com >
Please contact < enlightenment - devel @ lists . sourceforge . net > to get in
contact with the developers and maintainers .
*/
2011-05-24 04:31:32 -07:00
/*
@ page Ecore_Main_Loop_Page The Ecore Main Loop
@ section intro What is Ecore ?
Ecore is a clean and tiny event loop library with many modules to do lots of
convenient things for a programmer , to save time and effort .
It ' s small and lean , designed to work on embedded systems all the way to
large and powerful multi - cpu workstations . It serialises all system signals ,
events etc . into a single event queue , that is easily processed without
needing to worry about concurrency . A properly written , event - driven program
using this kind of programming doesn ' t need threads , nor has to worry about
concurrency . It turns a program into a state machine , and makes it very
robust and easy to follow .
Ecore gives you other handy primitives , such as timers to tick over for you
and call specified functions at particular times so the programmer can use
this to do things , like animate , or time out on connections or tasks that take
too long etc .
Idle handlers are provided too , as well as calls on entering an idle state
( often a very good time to update the state of the program ) . All events that
enter the system are passed to specific callback functions that the program
sets up to handle those events . Handling them is simple and other Ecore
modules produce more events on the queue , coming from other sources such as
file descriptors etc .
Ecore also lets you have functions called when file descriptors become active
for reading or writing , allowing for streamlined , non - blocking IO .
Here is an example of a simple program and its basic event loop flow :
@ image html prog_flow . png
2011-08-11 12:29:26 -07:00
@ image latex prog_flow . eps width = \ textwidth
2011-05-24 04:31:32 -07:00
@ section work How does Ecore work ?
Ecore is very easy to learn and use . All the function calls are designed to
be easy to remember , explicit in describing what they do , and heavily
name - spaced . Ecore programs can start and be very simple .
For example :
@ code
# include <Ecore.h>
int main ( int argc , const char * * argv )
{
ecore_init ( ) ;
ecore_app_args_set ( argc , argv ) ;
ecore_main_loop_begin ( ) ;
ecore_shutdown ( ) ;
return 0 ;
}
@ endcode
2011-08-17 21:24:21 -07:00
This program is very simple and doesn ' t check for errors , but it does start up
2011-05-24 04:31:32 -07:00
and begin a main loop waiting for events or timers to tick off . This program
doesn ' t set up any , but now we can expand on this simple program a little
more by adding some event handlers and timers .
@ code
# include <Ecore.h>
Ecore_Timer * timer1 = NULL ;
Ecore_Event_Handler * handler1 = NULL ;
double start_time = 0.0 ;
int timer_func ( void * data )
{
printf ( " Tick timer. Sec: %3.2f \n " , ecore_time_get ( ) - start_time ) ;
return 1 ;
}
int exit_func ( void * data , int ev_type , void * ev )
{
Ecore_Event_Signal_Exit * e ;
e = ( Ecore_Event_Signal_Exit * ) ev ;
if ( e - > interrupt ) printf ( " Exit: interrupt \n " ) ;
else if ( e - > quit ) printf ( " Exit: quit \n " ) ;
else if ( e - > terminate ) printf ( " Exit: terminate \n " ) ;
ecore_main_loop_quit ( ) ;
return 1 ;
}
int main ( int argc , const char * * argv )
{
ecore_init ( ) ;
ecore_app_args_set ( argc , argv ) ;
start_time = ecore_time_get ( ) ;
handler1 = ecore_event_handler_add ( ECORE_EVENT_SIGNAL_EXIT , exit_func , NULL ) ;
timer1 = ecore_timer_add ( 0.5 , timer_func , NULL ) ;
ecore_main_loop_begin ( ) ;
ecore_shutdown ( ) ;
return 0 ;
}
@ endcode
In the previous example , we initialize our application and get the time at
which our program has started so we can calculate an offset . We set
up a timer to tick off in 0.5 seconds , and since it returns 1 , will
keep ticking off every 0.5 seconds until it returns 0 , or is deleted
by hand . An event handler is set up to call a function - exit_func ( ) ,
whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received ( CTRL - C
on the command line will cause such an event to happen ) . If this event
occurs it tells you what kind of exit signal was received , and asks
the main loop to quit when it is finished by calling
ecore_main_loop_quit ( ) .
The handles returned by ecore_timer_add ( ) and ecore_event_handler_add ( ) are
only stored here as an example . If you don ' t need to address the timer or
event handler again you don ' t need to store the result , so just call the
function , and don ' t assign the result to any variable .
This program looks slightly more complex than needed to do these simple
things , but in principle , programs don ' t get any more complex . You add more
event handlers , for more events , will have more timers and such , BUT it all
follows the same principles as shown in this example .
*/
/*
@ page Ecore_Config_Page The Enlightened Property Library
The Enlightened Property Library ( Ecore_Config ) is an adbstraction
from the complexities of writing your own configuration . It provides
many features using the Enlightenment 17 development libraries .
To use the library , you :
@ li Set the default values of your properties .
@ li Load the configuration from a file . You must set the default values
first , so that the library knows the correct type of each argument .
The following examples show how to use the Enlightened Property Library :
@ li @ link config_basic_example . c config_basic_example . c @ endlink
@ li @ link config_listener_example . c config_listener_example . c @ endlink
*/
/**
@ page X_Window_System_Page X Window System
The Ecore library includes a wrapper for handling the X window system .
This page briefly explains what the X window system is and various terms
that are used .
*/
2003-09-23 01:09:32 -07:00
# ifndef _ECORE_H
# define _ECORE_H
2010-04-05 01:26:48 -07:00
# ifdef _MSC_VER
# include <Evil.h>
# endif
2009-08-04 02:13:49 -07:00
# include <Eina.h>
2004-11-24 21:18:31 -08:00
# ifdef EAPI
2008-05-25 22:16:34 -07:00
# undef EAPI
2004-11-24 21:18:31 -08:00
# endif
2008-05-25 22:16:34 -07:00
# ifdef _WIN32
# ifdef EFL_ECORE_BUILD
# ifdef DLL_EXPORT
# define EAPI __declspec(dllexport)
# else
# define EAPI
# endif /* ! DLL_EXPORT */
2004-11-24 21:18:31 -08:00
# else
# define EAPI __declspec(dllimport)
2008-05-25 22:16:34 -07:00
# endif /* ! EFL_ECORE_BUILD */
2004-11-24 21:18:31 -08:00
# else
2005-12-27 09:17:31 -08:00
# ifdef __GNUC__
# if __GNUC__ >= 4
# define EAPI __attribute__ ((visibility("default")))
# else
# define EAPI
# endif
2004-11-24 21:18:31 -08:00
# else
# define EAPI
# endif
2008-05-25 22:16:34 -07:00
# endif /* ! _WIN32 */
2004-11-24 21:18:31 -08:00
2009-04-16 10:12:40 -07:00
# ifdef _WIN32
# include <winsock2.h>
2009-10-25 07:48:12 -07:00
# elif (defined (__FreeBSD__) && (__FreeBSD_version >= 420001)) || defined (__OpenBSD__)
2009-07-28 02:58:12 -07:00
# include <sys / select.h>
2009-11-07 11:10:08 -08:00
# include <signal.h>
2009-04-16 10:12:40 -07:00
# else
2009-06-12 08:23:32 -07:00
# include <sys / time.h>
2009-04-16 10:12:40 -07:00
# include <signal.h>
2006-01-09 05:36:22 -08:00
# endif
2010-02-06 14:14:32 -08:00
2009-10-25 00:07:48 -07:00
# include <sys/types.h>
2004-03-17 21:29:54 -08:00
2005-04-14 18:22:46 -07:00
# ifdef __cplusplus
extern " C " {
# endif
2010-10-17 00:03:28 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ defgroup Ecore_Init_Group Ecore initialization and shutdown functions .
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* @ {
*/
EAPI int ecore_init ( void ) ;
EAPI int ecore_shutdown ( void ) ;
/**
* @ }
*/
/**
*
* @ defgroup Ecore_Main_Loop_Group Ecore main loop functions
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* These are functions acting on Ecore ' s main loop itself or on
* events and infrastructure directly linked to it . This loop is
* designed to work on embedded systems all the way to large and
* powerful multi - cpu workstations .
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* It serialises all system signals and events into a single event
* queue , that can be easily processed without needing to worry
* about concurrency . A properly written , event - driven program
* using this kind of programming does not need threads . It makes
* the program very robust and easy to follow .
*
* For example , for the main loop to be of any use , you need to be
* able to add @ b events and event handlers on it . Events for file
* descriptor events are covered in @ ref Ecore_FD_Handler_Group .
*
* Timer functions are covered in @ ref Ecore_Time_Group .
2010-10-17 00:03:28 -07:00
*
* There is also provision for callbacks for when the loop enters or
2011-08-10 12:14:48 -07:00
* exits an @ b idle state . See @ ref Ecore_Idle_Group for more
* information on it .
*
* Functions are also provided for spawning child processes using
* @ c fork ( ) . See @ ref Ecore_Exe_Group for more details on it .
*
* Here is an example of simple program and its basic event loop
* flow :
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* @ image html prog_flow . png
2011-08-11 12:29:26 -07:00
* @ image latex prog_flow . eps width = \ textwidth
2011-08-10 12:14:48 -07:00
*
* For examples of setting up and using a main loop , see
* @ ref Ecore_Main_Loop_Page .
2010-10-17 00:03:28 -07:00
*
* @ {
*/
2010-08-16 01:17:24 -07:00
# define ECORE_VERSION_MAJOR 1
# define ECORE_VERSION_MINOR 0
2010-05-28 23:37:02 -07:00
typedef struct _Ecore_Version
{
int major ;
int minor ;
int micro ;
int revision ;
} Ecore_Version ;
2011-08-10 12:14:48 -07:00
2010-05-28 23:37:02 -07:00
EAPI extern Ecore_Version * ecore_version ;
2010-06-24 09:15:56 -07:00
# 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 */
2008-01-25 10:28:16 -08:00
2011-08-10 12:14:48 -07:00
/**
* @ typedef Ecore_Task_Cb Ecore_Task_Cb
* A callback run for a task ( timer , idler , poller , animator , etc )
*/
typedef Eina_Bool ( * Ecore_Task_Cb ) ( void * data ) ;
/**
* @ typedef Ecore_Eselect_Function Ecore_Eselect_Function
* A function which can be used to replace select ( ) in the main loop
*/
typedef int ( * Ecore_Select_Function ) ( int nfds , fd_set * readfds , fd_set * writefds , fd_set * exceptfds , struct timeval * timeout ) ;
EAPI void ecore_main_loop_iterate ( void ) ;
EAPI void ecore_main_loop_select_func_set ( Ecore_Select_Function func ) ;
EAPI Ecore_Select_Function ecore_main_loop_select_func_get ( void ) ;
EAPI Eina_Bool ecore_main_loop_glib_integrate ( void ) ;
EAPI void ecore_main_loop_glib_always_integrate_disable ( void ) ;
EAPI void ecore_main_loop_begin ( void ) ;
EAPI void ecore_main_loop_quit ( void ) ;
/**
* @ typedef Ecore_Cb Ecore_Cb
* A generic callback called as a hook when a certain point in
* execution is reached .
*/
typedef void ( * Ecore_Cb ) ( void * data ) ;
2011-08-16 07:35:00 -07:00
/**
* @ typedef Ecore_Data_Cb Ecore_Data_Cb
* A callback which is used to return data to the main function
*/
typedef void * ( * Ecore_Data_Cb ) ( void * data ) ;
2011-08-10 12:14:48 -07:00
/**
2011-08-16 07:35:00 -07:00
* @ brief Call callback asynchronously in the main loop .
* @ since 1.1 .0
2011-08-10 12:14:48 -07:00
*
* @ param callback The callback to call in the main loop
* @ param data The data to give to that call back
*
2011-09-07 21:44:25 -07:00
* 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 .
2011-08-10 12:14:48 -07:00
*
* Remember after that function call , you should never touch again the @ p data
2011-09-07 21:44:25 -07:00
* in the thread , it is owned by the main loop and your callback should take
2011-08-10 12:14:48 -07:00
* care of freeing it if necessary .
*/
2011-08-16 07:35:00 -07:00
EAPI void ecore_main_loop_thread_safe_call_async ( Ecore_Cb callback , void * data ) ;
/**
* @ brief Call callback synchronously in the main loop .
* @ since 1.1 .0
*
* @ param callback The callback to call in the main loop
* @ param data The data to give to that call back
* @ return the value returned by the callback in the main loop
*
2011-09-07 21:44:25 -07:00
* 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 .
2011-08-16 07:35:00 -07:00
*
* 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 void * ecore_main_loop_thread_safe_call_sync ( Ecore_Data_Cb callback , void * data ) ;
2011-08-10 12:14:48 -07:00
2011-08-17 02:43:49 -07:00
/**
* @ brief This function suspend the main loop in a know state
* @ since 1.1 .0
*
2011-08-22 02:47:17 -07:00
* @ result 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 @ c - 1.
2011-08-17 02:43:49 -07:00
*
* This function suspend the main loop in a know state , this let you
* use any EFL call you want after it return . Be carefull , 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 .
*/
2011-08-22 02:47:17 -07:00
EAPI int ecore_thread_main_loop_begin ( void ) ;
2011-08-17 02:43:49 -07:00
/**
* @ brief Unlock the main loop .
* @ since 1.1 .0
*
2011-08-22 02:47:17 -07:00
* @ result the number of time ecore_thread_main_loop_end ( ) need to be called before
* the main loop is unlocked again . @ c - 1 will be returned if you are trying to unlock
* when there wasn ' t enough call to ecore_thread_main_loop_begin ( ) .
*
2011-08-17 02:43:49 -07:00
* After a call to ecore_thread_main_loop_begin ( ) , you need to absolutly
* call ecore_thread_main_loop_end ( ) , or you application will stay frozen .
*/
2011-08-22 02:47:17 -07:00
EAPI int ecore_thread_main_loop_end ( void ) ;
2011-08-17 02:43:49 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ }
*/
/**
* @ defgroup Ecore_Event_Group Ecore Event functions
*
* Ecore events are used to wake up the Ecore main loop to warn
* about state changes , tasks completed , data available for reading
* or writing , etc . They are the base of the event oriented
* programming .
*
* The idea is to write many functions ( callbacks ) that will be
* registered to specific events , and called when these events
* happen . This way , when the system state changes ( a mouse click is
* detected , a key is pressed , or the content of a file changes , for
* example ) , the respective callbacks will be called with some
* information about that event . Usually the function / callback will
* have a data pointer to the event info ( the position in the screen
* where the mouse was clicked , the name of the key that was
* pressed , or the name of the file that has changed ) .
*
* The basic usage , when one needs to watch for an existing event ,
* is to register a callback to it using ecore_event_add ( ) . Of
* course it ' s necessary to know beforehand what are the types of
* events that the system / library will emmit . This should be
* available with the documentation from that system / library .
*
* When writing a library or group of functions that need to inform
* about something , and you already are running on top of a main
* loop , it is usually a good approach to use events . This way you
* allow others to register as many callbacks as necessary to this
* event , and don ' t have to care about who is registering to it . The
* functions ecore_event_type_new ( ) and ecore_event_add ( ) are
* available for this purpose .
*
* Example that deals with events :
*
* @ li @ ref ecore_event_example_c
*
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
*/
2005-10-24 01:53:50 -07:00
# define ECORE_EVENT_NONE 0
2006-01-13 05:18:36 -08:00
# define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */
# define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */
# define ECORE_EVENT_SIGNAL_EXIT 3 /**< Exit signal event */
# define ECORE_EVENT_SIGNAL_POWER 4 /**< Power signal event */
# define ECORE_EVENT_SIGNAL_REALTIME 5 /**< Realtime signal event */
# define ECORE_EVENT_COUNT 6
2009-12-22 13:15:12 -08:00
typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler ; /**< A handle for HANDLE handlers on Windows */
typedef struct _Ecore_Event_Handler Ecore_Event_Handler ; /**< A handle for an event handler */
typedef struct _Ecore_Event_Filter Ecore_Event_Filter ; /**< A handle for an event filter */
typedef struct _Ecore_Event Ecore_Event ; /**< A handle for an event */
2005-10-24 01:53:50 -07:00
typedef struct _Ecore_Event_Signal_User Ecore_Event_Signal_User ; /**< User signal event */
typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup ; /**< Hup signal event */
typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit ; /**< Exit signal event */
typedef struct _Ecore_Event_Signal_Power Ecore_Event_Signal_Power ; /**< Power signal event */
2004-04-04 12:53:19 -07:00
typedef struct _Ecore_Event_Signal_Realtime Ecore_Event_Signal_Realtime ; /**< Realtime signal event */
2010-08-03 19:55:20 -07:00
/**
* @ typedef Ecore_Filter_Cb
* A callback used for filtering events from the main loop .
*/
typedef Eina_Bool ( * Ecore_Filter_Cb ) ( void * data , void * loop_data , int type , void * event ) ;
2011-08-10 12:14:48 -07:00
2010-08-03 19:55:20 -07:00
/**
* @ typedef Ecore_End_Cb Ecore_End_Cb
2011-08-10 12:14:48 -07:00
* This is the callback which is called at the end of a function ,
* usually for cleanup purposes .
2010-08-03 19:55:20 -07:00
*/
typedef void ( * Ecore_End_Cb ) ( void * user_data , void * func_data ) ;
2011-08-10 12:14:48 -07:00
2010-08-03 19:55:20 -07:00
/**
* @ typedef Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb
2011-08-10 12:14:48 -07:00
* A callback used by the main loop to handle events of a specified
* type .
2010-08-03 19:55:20 -07:00
*/
typedef Eina_Bool ( * Ecore_Event_Handler_Cb ) ( void * data , int type , void * event ) ;
2010-01-25 13:59:21 -08:00
2003-09-23 01:09:32 -07:00
struct _Ecore_Event_Signal_User /** User signal event */
{
2010-09-29 23:09:20 -07:00
int number ; /**< The signal number. Either 1 or 2 */
void * ext_data ; /**< Extension data - not used */
2004-10-20 10:51:29 -07:00
2011-09-20 15:06:33 -07:00
# if !defined (_WIN32) && !defined (__lv2ppu__)
2010-09-29 23:09:20 -07:00
siginfo_t data ; /**< Signal info */
2004-10-20 10:51:29 -07:00
# endif
2003-09-23 01:09:32 -07:00
} ;
2007-08-26 04:17:21 -07:00
2003-09-23 01:09:32 -07:00
struct _Ecore_Event_Signal_Hup /** Hup signal event */
{
2010-09-29 23:09:20 -07:00
void * ext_data ; /**< Extension data - not used */
2004-10-20 10:51:29 -07:00
2011-09-20 15:06:33 -07:00
# if !defined (_WIN32) && !defined (__lv2ppu__)
2010-09-29 23:09:20 -07:00
siginfo_t data ; /**< Signal info */
2004-10-20 10:51:29 -07:00
# endif
2003-09-23 01:09:32 -07:00
} ;
2007-08-26 04:17:21 -07:00
2003-09-23 01:09:32 -07:00
struct _Ecore_Event_Signal_Exit /** Exit request event */
{
2011-01-26 10:38:13 -08:00
Eina_Bool interrupt : 1 ; /**< Set if the exit request was an interrupt signal*/
Eina_Bool quit : 1 ; /**< set if the exit request was a quit signal */
Eina_Bool terminate : 1 ; /**< Set if the exit request was a terminate singal */
2010-09-29 23:09:20 -07:00
void * ext_data ; /**< Extension data - not used */
2004-10-20 10:51:29 -07:00
2011-09-20 15:06:33 -07:00
# if !defined (_WIN32) && !defined (__lv2ppu__)
2010-09-29 23:09:20 -07:00
siginfo_t data ; /**< Signal info */
2004-10-20 10:51:29 -07:00
# endif
2003-09-23 01:09:32 -07:00
} ;
struct _Ecore_Event_Signal_Power /** Power event */
{
2010-09-29 23:09:20 -07:00
void * ext_data ; /**< Extension data - not used */
2004-10-20 10:51:29 -07:00
2011-09-20 15:06:33 -07:00
# if !defined (_WIN32) && !defined (__lv2ppu__)
2010-09-29 23:09:20 -07:00
siginfo_t data ; /**< Signal info */
2004-10-20 10:51:29 -07:00
# endif
2004-04-04 12:53:19 -07:00
} ;
struct _Ecore_Event_Signal_Realtime /** Realtime event */
{
2010-09-29 23:09:20 -07:00
int num ; /**< The realtime signal's number */
2004-10-20 10:51:29 -07:00
2011-09-20 15:06:33 -07:00
# if !defined (_WIN32) && !defined (__lv2ppu__)
2010-09-29 23:09:20 -07:00
siginfo_t data ; /**< Signal info */
2004-10-20 10:51:29 -07:00
# endif
2003-09-23 01:09:32 -07:00
} ;
2011-08-10 12:14:48 -07:00
EAPI Ecore_Event_Handler * ecore_event_handler_add ( int type , Ecore_Event_Handler_Cb func , const void * data ) ;
EAPI void * ecore_event_handler_del ( Ecore_Event_Handler * event_handler ) ;
EAPI Ecore_Event * ecore_event_add ( int type , void * ev , Ecore_End_Cb func_free , void * data ) ;
EAPI void * ecore_event_del ( Ecore_Event * event ) ;
EAPI void * ecore_event_handler_data_get ( Ecore_Event_Handler * eh ) ;
EAPI void * ecore_event_handler_data_set ( Ecore_Event_Handler * eh , const void * data ) ;
EAPI int ecore_event_type_new ( void ) ;
EAPI Ecore_Event_Filter * ecore_event_filter_add ( Ecore_Data_Cb func_start , Ecore_Filter_Cb func_filter , Ecore_End_Cb func_end , const void * data ) ;
EAPI void * ecore_event_filter_del ( Ecore_Event_Filter * ef ) ;
EAPI int ecore_event_current_type_get ( void ) ;
EAPI void * ecore_event_current_event_get ( void ) ;
2006-01-15 03:27:19 -08:00
2011-08-10 12:14:48 -07:00
/**
* @ }
*/
2005-12-15 17:11:24 -08:00
2011-08-10 12:14:48 -07:00
/**
* @ defgroup Ecore_Exe_Group Process Spawning Functions
*
* Functions that deal with and send signals to spawned processes .
*
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
*/
2007-08-26 04:17:21 -07:00
2011-08-10 12:14:48 -07:00
# define ECORE_EXE_PRIORITY_INHERIT 9999
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
EAPI extern int ECORE_EXE_EVENT_ADD ; /**< A child process has been added */
EAPI extern int ECORE_EXE_EVENT_DEL ; /**< A child process has been deleted (it exited, naming consistent with the rest of ecore). */
EAPI extern int ECORE_EXE_EVENT_DATA ; /**< Data from a child process. */
EAPI extern int ECORE_EXE_EVENT_ERROR ; /**< Errors from a child process. */
2007-08-26 04:17:21 -07:00
2011-08-10 12:14:48 -07:00
enum _Ecore_Exe_Flags /* flags for executing a child with its stdin and/or stdout piped back */
{
ECORE_EXE_NONE = 0 , /**< No exe flags at all */
ECORE_EXE_PIPE_READ = 1 , /**< Exe Pipe Read mask */
ECORE_EXE_PIPE_WRITE = 2 , /**< Exe Pipe Write mask */
ECORE_EXE_PIPE_ERROR = 4 , /**< Exe Pipe error mask */
2011-08-30 07:43:29 -07:00
ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8 , /**< Reads are buffered until a newline and split 1 line per Ecore_Exe_Event_Data_Line */
ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16 , /**< Errors are buffered until a newline and split 1 line per Ecore_Exe_Event_Data_Line */
2011-08-10 12:14:48 -07:00
ECORE_EXE_PIPE_AUTO = 32 , /**< stdout and stderr are buffered automatically */
ECORE_EXE_RESPAWN = 64 , /**< FIXME: Exe is restarted if it dies */
ECORE_EXE_USE_SH = 128 , /**< Use /bin/sh to run the command. */
2011-10-07 16:37:42 -07:00
ECORE_EXE_NOT_LEADER = 256 , /**< Do not use setsid() to have the executed process be its own session leader */
ECORE_EXE_TERM_WITH_PARENT = 512 /**< Makes child receive SIGTERM when parent dies. */
2011-08-10 12:14:48 -07:00
} ;
typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags ;
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
enum _Ecore_Exe_Win32_Priority
{
ECORE_EXE_WIN32_PRIORITY_IDLE , /**< Idle priority, for monitoring the system */
ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL , /**< Below default priority */
ECORE_EXE_WIN32_PRIORITY_NORMAL , /**< Default priority */
ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL , /**< Above default priority */
ECORE_EXE_WIN32_PRIORITY_HIGH , /**< High priority, use with care as other threads in the system will not get processor time */
ECORE_EXE_WIN32_PRIORITY_REALTIME /**< Realtime priority, should be almost never used as it can interrupt system threads that manage mouse input, keyboard input, and background disk flushing */
} ;
typedef enum _Ecore_Exe_Win32_Priority Ecore_Exe_Win32_Priority ;
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
typedef struct _Ecore_Exe Ecore_Exe ; /**< A handle for spawned processes */
2004-11-24 21:18:31 -08:00
2011-08-10 12:14:48 -07:00
/**
* @ typedef Ecore_Exe_Cb Ecore_Exe_Cb
* A callback to run with the associated @ ref Ecore_Exe , usually
* for cleanup purposes .
*/
typedef void ( * Ecore_Exe_Cb ) ( void * data , const Ecore_Exe * exe ) ;
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add ; /**< Spawned Exe add event */
typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del ; /**< Spawned Exe exit event */
typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line ; /**< Lines from a child process */
typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data ; /**< Data from a child process */
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
struct _Ecore_Exe_Event_Add /** Process add event */
{
Ecore_Exe * exe ; /**< The handle to the added process */
void * ext_data ; /**< Extension data - not used */
} ;
2007-08-26 04:17:21 -07:00
2011-08-10 12:14:48 -07:00
struct _Ecore_Exe_Event_Del /** Process exit event */
{
pid_t pid ; /**< The process ID of the process that exited */
int exit_code ; /**< The exit code of the process */
Ecore_Exe * exe ; /**< The handle to the exited process, or NULL if not found */
int exit_signal ; /** < The signal that caused the process to exit */
Eina_Bool exited : 1 ; /** < set to 1 if the process exited of its own accord */
Eina_Bool signalled : 1 ; /** < set to 1 id the process exited due to uncaught signal */
void * ext_data ; /**< Extension data - not used */
2011-09-20 15:06:33 -07:00
# if !defined (_WIN32) && !defined (__lv2ppu__)
2011-08-10 12:14:48 -07:00
siginfo_t data ; /**< Signal info */
# endif
} ;
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
struct _Ecore_Exe_Event_Data_Line /**< Lines from a child process */
{
char * line ;
int size ;
} ;
struct _Ecore_Exe_Event_Data /** Data from a child process event */
{
Ecore_Exe * exe ; /**< The handle to the process */
void * data ; /**< the raw binary data from the child process that was received */
int size ; /**< the size of this data in bytes */
Ecore_Exe_Event_Data_Line * lines ; /**< an array of line data if line buffered, the last one has it's line member set to NULL */
} ;
2007-08-26 04:17:21 -07:00
2008-11-01 18:29:08 -07:00
EAPI void ecore_exe_run_priority_set ( int pri ) ;
EAPI int ecore_exe_run_priority_get ( void ) ;
2005-09-28 06:09:09 -07:00
EAPI Ecore_Exe * ecore_exe_run ( const char * exe_cmd , const void * data ) ;
2005-10-24 01:53:50 -07:00
EAPI Ecore_Exe * ecore_exe_pipe_run ( const char * exe_cmd , Ecore_Exe_Flags flags , const void * data ) ;
2010-08-03 19:55:20 -07:00
EAPI void ecore_exe_callback_pre_free_set ( Ecore_Exe * exe , Ecore_Exe_Cb func ) ;
2010-01-05 21:16:59 -08:00
EAPI Eina_Bool ecore_exe_send ( Ecore_Exe * exe , const void * data , int size ) ;
2006-01-04 12:53:07 -08:00
EAPI void ecore_exe_close_stdin ( Ecore_Exe * exe ) ;
2006-01-16 05:21:52 -08:00
EAPI void ecore_exe_auto_limits_set ( Ecore_Exe * exe , int start_bytes , int end_bytes , int start_lines , int end_lines ) ;
EAPI Ecore_Exe_Event_Data * ecore_exe_event_data_get ( Ecore_Exe * exe , Ecore_Exe_Flags flags ) ;
EAPI void ecore_exe_event_data_free ( Ecore_Exe_Event_Data * data ) ;
2005-09-28 06:09:09 -07:00
EAPI void * ecore_exe_free ( Ecore_Exe * exe ) ;
2010-01-05 21:16:59 -08:00
EAPI pid_t ecore_exe_pid_get ( const Ecore_Exe * exe ) ;
2005-09-28 06:09:09 -07:00
EAPI void ecore_exe_tag_set ( Ecore_Exe * exe , const char * tag ) ;
2010-01-05 21:16:59 -08:00
EAPI const char * ecore_exe_tag_get ( const Ecore_Exe * exe ) ;
EAPI const char * ecore_exe_cmd_get ( const Ecore_Exe * exe ) ;
EAPI void * ecore_exe_data_get ( const Ecore_Exe * exe ) ;
2011-04-19 14:38:24 -07:00
EAPI void * ecore_exe_data_set ( Ecore_Exe * exe , void * data ) ;
2010-01-05 21:16:59 -08:00
EAPI Ecore_Exe_Flags ecore_exe_flags_get ( const Ecore_Exe * exe ) ;
2005-09-28 06:09:09 -07:00
EAPI void ecore_exe_pause ( Ecore_Exe * exe ) ;
EAPI void ecore_exe_continue ( Ecore_Exe * exe ) ;
2008-07-29 15:07:19 -07:00
EAPI void ecore_exe_interrupt ( Ecore_Exe * exe ) ;
EAPI void ecore_exe_quit ( Ecore_Exe * exe ) ;
2005-09-28 06:09:09 -07:00
EAPI void ecore_exe_terminate ( Ecore_Exe * exe ) ;
EAPI void ecore_exe_kill ( Ecore_Exe * exe ) ;
EAPI void ecore_exe_signal ( Ecore_Exe * exe , int num ) ;
EAPI void ecore_exe_hup ( Ecore_Exe * exe ) ;
2007-08-26 04:17:21 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ }
*/
2007-08-26 04:17:21 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ defgroup Ecore_FD_Handler_Group File Event Handling Functions
*
* Functions that deal with file descriptor handlers .
*
* The @ ref Ecore_Fd_Handler can be used to watch a file descriptor
* for data available for reading , for the availability to write
* without blocking , and for errors on the file descriptor .
*
* ecore_main_fd_handler_add ( ) is used to setup a handler for a
* given file descriptor . This file descriptor can be the standard
* input , a network socket , a stream received through some driver
* of a hardware decoder , etc . Thus it can contain errors , like a
* disconnection , a broken pipe , and so , and that ' s why it ' s
* possible to check for these errors with the @ ref ECORE_FD_ERROR
* flag .
*
* An @ ref Ecore_Fd_Handler can be used to watch on a file
* descriptor without blocking , still being able to receive events ,
* expire timers , and other watch for other things that happen in
* the Ecore main loop .
*
* Example of use of a file descriptor handler :
* @ li @ ref ecore_fd_handler_example_c
*
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
*/
2004-11-24 21:18:31 -08:00
2011-08-10 12:14:48 -07:00
typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler ; /**< A handle for Fd handlers */
2004-11-24 21:18:31 -08:00
2011-08-10 12:14:48 -07:00
enum _Ecore_Fd_Handler_Flags
{
ECORE_FD_READ = 1 , /**< Fd Read mask */
ECORE_FD_WRITE = 2 , /**< Fd Write mask */
ECORE_FD_ERROR = 4 /**< Fd Error mask */
} ;
typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags ;
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ typedef Ecore_Fd_Cb Ecore_Fd_Cb
* A callback used by an @ ref Ecore_Fd_Handler .
*/
typedef Eina_Bool ( * Ecore_Fd_Cb ) ( void * data , Ecore_Fd_Handler * fd_handler ) ;
2010-10-17 00:03:28 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ typedef Ecore_Fd_Prep_Cb Ecore_Fd_Prep_Cb
* A callback used by an @ ref Ecore_Fd_Handler .
*/
typedef void ( * Ecore_Fd_Prep_Cb ) ( void * data , Ecore_Fd_Handler * fd_handler ) ;
2009-04-16 08:44:26 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb
* A callback used by an @ ref Ecore_Win32_Handler .
*/
typedef Eina_Bool ( * Ecore_Win32_Handle_Cb ) ( void * data , Ecore_Win32_Handler * wh ) ;
2009-04-16 08:44:26 -07:00
2010-08-03 19:55:20 -07:00
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 ) ;
EAPI void ecore_main_fd_handler_prepare_callback_set ( Ecore_Fd_Handler * fd_handler , Ecore_Fd_Prep_Cb func , const void * data ) ;
2004-11-24 21:18:31 -08:00
EAPI void * ecore_main_fd_handler_del ( Ecore_Fd_Handler * fd_handler ) ;
EAPI int ecore_main_fd_handler_fd_get ( Ecore_Fd_Handler * fd_handler ) ;
2010-09-20 19:06:41 -07:00
EAPI Eina_Bool ecore_main_fd_handler_active_get ( Ecore_Fd_Handler * fd_handler , Ecore_Fd_Handler_Flags flags ) ;
2004-11-24 21:18:31 -08:00
EAPI void ecore_main_fd_handler_active_set ( Ecore_Fd_Handler * fd_handler , Ecore_Fd_Handler_Flags flags ) ;
2009-10-25 03:11:59 -07:00
2011-03-13 03:46:25 -07:00
EAPI Ecore_Win32_Handler * ecore_main_win32_handler_add ( void * h , Ecore_Win32_Handle_Cb func , const void * data ) ;
2009-11-23 15:09:48 -08:00
EAPI void * ecore_main_win32_handler_del ( Ecore_Win32_Handler * win32_handler ) ;
2007-08-26 04:17:21 -07:00
2011-08-10 12:14:48 -07:00
/**
* @ }
*/
2011-07-28 06:33:14 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ defgroup Ecore_Poller_Group Ecore Poll functions
2011-07-28 06:33:14 -07:00
*
2011-08-10 12:14:48 -07:00
* These functions are for the need to poll information , but provide
* a shared abstracted API to pool such polling to minimise wakeup
* and ensure all the polling happens in as few spots as possible
* areound a core poll interval . For now only 1 core poller type is
* supprted : ECORE_POLLER_CORE
2011-07-28 06:33:14 -07:00
*
2011-08-10 12:14:48 -07:00
* Example of @ ref Ecore_Poller :
* @ li @ ref ecore_poller_example_c
2011-07-28 06:33:14 -07:00
*
2011-08-10 12:14:48 -07:00
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
2011-07-28 06:33:14 -07:00
*/
2011-08-10 12:14:48 -07:00
enum _Ecore_Poller_Type /* Poller types */
{
ECORE_POLLER_CORE = 0 /**< The core poller interval */
} ;
typedef enum _Ecore_Poller_Type Ecore_Poller_Type ;
typedef struct _Ecore_Poller Ecore_Poller ; /**< A handle for pollers */
EAPI void ecore_poller_poll_interval_set ( Ecore_Poller_Type type , double poll_time ) ;
EAPI double ecore_poller_poll_interval_get ( Ecore_Poller_Type type ) ;
EAPI Eina_Bool ecore_poller_poller_interval_set ( Ecore_Poller * poller , int interval ) ;
EAPI int ecore_poller_poller_interval_get ( Ecore_Poller * poller ) ;
EAPI Ecore_Poller * ecore_poller_add ( Ecore_Poller_Type type , int interval , Ecore_Task_Cb func , const void * data ) ;
EAPI void * ecore_poller_del ( Ecore_Poller * poller ) ;
2011-07-28 06:33:14 -07:00
2010-10-17 00:03:28 -07:00
/**
* @ }
*/
/**
2011-08-10 12:14:48 -07:00
* @ defgroup Ecore_Animator_Group Ecore Animator functions
*
* @ brief Ecore animators are a helper to simplify creating
* animations .
*
* Creating an animation is as simple as saying for how long it
* should be run and having a callback that does the animation ,
* something like this :
* @ code
* static Eina_Bool
* _do_animation ( void * data , double pos )
* {
* evas_object_move ( data , 100 * pos , 100 * pos ) ;
* . . . do some more animating . . .
* }
* . . .
* ecore_animator_timeline_add ( 2 , _do_animation , my_evas_object ) ;
* @ endcode
* In the sample above we create an animation to move
* @ c my_evas_object from position ( 0 , 0 ) to ( 100 , 100 ) in 2 seconds .
*
* If your animation will run for an unspecified amount of time you
* can use ecore_animator_add ( ) , which is like using
* ecore_timer_add ( ) with the interval being the
* @ ref ecore_animator_frametime_set " framerate " . Note that this has
* tangible benefits to creating a timer for each animation in terms
* of performance .
*
* For a more detailed example that show several animation see
* @ ref tutorial_ecore_animator .
*
* @ ingroup Ecore_Main_Loop_Group
2010-10-17 00:03:28 -07:00
*
* @ {
*/
2011-08-10 12:14:48 -07:00
typedef struct _Ecore_Animator Ecore_Animator ; /**< A handle for animators */
2008-11-02 21:42:27 -08:00
2011-08-10 12:14:48 -07:00
enum _Ecore_Pos_Map /* Position mappings */
{
ECORE_POS_MAP_LINEAR , /**< Linear 0.0 -> 1.0 */
ECORE_POS_MAP_ACCELERATE , /**< Start slow then speed up */
ECORE_POS_MAP_DECELERATE , /**< Start fast then slow down */
ECORE_POS_MAP_SINUSOIDAL , /**< Start slow, speed up then slow down at end */
ECORE_POS_MAP_ACCELERATE_FACTOR , /**< Start slow then speed up, v1 being a power factor, 0.0 being linear, 1.0 being normal accelerate, 2.0 being much more pronounced accelerate (squared), 3.0 being cubed, etc. */
ECORE_POS_MAP_DECELERATE_FACTOR , /**< Start fast then slow down, v1 being a power factor, 0.0 being linear, 1.0 being normal decelerate, 2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc. */
ECORE_POS_MAP_SINUSOIDAL_FACTOR , /**< Start slow, speed up then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 being normal sinusoidal, 2.0 being much more pronounced sinusoidal (squared), 3.0 being cubed, etc. */
ECORE_POS_MAP_DIVISOR_INTERP , /**< Start at gradient * v1, interpolated via power of v2 curve */
ECORE_POS_MAP_BOUNCE , /**< Start at 0.0 then "drop" like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of v1 */
ECORE_POS_MAP_SPRING /**< Start at 0.0 then "wobble" like a spring rest position 1.0, and wobble v2 times, with decay factor of v1 */
} ;
typedef enum _Ecore_Pos_Map Ecore_Pos_Map ;
enum _Ecore_Animator_Source /* Timing sources for animators */
{
ECORE_ANIMATOR_SOURCE_TIMER , /**< The default system clock/timer based animator that ticks every "frametime" seconds */
ECORE_ANIMATOR_SOURCE_CUSTOM /**< A custom animator trigger that you need to call ecore_animator_trigger() to make it tick */
} ;
typedef enum _Ecore_Animator_Source Ecore_Animator_Source ;
/**
* @ typedef Ecore_Timeline_Cb Ecore_Timeline_Cb
* A callback run for a task ( animators with runtimes )
*/
typedef Eina_Bool ( * Ecore_Timeline_Cb ) ( void * data , double pos ) ;
2010-07-30 01:52:18 -07:00
2010-10-17 00:03:28 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Add an animator to call @ p func at every animaton tick during main
* loop execution .
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param func The function to call when it ticks off
* @ param data The data to pass to the function
* @ return A handle to the new animator
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function adds a animator and returns its handle on success and NULL on
* failure . The function @ p func will be called every N seconds where N is the
* @ p frametime interval set by ecore_animator_frametime_set ( ) . The function
* will be passed the @ p data pointer as its parameter .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* When the animator @ p func is called , it must return a value of either 1 or
* 0. If it returns 1 ( or ECORE_CALLBACK_RENEW ) , it will be called again at
* the next tick , or if it returns 0 ( or ECORE_CALLBACK_CANCEL ) it will be
* deleted automatically making any references / handles for it invalid .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ note The default @ p frametime value is 1 / 30 th of a second .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_timeline_add ( )
* @ see ecore_animator_frametime_set ( )
*/
EAPI Ecore_Animator * ecore_animator_add ( Ecore_Task_Cb func , const void * data ) ;
/**
* @ brief Add a animator that runs for a limited time
2011-07-19 09:58:15 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param runtime The time to run in seconds
* @ param func The function to call when it ticks off
* @ param data The data to pass to the function
* @ return A handle to the new animator
2011-07-19 09:58:15 -07:00
*
2011-08-10 12:14:48 -07:00
* This function is just like ecore_animator_add ( ) except the animator only
* runs for a limited time specified in seconds by @ p runtime . Once the
* runtime the animator has elapsed ( animator finished ) it will automatically
* be deleted . The callback function @ p func can return ECORE_CALLBACK_RENEW
* to keep the animator running or ECORE_CALLBACK_CANCEL ro stop it and have
* it be deleted automatically at any time .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The @ p func will ALSO be passed a position parameter that will be in value
* from 0.0 to 1.0 to indicate where along the timeline ( 0.0 start , 1.0 end )
* the animator run is at . If the callback wishes not to have a linear
* transition it can " map " this value to one of several curves and mappings
* via ecore_animator_pos_map ( ) .
2011-07-19 09:58:15 -07:00
*
2011-08-10 12:14:48 -07:00
* @ note The default @ p frametime value is 1 / 30 th of a second .
2011-07-19 09:58:15 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_add ( )
* @ see ecore_animator_pos_map ( )
* @ since 1.1 .0
*/
EAPI Ecore_Animator * ecore_animator_timeline_add ( double runtime , Ecore_Timeline_Cb func , const void * data ) ;
/**
* @ brief Delete the specified animator from the animator list .
2011-07-12 06:38:25 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param animator The animator to delete
* @ return The data pointer set for the animator on add
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Delete the specified @ p animator from the set of animators that are
* executed during main loop execution . This function returns the data
* parameter that was being passed to the callback on success , or NULL on
* failure . After this call returns the specified animator object @ p animator
* is invalid and should not be used again . It will not get called again after
* deletion .
2010-10-17 00:03:28 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void * ecore_animator_del ( Ecore_Animator * animator ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Suspend the specified animator .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param animator The animator to delete
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The specified @ p animator will be temporarly removed from the set of
* animators that are executed during main loop .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ warning Freezing an animator doesn ' t freeze accounting of how long that
* animator has been running . Therefore if the animator was created with
* ecore_animator_timeline_add ( ) the @ p pos argument given to the callback
* will increase as if the animator hadn ' t been frozen and the animator may
* have it ' s execution halted if @ p runtime elapsed .
*/
EAPI void ecore_animator_freeze ( Ecore_Animator * animator ) ;
/**
* @ brief Restore execution of the specified animator .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param animator The animator to delete
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The specified @ p animator will be put back in the set of animators that are
* executed during main loop .
*/
EAPI void ecore_animator_thaw ( Ecore_Animator * animator ) ;
/**
* @ brief Set the animator call interval in seconds .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param frametime The time in seconds in between animator ticks .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function sets the time interval ( in seconds ) between animator ticks .
* At every tick the callback of every existing animator will be called .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ warning Too small a value may cause performance issues and too high a
* value may cause your animation to seem " jerky " .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ note The default @ p frametime value is 1 / 30 th of a second .
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_animator_frametime_set ( double frametime ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Get the animator call interval in seconds .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return The time in second in between animator ticks .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function retrieves the time in seconds between animator ticks .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_frametime_set ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI double ecore_animator_frametime_get ( void ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Maps an input position from 0.0 to 1.0 along a timeline to a
* position in a different curve .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param pos The input position to map
* @ param map The mapping to use
* @ param v1 A parameter use by the mapping ( pass 0.0 if not used )
* @ param v2 A parameter use by the mapping ( pass 0.0 if not used )
* @ return The mapped value
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Takes an input position ( 0.0 to 1.0 ) and maps to a new position ( normally
* between 0.0 and 1.0 , but it may go above / below 0.0 or 1.0 to show that it
* has " overshot " the mark ) using some interpolation ( mapping ) algorithm .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function useful to create non - linear animations . It offers a variety
* of possible animaton curves to be used :
* @ li ECORE_POS_MAP_LINEAR - Linear , returns @ p pos
* @ li ECORE_POS_MAP_ACCELERATE - Start slow then speed up
* @ li ECORE_POS_MAP_DECELERATE - Start fast then slow down
* @ li ECORE_POS_MAP_SINUSOIDAL - Start slow , speed up then slow down at end
* @ li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up , v1 being a
* power factor , 0.0 being linear , 1.0 being ECORE_POS_MAP_ACCELERATE , 2.0
* being much more pronounced accelerate ( squared ) , 3.0 being cubed , etc .
* @ li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down , v1 being a
* power factor , 0.0 being linear , 1.0 being ECORE_POS_MAP_DECELERATE , 2.0
* being much more pronounced decelerate ( squared ) , 3.0 being cubed , etc .
* @ li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow , speed up then slow down
* at end , v1 being a power factor , 0.0 being linear , 1.0 being
* ECORE_POS_MAP_SINUSOIDAL , 2.0 being much more pronounced sinusoidal
* ( squared ) , 3.0 being cubed , etc .
* @ li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1 , interpolated via
* power of v2 curve
* @ li ECORE_POS_MAP_BOUNCE - Start at 0.0 then " drop " like a ball bouncing to
* the ground at 1.0 , and bounce v2 times , with decay factor of v1
* @ li ECORE_POS_MAP_SPRING - Start at 0.0 then " wobble " like a spring rest
* position 1.0 , and wobble v2 times , with decay factor of v1
* @ note When not listed v1 and v2 have no effect .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ image html ecore - pos - map . png
* @ image latex ecore - pos - map . eps width = \ textwidth
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* One way to use this would be :
* @ code
* double pos ; // input position in a timeline from 0.0 to 1.0
* double out ; // output position after mapping
* int x1 , y1 , x2 , y2 ; // x1 & y1 are start position, x2 & y2 are end position
* int x , y ; // x & y are the calculated position
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* out = ecore_animator_pos_map ( pos , ECORE_POS_MAP_BOUNCE , 1.8 , 7 ) ;
* x = ( x1 * out ) + ( x2 * ( 1.0 - out ) ) ;
* y = ( y1 * out ) + ( y2 * ( 1.0 - out ) ) ;
* move_my_object_to ( myobject , x , y ) ;
* @ endcode
* This will make an animaton that bounces 7 each times diminishing by a
* factor of 1.8 .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see _Ecore_Pos_Map
*
* @ since 1.1 .0
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI double ecore_animator_pos_map ( double pos , Ecore_Pos_Map map , double v1 , double v2 ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Set the source of animator ticks for the mainloop
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param source The source of animator ticks to use
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This sets the source of animator ticks . When an animator is active the
* mainloop will " tick " over frame by frame calling all animators that are
* registered until none are . The mainloop will tick at a given rate based
* on the animator source . The default source is the system clock timer
* source - ECORE_ANIMATOR_SOURCE_TIMER . This source uses the system clock
* to tick over every N seconds ( specified by ecore_animator_frametime_set ( ) ,
* with the default being 1 / 30 th of a second unless set otherwise ) . You can
* set a custom tick source by setting the source to
* ECORE_ANIMATOR_SOURCE_CUSTOM and then drive it yourself based on some input
* tick source ( like another application via ipc , some vertical blanking
* interrupt interrupt etc . ) using
* ecore_animator_custom_source_tick_begin_callback_set ( ) and
* ecore_animator_custom_source_tick_end_callback_set ( ) to set the functions
* that will be called to start and stop the ticking source , which when it
* gets a " tick " should call ecore_animator_custom_tick ( ) to make the " tick " over 1
* frame .
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_animator_source_set ( Ecore_Animator_Source source ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Get the animator source currently set .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return The current animator source
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This gets the current animator source .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_source_set ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Ecore_Animator_Source ecore_animator_source_get ( void ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Set the function that begins a custom animator tick source
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param func The function to call when ticking is to begin
* @ param data The data passed to the tick begin function as its parameter
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The Ecore Animator infrastructure handles tracking if animators are needed
* or not and which ones need to be called and when , but when the tick source
* is custom , you have to provide a tick source by calling
* ecore_animator_custom_tick ( ) to indicate a frame tick happened . In order
* to allow the source of ticks to be dynamically enabled or disabled as
* needed , the @ p func when set is called to enable the tick source to
* produce tick events that call ecore_animator_custom_tick ( ) . If @ p func
* is NULL then no function is called to begin custom ticking .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_source_set ( )
* @ see ecore_animator_custom_source_tick_end_callback_set ( )
* @ see ecore_animator_custom_tick ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_animator_custom_source_tick_begin_callback_set ( Ecore_Cb func , const void * data ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Set the function that ends a custom animator tick source
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param func The function to call when ticking is to end
* @ param data The data passed to the tick end function as its parameter
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function is a matching pair to the function set by
* ecore_animator_custom_source_tick_begin_callback_set ( ) and is called
* when ticking is to stop . If @ p func is NULL then no function will be
* called to stop ticking . For more information please see
* ecore_animator_custom_source_tick_begin_callback_set ( ) .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_source_set ( )
* @ see ecore_animator_custom_source_tick_begin_callback_set ( )
* @ see ecore_animator_custom_tick ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_animator_custom_source_tick_end_callback_set ( Ecore_Cb func , const void * data ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ brief Trigger a custom animator tick
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* When animator source is set to ECORE_ANIMATOR_SOURCE_CUSTOM , then calling
* this function triggers a run of all animators currently registered with
* Ecore as this indicates a " frame tick " happened . This will do nothing if
* the animator source ( set by ecore_animator_source_set ( ) ) is not set to
* ECORE_ANIMATOR_SOURCE_CUSTOM .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_animator_source_set ( )
* @ see ecore_animator_custom_source_tick_begin_callback_set
* @ see ecore_animator_custom_source_tick_end_callback_set ( ) ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_animator_custom_tick ( void ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ }
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
/**
* @ defgroup Ecore_Time_Group Ecore Time functions
*
* Functions that deal with time . These functions include those
* that simply retrieve it in a given format , and those that create
* events based on it .
*
* The timer allows callbacks to be called at specific intervals .
*
* Examples with functions that deal with time :
* @ li @ ref ecore_time_functions_example_c
* @ li @ ref ecore_timer_example_c
*
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
*/
typedef struct _Ecore_Timer Ecore_Timer ; /**< A handle for timers */
EAPI double ecore_time_get ( void ) ;
EAPI double ecore_time_unix_get ( void ) ;
EAPI double ecore_loop_time_get ( void ) ;
EAPI Ecore_Timer * ecore_timer_add ( double in , Ecore_Task_Cb func , const void * data ) ;
EAPI Ecore_Timer * ecore_timer_loop_add ( double in , Ecore_Task_Cb func , const void * data ) ;
EAPI void * ecore_timer_del ( Ecore_Timer * timer ) ;
EAPI void ecore_timer_interval_set ( Ecore_Timer * timer , double in ) ;
EAPI double ecore_timer_interval_get ( Ecore_Timer * timer ) ;
EAPI void ecore_timer_freeze ( Ecore_Timer * timer ) ;
EAPI void ecore_timer_thaw ( Ecore_Timer * timer ) ;
EAPI void ecore_timer_delay ( Ecore_Timer * timer , double add ) ;
EAPI double ecore_timer_pending_get ( Ecore_Timer * timer ) ;
EAPI double ecore_timer_precision_get ( void ) ;
EAPI void ecore_timer_precision_set ( double precision ) ;
EAPI char * ecore_timer_dump ( void ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ }
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
/**
* @ defgroup Ecore_Idle_Group Ecore Idle functions
*
* Callbacks that are called when the program enters or exits an
* idle state .
*
* The ecore main loop enters an idle state when it is waiting for
* timers to time out , data to come in on a file descriptor or any
* other event to occur . You can set callbacks to be called when
* the main loop enters an idle state , during an idle state or just
* after the program wakes up .
*
* 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 .
*
* 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 .
*
* Exiter callbacks are called when the main loop wakes up from an
* idle state .
*
* @ note Idle state doesn ' t mean that the @ b program is idle , but
* that the < b > main loop < / b > is idle . It doesn ' t have any timers ,
* events , fd handlers or anything else to process ( which in most
* < em > event driven < / em > programs also means that the @ b 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 :
*
* @ li @ ref ecore_idler_example_c
*
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
*/
typedef struct _Ecore_Idler Ecore_Idler ; /**< A handle for idlers */
typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer ; /**< A handle for idle enterers */
typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter ; /**< A handle for idle exiters */
/**
* Add an idler handler .
* @ param func The function to call when idling .
* @ param data The data to be passed to this @ p func call .
* @ return 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 @ p 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 .
*/
EAPI Ecore_Idler * ecore_idler_add ( Ecore_Task_Cb func , const void * data ) ;
/**
* Delete an idler callback from the list to be executed .
* @ param idler The handle of the idler callback to delete
* @ return The data pointer passed to the idler callback on success . NULL
* otherwise .
*/
EAPI void * ecore_idler_del ( Ecore_Idler * idler ) ;
EAPI Ecore_Idle_Enterer * ecore_idle_enterer_add ( Ecore_Task_Cb func , const void * data ) ;
EAPI Ecore_Idle_Enterer * ecore_idle_enterer_before_add ( Ecore_Task_Cb func , const void * data ) ;
EAPI void * ecore_idle_enterer_del ( Ecore_Idle_Enterer * idle_enterer ) ;
EAPI Ecore_Idle_Exiter * ecore_idle_exiter_add ( Ecore_Task_Cb func , const void * data ) ;
EAPI void * ecore_idle_exiter_del ( Ecore_Idle_Exiter * idle_exiter ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ }
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* @ defgroup Ecore_Thread_Group Ecore Thread functions
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Facilities to run heavy tasks in different threads to avoid blocking
* the main loop .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The EFL is , for the most part , not thread safe . This means that if you
* have some task running in another thread and you have , for example , an
* Evas object to show the status progress of this task , you cannot update
* the object from within the thread . This can only be done from the main
* thread , the one running the main loop . This problem can be solved
* by running a thread that sends messages to the main one using an
* @ ref Ecore_Pipe_Group " Ecore_Pipe " , but when you need to handle other
* things like cancelling the thread , your code grows in coplexity and gets
* much harder to maintain .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Ecore Thread is here to solve that problem . It is @ b not a simple wrapper
* around standard POSIX threads ( or the equivalent in other systems ) and
* it ' s not meant to be used to run parallel tasks throughout the entire
* duration of the program , especially when these tasks are performance
* critical , as Ecore manages these tasks using a pool of threads based on
* system configuration .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* What Ecore Thread does , is make it a lot easier to dispatch a worker
* function to perform some heavy task and then get the result once it
* completes , without blocking the application ' s UI . In addition , cancelling
* and rescheduling comes practically for free and the developer needs not
* worry about how many threads are launched , since Ecore will schedule
* them according to the number of processors the system has and maximum
* amount of concurrent threads set for the application .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* At the system level , Ecore will start a new thread on an as - needed basis
* until the maximum set is reached . When no more threads can be launched ,
* new worker functions will be queued in a waiting list until a thread
* becomes available . This way , system threads will be shared throughout
* different worker functions , but running only one at a time . At the same
* time , a worker function that is rescheduled may be run on a different
* thread the next time .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The : : Ecore_Thread handler has two meanings , depending on what context
* it is on . The one returned when starting a worker with any of the
* functions ecore_thread_run ( ) or ecore_thread_feedback_run ( ) is an
* identifier of that specific instance of the function and can be used from
* the main loop with the ecore_thread_cancel ( ) and ecore_thread_check ( )
* functions . This handler must not be shared with the worker function
* function running in the thread . This same handler will be the one received
* on the @ c end , @ c cancel and @ c feedback callbacks .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The worker function , that ' s the one running in the thread , also receives
* an : : Ecore_Thread handler that can be used with ecore_thread_cancel ( ) and
* ecore_thread_check ( ) , sharing the flag with the main loop . But this
* handler is also associated with the thread where the function is running .
* This has strong implications when working with thread local data .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* There are two kinds of worker threads Ecore handles : simple , or short ,
* workers and feedback workers .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The first kind is for simple functions that perform a
* usually small but time consuming task . Ecore will run this function in
* a thread as soon as one becomes available and notify the calling user of
* its completion once the task is done .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The following image shows the flow of a program running four tasks on
* a pool of two threads .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ image html ecore_thread . png
* @ image rtf ecore_thread . png
* @ image latex ecore_thread . eps width = \ textwidth
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* For larger tasks that may require continuous communication with the main
* program , the feedback workers provide the same functionality plus a way
* for the function running in the thread to send messages to the main
* thread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The next diagram omits some details shown in the previous one regarding
* how threads are spawned and tasks are queued , but illustrates how feedback
* jobs communicate with the main loop and the special case of threads
* running out of pool .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ image html ecore_thread_feedback . png
* @ image rtf ecore_thread_feedback . png
* @ image latex ecore_thread_feedback . eps width = \ textwidth
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* See an overview example in @ ref ecore_thread_example_c .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ ingroup Ecore_Main_Loop_Group
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ {
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
typedef struct _Ecore_Thread Ecore_Thread ; /**< A handle for threaded jobs */
/**
* @ typedef Ecore_Thread_Cb Ecore_Thread_Cb
* A callback used by Ecore_Thread helper .
*/
typedef void ( * Ecore_Thread_Cb ) ( void * data , Ecore_Thread * thread ) ;
/**
* @ typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb
* A callback used by the main loop to receive data sent by an
* @ ref Ecore_Thread_Group .
*/
typedef void ( * Ecore_Thread_Notify_Cb ) ( void * data , Ecore_Thread * thread , void * msg_data ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* Schedule a task to run in a parallel thread to avoid locking the main loop
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param func_blocking The function that should run in another thread .
* @ param func_end Function to call from main loop when @ p func_blocking
* completes its task successfully ( may be NULL )
* @ param func_cancel Function to call from main loop if the thread running
* @ p func_blocking is cancelled or fails to start ( may be NULL )
* @ param data User context data to pass to all callbacks .
* @ return A new thread handler , or NULL on failure
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function will try to create a new thread to run @ p func_blocking in ,
* or if the maximum number of concurrent threads has been reached , will
* add it to the pending list , where it will wait until a thread becomes
* available . The return value will be an : : Ecore_Thread handle that can
* be used to cancel the thread before its completion .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ note This function should always return immediately , but in the rare
* case that Ecore is built with no thread support , @ p func_blocking will
* be called here , actually blocking the main loop .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Once a thread becomes available , @ p func_blocking will be run in it until
* it finishes , then @ p func_end is called from the thread containing the
* main loop to inform the user of its completion . While in @ p func_blocking ,
* no functions from the EFL can be used , except for those from Eina that are
* marked to be thread - safe . Even for the latter , caution needs to be taken
* if the data is shared across several threads .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ p func_end will be called from the main thread when @ p func_blocking ends ,
* so here it ' s safe to use anything from the EFL freely .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The thread can also be cancelled before its completion calling
* ecore_thread_cancel ( ) , either from the main thread or @ p func_blocking .
* In this case , @ p func_cancel will be called , also from the main thread
* to inform of this happening . If the thread could not be created , this
* function will be called and it ' s @ c thread parameter will be NULL . It ' s
* also safe to call any EFL function here , as it will be running in the
* main thread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Inside @ p func_blocking , it ' s possible to call ecore_thread_reschedule ( )
* to tell Ecore that this function should be called again .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Be aware that no assumptions can be made about the order in which the
* @ p func_end callbacks for each task will be called . Once the function is
* running in a different thread , it ' s the OS that will handle its running
* schedule , and different functions may take longer to finish than others .
* Also remember that just starting several tasks together doesn ' t mean they
* will be running at the same time . Ecore will schedule them based on the
* number of threads available for the particular system it ' s running in ,
* so some of the jobs started may be waiting until another one finishes
* before it can execute its own @ p func_blocking .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_feedback_run ( )
* @ see ecore_thread_cancel ( )
* @ see ecore_thread_reschedule ( )
* @ see ecore_thread_max_set ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Ecore_Thread * ecore_thread_run ( Ecore_Thread_Cb func_blocking ,
Ecore_Thread_Cb func_end ,
Ecore_Thread_Cb func_cancel ,
const void * data ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* Launch a thread to run a task than can talk back to the main thread
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param func_heavy The function that should run in another thread .
* @ param func_notify Function that receives the data sent from the thread
* @ param func_end Function to call from main loop when @ p func_heavy
* completes its task successfully
* @ param func_cancel Function to call from main loop if the thread running
* @ p func_heavy is cancelled or fails to start
* @ param data User context data to pass to all callback .
* @ param try_no_queue If you want to run outside of the thread pool .
* @ return A new thread handler , or NULL on failure
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* See ecore_thread_run ( ) for a general description of this function .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The difference with the above is that ecore_thread_run ( ) is meant for
* tasks that don ' t need to communicate anything until they finish , while
* this function is provided with a new callback , @ p func_notify , that will
* be called from the main thread for every message sent from @ p func_heavy
* with ecore_thread_feedback ( ) .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Like with ecore_thread_run ( ) , a new thread will be launched to run
* @ p func_heavy unless the maximum number of simultaneous threadas has been
* reached , in which case the function will be scheduled to run whenever a
* running task ends and a thread becomes free . But if @ p try_no_queue is
* set , Ecore will first try to launch a thread outside of the pool to run
* the task . If it fails , it will revert to the normal behaviour of using a
* thread from the pool as if @ p try_no_queue had not been set .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Keep in mind that Ecore handles the thread pool based on the number of
* CPUs available , but running a thread outside of the pool doesn ' t count for
* this , so having too many of them may have drastic effects over the
* program ' s performance .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_feedback ( )
* @ see ecore_thread_run ( )
* @ see ecore_thread_cancel ( )
* @ see ecore_thread_reschedule ( )
* @ see ecore_thread_max_set ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Ecore_Thread * ecore_thread_feedback_run ( Ecore_Thread_Cb func_heavy ,
Ecore_Thread_Notify_Cb func_notify ,
Ecore_Thread_Cb func_end ,
Ecore_Thread_Cb func_cancel ,
const void * data ,
Eina_Bool try_no_queue ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* Cancel a running thread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The thread to cancel .
* @ return Will return EINA_TRUE if the thread has been cancelled ,
* EINA_FALSE if it is pending .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function can be called both in the main loop or in the running thread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function cancels a running thread . If @ p thread can be immediately
* cancelled ( it ' s still pending execution after creation or rescheduling ) ,
* then the @ c cancel callback will be called , @ p thread will be freed and
* the function will return EINA_TRUE .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* If the thread is already running , then this function returns EINA_FALSE
* after marking the @ p thread as pending cancellation . For the thread to
* actually be terminated , it needs to return from the user function back
* into Ecore control . This can happen in several ways :
* @ li The function ends and returns normally . If it hadn ' t been cancelled ,
* @ c func_end would be called here , but instead @ c func_cancel will happen .
* @ li The function returns after requesting to be rescheduled with
* ecore_thread_reschedule ( ) .
* @ li The function is prepared to leave early by checking if
* ecore_thread_check ( ) returns EINA_TRUE .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The user function can cancel itself by calling ecore_thread_cancel ( ) , but
* it should always use the : : Ecore_Thread handle passed to it and never
* share it with the main loop thread by means of shared user data or any
* other way .
*
* @ p thread will be freed and should not be used again if this function
* returns EINA_TRUE or after the @ c func_cancel callback returns .
*
* @ see ecore_thread_check ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_cancel ( Ecore_Thread * thread ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* Checks if a thread is pending cancellation
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The thread to test .
* @ return EINA_TRUE if the thread is pending cancellation ,
* EINA_FALSE if it is not .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function can be called both in the main loop or in the running thread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* When ecore_thread_cancel ( ) is called on an already running task , the
* thread is marked as pending cancellation . This function returns EINA_TRUE
* if this mark is set for the given @ p thread and can be used from the
* main loop thread to check if a still active thread has been cancelled ,
* or from the user function running in the thread to check if it should
* stop doing what it ' s doing and return early , effectively cancelling the
* task .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_cancel ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_check ( Ecore_Thread * thread ) ;
2011-07-06 11:08:21 -07:00
/**
2011-08-10 12:14:48 -07:00
* Sends data from the worker thread to the main loop
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The current : : Ecore_Thread context to send data from
* @ param msg_data Data to be transmitted to the main loop
* @ return EINA_TRUE if @ p msg_data was successfully sent to main loop ,
* EINA_FALSE if anything goes wrong .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* You should use this function only in the @ c func_heavy call .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Only the address to @ p msg_data will be sent and once this function
* returns EINA_TRUE , the job running in the thread should never touch the
* contents of it again . The data sent should be malloc ( ) ' ed or something
* similar , as long as it ' s not memory local to the thread that risks being
* overwritten or deleted once it goes out of scope or the thread finishes .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Care must be taken that @ p msg_data is properly freed in the @ c func_notify
* callback set when creating the thread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_feedback_run ( )
2011-07-06 11:08:21 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_feedback ( Ecore_Thread * thread , const void * msg_data ) ;
2010-10-17 00:03:28 -07:00
/**
2011-08-10 12:14:48 -07:00
* Asks for the function in the thread to be called again at a later time
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The current : : Ecore_Thread context to rescheduled
* @ return EINA_TRUE if the task was successfully rescheduled ,
* EINA_FALSE if anything goes wrong .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This function should be called only from the same function represented
* by @ pthread .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* Calling this function will mark the thread for a reschedule , so as soon
* as it returns , it will be added to the end of the list of pending tasks .
* If no other tasks are waiting or there are sufficient threads available ,
* the rescheduled task will be launched again immediately .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* This should never return EINA_FALSE , unless it was called from the wrong
* thread or with the wrong arguments .
2011-07-06 11:08:21 -07:00
*
2011-08-10 12:14:48 -07:00
* The @ c func_end callback set when the thread is created will not be
* called until the function in the thread returns without being rescheduled .
* Similarly , if the @ p thread is cancelled , the reschedule will not take
* effect .
2010-10-17 00:03:28 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_reschedule ( Ecore_Thread * thread ) ;
2010-10-17 00:03:28 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets the number of active threads running jobs
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return Number of active threads running jobs
2010-10-17 00:03:28 -07:00
*
2011-08-10 12:14:48 -07:00
* This returns the number of threads currently running jobs of any type
* through the Ecore_Thread API .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ note Jobs started through the ecore_thread_feedback_run ( ) function with
* the @ c try_no_queue parameter set to EINA_TRUE will not be accounted for
* in the return of this function unless the thread creation fails and it
* falls back to using one from the pool .
*/
EAPI int ecore_thread_active_get ( void ) ;
/**
* Gets the number of short jobs waiting for a thread to run
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return Number of pending threads running " short " jobs
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This returns the number of tasks started with ecore_thread_run ( ) that are
* pending , waiting for a thread to become available to run them .
2010-10-17 00:03:28 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI int ecore_thread_pending_get ( void ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets the number of feedback jobs waiting for a thread to run
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return Number of pending threads running " feedback " jobs
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This returns the number of tasks started with ecore_thread_feedback_run ( )
* that are pending , waiting for a thread to become available to run them .
*/
EAPI int ecore_thread_pending_feedback_get ( void ) ;
/**
* Gets the total number of pending jobs
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return Number of pending threads running jobs
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Same as the sum of ecore_thread_pending_get ( ) and
* ecore_thread_pending_feedback_get ( ) .
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI int ecore_thread_pending_total_get ( void ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets the maximum number of threads that can run simultaneously
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return Max possible number of Ecore_Thread ' s running concurrently
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This returns the maximum number of Ecore_Thread ' s that may be running at
* the same time . If this number is reached , new jobs started by either
* ecore_thread_run ( ) or ecore_thread_feedback_run ( ) will be added to the
* respective pending queue until one of the running threads finishes its
* task and becomes available to run a new one .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* By default , this will be the number of available CPUs for the
* running program ( as returned by eina_cpu_count ( ) ) , or 1 if this value
* could not be fetched .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_max_set ( )
* @ see ecore_thread_max_reset ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI int ecore_thread_max_get ( void ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Sets the maximum number of threads allowed to run simultaneously
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param num The new maximum
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This sets a new value for the maximum number of concurrently running
* Ecore_Thread ' s . It @ b must an integer between 1 and ( 2 * @ c x ) , where @ c x
* is the number for CPUs available .
*
* @ see ecore_thread_max_get ( )
* @ see ecore_thread_max_reset ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_thread_max_set ( int num ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Resets the maximum number of concurrently running threads to the default
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This resets the value returned by ecore_thread_max_get ( ) back to its
* default .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_max_get ( )
* @ see ecore_thread_max_set ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void ecore_thread_max_reset ( void ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets the number of threads available for running tasks
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ return The number of available threads
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Same as doing ecore_thread_max_get ( ) - ecore_thread_active_get ( ) .
*
* This function may return a negative number only in the case the user
* changed the maximum number of running threads while other tasks are
* running .
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI int ecore_thread_available_get ( void ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Adds some data to a hash local to the thread
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The thread context the data belongs to
* @ param key The name under which the data will be stored
* @ param value The data to add
* @ param cb Function to free the data when removed from the hash
* @ param direct If true , this will not copy the key string ( like
* eina_hash_direct_add ( ) )
* @ return EINA_TRUE on success , EINA_FALSE on failure
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Ecore Thread has a mechanism to share data across several worker functions
* that run on the same system thread . That is , the data is stored per
* thread and for a worker function to have access to it , it must be run
* by the same thread that stored the data .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* When there are no more workers pending , the thread will be destroyed
* along with the internal hash and any data left in it will be freed with
* the @ p cb function given .
2011-07-07 11:57:10 -07:00
*
2011-08-10 12:14:48 -07:00
* This set of functions is useful to share things around several instances
* of a function when that thing is costly to create and can be reused , but
* may only be used by one function at a time .
*
* For example , if you have a program doing requisitions to a database ,
* these requisitions can be done in threads so that waiting for the
* database to respond doesn ' t block the UI . Each of these threads will
* run a function , and each function will be dependent on a connection to
* the database , which may not be able to handle more than one request at
* a time so for each running function you will need one connection handle .
* The options then are :
* @ li Each function opens a connection when it ' s called , does the work and
* closes the connection when it finishes . This may be costly , wasting a lot
* of time on resolving hostnames , negotiating permissions and allocating
* memory .
* @ li Open the connections in the main loop and pass it to the threads
* using the data pointer . Even worse , it ' s just as costly as before and now
* it may even be kept with connections open doing nothing until a thread
* becomes available to run the function .
* @ li Have a way to share connection handles , so that each instance of the
* function can check if an available connection exists , and if it doesn ' t ,
* create one and add it to the pool . When no more connections are needed ,
* they are all closed .
*
* The last option is the most efficient , but it requires a lot of work to
* implement properly . Using thread local data helps to achieve the same
* result while avoiding doing all the tracking work on your code . The way
* to use it would be , at the worker function , to ask for the connection
* with ecore_thread_local_data_find ( ) and if it doesn ' t exist , then open
* a new one and save it with ecore_thread_local_data_add ( ) . Do the work and
* forget about the connection handle , when everything is done the function
* just ends . The next worker to run on that thread will check if a
* connection exists and find that it does , so the process of opening a
* new one has been spared . When no more workers exist , the thread is
* destroyed and the callback used when saving the connection will be called
* to close it .
*
* This function adds the data @ p value to the thread data under the given
* @ p key .
* No other value in the hash may have the same @ p key . If you need to
* change the value under a @ p key , or you don ' t know if one exists already ,
* you can use ecore_thread_local_data_set ( ) .
*
* Neither @ p key nor @ p value may be NULL and @ p key will be copied in the
* hash , unless @ p direct is set , in which case the string used should not
* be freed until the data is removed from the hash .
*
* The @ p cb function will be called when the data in the hash needs to be
* freed , be it because it got deleted with ecore_thread_local_data_del ( ) or
* because @ p thread was terminated and the hash destroyed . This parameter
* may be NULL , in which case @ p value needs to be manually freed after
* removing it from the hash with either ecore_thread_local_data_del ( ) or
* ecore_thread_local_data_set ( ) , but it ' s very unlikely that this is what
* you want .
*
* This function , and all of the others in the @ c ecore_thread_local_data
* family of functions , can only be called within the worker function running
* in the thread . Do not call them from the main loop or from a thread
* other than the one represented by @ p thread .
*
* @ see ecore_thread_local_data_set ( )
* @ see ecore_thread_local_data_find ( )
* @ see ecore_thread_local_data_del ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_local_data_add ( Ecore_Thread * thread , const char * key , void * value , Eina_Free_Cb cb , Eina_Bool direct ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Sets some data in the hash local to the given thread
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The thread context the data belongs to
* @ param key The name under which the data will be stored
* @ param value The data to add
* @ param cb Function to free the data when removed from the hash
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If no data exists in the hash under the @ p key , this function adds
* @ p value in the hash under the given @ p key and returns NULL .
* The key itself is copied .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If the hash already contains something under @ p key , the data will be
* replaced by @ p value and the old value will be returned .
*
* NULL will also be returned if either @ p key or @ p value are NULL , or if
* an error occurred .
*
* This function , and all of the others in the @ c ecore_thread_local_data
* family of functions , can only be called within the worker function running
* in the thread . Do not call them from the main loop or from a thread
* other than the one represented by @ p thread .
*
* @ see ecore_thread_local_data_add ( )
* @ see ecore_thread_local_data_del ( )
* @ see ecore_thread_local_data_find ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void * ecore_thread_local_data_set ( Ecore_Thread * thread , const char * key , void * value , Eina_Free_Cb cb ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets data stored in the hash local to the given thread
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The thread context the data belongs to
* @ param key The name under which the data is stored
* @ return The value under the given key , or NULL on error
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Finds and return the data stored in the shared hash under the key @ p key .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This function , and all of the others in the @ c ecore_thread_local_data
* family of functions , can only be called within the worker function running
* in the thread . Do not call them from the main loop or from a thread
* other than the one represented by @ p thread .
*
* @ see ecore_thread_local_data_add ( )
* @ see ecore_thread_local_data_wait ( )
*/
EAPI void * ecore_thread_local_data_find ( Ecore_Thread * thread , const char * key ) ;
/**
* Deletes from the thread ' s hash the data corresponding to the given key
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param thread The thread context the data belongs to
* @ param key The name under which the data is stored
* @ return EINA_TRUE on success , EINA_FALSE on failure
2011-08-03 07:40:06 -07:00
*
2011-08-10 12:14:48 -07:00
* If there ' s any data stored associated with @ p key in the global hash ,
* this function will remove it from it and return EINA_TRUE . If no data
* exists or an error occurs , it returns EINA_FALSE .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If the data was added to the hash with a free function , then it will
* also be freed after removing it from the hash , otherwise it requires
* to be manually freed by the user , which means that if no other reference
* to it exists before calling this function , it will result in a memory
* leak .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* This function , and all of the others in the @ c ecore_thread_local_data
* family of functions , can only be called within the worker function running
* in the thread . Do not call them from the main loop or from a thread
* other than the one represented by @ p thread .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ see ecore_thread_local_data_add ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_local_data_del ( Ecore_Thread * thread , const char * key ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Adds some data to a hash shared by all threads
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param key The name under which the data will be stored
* @ param value The data to add
* @ param cb Function to free the data when removed from the hash
* @ param direct If true , this will not copy the key string ( like
* eina_hash_direct_add ( ) )
* @ return EINA_TRUE on success , EINA_FALSE on failure
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Ecore Thread keeps a hash that can be used to share data across several
* threads , including the main loop one , without having to manually handle
* mutexes to do so safely .
*
* This function adds the data @ p value to this hash under the given @ p key .
* No other value in the hash may have the same @ p key . If you need to
* change the value under a @ p key , or you don ' t know if one exists already ,
* you can use ecore_thread_global_data_set ( ) .
*
* Neither @ p key nor @ p value may be NULL and @ p key will be copied in the
* hash , unless @ p direct is set , in which case the string used should not
* be freed until the data is removed from the hash .
*
* The @ p cb function will be called when the data in the hash needs to be
* freed , be it because it got deleted with ecore_thread_global_data_del ( ) or
* because Ecore Thread was shut down and the hash destroyed . This parameter
* may be NULL , in which case @ p value needs to be manually freed after
* removing it from the hash with either ecore_thread_global_data_del ( ) or
* ecore_thread_global_data_set ( ) .
*
* Manually freeing any data that was added to the hash with a @ p cb function
* is likely to produce a segmentation fault , or any other strange
* happenings , later on in the program .
*
* @ see ecore_thread_global_data_del ( )
* @ see ecore_thread_global_data_set ( )
* @ see ecore_thread_global_data_find ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_global_data_add ( const char * key , void * value , Eina_Free_Cb cb , Eina_Bool direct ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Sets some data in the hash shared by all threads
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param key The name under which the data will be stored
* @ param value The data to add
* @ param cb Function to free the data when removed from the hash
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If no data exists in the hash under the @ p key , this function adds
* @ p value in the hash under the given @ p key and returns NULL .
* The key itself is copied .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If the hash already contains something under @ p key , the data will be
* replaced by @ p value and the old value will be returned .
*
* NULL will also be returned if either @ p key or @ p value are NULL , or if
* an error occurred .
*
* @ see ecore_thread_global_data_add ( )
* @ see ecore_thread_global_data_del ( )
* @ see ecore_thread_global_data_find ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void * ecore_thread_global_data_set ( const char * key , void * value , Eina_Free_Cb cb ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets data stored in the hash shared by all threads
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param key The name under which the data is stored
* @ return The value under the given key , or NULL on error
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Finds and return the data stored in the shared hash under the key @ p key .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Keep in mind that the data returned may be used by more than one thread
* at the same time and no reference counting is done on it by Ecore .
* Freeing the data or modifying its contents may require additional
* precautions to be considered , depending on the application ' s design .
*
* @ see ecore_thread_global_data_add ( )
* @ see ecore_thread_global_data_wait ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void * ecore_thread_global_data_find ( const char * key ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Deletes from the shared hash the data corresponding to the given key
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param key The name under which the data is stored
* @ return EINA_TRUE on success , EINA_FALSE on failure
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If there ' s any data stored associated with @ p key in the global hash ,
* this function will remove it from it and return EINA_TRUE . If no data
* exists or an error occurs , it returns EINA_FALSE .
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* If the data was added to the hash with a free function , then it will
* also be freed after removing it from the hash , otherwise it requires
* to be manually freed by the user , which means that if no other reference
* to it exists before calling this function , it will result in a memory
* leak .
*
* Note , also , that freeing data that other threads may be using will result
* in a crash , so appropriate care must be taken by the application when
* that possibility exists .
*
* @ see ecore_thread_global_data_add ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI Eina_Bool ecore_thread_global_data_del ( const char * key ) ;
2011-07-07 11:56:57 -07:00
/**
2011-08-10 12:14:48 -07:00
* Gets data stored in the shared hash , or wait for it if it doesn ' t exist
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* @ param key The name under which the data is stored
* @ param seconds The amount of time in seconds to wait for the data .
* @ return The value under the given key , or NULL on error
2011-07-07 11:56:57 -07:00
*
2011-08-10 12:14:48 -07:00
* Finds and return the data stored in the shared hash under the key @ p key .
*
* If there ' s nothing in the hash under the given @ p key , the function
* will block and wait up to @ p seconds seconds for some other thread to
* add it with either ecore_thread_global_data_add ( ) or
* ecore_thread_global_data_set ( ) . If after waiting there ' s still no data
* to get , NULL will be returned .
*
* If @ p seconds is 0 , then no waiting will happen and this function works
* like ecore_thread_global_data_find ( ) . If @ p seconds is less than 0 , then
* the function will wait indefinitely .
*
* Keep in mind that the data returned may be used by more than one thread
* at the same time and no reference counting is done on it by Ecore .
* Freeing the data or modifying its contents may require additional
* precautions to be considered , depending on the application ' s design .
*
* @ see ecore_thread_global_data_add ( )
* @ see ecore_thread_global_data_find ( )
2011-07-07 11:56:57 -07:00
*/
2011-08-10 12:14:48 -07:00
EAPI void * ecore_thread_global_data_wait ( const char * key , double seconds ) ;
2010-10-17 00:03:28 -07:00
/**
* @ }
*/
/**
2011-08-10 12:14:48 -07:00
* @ defgroup Ecore_Pipe_Group Pipe wrapper
*
* These functions wrap the pipe / write / read functions to easily
* integrate its use into ecore ' s main loop .
*
* The ecore_pipe_add ( ) function creates file descriptors ( sockets
* on Windows ) and attach a handle to the ecore main loop . That
* handle is called when data is read in the pipe . To write data in
* the pipe , just call ecore_pipe_write ( ) . When you are done , just
* call ecore_pipe_del ( ) .
*
* For examples see here :
* @ li @ ref tutorial_ecore_pipe_gstreamer_example
* @ li @ ref tutorial_ecore_pipe_simple_example
*
* @ ingroup Ecore_Main_Loop_Group
2010-10-17 00:03:28 -07:00
*
* @ {
*/
2011-08-10 12:14:48 -07:00
typedef struct _Ecore_Pipe Ecore_Pipe ; /**< A handle for pipes */
/**
* @ typedef Ecore_Pipe_Cb Ecore_Pipe_Cb
* The callback that data written to the pipe is sent to .
*/
typedef void ( * Ecore_Pipe_Cb ) ( void * data , void * buffer , unsigned int nbyte ) ;
EAPI Ecore_Pipe * ecore_pipe_add ( Ecore_Pipe_Cb handler , const void * data ) ;
EAPI void * ecore_pipe_del ( Ecore_Pipe * p ) ;
EAPI Eina_Bool ecore_pipe_write ( Ecore_Pipe * p , const void * buffer , unsigned int nbytes ) ;
EAPI void ecore_pipe_write_close ( Ecore_Pipe * p ) ;
EAPI void ecore_pipe_read_close ( Ecore_Pipe * p ) ;
EAPI void ecore_pipe_thaw ( Ecore_Pipe * p ) ;
EAPI void ecore_pipe_freeze ( Ecore_Pipe * p ) ;
EAPI int ecore_pipe_wait ( Ecore_Pipe * p , int message_count , double wait ) ;
2008-01-10 23:33:57 -08:00
2010-10-17 00:03:28 -07:00
/**
* @ }
*/
2011-08-10 12:14:48 -07:00
/**
* @ defgroup Ecore_Job_Group Ecore Job functions
*
* You can queue jobs that are to be done by the main loop when the
* current event is dealt with .
*
* Jobs are processed by the main loop similarly to events . They
* also will be executed in the order in which they were added .
*
* A good use for them is when you don ' t want to execute an action
* immeditately , but want to give the control back to the main loop
* so that it will call your job callback when jobs start being
* processed ( and if there are other jobs added before yours , they
* will be processed first ) . This also gives the chance to other
* actions in your program to cancel the job before it is started .
*
* Examples of using @ ref Ecore_Job :
* @ li @ ref ecore_job_example_c
*
* @ ingroup Ecore_Main_Loop_Group
*
* @ {
*/
typedef struct _Ecore_Job Ecore_Job ; /**< A job handle */
2010-10-17 00:03:28 -07:00
2010-08-03 19:55:20 -07:00
EAPI Ecore_Job * ecore_job_add ( Ecore_Cb func , const void * data ) ;
2010-01-25 13:59:21 -08:00
EAPI void * ecore_job_del ( Ecore_Job * job ) ;
2008-05-25 22:16:34 -07:00
2010-10-17 00:03:28 -07:00
/**
* @ }
*/
2011-08-10 12:14:48 -07:00
/**
* @ defgroup Ecore_Application_Group Ecore Application functions
*
* @ {
*/
EAPI void ecore_app_args_set ( int argc , const char * * argv ) ;
EAPI void ecore_app_args_get ( int * argc , char * * * argv ) ;
EAPI void ecore_app_restart ( void ) ;
2010-10-17 00:03:28 -07:00
/**
* @ }
*/
2011-06-28 05:34:52 -07:00
/**
* @ defgroup Ecore_Throttle_Group Ecore Throttle functions
*
2011-08-10 12:14:48 -07:00
* @ ingroup Ecore_Main_Loop_Group
*
2011-06-28 05:34:52 -07:00
* @ {
*/
EAPI void ecore_throttle_adjust ( double amount ) ;
EAPI double ecore_throttle_get ( void ) ;
/**
* @ }
*/
2003-09-23 01:09:32 -07:00
# ifdef __cplusplus
}
# endif
# endif