summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--src/lib/ecore/Ecore.h3391
-rw-r--r--src/lib/ecore/Ecore_Getopt.h1004
-rw-r--r--src/lib/ecore_con/Ecore_Con.h1586
-rw-r--r--src/lib/ecore_con/Ecore_Con_Eet.h211
-rwxr-xr-x[-rw-r--r--]src/lib/ecore_evas/Ecore_Evas.h2689
-rw-r--r--src/lib/ecore_fb/Ecore_Fb.h18
-rw-r--r--src/lib/ecore_file/Ecore_File.h39
-rw-r--r--src/lib/ecore_imf/Ecore_IMF.h1359
-rw-r--r--src/lib/ecore_imf_evas/Ecore_IMF_Evas.h75
-rw-r--r--src/lib/ecore_input/Ecore_Input.h433
-rw-r--r--src/lib/ecore_ipc/Ecore_Ipc.h125
-rwxr-xr-x[-rw-r--r--]src/lib/ecore_x/Ecore_X.h828
-rwxr-xr-x[-rw-r--r--]src/lib/ecore_x/Ecore_X_Atoms.h76
-rw-r--r--src/lib/ecore_x/Ecore_X_Cursor.h3
-rw-r--r--src/lib/edje/Edje.h5345
-rw-r--r--src/lib/edje/Edje_Edit.h5141
-rw-r--r--src/lib/eet/Eet.h4600
-rw-r--r--src/lib/efreet/Efreet.h95
-rw-r--r--src/lib/efreet/Efreet_Mime.h83
-rw-r--r--src/lib/efreet/Efreet_Trash.h67
-rw-r--r--src/lib/efreet/efreet_base.h202
-rw-r--r--src/lib/efreet/efreet_desktop.h189
-rw-r--r--src/lib/efreet/efreet_icon.h69
-rw-r--r--src/lib/efreet/efreet_ini.h125
-rw-r--r--src/lib/efreet/efreet_menu.h109
-rw-r--r--src/lib/efreet/efreet_uri.h20
-rw-r--r--src/lib/efreet/efreet_utils.h43
-rw-r--r--src/lib/eina/eina_array.h491
-rw-r--r--src/lib/eina/eina_benchmark.h436
-rw-r--r--src/lib/eina/eina_binbuf.h276
-rw-r--r--src/lib/eina/eina_convert.h253
-rw-r--r--src/lib/eina/eina_cpu.h100
-rw-r--r--src/lib/eina/eina_fp.h451
-rw-r--r--src/lib/eina/eina_hamster.h32
-rw-r--r--src/lib/eina/eina_hash.h1390
-rw-r--r--src/lib/eina/eina_inarray.h626
-rw-r--r--src/lib/eina/eina_inlist.h897
-rw-r--r--src/lib/eina/eina_iterator.h282
-rw-r--r--src/lib/eina/eina_lalloc.h67
-rw-r--r--src/lib/eina/eina_list.h1655
-rw-r--r--src/lib/eina/eina_log.h869
-rw-r--r--src/lib/eina/eina_main.h144
-rw-r--r--src/lib/eina/eina_matrixsparse.h406
-rw-r--r--src/lib/eina/eina_mmap.h69
-rw-r--r--src/lib/eina/eina_model.h281
-rw-r--r--src/lib/eina/eina_module.h412
-rw-r--r--src/lib/eina/eina_quadtree.h4
-rw-r--r--src/lib/eina/eina_rbtree.h203
-rw-r--r--src/lib/eina/eina_rectangle.h535
-rw-r--r--src/lib/eina/eina_refcount.h44
-rw-r--r--src/lib/eina/eina_safety_checks.h35
-rw-r--r--src/lib/eina/eina_sched.h10
-rw-r--r--src/lib/eina/eina_simple_xml_parser.h472
-rw-r--r--src/lib/eina/eina_str.h467
-rw-r--r--src/lib/eina/eina_strbuf.h746
-rw-r--r--src/lib/eina/eina_stringshare.h356
-rw-r--r--src/lib/eina/eina_tiler.h349
-rw-r--r--src/lib/eina/eina_tmpstr.h197
-rw-r--r--src/lib/eina/eina_types.h155
-rw-r--r--src/lib/eina/eina_unicode.h214
-rw-r--r--src/lib/eina/eina_ustrbuf.h504
-rw-r--r--src/lib/eina/eina_ustringshare.h201
-rw-r--r--src/lib/eina/eina_value.h2454
-rw-r--r--src/lib/eina/eina_xattr.h281
-rw-r--r--src/lib/eio/Eio.h678
-rw-r--r--src/lib/embryo/Embryo.h460
-rw-r--r--src/lib/ethumb/Ethumb.h453
-rw-r--r--src/lib/ethumb/Ethumb_Plugin.h6
-rw-r--r--src/lib/ethumb_client/Ethumb_Client.h65
-rwxr-xr-x[-rw-r--r--]src/lib/evas/Evas.h14734
-rwxr-xr-x[-rw-r--r--]src/lib/evas/Evas_GL.h130
-rw-r--r--src/modules/evas/engines/buffer/Evas_Engine_Buffer.h2
-rwxr-xr-x[-rw-r--r--]src/modules/evas/engines/gl_x11/Evas_Engine_GL_X11.h33
-rw-r--r--src/modules/evas/engines/software_x11/Evas_Engine_Software_X11.h7
74 files changed, 38398 insertions, 22459 deletions
diff --git a/src/lib/ecore/Ecore.h b/src/lib/ecore/Ecore.h
index a6ac338cab..efd2bf95f6 100644
--- a/src/lib/ecore/Ecore.h
+++ b/src/lib/ecore/Ecore.h
@@ -1,103 +1,60 @@
1/** 1/**
2 @brief Ecore Library Public API Calls 2 * @defgroup Ecore_Group Ecore
3 3 * @ingroup EFL_Group
4 These routines are used for Ecore Library interaction 4 *
5 */ 5 * @brief Ecore Library Public API Calls
6 6 *
7/** 7 * @remarks These routines are used for Ecore Library interaction.
8 8 *
9 @page ecore_main Ecore 9 * See @ref ecore_main for more details
10 10 *
11 @date 2000 (created) 11 * @page ecore_main Ecore
12 12 *
13 @section toc Table of Contents 13 * @date 2000 (created)
14 14 *
15 @li @ref ecore_main_intro 15 * @section toc Table of Contents
16 @li @ref ecore_main_compiling 16 *
17 @li @ref ecore_main_next_steps 17 * @li @ref ecore_main_intro
18 @li @ref ecore_main_intro_example 18 * @li @ref ecore_main_next_steps
19 19 *
20 @section ecore_main_intro Introduction 20 * @section ecore_main_intro Introduction
21 21 *
22 Ecore is a library of convenience functions. A brief explanation of how to use 22 * Ecore is a library of convenience functions. A brief explanation of how to use
23 it can be found in @ref Ecore_Main_Loop_Page. 23 * it can be found in @ref Ecore_Main_Loop_Page.
24 24 *
25 The Ecore library provides the following modules: 25 * The Ecore library provides the following modules:
26 @li @ref Ecore_Init_Group 26 * @li @ref Ecore_Main_Loop_Group
27 @li @ref Ecore_Getopt_Group 27 * @internal
28 @li @ref Ecore_Main_Loop_Group 28 * @li @ref Ecore_File_Group
29 @li @ref Ecore_System_Events 29 * @li @ref Ecore_Con_Group
30 @li @ref Ecore_Time_Group 30 * @li @ref Ecore_Evas_Group
31 @li @ref Ecore_Thread_Group 31 * @li @ref Ecore_FB_Group
32 @li @ref Ecore_Pipe_Group 32 * @li @ref Ecore_IMF_Group
33 @li @ref Ecore_Application_Group 33 * @li @ref Ecore_IMF_Context_Group
34 @li @ref Ecore_Throttle_Group 34 * @li @ref Ecore_IMF_Evas_Group
35 @li @ref Ecore_Job_Group 35 * @endinternal
36 @li @ref Ecore_File_Group 36 * @li @link Ecore_Ipc.h Ecore_IPC - Inter Process Communication functions. @endlink
37 @li @ref Ecore_Con_Group 37 * @internal
38 @li @ref Ecore_Evas_Group 38 * @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink
39 @li @ref Ecore_FB_Group 39 * @endinternal
40 @li @ref Ecore_Input_Group 40 *
41 @li @ref Ecore_IMF_Lib_Group 41 * @section ecore_main_next_steps Next Steps
42 @li @ref Ecore_IPC_Group 42 *
43 @li @link Ecore_X.h Ecore_X - X Windows System wrapper. @endlink 43 * After you understood what Ecore is and installed it in your system
44 @li @ref Ecore_Win32_Group 44 * you should proceed understanding the programming interface. We'd
45 @li @ref Ecore_Audio_Group 45 * recommend you to take a while to learn @ref Eina_Group as it is very
46 @li @ref Ecore_Avahi_Group 46 * convenient and optimized, and Ecore uses it extensively.
47 @li @ref Ecore_Drm_Group 47 *
48 @li @ref Ecore_Wl_Group 48 * Recommended reading:
49 49 *
50 50 * @li @ref Ecore_Timer_Group
51 51 * @li @ref Ecore_Idle_Group
52 For more info on Ecore usage, there are these @ref ecore_examples. 52 * @li @ref Ecore_FD_Handler_Group
53 53 * @li @ref Ecore_Event_Group
54 @section ecore_main_compiling How to compile 54 * @internal
55 55 * @li @ref Ecore_Exe_Group
56 Ecore is a library your application links to. The procedure for 56 * @endinternal
57 this is very simple. You simply have to compile your application 57 *
58 with the appropriate compiler flags that the @p pkg-config script
59 outputs. Note that each module is separate in pkg-config. For
60 example using @ref Ecore_Evas_Group:
61
62 Compiling C or C++ files into object files:
63
64 @verbatim
65 gcc -c -o main.o main.c `pkg-config --cflags ecore ecore-evas`
66 @endverbatim
67
68 Linking object files into a binary executable:
69
70 @verbatim
71 gcc -o my_application main.o `pkg-config --libs ecore ecore-evas`
72 @endverbatim
73
74 See @ref pkgconfig
75
76 @section ecore_main_next_steps Next Steps
77
78 After you understood what Ecore is and installed it in your system
79 you should proceed understanding the programming interface. We'd
80 recommend you to take a while to learn @ref Eina as it is very
81 convenient and optimized, and Ecore uses it extensively.
82
83 Recommended reading:
84
85 @li @ref Ecore_Timer_Group
86 @li @ref Ecore_Idle_Group
87 @li @ref Ecore_FD_Handler_Group
88 @li @ref Ecore_Event_Group
89 @li @ref Ecore_Exe_Group
90 @li @ref Ecore_Animator_Group
91 @li @ref Ecore_Poller_Group
92
93
94 @section ecore_main_intro_example Introductory Examples
95
96 @include ecore_timer_example.c
97
98 More examples can be found at @ref ecore_examples.
99
100
101 */ 58 */
102 59
103/** 60/**
@@ -106,7 +63,7 @@
106 * @section Ecore_Main_Loop_Page_intro What is Ecore? 63 * @section Ecore_Main_Loop_Page_intro What is Ecore?
107 * 64 *
108 * Ecore is a clean and tiny event loop library with many modules to do lots of 65 * Ecore is a clean and tiny event loop library with many modules to do lots of
109 * convenient things for a programmer, to save time and effort. It's small and 66 * convenient things for a programmer as well as to save time and effort. It's small and
110 * lean, designed to work from embedded systems all the way up to large and 67 * lean, designed to work from embedded systems all the way up to large and
111 * powerful multi-cpu workstations. The main loop has a number of primitives to 68 * powerful multi-cpu workstations. The main loop has a number of primitives to
112 * be used with its main loop. It serializes all the primitives and allows for 69 * be used with its main loop. It serializes all the primitives and allows for
@@ -120,7 +77,7 @@
120 * 77 *
121 * @subsection pollers Pollers 78 * @subsection pollers Pollers
122 * 79 *
123 * Pollers allow for polling to be centralized into a single place therefore 80 * Pollers allow for polling to be centralized into a single place. Therefore,
124 * alleviating the need for different parts of the program to wake up at 81 * alleviating the need for different parts of the program to wake up at
125 * different times to do polling, thereby making the code simpler and more 82 * different times to do polling, thereby making the code simpler and more
126 * efficient. 83 * efficient.
@@ -128,30 +85,30 @@
128 * 85 *
129 * @subsection idler Idlers 86 * @subsection idler Idlers
130 * 87 *
131 * There are three types of idlers, enterers, idlers(proper) and exiters, they 88 * There are three types of idlers: enterers, idlers(proper), and exiters, they
132 * are called, respectively, when the program is about to enter an idle state, 89 * are called respectively when the program is about to enter an idle state,
133 * when the program is idle and when the program is leaving an idle state. Idler 90 * when the program is idle, and when the program is leaving an idle state. Idler
134 * enterers are usually a good place to update the program state. Proper idlers 91 * enterers are usually a good place to update the program state. Proper idlers
135 * are the appropriate place to do heavy computational tasks thereby using what 92 * are the appropriate place to do heavy computational tasks thereby using what
136 * would otherwise be wasted CPU cycles. Exiters are the perfect place to do 93 * would otherwise be wasted CPU cycles. Exiters are the perfect place to do
137 * anything your program should do just before processing events (also timers, 94 * anything that your program should do just before processing events(also timers,
138 * pollers, file descriptor handlers and animators) 95 * poolers, file descriptor handlers, and animators)
139 * @see Ecore_Idle_Group 96 * @see Ecore_Idle_Group
140 * 97 *
141 * @subsection fd_handler File descriptor handlers 98 * @subsection fd_handler File descriptor handlers
142 * 99 *
143 * File descriptor handlers allow you to monitor when there is data available to 100 * File descriptor handlers allow you to monitor when there is data available to
144 * read on file descriptors, when writing will not block or if there was an 101 * read on file descriptors, when writing is not blocked or when there is an
145 * error. Any valid file descriptor can be used with this API, regardless of if 102 * error. Any valid file descriptor can be used with this API, regardless of whether
146 * was gotten with an OS specific API or from ecore. 103 * it is obtained with an OS specific API or from ecore.
147 * @see Ecore_FD_Handler_Group 104 * @see Ecore_FD_Handler_Group
148 * 105 *
149 * @subsection animators Animators 106 * @subsection animators Animators
150 * 107 *
151 * Ecore provides a facility called animators, so named since the intended use 108 * Ecore provides a facility called animators, so named since the intended use
152 * was in animations, that facilitates knowing what percentage of a given 109 * is in animations, that facilitates knowing what percentage of a given
153 * interval has elapsed. This is perfect for performing animations, but is not 110 * interval has elapsed. This is perfect for performing animations, but is not
154 * limited to that use, it can, for example, also be used to create a progress 111 * limited to that use. It can, for example, also be used to create a progress
155 * bar. 112 * bar.
156 * @see Ecore_Animator_Group 113 * @see Ecore_Animator_Group
157 * 114 *
@@ -159,25 +116,23 @@
159 * 116 *
160 * Event handlers are, arguably, the most important feature of the ecore main 117 * Event handlers are, arguably, the most important feature of the ecore main
161 * loop, they are what allows the programmer to easily handle user interaction. 118 * loop, they are what allows the programmer to easily handle user interaction.
162 * Events however are not only things the user does, events can represent 119 * Events, however, are not the only things that the user does. Events can represent
163 * anything for which a type is created. 120 * anything for which a type is created.
164 * @see Ecore_Event_Group 121 * @see Ecore_Event_Group
165 * 122 *
166 * All of these primitives are discussed in more detail in their respective 123 * All of these primitives are discussed in more detail in their respective
167 * pages linked above. 124 * pages that are linked above.
168 * 125 *
169 * Here is a diagram of the main loop flow of a simple program: 126 * Here is a diagram of the main loop flow of a simple program:
170 * 127 *
171 * @image html prog_flow.png 128 * @image html prog_flow.png
172 * @image latex prog_flow.eps width=\textwidth 129 * @image latex prog_flow.eps "prog flow" width=\textwidth
173 *
174 *
175 * 130 *
176 * @section Ecore_Main_Loop_Page_work How does Ecore work? 131 * @section Ecore_Main_Loop_Page_work How does Ecore work?
177 * 132 *
178 * Ecore is very easy to learn and use. All the function calls are designed to 133 * Ecore is very easy to learn and use. All the function calls are designed to
179 * be easy to remember, explicit in describing what they do, and heavily 134 * be easy to remember, explicit in describing what they do, and heavily
180 * name-spaced. Ecore programs can start and be very simple. 135 * name-spaced. Ecore programs can start easily and are very simple.
181 * 136 *
182 * For example: 137 * For example:
183 * 138 *
@@ -196,7 +151,7 @@
196 * @endcode 151 * @endcode
197 * 152 *
198 * This program is very simple and doesn't check for errors, but it does start up 153 * This program is very simple and doesn't check for errors, but it does start up
199 * and begin a main loop waiting for events or timers to tick off. This program 154 * and begin a main loop that is waiting for events or timers to tick off. This program
200 * doesn't set up any, but now we can expand on this simple program a little 155 * doesn't set up any, but now we can expand on this simple program a little
201 * more by adding some event handlers and timers. 156 * more by adding some event handlers and timers.
202 * 157 *
@@ -242,14 +197,14 @@
242 * @endcode 197 * @endcode
243 * 198 *
244 * In the previous example, we initialize our application and get the time at 199 * In the previous example, we initialize our application and get the time at
245 * which our program has started so we can calculate an offset. We set 200 * which our program has started so that we can calculate an offset. We set
246 * up a timer to tick off in 0.5 seconds, and since it returns 1, will 201 * up a timer to tick off in @c 0.5 seconds, and since it returns @c 1, it
247 * keep ticking off every 0.5 seconds until it returns 0, or is deleted 202 * keeps ticking off every @c 0.5 seconds until it returns @c 0, or is deleted
248 * by hand. An event handler is set up to call a function - 203 * by hand. An event handler is set up to call a function -
249 * exit_func(), 204 * exit_func(),
250 * whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C 205 * whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C
251 * on the command line will cause such an event to happen). If this event 206 * on the command line causes such an event to happen). If this event
252 * occurs it tells you what kind of exit signal was received, and asks 207 * occurs it tells you what kind of exit signal is received, and asks
253 * the main loop to quit when it is finished by calling 208 * the main loop to quit when it is finished by calling
254 * ecore_main_loop_quit(). 209 * ecore_main_loop_quit().
255 * 210 *
@@ -257,11 +212,11 @@
257 * ecore_event_handler_add() are 212 * ecore_event_handler_add() are
258 * only stored here as an example. If you don't need to address the timer or 213 * only stored here as an example. If you don't need to address the timer or
259 * event handler again you don't need to store the result, so just call the 214 * event handler again you don't need to store the result, so just call the
260 * function, and don't assign the result to any variable. 215 * function and don't assign the result to any variable.
261 * 216 *
262 * This program looks slightly more complex than needed to do these simple 217 * This program looks slightly more complex than needed to do these simple
263 * things, but in principle, programs don't get any more complex. You add more 218 * things, but in principle, programs don't get any more complex. You add more
264 * event handlers, for more events, will have more timers and such, BUT it all 219 * event handlers for more events, you have more timers, BUT it all
265 * follows the same principles as shown in this example. 220 * follows the same principles as shown in this example.
266 * 221 *
267 */ 222 */
@@ -275,34 +230,19 @@
275 230
276 To use the library, you: 231 To use the library, you:
277 @li Set the default values of your properties. 232 @li Set the default values of your properties.
278 @li Load the configuration from a file. You must set the default values 233 @li Load the configuration from a file. You must set the default values
279 first, so that the library knows the correct type of each argument. 234 first, so that the library knows the correct type of each argument.
280 235
281 The following examples show how to use the Enlightened Property Library:
282 @li @link config_basic_example.c config_basic_example.c @endlink
283 @li @link config_listener_example.c config_listener_example.c @endlink
284
285 */
286
287/**
288 @page X_Window_System_Page X Window System
289
290 The Ecore library includes a wrapper for handling the X window system.
291 This page briefly explains what the X window system is and various terms
292 that are used.
293 */ 236 */
294 237
295#ifndef _ECORE_H 238#ifndef _ECORE_H
296#define _ECORE_H 239#define _ECORE_H
297 240
298#include <Efl_Config.h>
299
300#ifdef _MSC_VER 241#ifdef _MSC_VER
301# include <Evil.h> 242# include <Evil.h>
302#endif 243#endif
303 244
304#include <Eina.h> 245#include <Eina.h>
305#include <Eo.h>
306 246
307#ifdef EAPI 247#ifdef EAPI
308# undef EAPI 248# undef EAPI
@@ -350,13 +290,3172 @@
350extern "C" { 290extern "C" {
351#endif 291#endif
352 292
353#include "Ecore_Common.h" 293/**
354#ifndef EFL_NOLEGACY_API_SUPPORT 294 * @internal
355#include "Ecore_Legacy.h" 295 * @defgroup Ecore_Init_Group Ecore initialization, shutdown functions and reset on fork.
296 * @ingroup Ecore_Group
297 *
298 * @{
299 */
300
301/**
302 * @brief Initialize the Ecore library.
303 *
304 * @details This function sets up connections, sockets, all singal handlers and
305 * the basic event loop, etc. If it succeeds, 1 or greater will be
306 * returned, otherwise 0 will be returned.
307 *
308 * @remarks This function initializes the Ecore library, making the proper calls
309 * to internal initialization functions. It will also initialize its
310 * @b dependencies, making calls to @c eina_init().
311 * So, there is no need to call those functions again, in your code.
312 * To shutdown Ecore, there is the function ecore_shutdown().
313 *
314 * @code
315 * #include <Ecore.h>
316 *
317 * int main(int argc, char **argv)
318 * {
319 * if (!ecore_init())
320 * {
321 * printf("ERROR: Cannot init Ecore!\n");
322 * return -1;
323 * }
324 * ecore_main_loop_begin();
325 * ecore_shutdown();
326 * }
327 * @endcode
328 *
329 * @return 1 or greater on success, 0 otherwise
330 *
331 * @see ecore_shutdown()
332 * @see eina_init()
333 */
334EAPI int ecore_init(void);
335
336/**
337 * @brief Shutdown the Ecore library.
338 *
339 * @details Shut down connections, signal handlers sockets etc.
340 *
341 * @remarks This function shuts down all things set up in ecore_init() and
342 * cleans up all event queues, handlers, filters, timers, idlers,
343 * idle enterers/exiters etc. set up after ecore_init() was called.
344 *
345 * @remarks Do not call this function from any callback that may be called
346 * from the main loop, as the main loop will then fall over and not
347 * function properly.
348 *
349 * @details This function shuts down the Edje library. It will also call the
350 * shutdown functions of its @b dependencies, which is @c
351 * eina_shutdown().
352 * so there is no need to call these functions again in your code.
353 * This returns The number of times the library has been initialised
354 * without being shutdown.
355 *
356 * @return 0 if ecore shuts down, greater than 0 otherwise.
357 *
358 * @see ecore_init()
359 * @see eina_shutdown()
360 */
361EAPI int ecore_shutdown(void);
362
363/**
364 * @}
365 */
366
367/**
368 * @internal
369 * @defgroup Ecore_Application_Group Ecore Application
370 * @ingroup Ecore_Group
371 *
372 * @{
373 */
374
375EAPI void ecore_app_args_set(int argc, const char **argv);
376EAPI void ecore_app_args_get(int *argc, char ***argv);
377EAPI void ecore_app_restart(void);
378
379/**
380 * @}
381 */
382
383/**
384 * @defgroup Ecore_Main_Loop_Group Ecore Main Loop
385 * @ingroup Ecore_Group
386 *
387 * @brief This group discusses functions that are acting on Ecore's main loop itself or
388 * on events and infrastructure directly linked to it. Most programs only need
389 * to start and end the main loop, the rest of the function discussed here is
390 * meant to be used in special situations, and with great care.
391 *
392 * For details on the usage of ecore's main loop and how it interacts with other
393 * ecore facilities see: @ref Ecore_Main_Loop_Page.
394 *
395 * @{
396 */
397
398#define ECORE_VERSION_MAJOR 1
399#define ECORE_VERSION_MINOR 8
400
401typedef struct _Ecore_Version
402{
403 int major;
404 int minor;
405 int micro;
406 int revision;
407} Ecore_Version;
408
409EAPI extern Ecore_Version *ecore_version;
410
411#define ECORE_CALLBACK_CANCEL EINA_FALSE /**< Return value to remove a callback */
412#define ECORE_CALLBACK_RENEW EINA_TRUE /**< Return value to keep a callback */
413
414#define ECORE_CALLBACK_PASS_ON EINA_TRUE /**< Return value to pass an event to the next handler */
415#define ECORE_CALLBACK_DONE EINA_FALSE /**< Return value to stop event handling */
416
417/**
418 * @typedef Ecore_Task_Cb Ecore_Task_Cb
419 * @brief The boolean type for a callback that is run for a task (timer, idler, poller, animator, and so on).
420 */
421typedef Eina_Bool (*Ecore_Task_Cb)(void *data);
422
423/**
424 * @typedef Ecore_Cb Ecore_Cb
425 * @brief Called as a hook when a certain point in the execution is reached.
426 */
427typedef void (*Ecore_Cb)(void *data);
428
429/**
430 * @typedef Ecore_Data_Cb Ecore_Data_Cb
431 * @brief Called to return data to the main function.
432 */
433typedef void *(*Ecore_Data_Cb)(void *data);
434
435/**
436 * @typedef Ecore_Select_Function
437 * @brief The integer type for a function that can be used to replace select() in the main loop.
438 */
439typedef int (*Ecore_Select_Function)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout);
440
441/**
442 * @brief Adds a function to be called by ecore_fork_reset().
443 *
444 * @details This queues @a func to be called (and passes @a data as its argument) when
445 * ecore_fork_reset() is called. This allows other libraries and subsystems
446 * to also reset their internal state after a fork.
447 *
448 * @param[in] func The function to be called
449 * @param[in] data A data pointer to pass to the called function @a func
450 * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE.
451 *
452 * @since 1.7
453 * @since_tizen 2.3
454 */
455EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data);
456
457/**
458 * @brief Removes the specified callback.
459 *
460 * @details This deletes the callback added by ecore_fork_reset_callback_add() using
461 * the function and data pointer to specify which callback to remove.
462 *
463 * @param[in] func The function to be called
464 * @param[in] data A data pointer to pass to the called function @a func
465 * @return #EINA_TRUE if succeed, otherwise #EINA_FALSE.
466 *
467 * @since 1.7
468 * @since_tizen 2.3
469 */
470EAPI Eina_Bool ecore_fork_reset_callback_del(Ecore_Cb func, const void *data);
471
472/**
473 * @brief Resets the ecore's internal state after a fork.
474 *
475 * @since 1.7
476 * @since_tizen 2.3
477 *
478 * @remarks Ecore maintains the internal data that can be affected by the fork() system call,
479 * which creates a duplicate of the current process. This also duplicates
480 * file descriptors, which is problematic as these file descriptors still
481 * point to their original sources. This function makes ecore's reset internal
482 * state (e.g. pipes used for signalling between threads) so they function
483 * correctly afterwards.
484 *
485 * @remarks It is highly suggested that you call this function after any fork()
486 * system call inside the child process. If you intend to use ecore features
487 * after this point and not call exec() family functions. Not doing so
488 * causes a possible misbehaviour.
489 */
490EAPI void ecore_fork_reset(void);
491
492/**
493 * @brief Runs a single iteration of the main loop to process everything on the
494 * queue.
495 *
496 * @details It does everything that is already done inside an @c Ecore main loop,
497 * like checking for expired timers, idlers, etc. But it will do it
498 * only once and return, instead of keep watching for new events.
499 *
500 * @remarks DO NOT use this function unless you are the person God comes to ask
501 * for advice when He has trouble managing the Universe.
502 *
503 * @see ecore_main_loop_iterate_may_block()
504 */
505EAPI void ecore_main_loop_iterate(void);
506
507/**
508 * @brief Sets the function to use when monitoring multiple file descriptors,
509 * and waiting until one of more of the file descriptors before ready
510 * for some class of I/O operation.
511 *
512 * @remarks This function will be used instead of the system call select and
513 * could possible be used to integrate the Ecore event loop with an
514 * external event loop.
515 *
516 * @remarks you don't know how to use, don't even try to use it.
517 *
518 * @param func The function to be used.
519 *
520 * @see ecore_main_loop_select_func_get()
521 */
522EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func);
523
524/**
525 * @brief Gets the select function set by ecore_select_func_set(),
526 * or the native select function if none was set.
527 *
528 * @return The select function
529 *
530 * @see ecore_main_loop_select_func_get()
531 */
532EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void);
533
534/**
535 * @brief Request ecore to integrate GLib's main loop.
536 *
537 * @details This will add a small overhead during every main loop interaction
538 * by checking glib's default main context (used by its main loop). If
539 * it have events to be checked (timers, file descriptors or idlers),
540 * then these will be polled alongside with Ecore's own events, then
541 * dispatched before Ecore's. This is done by calling
542 * ecore_main_loop_select_func_set().
543 *
544 * @remarks This will cooperate with previously set
545 * ecore_main_loop_select_func_set() by calling the old function.
546 * Similarly, if you want to override
547 * ecore_main_loop_select_func_set() after main loop is integrated,
548 * call the new select function set by this call (get it by calling
549 * ecore_main_loop_select_func_get() right after
550 * ecore_main_loop_glib_integrate()).
551 *
552 * @remarks This is useful to use GMainLoop libraries, like GTK, GUPnP,
553 * LibSoup, GConf and more. Adobe Flash plugin and other plugins
554 * systems depend on this as well.
555 *
556 * @remarks Once initialized/integrated, it will be valid until Ecore is
557 * completely shut down.
558 *
559 * Example of use:
560 * @code
561 *
562 * int main(void)
563 * {
564 * ecore_init();
565 * ecore_main_loop_glib_integrate();
566 *
567 * // some code here
568 *
569 * ecore_main_loop_begin();
570 *
571 * ecore_shutdown();
572 *
573 * return 0;
574 * }
575 *
576 * @endcode
577 *
578 * @remarks This is only available if Ecore was compiled with GLib support.
579 * @remarks You don't need to call this function if Ecore was compiled with
580 * --with-glib=always.
581 *
582 * @return #EINA_TRUE on success of @c EINA_FALSE if it failed,
583 * likely no GLib support in Ecore.
584 */
585EAPI Eina_Bool ecore_main_loop_glib_integrate(void);
586
587/**
588 * @brief Disable always integrating glib
589 *
590 * @remarks If ecore is compiled with --with-glib=always (to always call
591 * ecore_main_loop_glib_integrate() when ecore_init() is called),
592 * then calling this before calling ecore_init() will disable the
593 * integration. This is for apps that explicitly do not want this
594 * to happen for whatever reasons they may have.
595 */
596EAPI void ecore_main_loop_glib_always_integrate_disable(void);
597
598/**
599 * @brief Runs the application main loop.
600 *
601 * @details This function will not return until @ref ecore_main_loop_quit is
602 * called. It will check for expired timers, idlers, file descriptors
603 * being watched by fd handlers, etc. Once everything is done, before
604 * entering again on idle state, any callback set as @c Idle_Enterer
605 * will be called.
606 *
607 * @remarks Each main loop iteration is done by calling
608 * ecore_main_loop_iterate() internally.
609 *
610 * @remarks The polling (select) function used can be changed with
611 * ecore_main_loop_select_func_set().
612 *
613 * @remarks The function used to check for file descriptors, events, and that
614 * has a timeout for the timers can be changed using
615 * ecore_main_loop_select_func_set().
616 */
617EAPI void ecore_main_loop_begin(void);
618
619/**
620 * @brief Quits the main loop once all the events currently on the queue have
621 * been processed.
622 *
623 * @details This function returns immediately, but will mark the
624 * ecore_main_loop_begin() function to return at the end of the
625 * current main loop iteration.
626 */
627EAPI void ecore_main_loop_quit(void);
628
629/**
630 * @brief Called asynchronously in the main loop.
631 *
632 * @since 1.1.0
633 *
634 * @remarks For all calls that need to happen in the main loop (most EFL functions do),
635 * this helper function provides the infrastructure needed to do it safely
636 * by avoiding a dead lock, race condition, and by properly waking up the main loop.
637 *
638 * @remarks Remember that after the function call, you should never touch the @a data
639 * in the thread again, it is owned by the main loop and your callback should take
640 * care of freeing it, if necessary.
641 *
642 * @param callback The callback to call in the main loop
643 * @param data The data to give to that call
644 */
645EAPI void ecore_main_loop_thread_safe_call_async(Ecore_Cb callback, void *data);
646
647/**
648 * @brief Called synchronously in the main loop.
649 *
650 * @since 1.1.0
651 *
652 * @remarks For all calls that need to happen in the main loop (most EFL functions do),
653 * this helper function provides the infrastructure needed to do it safely
654 * by avoiding a dead lock, race condition, and by properly waking up the main loop.
655 *
656 * @remarks Remember that this function blocks until the callback is executed in the
657 * main loop. It can take time and you have no guarantee about the timeline.
658 *
659 * @param callback The callback to call in the main loop
660 * @param data The data to give to that call
661 * @return The value returned by the callback in the main loop
662 */
663EAPI void *ecore_main_loop_thread_safe_call_sync(Ecore_Data_Cb callback, void *data);
664
665/**
666 * @brief Suspends the main loop in the know state.
667 *
668 * @details This function suspends the main loop in the know state. This lets you
669 * use any EFL call that you want after it returns. Be careful, the main loop
670 * is blocked until you call ecore_thread_main_loop_end(). This is
671 * the only way to achieve pseudo thread safety.
672 *
673 * @since 1.1.0
674 *
675 * @remarks Notice that till the main loop is blocked, the thread is blocked
676 * and there is no way around that.
677 *
678 * @remarks We still advise you, if possible, to use ecore_main_loop_thread_safe_call_async()
679 * as it does not block the thread or the main loop.
680 *
681 * @return The number of times ecore_thread_main_loop_begin() has been called
682 * in this thread, if the main loop is suspended correctly \n
683 * If not, it returns @c -1.
684 */
685EAPI int ecore_thread_main_loop_begin(void);
686
687/**
688 * @brief Unlocks the main loop.
689 *
690 * @since 1.1.0
691 *
692 * @remarks After a call to ecore_thread_main_loop_begin(), you need to absolutely
693 * call ecore_thread_main_loop_end(), or your application stays frozen.
694 *
695 * @return The number of times ecore_thread_main_loop_end() needs to be called before
696 * the main loop is unlocked again \n
697 * @c -1 is retured if you are trying to unlock
698 * when there aren't enough calls to ecore_thread_main_loop_begin().
699 *
700 */
701EAPI int ecore_thread_main_loop_end(void);
702
703/**
704 * @}
705 */
706
707/**
708 * @defgroup Ecore_Event_Group Ecore Event
709 * @ingroup Ecore_Main_Loop_Group
710 *
711 * @brief Ecore event are a helper to create events are being notified of events.
712 *
713 * Ecore events provide two main features that are of use to those using ecore:
714 * creating events and being notified of events. Those two are usually used
715 * in different contexts, creating events is mainly done by libraries wrapping
716 * some system functionality while being notified of events is mainly a
717 * necessity of applications.
718 *
719 * For a program to be notified of events it's interested in, it needs to have a
720 * function to process the event and to register that function as the callback
721 * to the event, that's all:
722 * @code
723 * ecore_event_handler_add(EVENT_TYPE, _my_event_handler, some_data);
724 * ...
725 * static Eina_Bool
726 * _my_event_handler(void *data, int type, void *event)
727 * {
728 * //Data is some_data
729 * //Event is provided by whoever created the event
730 * //Do really cool stuff with the event
731 * }
732 * @endcode
733 *
734 * One very important thing to note here is the @c EVENT_TYPE. To register a
735 * handler for an event, you must know its type before hand. Ecore provides
736 * the following events that are emitted in response to POSIX
737 * signals(https://en.wikipedia.org/wiki/Signal_%28computing%29):
738 * @li @b ECORE_EVENT_SIGNAL_USER
739 * @li @b ECORE_EVENT_SIGNAL_HUP
740 * @li @b ECORE_EVENT_SIGNAL_POWER
741 * @li @b ECORE_EVENT_SIGNAL_EXIT
742 *
743 * Don't override these using the @c signal or @c sigaction calls.
744 * These, however, aren't the only signals one can handle. Many
745 * libraries(including ecore modules) have their own signals that can be
746 * listened to and handled. To do that one only needs to know the type of the
747 * event. This information can be found on the documentation of the library
748 * emitting the signal.
749 * @internal
750 * So, for example, for events related to windowing one
751 * would use @ref Ecore_Evas_Group.
752 *
753 * Examples of libraries that integrate into ecore's main loop by providing
754 * events are @ref Ecore_Con_Group, @ref Ecore_Evas_Group, and @ref
755 * Ecore_Exe_Group, amongst others.
756 * @endinternal
757 *
758 * This usage can be divided into two parts,
759 * setup and adding events. The setup is very simple, all that needs to be done is
760 * getting a type ID for the event:
761 * @code
762 * int MY_EV_TYPE = ecore_event_type_new();
763 * @endcode
764 * This variable should be declared in the header since it is needed by
765 * anyone wishing to register a handler to your event.
766 *
767 * The complexity of adding an event to the queue depends on whether that
768 * event sends or uses @a event, if it doesn't it is a one-liner:
769 * @code
770 * ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL);
771 * @endcode
772 * The usage when an @c event is needed is not that complex and can be
773 * seen in @ref ecore_event_add.
774 *
775 * @{
776 */
777
778#define ECORE_EVENT_NONE 0
779#define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */
780#define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */
781#define ECORE_EVENT_SIGNAL_EXIT 3 /**< Exit signal event */
782#define ECORE_EVENT_SIGNAL_POWER 4 /**< Power signal event */
783#define ECORE_EVENT_SIGNAL_REALTIME 5 /**< Realtime signal event */
784#define ECORE_EVENT_COUNT 6
785
786typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< @internal @brief A handle for HANDLE handlers on Windows */
787typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< @brief A handle for an event handler */
788typedef struct _Ecore_Event_Filter Ecore_Event_Filter; /**< @brief A handle for an event filter */
789typedef struct _Ecore_Event Ecore_Event; /**< @brief A handle for an event */
790typedef struct _Ecore_Event_Signal_User Ecore_Event_Signal_User; /**< @brief User signal event */
791typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup; /**< @brief Hup signal event */
792typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit; /**< @brief Exit signal event */
793typedef struct _Ecore_Event_Signal_Power Ecore_Event_Signal_Power; /**< @brief Power signal event */
794typedef struct _Ecore_Event_Signal_Realtime Ecore_Event_Signal_Realtime; /**< @brief Realtime signal event */
795
796/**
797 * @typedef Ecore_Filter_Cb
798 * @brief The boolean type for a callback used for filtering events from the main loop.
799 */
800typedef Eina_Bool (*Ecore_Filter_Cb)(void *data, void *loop_data, int type, void *event);
801
802/**
803 * @typedef Ecore_End_Cb Ecore_End_Cb
804 * @brief Called at the end of a function, usually for cleanup purposes.
805 */
806typedef void (*Ecore_End_Cb)(void *user_data, void *func_data);
807
808/**
809 * @typedef Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb
810 * @brief The boolean type used by the main loop to handle events of a specified type.
811 */
812typedef Eina_Bool (*Ecore_Event_Handler_Cb)(void *data, int type, void *event);
813
814struct _Ecore_Event_Signal_User /** User signal event */
815{
816 int number; /**< The signal number. Either 1 or 2 */
817 void *ext_data; /**< Extension data - not used */
818
819#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
820 siginfo_t data; /**< Signal info */
821#endif
822};
823
824struct _Ecore_Event_Signal_Hup /** Hup signal event */
825{
826 void *ext_data; /**< Extension data - not used */
827
828#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
829 siginfo_t data; /**< Signal info */
830#endif
831};
832
833struct _Ecore_Event_Signal_Exit /** Exit request event */
834{
835 Eina_Bool interrupt : 1; /**< Set if the exit request is an interrupt signal*/
836 Eina_Bool quit : 1; /**< Set if the exit request is a quit signal */
837 Eina_Bool terminate : 1; /**< Set if the exit request is a terminate signal */
838 void *ext_data; /**< Extension data - not used */
839
840#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
841 siginfo_t data; /**< Signal info */
356#endif 842#endif
357#ifdef EFL_EO_API_SUPPORT 843};
358#include "Ecore_Eo.h" 844
845struct _Ecore_Event_Signal_Power /** Power event */
846{
847 void *ext_data; /**< Extension data - not used */
848
849#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
850 siginfo_t data; /**< Signal info */
851#endif
852};
853
854struct _Ecore_Event_Signal_Realtime /** Realtime event */
855{
856 int num; /**< The realtime signal's number */
857
858#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
859 siginfo_t data; /**< Signal info */
860#endif
861};
862
863/**
864 * @brief Adds an event handler.
865 *
866 * @details This adds an event handler to the list of handlers. This, on success, returns
867 * a handle to the event handler object that is created, that can be used
868 * later to remove the handler using ecore_event_handler_del(). The @a type
869 * parameter is the integer of the event type that triggers this callback
870 * to be called. The callback @a func is called when this event is processed
871 * and is passed the event type, a pointer to the private event
872 * structure that is specific to that event type, and a data pointer that is
873 * provided in this call as the @a data parameter.
874 *
875 * @since_tizen 2.3
876 *
877 * @remarks When the callback @a func is called, it must return @c 1 or @c 0. If it returns
878 * @c 1 (or @c ECORE_CALLBACK_PASS_ON), it keeps being called as per normal, for
879 * each handler set up for that event type. If it returns @c 0 (or
880 * @c ECORE_CALLBACK_DONE), it ceases processing handlers for that particular
881 * event, so all handlers set to handle that event type that have not already
882 * been called, are not called.
883 *
884 * @param[in] type The type of the event that this handler gets called for
885 * @param[in] func The function to call when the event is found in the queue
886 * @param[in] data A data pointer to pass to the called function @a func
887 * @return A new Event handler,
888 * otherwise @c NULL on failure
889 */
890EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data);
891
892/**
893 * @brief Deletes an event handler.
894 *
895 * @details This deletes a specified event handler from the handler list. On success, this
896 * deletes the event handler and returns the pointer passed as @a data when the
897 * handler is added by ecore_event_handler_add(). On failure, @c NULL is
898 * returned. Once a handler is deleted it is no longer called.
899 *
900 * @since_tizen 2.3
901 *
902 * @param[in] event_handler The event handler handle to delete
903 * @return The data passed to the handler
904 */
905EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler);
906
907/**
908 * @brief Adds an event to the event queue.
909 *
910 * @remarks If it succeeds, an event of type @a type is added to the queue for
911 * processing by event handlers added by ecore_event_handler_add(). The @a ev
912 * parameter is passed as the @a event parameter of the handler. When the
913 * event is no longer needed, @a func_free is called and it passes @a ev for
914 * cleaning up. If @a func_free is @c NULL, free() is called with the private
915 * structure pointer.
916 *
917 * @since_tizen 2.3
918 *
919 * @param[in] type The event type to add to the end of the event queue
920 * @param[in] ev The data structure passed as @a event to event handlers
921 * @param[in] func_free The function to be called to free @a ev
922 * @param[in] data The data pointer to be passed to the free function
923 * @return A Handle for that event on success,
924 * otherwise @c NULL on failure
925 */
926EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data);
927
928/**
929 * @brief Deletes an event from the queue.
930 *
931 * @details This deletes the event @a event from the event queue, and returns the
932 * @a data parameter originally set when adding it using ecore_event_add(). This
933 * does not immediately call the free function, and it may be called later for
934 * cleanup, and so if the free function depends on the data pointer to work,
935 * you should defer cleaning of this till the free function is called later.
936 *
937 * @since_tizen 2.3
938 *
939 * @param[in] event The event handle to delete
940 * @return The data pointer originally set for the event free function
941 */
942EAPI void *ecore_event_del(Ecore_Event *event);
943
944/**
945 * @brief Gets the data associated with an #Ecore_Event_Handler.
946 *
947 * @details This function returns the data previously associated with @a eh by
948 * ecore_event_handler_add().
949 *
950 * @since_tizen 2.3
951 *
952 * @param[in] eh The event handler
953 * @return The data
954 */
955EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh);
956
957/**
958 * @brief Sets the data associated with an #Ecore_Event_Handler.
959 *
960 * @details This function sets @a data to @a eh and returns the old data pointer
961 * that had been previously associated with @a eh by ecore_event_handler_add().
962 *
963 * @since_tizen 2.3
964 *
965 * @param[in] eh The event handler
966 * @param[in] data The data to associate
967 * @return The previous data
968 */
969EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data);
970
971/**
972 * @brief Allocates a new event type ID sensibly and returns the new ID.
973 *
974 * @details This function allocates a new event type ID and returns it. Once an event
975 * type has been allocated it can never be de-allocated during the life of
976 * the program. There is no guarantee of the contents of this event ID, or how
977 * it is calculated, except that the ID is unique to the current instance
978 * of the process.
979 *
980 * @since_tizen 2.3
981 *
982 * @return A new event type ID
983 *
984 */
985EAPI int ecore_event_type_new(void);
986
987/**
988 * @brief Adds a filter to the current event queue.
989 *
990 * @details This adds a callback to filter events from the event queue. Filters are called on
991 * the queue just before Event handler processing to try and remove redundant
992 * events. Just when processing is about to start @a func_start is called and
993 * passed the @a data pointer. The return value of this function is passed to
994 * @a func_filter as loop_data. @a func_filter is also passed @a data, the
995 * event type, and the event structure. If this @a func_filter returns
996 * @c EINA_FALSE, the event is removed from the queue. If it returns
997 * #EINA_TRUE, the event is kept. When processing is finished @a func_end is
998 * called and is passed the loop_data(returned by @a func_start) and @a data
999 * pointer to clean up.
1000 *
1001 * @since_tizen 2.3
1002 *
1003 * @param[in] func_start The function to call just before filtering and returning data
1004 * @param[in] func_filter The function to call on each event
1005 * @param[in] func_end The function to call after the queue has been filtered
1006 * @param[in] data The data to pass to the filter functions
1007 * @return A filter handle on success,
1008 * otherwise @c NULL on failure
1009 *
1010 */
1011EAPI 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);
1012
1013/**
1014 * @brief Deletes an event filter.
1015 *
1016 * @details This deletes a filter that has been added by its @a ef handle.
1017 *
1018 * @since_tizen 2.3
1019 *
1020 * @param[in] ef The event filter handle
1021 * @return The data set for the filter on success,
1022 * otherwise @c NULL
1023 */
1024EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef);
1025
1026/**
1027 * @brief Returns the current event type being handled.
1028 *
1029 * @since_tizen 2.3
1030 *
1031 * @remarks If the program is currently inside an Ecore event handler callback this
1032 * returns the type of the current event being processed.
1033 *
1034 * This is useful when certain Ecore modules such as Ecore_Evas "swallow"
1035 * events and not all the original information is passed on. In special cases,
1036 * this extra information may be useful or needed and using this call can let
1037 * the program know if the event type being handled is the one about which it wants to get more
1038 * information.
1039 *
1040 * @return The current event type being handled if inside a handler callback,
1041 * otherwise @c ECORE_EVENT_NONE
1042 */
1043EAPI int ecore_event_current_type_get(void);
1044/**
1045 * @brief Returns the current event type pointer handled.
1046 *
1047 * @since_tizen 2.3
1048 *
1049 * @remarks If the program is currently inside an Ecore event handler callback this
1050 * returns the pointer of the current event being processed.
1051 *
1052 * @remarks This is useful when certain Ecore modules such as Ecore_Evas "swallow"
1053 * events and not all the original information is passed on. In special cases,
1054 * this extra information may be useful or needed and using this call can let
1055 * the program access the event data if the type of the event is handled by
1056 * the program.
1057 *
1058 * @return The current event pointer being handled if inside a handler callback,
1059 * otherwise @c NULL
1060 */
1061EAPI void *ecore_event_current_event_get(void);
1062
1063/**
1064 * @}
1065 */
1066
1067/**
1068 * @internal
1069 * @defgroup Ecore_Exe_Group Process Spawning
1070 * @ingroup Ecore_Main_Loop_Group
1071 *
1072 * This module is responsible for managing portable processes using Ecore.
1073 * With this module you're able to spawn processes and you can also pause and
1074 * quit your spawned processes.
1075 * An interaction between your process and those spawned is possible
1076 * using pipes or signals.
1077 *
1078 * @{
1079 */
1080
1081/** Inherit priority from the parent process */
1082#define ECORE_EXE_PRIORITY_INHERIT 9999
1083
1084EAPI extern int ECORE_EXE_EVENT_ADD; /**< @brief A child process has been added */
1085EAPI extern int ECORE_EXE_EVENT_DEL; /**< @brief A child process has been deleted (it exited, naming is consistent with the rest of ecore) */
1086EAPI extern int ECORE_EXE_EVENT_DATA; /**< @brief Data from a child process */
1087EAPI extern int ECORE_EXE_EVENT_ERROR; /**< @brief Errors from a child process */
1088
1089/**
1090 * @internal
1091 * @enum _Ecore_Exe_Flags
1092 * @brief Enumeration that defines the flags for executing a child with its stdin and/or stdout piped back.
1093 */
1094enum _Ecore_Exe_Flags /* Flags for executing a child with its stdin and/or stdout piped back */
1095{
1096 ECORE_EXE_NONE = 0, /**< No exe flags at all */
1097 ECORE_EXE_PIPE_READ = 1, /**< Exe Pipe Read mask */
1098 ECORE_EXE_PIPE_WRITE = 2, /**< Exe Pipe Write mask */
1099 ECORE_EXE_PIPE_ERROR = 4, /**< Exe Pipe error mask */
1100 ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8, /**< Reads are buffered till a new line and 1 line is split per Ecore_Exe_Event_Data_Line */
1101 ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16, /**< Errors are buffered till a new line and 1 line is split per Ecore_Exe_Event_Data_Line */
1102 ECORE_EXE_PIPE_AUTO = 32, /**< stdout and stderr are buffered automatically */
1103 ECORE_EXE_RESPAWN = 64, /**< FIXME: Exe is restarted if it dies */
1104 ECORE_EXE_USE_SH = 128, /**< Use /bin/sh to run the command */
1105 ECORE_EXE_NOT_LEADER = 256, /**< Do not use setsid() to make the executed process its own session leader */
1106 ECORE_EXE_TERM_WITH_PARENT = 512 /**< Makes a child receive SIGTERM when the parent dies */
1107};
1108typedef enum _Ecore_Exe_Flags Ecore_Exe_Flags;
1109
1110/**
1111 * @internal
1112 * @enum _Ecore_Exe_Win32_Priority
1113 * @brief Enumeration that defines the priority of the proccess.
1114 */
1115enum _Ecore_Exe_Win32_Priority
1116{
1117 ECORE_EXE_WIN32_PRIORITY_IDLE, /**< Idle priority, for monitoring the system */
1118 ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL, /**< Below default priority */
1119 ECORE_EXE_WIN32_PRIORITY_NORMAL, /**< Default priority */
1120 ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL, /**< Above default priority */
1121 ECORE_EXE_WIN32_PRIORITY_HIGH, /**< High priority, use with care as other threads in the system do not get processor time */
1122 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 */
1123};
1124typedef enum _Ecore_Exe_Win32_Priority Ecore_Exe_Win32_Priority;
1125
1126typedef struct _Ecore_Exe Ecore_Exe; /**< @brief A handle for spawned processes */
1127
1128/**
1129 * @typedef Ecore_Exe_Cb Ecore_Exe_Cb
1130 * @brief Called to run with the associated @ref Ecore_Exe, usually
1131 * for cleanup purposes.
1132 */
1133typedef void (*Ecore_Exe_Cb)(void *data, const Ecore_Exe *exe);
1134
1135typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add; /**< @brief Spawned Exe add event */
1136typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< @brief Spawned Exe exit event */
1137typedef struct _Ecore_Exe_Event_Data_Line Ecore_Exe_Event_Data_Line; /**< @brief Lines from a child process */
1138typedef struct _Ecore_Exe_Event_Data Ecore_Exe_Event_Data; /**< @brief Data from a child process */
1139
1140/**
1141* @internal
1142* @brief Structure of Ecore Exe Event Add
1143*/
1144struct _Ecore_Exe_Event_Add /** Process add event */
1145{
1146 Ecore_Exe *exe; /**< The handle to the added process */
1147 void *ext_data; /**< Extension data - not used */
1148};
1149
1150struct _Ecore_Exe_Event_Del /** Process exit event */
1151{
1152 pid_t pid; /**< The process ID of the process that exited */
1153 int exit_code; /**< The exit code of the process */
1154 Ecore_Exe *exe; /**< The handle to the exited process, otherwise @c NULL if not found */
1155 int exit_signal; /** < The signal that caused the process to exit */
1156 Eina_Bool exited : 1; /** < Set to @c 1 if the process exited on its own */
1157 Eina_Bool signalled : 1; /** < Set to @c 1 if the process exited due to an uncaught signal */
1158 void *ext_data; /**< Extension data - not used */
1159#if !defined (_WIN32) && !defined (__lv2ppu__) && !defined (EXOTIC_NO_SIGNAL)
1160 siginfo_t data; /**< Signal info */
1161#endif
1162};
1163
1164struct _Ecore_Exe_Event_Data_Line /**< Lines from a child process */
1165{
1166 char *line; /**< The bytes of a line of buffered data */
1167 int size; /**< The size of the line buffer in bytes */
1168};
1169
1170struct _Ecore_Exe_Event_Data /** Data from a child process event */
1171{
1172 Ecore_Exe *exe; /**< The handle to the process */
1173 void *data; /**< The raw binary data from the child process that is received */
1174 int size; /**< The size of this data in bytes */
1175 Ecore_Exe_Event_Data_Line *lines; /**< An array of line data if line buffered, the last one has its line member set to @c NULL */
1176};
1177
1178EAPI void ecore_exe_run_priority_set(int pri);
1179EAPI int ecore_exe_run_priority_get(void);
1180EAPI Ecore_Exe *ecore_exe_run(const char *exe_cmd, const void *data);
1181EAPI Ecore_Exe *ecore_exe_pipe_run(const char *exe_cmd, Ecore_Exe_Flags flags, const void *data);
1182EAPI void ecore_exe_callback_pre_free_set(Ecore_Exe *exe, Ecore_Exe_Cb func);
1183EAPI Eina_Bool ecore_exe_send(Ecore_Exe *exe, const void *data, int size);
1184EAPI void ecore_exe_close_stdin(Ecore_Exe *exe);
1185EAPI void ecore_exe_auto_limits_set(Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines);
1186EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Flags flags);
1187EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data);
1188EAPI void *ecore_exe_free(Ecore_Exe *exe);
1189EAPI pid_t ecore_exe_pid_get(const Ecore_Exe *exe);
1190EAPI void ecore_exe_tag_set(Ecore_Exe *exe, const char *tag);
1191EAPI const char *ecore_exe_tag_get(const Ecore_Exe *exe);
1192EAPI const char *ecore_exe_cmd_get(const Ecore_Exe *exe);
1193EAPI void *ecore_exe_data_get(const Ecore_Exe *exe);
1194EAPI void *ecore_exe_data_set(Ecore_Exe *exe, void *data);
1195EAPI Ecore_Exe_Flags ecore_exe_flags_get(const Ecore_Exe *exe);
1196EAPI void ecore_exe_pause(Ecore_Exe *exe);
1197EAPI void ecore_exe_continue(Ecore_Exe *exe);
1198EAPI void ecore_exe_interrupt(Ecore_Exe *exe);
1199EAPI void ecore_exe_quit(Ecore_Exe *exe);
1200EAPI void ecore_exe_terminate(Ecore_Exe *exe);
1201EAPI void ecore_exe_kill(Ecore_Exe *exe);
1202EAPI void ecore_exe_signal(Ecore_Exe *exe, int num);
1203EAPI void ecore_exe_hup(Ecore_Exe *exe);
1204
1205/**
1206 * @}
1207 */
1208
1209/**
1210 * @defgroup Ecore_FD_Handler_Group Ecore File Descriptor Handling
1211 * @ingroup Ecore_Main_Loop_Group
1212 *
1213 * @brief This group discusses functions that deal with file descriptor handlers.
1214 *
1215 * File descriptor handlers facilitate reading, writing, and checking for errors
1216 * without blocking the program or doing expensive pooling. This can be used to
1217 * monitor a socket, pipe, or some other stream for which an FD can be present.
1218 *
1219 * File descriptor handlers can't be used to monitor file creation,
1220 * modification, or deletion,
1221 * @internal
1222 * see @ref Ecore_File_Group for this.
1223 * @endinternal
1224 *
1225 * One common FD to be monitored is the standard input(stdin), monitoring it for
1226 * reading requires a single call:
1227 * @code
1228 * static Eina_Bool
1229 * _my_cb_func(void *data, Ecore_Fd_Handler *handler)
1230 * {
1231 * char c;
1232 * scanf("%c", &c); //Guaranteed not to block
1233 * ... do stuff with c ...
1234 * }
1235 * ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL);
1236 * @endcode
1237 *
1238 * When using a socket, pipe, or some other stream it's important to remember that
1239 * errors may occur and we must monitor not only for reading/writing, but also
1240 * for errors using the @ref ECORE_FD_ERROR flag.
1241 *
1242 * @{
1243 */
1244
1245/**
1246 * @brief typedef to struct _Ecore_Fd_Handler
1247 */
1248typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler; /**< A handle for FD handlers */
1249
1250/**
1251 * @enum _Ecore_Fd_Handler_Flags
1252 * @brief Enumeration that defines the handler flags to monitor the file descriptor for: reading, writing, or error.
1253 */
1254enum _Ecore_Fd_Handler_Flags
1255{
1256 ECORE_FD_READ = 1, /**< FD Read mask */
1257 ECORE_FD_WRITE = 2, /**< FD Write mask */
1258 ECORE_FD_ERROR = 4 /**< FD Error mask */
1259};
1260
1261/**
1262 * @brief typedef to enum _Ecore_Fd_Handler_Flags
1263 */
1264typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags;
1265
1266/**
1267 * @typedef Ecore_Fd_Cb Ecore_Fd_Cb
1268 * @brief The boolean type for a callback used by an @ref Ecore_Fd_Handler.
1269 */
1270typedef Eina_Bool (*Ecore_Fd_Cb)(void *data, Ecore_Fd_Handler *fd_handler);
1271
1272/**
1273 * @typedef Ecore_Fd_Prep_Cb Ecore_Fd_Prep_Cb
1274 * @brief Called to be used by an @ref Ecore_Fd_Handler.
1275 */
1276typedef void (*Ecore_Fd_Prep_Cb)(void *data, Ecore_Fd_Handler *fd_handler);
1277
1278/**
1279 * @internal
1280 * @typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb
1281 * @brief The boolean type for a callback used by an @ref Ecore_Win32_Handler.
1282 */
1283typedef Eina_Bool (*Ecore_Win32_Handle_Cb)(void *data, Ecore_Win32_Handler *wh);
1284
1285/**
1286 * @brief Adds a callback for activity on the given file descriptor.
1287 *
1288 * @since_tizen 2.3
1289 *
1290 * @remarks @a func is called during the execution of @ref Ecore_Main_Loop_Page
1291 * when the file descriptor is available for reading, writing, or there has been
1292 * an error(depending on the given @a flags).
1293 *
1294 * @remarks When @a func returns @c ECORE_CALLBACK_CANCEL, it indicates that the
1295 * handler should be marked for deletion (identical to calling @ref
1296 * ecore_main_fd_handler_del).
1297 *
1298 * @remarks @a buf_func is meant for @b internal use only and should be @b
1299 * avoided.
1300 *
1301 * @remarks The return value of @a buf_func has a different meaning, when it returns
1302 * @c ECORE_CALLBACK_CANCEL, it indicates that @a func @b shouldn't be called, and
1303 * when it returns @c ECORE_CALLBACK_RENEW it indicates @a func should be called.
1304 * The return value of @a buf_func does not cause the FD handler to get deleted.
1305 *
1306 * @remarks @a buf_func is called during event loop handling to check if data that has
1307 * been read from the file descriptor is in a buffer and is available to read.
1308 * Some systems, notably xlib, handle their own buffering, and would otherwise
1309 * not work with select(). These systems should use a @a buf_func. This is the
1310 * most annoying hack, only ecore_x uses it, so refer to that for an example.
1311 *
1312 * @remarks This function should @b not be used for monitoring "normal" files, like text files.
1313 *
1314 * @param[in] fd The file descriptor to watch
1315 * @param[in] flags The flags to monitor it, for reading use @c ECORE_FD_READ, for writing use @c
1316 * ECORE_FD_WRITE, and for error use @c ECORE_FD_ERROR \n
1317 * Values by |(ored).
1318 * @param[in] func The callback function
1319 * @param[in] data The data to pass to the callback
1320 * @param[in] buf_func The function to call to check if any data has been buffered
1321 * and already read from the fd \n
1322 * May be @c NULL.
1323 * @param[in] buf_data The data to pass to the @a buf_func function
1324 * @return An fd handler handle on success,
1325 * otherwise @c NULL on failure
1326 *
1327 */
1328EAPI 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);
1329
1330/**
1331 * @brief Adds a callback for activity on the given file descriptor.
1332 *
1333 * @since 1.7
1334 *
1335 * @since_tizen 2.3
1336 *
1337 * @remarks This function is identical to ecore_main_fd_handler_add, except that it supports regular files.
1338 *
1339 * @remarks This function should ONLY be called with @c ECORE_FD_ERROR, otherwise it calls the fd
1340 * handler constantly.
1341 * @remarks Do not use this function unless you know what you are doing.
1342 *
1343 * @param[in] fd The file descriptor to watch
1344 * @param[in] flags The flags to monitor it, for reading use @c ECORE_FD_READ, for writing use @c
1345 * ECORE_FD_WRITE, and for error use @c ECORE_FD_ERROR \n
1346 * Values by |(ored).
1347 * @param[in] func The callback function
1348 * @param[in] data The data to pass to the callback
1349 * @param[in] buf_func The function to call to check if any data has been buffered
1350 * and already read from the fd \n
1351 * May be @c NULL.
1352 * @param[in] buf_data The data to pass to the @a buf_func function.
1353 * @return An fd handler handle on success,
1354 * otherwise @c NULL on failure
1355 */
1356EAPI Ecore_Fd_Handler *ecore_main_fd_handler_file_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data);
1357
1358/**
1359 * @brief Sets the prepare callback with data for a given #Ecore_Fd_Handler.
1360 *
1361 * @since_tizen 2.3
1362 *
1363 * @remarks This function is called prior to any fd handler's callback function
1364 * (even the other fd handlers), before entering the main loop select function.
1365 *
1366 * @remarks Once a prepare callback is set for an fd handler, it cannot be changed.
1367 * You need to delete the fd handler and create a new one, to set another
1368 * callback.
1369 *
1370 * @remarks You probably don't need this function. It is only necessary for very
1371 * uncommon cases that need special behavior.
1372 *
1373 * @param[in] fd_handler The fd handler
1374 * @param[in] func The prep function
1375 * @param[in] data The data to pass to the prep function
1376 */
1377EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data);
1378
1379/**
1380 * @brief Marks an FD handler for deletion.
1381 *
1382 * @since_tizen 2.3
1383 *
1384 * @details This function marks an fd handler to be deleted during an iteration of the
1385 * main loop. It does NOT close the associated fd.
1386 *
1387 * @remarks If the underlying fd is already closed ecore may complain if the
1388 * main loop is using epoll internally, and also in some rare cases this may
1389 * cause crashes and instability. Remember to delete your fd handlers before the
1390 * fds they listen to are closed.
1391 *
1392 * @param[in] fd_handler The fd handler
1393 * @return The data pointer set using @ref ecore_main_fd_handler_add, for
1394 * @a fd_handler on success,
1395 * otherwise @c NULL on failure
1396 */
1397EAPI void *ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler);
1398
1399/**
1400 * @brief Retrieves the file descriptor that the given handler is handling.
1401 *
1402 * @since_tizen 2.3
1403 *
1404 * @param[in] fd_handler The given fd handler
1405 * @return The file descriptor that the handler is watching
1406 */
1407EAPI int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler);
1408
1409/**
1410 * @brief Gets which flags are active on an FD handler.
1411 *
1412 * @since_tizen 2.3
1413 *
1414 * @param[in] fd_handler The given fd handler
1415 * @param[in] flags The flags, @c ECORE_FD_READ, @c ECORE_FD_WRITE, or
1416 * @c ECORE_FD_ERROR to query
1417 * @return #EINA_TRUE if any of the given flags are active,
1418 * otherwise @c EINA_FALSE
1419 */
1420EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags);
1421
1422/**
1423 * @brief Sets what active streams the given FD handler should be monitoring.
1424 *
1425 * @since_tizen 2.3
1426 *
1427 * @param[in] fd_handler The given fd handler
1428 * @param[in] flags The flags to be watching
1429 */
1430EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags);
1431
1432/**
1433 * @internal
1434 */
1435EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data);
1436
1437/**
1438 * @internal
1439 */
1440EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler);
1441
1442/**
1443 * @}
1444 */
1445
1446/**
1447 * @defgroup Ecore_Time_Group Ecore Time
1448 * @ingroup Ecore_Main_Loop_Group
1449 *
1450 * @brief This group discusses the functions to retrieve time in a given format.
1451 *
1452 * @{
1453 */
1454
1455/**
1456 * @brief Retrieves the current system time as a floating point value in seconds.
1457 *
1458 * @details This uses a monotonic clock and thus never goes back in time while
1459 * machine is live (even if user changes time or timezone changes,
1460 * however it may be reset whenever the machine is restarted).
1461 *
1462 * @since_tizen 2.3
1463 *
1464 * @return The number of seconds. Start time is not defined (it may be
1465 * when the machine was booted, unix time, etc), all it is
1466 * defined is that it never goes backwards (unless you got big critical
1467 * messages when the application started).
1468 *
1469 * @see ecore_loop_time_get().
1470 * @see ecore_time_unix_get().
1471 */
1472EAPI double ecore_time_get(void);
1473
1474/**
1475 * @brief Retrieves the current UNIX time as a floating point value in seconds.
1476 *
1477 * @since_tizen 2.3
1478 *
1479 * @return The number of seconds since 12.00AM 1st January 1970.
1480 *
1481 * @see ecore_time_get().
1482 * @see ecore_loop_time_get().
1483 */
1484EAPI double ecore_time_unix_get(void);
1485
1486/**
1487 * @brief Retrieves the time at which the last loop stopped waiting for
1488 * timeouts or events.
1489 *
1490 * @since_tizen 2.3
1491 *
1492 * @remarks This gets the time that the main loop ceased waiting for timouts
1493 * and/or events to come in or for signals or any other interrupt
1494 * source. This should be considered a reference point for all time
1495 * based activity that should calculate its timepoint from the return
1496 * of ecore_loop_time_get(). Use this UNLESS you absolutely must get
1497 * the current actual timepoint - then use ecore_time_get().
1498 * Note that this time is meant to be used as relative to other times
1499 * obtained on this run. If you need absolute time references, use
1500 * ecore_time_unix_get() instead.
1501 *
1502 * @remarks This function can be called before any loop has ever been run, but
1503 * either ecore_init() or ecore_time_get() must have been called once.
1504 *
1505 * @return The number of seconds. Start time is not defined (it may be
1506 * when the machine was booted, unix time, etc), all it is
1507 * defined is that it never goes backwards (unless you got big critical
1508 * messages when the application started).
1509 */
1510EAPI double ecore_loop_time_get(void);
1511
1512/**
1513 * @}
1514 */
1515
1516/**
1517 * @defgroup Ecore_Thread_Group Ecore Thread
1518 * @ingroup Ecore_Main_Loop_Group
1519 *
1520 * @brief Facilities to run heavy tasks in different threads to avoid blocking
1521 * the main loop.
1522 *
1523 * The EFL is, for the most part, not thread safe. This means that if you
1524 * have some task running in another thread and you have, for example, an
1525 * Evas object to show the status progress of this task, you cannot update
1526 * the object from within the thread. This can only be done from the main
1527 * thread, the one running the main loop. This problem can be solved
1528 * by running a thread that sends messages to the main one using an
1529 * @ref Ecore_Pipe_Group "Ecore_Pipe", but when you need to handle other
1530 * things like cancelling the thread, your code grows in complexity and gets
1531 * much harder to maintain.
1532 *
1533 * Ecore Thread is here to solve that problem. It is not a simple wrapper
1534 * around standard POSIX threads (or an equivalent in other systems) and
1535 * it's not meant to be used to run parallel tasks throughout the entire
1536 * duration of the program, especially when these tasks are performance
1537 * critical, as Ecore manages these tasks using a pool of threads based on
1538 * system configuration.
1539 *
1540 * What Ecore Thread does is it makes it a lot easier to dispatch a worker
1541 * function to perform some heavy tasks and then get the result once it
1542 * completes, without blocking the application's UI. In addition, cancelling
1543 * and rescheduling comes practically for free and the developer need not
1544 * worry about how many threads are launched, since Ecore schedules
1545 * them according to the number of processors the system has and the maximum
1546 * amount of concurrent threads set for the application.
1547 *
1548 * At the system level, Ecore starts a new thread on an as-needed basis
1549 * until the maximum set is reached. When no more threads can be launched,
1550 * new worker functions are queued in a waiting list until a thread
1551 * becomes available. This way, system threads are shared throughout
1552 * different worker functions, but running only one at a time. At the same
1553 * time, a worker function that is rescheduled may be run on a different
1554 * thread the next time.
1555 *
1556 * The ::Ecore_Thread handler has two meanings, depending on what context
1557 * it is on. The one returned when starting a worker with any of the
1558 * functions ecore_thread_run() or ecore_thread_feedback_run() is an
1559 * identifier of that specific instance of the function and can be used from
1560 * the main loop with the ecore_thread_cancel() and ecore_thread_check()
1561 * functions. This handler must not be shared with the worker function
1562 * running in the thread. This same handler is the one received
1563 * on the @c end, @c cancel, and @c feedback callbacks.
1564 *
1565 * The worker function, that's the one running in the thread, also receives
1566 * an ::Ecore_Thread handler that can be used with ecore_thread_cancel() and
1567 * ecore_thread_check(), sharing the flag with the main loop. But this
1568 * handler is also associated with the thread where the function is running.
1569 * This has strong implications when working with thread local data.
1570 *
1571 * There are two kinds of worker threads that Ecore handles: simple or short,
1572 * workers, and feedback workers.
1573 *
1574 * The first kind is for simple functions that perform a
1575 * usually small but time consuming task. Ecore runs this function in
1576 * a thread as soon as one becomes available and notifies the calling user of
1577 * its completion once the task is done.
1578 *
1579 * The following image shows the flow of a program running four tasks on
1580 * a pool of two threads.
1581 *
1582 * @image html ecore_thread.png
1583 * @image rtf ecore_thread.png
1584 * @image latex ecore_thread.eps "ecore thread" width=\textwidth
1585 *
1586 * For larger tasks that may require continuous communication with the main
1587 * program, the feedback workers provide the same functionality plus a way
1588 * for the function running in the thread to send messages to the main
1589 * thread.
1590 *
1591 * The next diagram omits some details shown in the previous one regarding
1592 * how threads are spawned and tasks are queued, but illustrates how feedback
1593 * jobs communicate with the main loop and the special case of threads
1594 * running out of the pool.
1595 *
1596 * @image html ecore_thread_feedback.png
1597 * @image rtf ecore_thread_feedback.png
1598 * @image latex ecore_thread_feedback.eps "ecore thread feedback" width=\textwidth
1599 *
1600 * @{
1601 */
1602
1603typedef struct _Ecore_Thread Ecore_Thread; /**< @brief A handle for threaded jobs */
1604
1605/**
1606 * @typedef Ecore_Thread_Cb Ecore_Thread_Cb
1607 * @brief Called to be used by Ecore_Thread helper.
1608 */
1609typedef void (*Ecore_Thread_Cb)(void *data, Ecore_Thread *thread);
1610/**
1611 * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb
1612 * @brief Called to be used by the main loop to receive data sent by an
1613 * @ref Ecore_Thread_Group.
1614 */
1615typedef void (*Ecore_Thread_Notify_Cb)(void *data, Ecore_Thread *thread, void *msg_data);
1616
1617/**
1618 * @brief Schedules a task to run in a parallel thread to avoid locking the main loop.
1619 *
1620 * @details This function tries to create a new thread to run @a func_blocking in,
1621 * or if the maximum number of concurrent threads has been reached it
1622 * adds it to the pending list, where it waits until a thread becomes
1623 * available. The return value is an ::Ecore_Thread handle that can
1624 * be used to cancel the thread before its completion.
1625 *
1626 * @since_tizen 2.3
1627 *
1628 * @remarks This function should always return immediately, but in the rare
1629 * case that Ecore is built with no thread support, @a func_blocking is
1630 * be called here, actually blocking the main loop.
1631 *
1632 * @remarks Once a thread becomes available, @a func_blocking is run in it until
1633 * it finishes, then @a func_end is called from the thread containing the
1634 * main loop to inform the user of its completion. While in @a func_blocking,
1635 * no functions from the EFL can be used, except for those from Eina that are
1636 * marked to be thread-safe. Even for the latter, caution needs to be taken
1637 * if the data is shared across several threads.
1638 *
1639 * @remarks @a func_end is called from the main thread when @a func_blocking ends,
1640 * so here it's safe to use anything from the EFL freely.
1641 *
1642 * @remarks The thread can also be cancelled before its completion by calling
1643 * ecore_thread_cancel(), either from the main thread or @a func_blocking.
1644 * In this case, @a func_cancel is called, also from the main thread
1645 * to inform of this happening. If the thread could not be created, this
1646 * function is called and its @c thread parameter is @c NULL. It's
1647 * also safe to call any EFL function here, as it is running in the
1648 * main thread.
1649 *
1650 * @remarks Inside @a func_blocking, it's possible to call ecore_thread_reschedule()
1651 * to tell Ecore that this function should be called again.
1652 *
1653 * @remarks Be aware that no assumptions can be made about the order in which the
1654 * @a func_end callbacks for each task are called. Once the function is
1655 * running in a different thread, it's the OS that handles its running
1656 * schedule, and different functions may take longer to finish than others.
1657 * Also remember that just starting several tasks together doesn't mean they
1658 * are going to run at the same time. Ecore schedules them based on the
1659 * number of threads available for the particular system it's running in,
1660 * so some of the jobs started may be waiting until another one finishes
1661 * before it can execute its own @a func_blocking.
1662 *
1663 * @param[in] func_blocking The function that should run in another thread
1664 * @param[in] func_end The function to call from the main loop when @a func_blocking
1665 * completes its task successfully (may be @c NULL)
1666 * @param[in] func_cancel The function to call from the main loop if the thread running
1667 * @a func_blocking is cancelled or fails to start (may be @c NULL)
1668 * @param[in] data The user context data to pass to all callbacks
1669 * @return A new thread handler,
1670 * otherwise @c NULL on failure
1671 *
1672 * @see ecore_thread_feedback_run()
1673 * @see ecore_thread_cancel()
1674 * @see ecore_thread_reschedule()
1675 * @see ecore_thread_max_set()
1676 */
1677EAPI Ecore_Thread *ecore_thread_run(Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data);
1678
1679/**
1680 * @brief Launches a thread to run a task that can talk back to the main thread.
1681 *
1682 * @since_tizen 2.3
1683 *
1684 * @remarks The difference in the above is that ecore_thread_run() is meant for
1685 * tasks that don't need to communicate anything until they finish, while
1686 * this function is provided with a new callback, @a func_notify, that is
1687 * called from the main thread for every message sent from @a func_heavy
1688 * with ecore_thread_feedback().
1689 *
1690 * @remarks Like with ecore_thread_run(), a new thread is launched to run
1691 * @a func_heavy unless the maximum number of simultaneous threads has been
1692 * reached, in which case the function is scheduled to run whenever a
1693 * running task ends and a thread becomes free. But if @a try_no_queue is
1694 * set, Ecore first tries to launch a thread outside of the pool to run
1695 * the task. If it fails, it reverts to the normal behaviour of using a
1696 * thread from the pool as if @a try_no_queue had not been set.
1697 *
1698 * @remarks Keep in mind that Ecore handles the thread pool based on the number of
1699 * CPUs available, but running a thread outside of the pool doesn't count for
1700 * this, so having too many of them may have drastic effects over the
1701 * program's performance.
1702 *
1703 * @remarks See ecore_thread_run() for a general description of this function.
1704 *
1705 * @param[in] func_heavy The function that should run in another thread
1706 * @param[in] func_notify the function that receives the data sent from the thread
1707 * @param[in] func_end The function to call from the main loop when @a func_heavy
1708 * completes its task successfully
1709 * @param[in] func_cancel The function to call from the main loop if the thread running
1710 * @a func_heavy is cancelled or fails to start
1711 * @param[in] data The user context data to pass to all callbacks
1712 * @param[in] try_no_queue The boolean value that indicates whether to run outside the thread pool
1713 * @return A new thread handler,
1714 * otherwise @c NULL on failure
1715 *
1716 * @see ecore_thread_feedback()
1717 * @see ecore_thread_run()
1718 * @see ecore_thread_cancel()
1719 * @see ecore_thread_reschedule()
1720 * @see ecore_thread_max_set()
1721 */
1722EAPI Ecore_Thread *ecore_thread_feedback_run(Ecore_Thread_Cb func_heavy, Ecore_Thread_Notify_Cb func_notify,
1723 Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel,
1724 const void *data, Eina_Bool try_no_queue);
1725
1726/**
1727 * @brief Cancels a running thread.
1728 *
1729 * @details This function cancels a running thread. If @a thread can be immediately
1730 * cancelled (its still pending execution after creation or rescheduling),
1731 * then the @a cancel callback is called, @a thread is freed and
1732 * the function returns #EINA_TRUE.
1733 *
1734 * @since_tizen 2.3
1735 *
1736 * @remarks If the thread is already running, then this function returns @c EINA_FALSE
1737 * after marking the @a thread as pending cancellation. For the thread to
1738 * actually be terminated, it needs to return from the user function back
1739 * into Ecore control. This can happen in several ways:
1740 * @li The function ends and returns normally. If it hadn't been cancelled,
1741 * @a func_end would be called here, but instead @a func_cancel happens.
1742 * @li The function returns after requesting to be rescheduled with
1743 * ecore_thread_reschedule().
1744 * @li The function is prepared to leave early by checking if
1745 * ecore_thread_check() returns #EINA_TRUE.
1746 *
1747 * @remarks The user function can cancel itself by calling ecore_thread_cancel(), but
1748 * it should always use the ::Ecore_Thread handle passed to it and never
1749 * share it with the main loop thread by means of shared user data or in any
1750 * other way.
1751 *
1752 * @remarks @a thread is freed and should not be used again if this function
1753 * returns #EINA_TRUE or after the @a func_cancel callback returns.
1754 *
1755 * @remarks This function can be called both in the main loop and in the running thread.
1756 *
1757 * @param[in] thread The thread to cancel
1758 * @return #EINA_TRUE if the thread has been cancelled,
1759 * otherwise @c EINA_FALSE if it is pending
1760 *
1761 * @see ecore_thread_check()
1762 */
1763EAPI Eina_Bool ecore_thread_cancel(Ecore_Thread *thread);
1764
1765/**
1766 * @brief Checks whether a thread is in pending cancellation.
1767 *
1768 * @details This function can be called both in the main loop and in the running thread.
1769 *
1770 * @since_tizen 2.3
1771 *
1772 * @remarks When ecore_thread_cancel() is called on an already running task, the
1773 * thread is marked as pending cancellation. This function returns #EINA_TRUE
1774 * if this mark is set for the given @a thread and can be used from the
1775 * main loop thread to check if a still active thread has been cancelled,
1776 * or from the user function running in the thread to check if it should
1777 * stop doing what it's doing and return early, effectively cancelling the
1778 * task.
1779 *
1780 * @param[in] thread The thread to test
1781 * @return #EINA_TRUE if the thread is in pending cancellation,
1782 * otherwise @c EINA_FALSE if it is not
1783 *
1784 * @see ecore_thread_cancel()
1785 */
1786EAPI Eina_Bool ecore_thread_check(Ecore_Thread *thread);
1787
1788/**
1789 * @brief Sends data from the worker thread to the main loop.
1790 *
1791 * @since_tizen 2.3
1792 *
1793 * @remarks You should use this function only in the @a func_heavy call.
1794 *
1795 * @remarks Only the address to @a msg_data is sent and once this function
1796 * returns #EINA_TRUE, the job running in the thread should never touch the
1797 * contents of it again. The data sent should be malloc()'ed or something
1798 * similar, as long as it's not the memory that is local to the thread that risks being
1799 * overwritten or deleted once it goes out of scope or the thread finishes.
1800 *
1801 * @remarks Care must be taken that @a msg_data is properly freed in the @a func_notify
1802 * callback set when creating the thread.
1803 *
1804 * @param[in] thread The current ::Ecore_Thread context to send data from
1805 * @param[in] msg_data The data to be transmitted to the main loop
1806 * @return #EINA_TRUE if @a msg_data is successfully sent to the main loop,
1807 * otherwise @c EINA_FALSE if anything goes wrong
1808 *
1809 * @see ecore_thread_feedback_run()
1810 */
1811EAPI Eina_Bool ecore_thread_feedback(Ecore_Thread *thread, const void *msg_data);
1812
1813/**
1814 * @brief Asks for the function in the thread to be called again at a later period.
1815 *
1816 * @since_tizen 2.3
1817 *
1818 * @remarks This function should be called only from the function represented
1819 * by @a thread.
1820 *
1821 * Calling this function marks the thread for a reschedule, so as soon
1822 * as it returns, it is added to the end of the list of pending tasks.
1823 * If no other tasks are waiting or there are sufficient threads available,
1824 * the rescheduled task is launched again immediately.
1825 *
1826 * This should never return @c EINA_FALSE, unless it is called from the wrong
1827 * thread or with the wrong arguments.
1828 *
1829 * @remarks The @a func_end callback set when the thread is created is not
1830 * called until the function in the thread returns without being rescheduled.
1831 * Similarly, if the @a thread is cancelled, the reschedule does not take
1832 * effect.
1833 *
1834 * @param[in] thread The current ::Ecore_Thread context to reschedule
1835 * @return #EINA_TRUE if the task is successfully rescheduled,
1836 * otherwise @c EINA_FALSE if anything goes wrong
1837 *
1838 */
1839EAPI Eina_Bool ecore_thread_reschedule(Ecore_Thread *thread);
1840
1841/**
1842 * @brief Gets the number of active threads running jobs.
1843 *
1844 * @details This returns the number of threads currently running jobs of any type
1845 * through the Ecore_Thread API.
1846 *
1847 * @since_tizen 2.3
1848 *
1849 * @remarks Jobs started through the ecore_thread_feedback_run() function with
1850 * the @a try_no_queue parameter set to #EINA_TRUE are not accounted for
1851 * in the return of this function unless the thread creation fails and it
1852 * falls back to using one from the pool.
1853 *
1854 * @return The number of active threads running jobs
1855 *
1856 */
1857EAPI int ecore_thread_active_get(void);
1858
1859/**
1860 * @brief Gets the number of short jobs waiting for a thread to run.
1861 *
1862 * @details This returns the number of tasks started with ecore_thread_run() that are
1863 * pending and waiting for a thread to become available to run them.
1864 *
1865 * @since_tizen 2.3
1866 *
1867 * @return The number of pending threads running "short" jobs
1868 *
1869 */
1870EAPI int ecore_thread_pending_get(void);
1871
1872/**
1873 * @brief Gets the number of feedback jobs waiting for a thread to run.
1874 *
1875 * @details This returns the number of tasks started with ecore_thread_feedback_run()
1876 * that are pending and waiting for a thread to become available to run them.
1877 *
1878 * @since_tizen 2.3
1879 *
1880 * @return The number of pending threads running "feedback" jobs
1881 *
1882 */
1883EAPI int ecore_thread_pending_feedback_get(void);
1884
1885/**
1886 * @brief Gets the total number of pending jobs.
1887 *
1888 * @since_tizen 2.3
1889 *
1890 * @remarks This is same as the sum of ecore_thread_pending_get() and
1891 * ecore_thread_pending_feedback_get().
1892 *
1893 * @return The number of pending threads running jobs
1894 *
1895 */
1896EAPI int ecore_thread_pending_total_get(void);
1897
1898/**
1899 * @brief Gets the maximum number of threads that can run simultaneously.
1900 *
1901 * @details This returns the maximum number of Ecore_Thread's that may be running at
1902 * the same time. If this number is reached, new jobs started by either
1903 * ecore_thread_run() or ecore_thread_feedback_run() are added to the
1904 * respective pending queues until one of the running threads finishes its
1905 * task and becomes available to run a new one.
1906 *
1907 * @since_tizen 2.3
1908 *
1909 * @remarks By default, this is the number of available CPUs for the
1910 * running program (as returned by eina_cpu_count()), or @c 1 if this value
1911 * could not be fetched.
1912 *
1913 * @return The maximum possible number of Ecore_Thread's running concurrently
1914 *
1915 * @see ecore_thread_max_set()
1916 * @see ecore_thread_max_reset()
1917 */
1918EAPI int ecore_thread_max_get(void);
1919
1920/**
1921 * @brief Sets the maximum number of threads allowed to run simultaneously.
1922 *
1923 * @details This sets a new value for the maximum number of concurrently running
1924 * Ecore_Thread's. It @b must be an integer between @c 1 and (@c 16 * @c x), where @c x
1925 * is the number for CPUs available.
1926 *
1927 * @since_tizen 2.3
1928 *
1929 * @param[in] num The new maximum
1930 *
1931 * @see ecore_thread_max_get()
1932 * @see ecore_thread_max_reset()
1933 */
1934EAPI void ecore_thread_max_set(int num);
1935
1936/**
1937 * @brief Resets the maximum number of concurrently running threads to the default.
1938 *
1939 * @details This resets the value returned by ecore_thread_max_get() back to its
1940 * default.
1941 *
1942 * @since_tizen 2.3
1943 *
1944 * @see ecore_thread_max_get()
1945 * @see ecore_thread_max_set()
1946 */
1947EAPI void ecore_thread_max_reset(void);
1948
1949/**
1950 * @brief Gets the number of threads available for running tasks.
1951 *
1952 * @since_tizen 2.3
1953 *
1954 * @remarks This is same as doing ecore_thread_max_get() - ecore_thread_active_get().
1955 *
1956 * @remarks This function may return a negative number only in the case when the user
1957 * changes the maximum number of running threads while other tasks are
1958 * running.
1959 *
1960 * @return The number of available threads
1961 *
1962 */
1963EAPI int ecore_thread_available_get(void);
1964
1965/**
1966 * @brief Adds some data present in the hash local to the thread.
1967 *
1968 * @since_tizen 2.3
1969 *
1970 * @remarks Ecore Thread has a mechanism to share data across several worker functions
1971 * that run on the same system thread. That is, the data is stored per
1972 * thread and for a worker function to have access to it, it must be run
1973 * by the same thread that stored the data.
1974 *
1975 * @remarks When there are no more workers pending, the thread is destroyed
1976 * along with the internal hash and any data left in it is freed with
1977 * the given @a cb function.
1978 *
1979 * @ This set of functions is useful to share things around several instances
1980 * of a function when that thing is costly to create and can be reused, but
1981 * may only be used by one function at a time.
1982 *
1983 * For example, if you have a program doing requisitions to a database,
1984 * these requisitions can be done in threads so that waiting for the
1985 * database to respond doesn't block the UI. Each of these threads
1986 * run a function, and each function is dependent on a connection to
1987 * the database, which may not be able to handle more than one request at
1988 * a time so for each running function you need one connection handle.
1989 *
1990 * The options then are:
1991 * @li Each function opens a connection when it's called, does the work and
1992 * closes the connection when it finishes. This may be costly, wasting a lot
1993 * of time on resolving hostnames, negotiating permissions, and allocating
1994 * memory.
1995 * @li Open the connections in the main loop and pass it to the threads
1996 * using the data pointer. Even worse, it's just as costly as before and now
1997 * it may even be kept with connections open doing nothing until a thread
1998 * becomes available to run the function.
1999 * @li Have a way to share connection handles, so that each instance of the
2000 * function can check if an available connection exists, and if it doesn't,
2001 * create one and add it to the pool. When no more connections are needed,
2002 * they are all closed.
2003 *
2004 * The last option is the most efficient, but it requires a lot of work to
2005 * be implemented properly. Using thread local data helps to achieve the same
2006 * result while avoiding all the tracking work on your code. The way
2007 * to use it would be at the worker function, to ask for the connection
2008 * using ecore_thread_local_data_find() and if it doesn't exist, then open
2009 * a new one and save it with ecore_thread_local_data_add(). Complete the work and
2010 * forget about the connection handle, when everything is done the function
2011 * just ends. The next worker to run on that thread checks if a
2012 * connection exists and finds that it does, so the process of opening a
2013 * new one has been spared. When no more workers exist, the thread is
2014 * destroyed and the callback used when saving the connection is called
2015 * to close it.
2016 *
2017 * @remarks This function adds the data @a value to the thread data under the given
2018 * @a key. No other value in the hash may have the same @a key. If you need to
2019 * change the value under a @a key, or you don't know if one exists already,
2020 * you can use ecore_thread_local_data_set().
2021 *
2022 * Neither @a key nor @a value may be @c NULL and @a key gets copied in the
2023 * hash, unless @a direct is set, in which case the string used should not
2024 * be freed until the data is removed from the hash.
2025 *
2026 * @remarks The @a cb function is called when the data in the hash needs to be
2027 * freed, be it because it got deleted by ecore_thread_local_data_del() or
2028 * because @a thread got terminated and the hash got destroyed. This parameter
2029 * may be @c NULL, in which case @a value needs to be manually freed after
2030 * removing it from the hash with either ecore_thread_local_data_del() or
2031 * ecore_thread_local_data_set(), but it's very unlikely that this is what
2032 * you want.
2033 *
2034 * This function, and all of the others in the @a ecore_thread_local_data
2035 * family of functions, can only be called within the worker function running
2036 * in the thread. Do not call them from the main loop or from a thread
2037 * other than the one represented by @a thread.
2038 *
2039 * @param[in] thread The thread context the data belongs to
2040 * @param[in] key The name under which the data is stored
2041 * @param[in] value The data to add
2042 * @param[in] cb The function to free the data when removed from the hash
2043 * @param[in] direct If @c true, this does not copy the key string (like eina_hash_direct_add()),
2044 * otherwise @c false
2045 * @return #EINA_TRUE on success,
2046 * otherwise @c EINA_FALSE on failure
2047 *
2048 * @see ecore_thread_local_data_set()
2049 * @see ecore_thread_local_data_find()
2050 * @see ecore_thread_local_data_del()
2051 */
2052EAPI Eina_Bool ecore_thread_local_data_add(Ecore_Thread *thread, const char *key, void *value,
2053 Eina_Free_Cb cb, Eina_Bool direct);
2054
2055/**
2056 * @brief Sets some data present in the hash local to the given thread.
2057 *
2058 * @since_tizen 2.3
2059 *
2060 * @remarks If no data exists in the hash under the @a key, this function adds
2061 * @a value in the hash under the given @a key and returns @c NULL.
2062 * The key itself is copied.
2063 *
2064 * If the hash already contains something under @a key, the data is
2065 * replaced by @a value and the old value is returned.
2066 *
2067 * @c NULL is also returned if either @a key or @a value are @c NULL, or
2068 * if an error occurs.
2069 *
2070 * @remarks This function, and all of the others in the @a ecore_thread_local_data
2071 * family of functions, can only be called within the worker function running
2072 * in the thread. Do not call them from the main loop or from a thread
2073 * other than the one represented by @a thread.
2074 *
2075 * @param[in] thread The thread context the data belongs to
2076 * @param[in] key The name under which the data is stored
2077 * @param[in] value The data to add
2078 * @param[in] cb The function to free the data when removed from the hash
2079 *
2080 * @see ecore_thread_local_data_add()
2081 * @see ecore_thread_local_data_del()
2082 * @see ecore_thread_local_data_find()
2083 */
2084EAPI void *ecore_thread_local_data_set(Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb);
2085
2086/**
2087 * @brief Gets data stored in the hash local to the given thread.
2088 *
2089 * @since_tizen 2.3
2090 *
2091 * @details This finds and returns the data stored in the shared hash under the key @a key.
2092 *
2093 * @remarks This function, and all the others in the @a ecore_thread_local_data
2094 * family of functions, can only be called within the worker function running
2095 * in the thread. Do not call them from the main loop or from a thread
2096 * other than the one represented by @a thread.
2097 *
2098 * @param[in] thread The thread context the data belongs to
2099 * @param[in] key The name under which the data is stored
2100 * @return The value under the given key,
2101 * otherwise @c NULL on an error
2102 *
2103 * @see ecore_thread_local_data_add()
2104 * @see ecore_thread_local_data_wait()
2105 */
2106EAPI void *ecore_thread_local_data_find(Ecore_Thread *thread, const char *key);
2107
2108/**
2109 * @brief Deletes the data corresponding to the given key from the thread's hash.
2110 *
2111 * @since_tizen 2.3
2112 *
2113 * @remarks If there's any data associated with @a key that is stored in the global hash,
2114 * this function removes it from the hash and returns #EINA_TRUE. If no data
2115 * exists or an error occurs, it returns @c EINA_FALSE.
2116 *
2117 * @remarks If the data is added to the hash with a free function, then it is
2118 * also freed after removing it from the hash, otherwise it requires
2119 * to be manually freed by the user, which means that if no other reference
2120 * to it exists before calling this function, it results in a memory
2121 * leak.
2122 *
2123 * @remarks This function, and all the others in the @a ecore_thread_local_data
2124 * family of functions, can only be called within the worker function running
2125 * in the thread. Do not call them from the main loop or from a thread
2126 * other than the one represented by @a thread.
2127 *
2128 * @param[in] thread The thread context the data belongs to
2129 * @param[in] key The name under which the data is stored
2130 * @return #EINA_TRUE on success,
2131 * otherwise @c EINA_FALSE on failure
2132 *
2133 * @see ecore_thread_local_data_add()
2134 */
2135EAPI Eina_Bool ecore_thread_local_data_del(Ecore_Thread *thread, const char *key);
2136
2137/**
2138 * @brief Adds some data to a hash shared by all threads.
2139 *
2140 * @since_tizen 2.3
2141 *
2142 * @remarks Ecore Thread keeps a hash that can be used to share data across several
2143 * threads, including the main loop thread, without having to manually handle
2144 * mutexes to do it safely.
2145 *
2146 * @remarks This function adds the data @a value to this hash under the given @a key.
2147 * No other value in the hash may have the same @a key. If you need to
2148 * change the value under a @a key, or you don't know if one exists already,
2149 * you can use ecore_thread_global_data_set().
2150 *
2151 * Neither @a key nor @a value may be @c NULL and @a key gets copied in the
2152 * hash, unless @a direct is set, in which case the string used should not
2153 * be freed until the data is removed from the hash.
2154 *
2155 * @remarks The @a cb function is called when the data in the hash needs to be
2156 * freed, be it because it got deleted with ecore_thread_global_data_del() or
2157 * because Ecore Thread got shut down and the hash got destroyed. This parameter
2158 * may be @c NULL, in which case @a value needs to be manually freed after
2159 * removing it from the hash with either by ecore_thread_global_data_del() or
2160 * ecore_thread_global_data_set().
2161 *
2162 * Manually freeing any data that is added to the hash with the @a cb function
2163 * is likely to produce a segmentation fault, or any other strange
2164 * happening at a later stage in the program.
2165 *
2166 * @param[in] key The name under which the data is stored
2167 * @param[in] value The data to add
2168 * @param[in] cb The function to free the data when removed from the hash
2169 * @param[in] direct If @c true, this does not copy the key string (like eina_hash_direct_add()),
2170 * otherwise @c false
2171 * @return #EINA_TRUE on success,
2172 * otherwise @c EINA_FALSE on failure
2173 *
2174 * @see ecore_thread_global_data_del()
2175 * @see ecore_thread_global_data_set()
2176 * @see ecore_thread_global_data_find()
2177 */
2178EAPI Eina_Bool ecore_thread_global_data_add(const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct);
2179
2180/**
2181 * @brief Sets some data in the hash shared by all threads.
2182 *
2183 * @since_tizen 2.3
2184 *
2185 * @remarks If no data exists in the hash under the @a key, this function adds
2186 * @a value in the hash under the given @a key and returns @c NULL.
2187 * The key itself is copied.
2188 *
2189 * If the hash already contains something under @a key, the data is
2190 * replaced by @a value and the old value is returned.
2191 *
2192 * @c NULL is also returned if either @a key or @a value is @c NULL, or
2193 * if an error occurs.
2194 *
2195 *
2196 * @param[in] key The name under which the data is stored
2197 * @param[in] value The data to add
2198 * @param[in] cb The function to free the data when removed from the hash
2199 *
2200 * @see ecore_thread_global_data_add()
2201 * @see ecore_thread_global_data_del()
2202 * @see ecore_thread_global_data_find()
2203 */
2204EAPI void *ecore_thread_global_data_set(const char *key, void *value, Eina_Free_Cb cb);
2205
2206/**
2207 * @brief Gets data stored in the hash shared by all threads.
2208 *
2209 * @since_tizen 2.3
2210 *
2211 * @details This finds and returns the data stored in the shared hash under the key @a key.
2212 *
2213 * @remarks Keep in mind that the data returned may be used by more than one thread
2214 * at the same time and no reference counting is done on it by Ecore.
2215 * Freeing the data or modifying its contents may require additional
2216 * precautions to be considered, depending on the application's design.
2217 *
2218 * @param[in] key The name under which the data is stored
2219 * @return The value under the given key,
2220 * otherwise @c NULL on an error
2221 *
2222 * @see ecore_thread_global_data_add()
2223 * @see ecore_thread_global_data_wait()
2224 */
2225EAPI void *ecore_thread_global_data_find(const char *key);
2226
2227/**
2228 * @brief Deletes the data corresponding to the given key from the shared hash.
2229 *
2230 * @since_tizen 2.3
2231 *
2232 * @remarks If there's any data associated with @p key that is stored in the global hash,
2233 * this function removes it from the hash and returns #EINA_TRUE. If no data
2234 * exists or an error occurs, it returns @c EINA_FALSE.
2235 *
2236 * @remarks If the data is added to the hash with a free function, then it is
2237 * also freed after removing it from the hash, otherwise it requires
2238 * to be manually freed by the user, which means that if no other reference
2239 * to it exists before calling this function, it results in a memory
2240 * leak.
2241 *
2242 * Note, also, that freeing data that other threads may be using results
2243 * in a crash, so appropriate care must be taken by the application when
2244 * that possibility exists.
2245 *
2246 * @param[in] key The name under which the data is stored
2247 * @return #EINA_TRUE on success,
2248 * otherwise @c EINA_FALSE on failure
2249 *
2250 * @see ecore_thread_global_data_add()
2251 */
2252EAPI Eina_Bool ecore_thread_global_data_del(const char *key);
2253
2254/**
2255 * @brief Gets data stored in the shared hash or waits for it if it doesn't exist.
2256 *
2257 * @since_tizen 2.3
2258 *
2259 * @remarks This finds and returns the data stored in the shared hash under the key @a key.
2260 *
2261 * If there's nothing in the hash under the given @a key, the function
2262 * blocks and waits for @a seconds seconds for some other thread to
2263 * add it with either ecore_thread_global_data_add() or
2264 * ecore_thread_global_data_set(). If after waiting there's still no data
2265 * to obtain, @c NULL is returned.
2266 *
2267 * If @a seconds is @c 0, then no waiting happens and this function works
2268 * like ecore_thread_global_data_find(). If @a seconds is less than @c 0, then
2269 * the function waits indefinitely.
2270 *
2271 * @remarks Keep in mind that the data returned may be used by more than one thread
2272 * at the same time and no reference counting is done on it by Ecore.
2273 * Freeing the data or modifying its contents may require additional
2274 * precautions to be considered, depending on the application's design.
2275 *
2276 * @param[in] key The name under which the data is stored
2277 * @param[in] seconds The amount of time in seconds to wait for the data
2278 * @return The value under the given key,
2279 * otherwise @c NULL on an error
2280 *
2281 * @see ecore_thread_global_data_add()
2282 * @see ecore_thread_global_data_find()
2283 */
2284EAPI void *ecore_thread_global_data_wait(const char *key, double seconds);
2285
2286/**
2287 * @}
2288 */
2289
2290/**
2291 * @defgroup Ecore_Timer_Group Ecore Timer
2292 * @ingroup Ecore_Main_Loop_Group
2293 *
2294 * @brief Ecore provides very flexible timer functionality.
2295 *
2296 * The basic usage of timers is to call a certain function at a certain
2297 * interval, which can be achieved with a single line:
2298 * @code
2299 * Eina_Bool my_func(void *data) {
2300 * do_funky_stuff_with_data(data);
2301 * return ECORE_CALLBACK_RENEW;
2302 * }
2303 * ecore_timer_add(interval_in_seconds, my_func, data_given_to_function);
2304 * @endcode
2305 * If the function is to be executed only once simply return
2306 * @c CORE_CALLBACK_CANCEL instead.
2307 *
2308 * @{
2309 */
2310
2311typedef struct _Ecore_Timer Ecore_Timer; /**< @brief A handle for timers */
2312
2313/**
2314 * @brief Creates a timer to call the given function in the given period of time.
2315 *
2316 * @details This function adds a timer and returns its handle on success and NULL on
2317 * failure. The function @p func will be called every @p in seconds. The
2318 * function will be passed the @p data pointer as its parameter.
2319 *
2320 * @since_tizen 2.3
2321 *
2322 * @remarks When the timer @p func is called, it must return a value of either 1
2323 * (or ECORE_CALLBACK_RENEW) or 0 (or ECORE_CALLBACK_CANCEL).
2324 * If it returns 1, it will be called again at the next tick, or if it returns
2325 * 0 it will be deleted automatically making any references/handles for it
2326 * invalid.
2327 *
2328 * @param[in] in The interval in seconds.
2329 * @param[in] func The given function. If @p func returns 1, the timer is
2330 * rescheduled for the next interval @p in.
2331 * @param[in] data Data to pass to @p func when it is called.
2332 * @return A timer object on success. @c NULL on failure.
2333 */
2334EAPI Ecore_Timer *ecore_timer_add(double in, Ecore_Task_Cb func, const void *data);
2335
2336/**
2337 * @brief Creates a timer to call the given function in the given period of time.
2338 *
2339 * @since_tizen 2.3
2340 *
2341 * @remarks This is same as ecore_timer_add(), but "now" is the time from
2342 * ecore_loop_time_get(), not ecore_time_get(), as ecore_timer_add() uses it. See
2343 * ecore_timer_add() for more details.
2344 *
2345 * @param[in] in The interval in seconds from the current loop time
2346 * @param[in] func The given function \n
2347 * If @a func returns @c 1, the timer is
2348 * rescheduled for the next interval @a in.
2349 * @param[in] data The data to pass to @a func when it is called
2350 * @return A timer object on success,
2351 * otherwise @c NULL on failure
2352 */
2353EAPI Ecore_Timer *ecore_timer_loop_add(double in, Ecore_Task_Cb func, const void *data);
2354
2355/**
2356 * @brief Deletes the specified timer from the timer list.
2357 *
2358 * @details This deletes the specified @a timer from the set of timer that are
2359 * executed during main loop execution. This function returns the data
2360 * parameter that is being passed to the callback on success, otherwise @c NULL on
2361 * failure.
2362 *
2363 * @since_tizen 2.3
2364 *
2365 * @param[in] timer The timer to delete
2366 * @return The data pointer set for the timer on add
2367 *
2368 */
2369EAPI void *ecore_timer_del(Ecore_Timer *timer);
2370
2371/**
2372 * @brief Change the interval the timer ticks off.
2373 *
2374 * @since_tizen 2.3
2375 *
2376 * @param[in] timer The timer to change.
2377 * @param[in] in The interval in seconds.
2378 */
2379EAPI void ecore_timer_interval_set(Ecore_Timer *timer, double in);
2380
2381/**
2382 * @brief Get the interval the timer ticks on.
2383 *
2384 * @since_tizen 2.3
2385 *
2386 * @param[in] timer The timer to retrieve the interval from
2387 * @return The interval on success. -1 on failure.
2388 */
2389EAPI double ecore_timer_interval_get(Ecore_Timer *timer);
2390
2391/**
2392 * @brief Pauses a running timer.
2393 *
2394 * @since_tizen 2.3
2395 *
2396 * @remarks The timer callback won't be called while the timer is paused. The remaining
2397 * time until the timer expires will be saved, so the timer can be resumed with
2398 * that same remaining time to expire, instead of expiring instantly. Use
2399 * ecore_timer_thaw() to resume it.
2400 *
2401 * @remarks Nothing happens if the timer was already paused.
2402 *
2403 * @param[in] timer The timer to be paused.
2404 *
2405 * @see ecore_timer_thaw()
2406 */
2407EAPI void ecore_timer_freeze(Ecore_Timer *timer);
2408
2409/**
2410 * @brief Resumes a frozen (paused) timer.
2411 *
2412 * @since_tizen 2.3
2413 *
2414 * @remarks The timer will be resumed from its previous relative position in time. That
2415 * means, if it had X seconds remaining until expire when it was paused, it will
2416 * be started now with those same X seconds remaining to expire again. But
2417 * notice that the interval time won't be touched by this call or by
2418 * ecore_timer_freeze().
2419 *
2420 * @param[in] timer The timer to be resumed.
2421 *
2422 * @see ecore_timer_freeze()
2423 */
2424EAPI void ecore_timer_thaw(Ecore_Timer *timer);
2425
2426/**
2427 * @brief Add some delay for the next occurrence of a timer.
2428 *
2429 * @since_tizen 2.3
2430 *
2431 * @remarks This doesn't affect the interval of a timer.
2432 *
2433 * @param[in] timer The timer to change.
2434 * @param[in] add The delay to add to the next iteration.
2435 */
2436EAPI void ecore_timer_delay(Ecore_Timer *timer, double add);
2437
2438/**
2439 * @brief Reset a timer to its full interval. This effectively makes
2440 * the timer start ticking off from zero now.
2441 *
2442 * @param[in] timer The timer
2443 *
2444 * @since_tizen 2.3
2445 */
2446EAPI void ecore_timer_reset(Ecore_Timer *timer);
2447
2448/**
2449 * @brief Get the pending time regarding a timer.
2450 *
2451 * @param[in] timer The timer
2452 * @return The pending time
2453 *
2454 * @since_tizen 2.3
2455 */
2456EAPI double ecore_timer_pending_get(Ecore_Timer *timer);
2457
2458/**
2459 * @brief Retrieves the current precision used by timer infrastructure.
2460 *
2461 * @since_tizen 2.3
2462 *
2463 * @return Current precision.
2464 *
2465 * @see ecore_timer_precision_set()
2466 */
2467EAPI double ecore_timer_precision_get(void);
2468
2469/**
2470 * @brief Sets the precision to be used by timer infrastructure.
2471 *
2472 * @since_tizen 2.3
2473 *
2474 * @remarks This sets the precision for @b all timers. The precision determines how much
2475 * of an difference from the requested interval is acceptable. One common reason
2476 * to use this function is to @b increase the allowed timeout and thus @b
2477 * decrease precision of the timers, this is because less precise the timers
2478 * result in the system waking up less often and thus consuming less resources.
2479 *
2480 * @remarks Be aware that kernel may delay delivery even further, these delays
2481 * are always possible due other tasks having higher priorities or
2482 * other scheduler policies.
2483 *
2484 * @remarks Example:
2485 * We have 2 timers, one that expires in a 2.0s and another that
2486 * expires in 2.1s, if precision is 0.1s, then the Ecore will request
2487 * for the next expire to happen in 2.1s and not 2.0s and another one
2488 * of 0.1 as it would before.
2489 *
2490 * @remarks Ecore is smart enough to see if there are timers in the
2491 * precision range, if it does not, in our example if no second timer
2492 * in (T + precision) existed, then it would use the minimum timeout.
2493
2494 * @param[in] precision difference from the requested internval.
2495 */
2496EAPI void ecore_timer_precision_set(double precision);
2497
2498/**
2499 * @brief Dump the all timers.
2500 *
2501 * @since_tizen 2.3
2502 *
2503 * @return The information of all timers
2504 */
2505EAPI char *ecore_timer_dump(void);
2506
2507/**
2508 * @}
2509 */
2510
2511/**
2512 * @defgroup Ecore_Idle_Group Ecore Idle
2513 * @ingroup Ecore_Main_Loop_Group
2514 *
2515 * @brief The idler functionality in Ecore allows for callbacks to be called when the
2516 * program isn't handling @ref Ecore_Event_Group "events", @ref Ecore_Timer_Group
2517 * "timers", or @ref Ecore_FD_Handler_Group "fd handlers".
2518 *
2519 * There are three types of idlers: Enterers, Idlers(proper), and Exiters. They
2520 * are called respectively when the program is about to enter an idle state,
2521 * when the program is in an idle state and when the program has just left an
2522 * idle state and begins processing @ref Ecore_Event_Group "events", @ref
2523 * Ecore_Timer_Group "timers", or @ref Ecore_FD_Handler_Group "fd handlers".
2524 *
2525 * Enterer callbacks are good for updating your program's state, if
2526 * it has a state engine. Once all of the enterer handlers are
2527 * called, the program enters a "sleeping" state.
2528 *
2529 * Idler callbacks are called when the main loop has called all
2530 * enterer handlers. They are useful for interfaces that require
2531 * polling and timers without which they would be too slow to use.
2532 *
2533 * Exiter callbacks are called when the main loop wakes up from an idle state.
2534 *
2535 * If no idler callbacks are specified, then the process literally
2536 * goes to sleep. Otherwise, the idler callbacks are called
2537 * continuously while the loop is "idle", using as much CPU as is
2538 * available to the process.
2539 *
2540 * Idle state doesn't mean that the @b program is idle, but
2541 * that the <b>main loop</b> is idle. It doesn't have any timers,
2542 * events, fd handlers, or anything else to process (which in most
2543 * <em>event driven</em> programs also means that the @b program is
2544 * idle too, but it's not a rule). The program itself may be doing
2545 * a lot of processing in the idler, or in another thread, for
2546 * example.
2547 *
2548 * @{
2549 */
2550
2551typedef struct _Ecore_Idler Ecore_Idler; /**< @brief A handle for idlers */
2552typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer; /**< @brief A handle for idle enterers */
2553typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter; /**< @brief A handle for idle exiters */
2554
2555/**
2556 * @brief Adds an idler handler.
2557 *
2558 * @details This adds an idler handle to the event loop, returning a handle on
2559 * success and @c NULL otherwise. The function @a func is called
2560 * repeatedly while no other events are ready to be processed, as
2561 * long as it returns @c 1 (or @c ECORE_CALLBACK_RENEW). A return of @c 0
2562 * (or @c ECORE_CALLBACK_CANCEL) deletes the idler.
2563 *
2564 * @since_tizen 2.3
2565 *
2566 * @remarks Idlers are useful for progressively processing data without blocking.
2567 *
2568 * @param[in] func The function to call when idling
2569 * @param[in] data The data to be passed to this @a func call
2570 * @return A idler handle if successfully added,
2571 * otherwise @c NULL
2572 *
2573 */
2574EAPI Ecore_Idler *ecore_idler_add(Ecore_Task_Cb func, const void *data);
2575
2576/**
2577 * @brief Deletes an idler callback from the list to be executed.
2578 *
2579 * @since_tizen 2.3
2580 *
2581 * @param[in] idler The handle of the idler callback to delete
2582 * @return The data pointer passed to the idler callback on success,
2583 * otherwise @c NULL
2584 */
2585EAPI void *ecore_idler_del(Ecore_Idler *idler);
2586
2587/**
2588 * @brief Add an idle enterer handler.
2589 *
2590 * @since_tizen 2.3
2591 *
2592 * @remarks The function func will be called every time the main loop is entering
2593 * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0
2594 * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer.
2595 *
2596 * @param[in] func The function to call when entering an idle state.
2597 * @param[in] data The data to be passed to the @p func call
2598 * @return A handle to the idle enterer callback if successful. Otherwise,
2599 * NULL is returned.
2600 */
2601EAPI Ecore_Idle_Enterer *ecore_idle_enterer_add(Ecore_Task_Cb func, const void *data);
2602
2603/**
2604 * @brief Add an idle enterer handler at the start of the list so it gets called earlier than others.
2605 *
2606 * @since_tizen 2.3
2607 *
2608 * @remarks The function func will be called every time the main loop is entering
2609 * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0
2610 * (or ECORE_CALLBACK_CANCEL) deletes the idle enterer.
2611 *
2612 * @param[in] func The function to call when entering an idle state.
2613 * @param[in] data The data to be passed to the @p func call
2614 * @return A handle to the idle enterer callback if successful. Otherwise,
2615 * NULL is returned.
2616 */
2617EAPI Ecore_Idle_Enterer *ecore_idle_enterer_before_add(Ecore_Task_Cb func, const void *data);
2618
2619/**
2620 * @brief Delete an idle enterer callback.
2621 *
2622 * @since_tizen 2.3
2623 *
2624 * @param[in] idle_enterer The idle enterer to delete
2625 * @return The data pointer passed to the idler enterer callback on success.
2626 * NULL otherwise.
2627 */
2628EAPI void *ecore_idle_enterer_del(Ecore_Idle_Enterer *idle_enterer);
2629
2630/**
2631 * @brief Add an idle exiter handler.
2632 *
2633 * @since_tizen 2.3
2634 *
2635 * @remarks The function func will be called every time the main loop is exiting
2636 * idle state, as long as it returns 1 (or ECORE_CALLBACK_RENEW). A return of 0
2637 * (or ECORE_CALLBACK_CANCEL) deletes the idle exiter.
2638 *
2639 * @param[in] func The function to call when exiting an idle state.
2640 * @param[in] data The data to be passed to the @p func call
2641 * @return A handle to the idle exiter callback on success. NULL otherwise.
2642 */
2643EAPI Ecore_Idle_Exiter *ecore_idle_exiter_add(Ecore_Task_Cb func, const void *data);
2644
2645/**
2646 * @brief Delete an idle exiter handler from the list to be run on exiting idle state.
2647 *
2648 * @since_tizen 2.3
2649 *
2650 * @param[in] idle_exiter The idle exiter to delete
2651 * @return The data pointer that was being being passed to the handler if
2652 * successful. NULL otherwise.
2653 */
2654EAPI void *ecore_idle_exiter_del(Ecore_Idle_Exiter *idle_exiter);
2655
2656/**
2657 * @}
2658 */
2659
2660/**
2661 * @defgroup Ecore_Pipe_Group Ecore Pipe Wrapper
2662 * @ingroup Ecore_Main_Loop_Group
2663 *
2664 * @brief This group discusses the functions that wrap the write / read functions of the pipe to easily
2665 * integrate its use into ecore's main loop.
2666 *
2667 * @remarks The ecore_pipe_add() function creates file descriptors (sockets
2668 * on Windows) and attaches a handle to the ecore main loop. That
2669 * handle is called when data is read in the pipe. To write data in
2670 * the pipe, just call ecore_pipe_write(). When you are done, just
2671 * call ecore_pipe_del().
2672 *
2673 * @{
2674 */
2675
2676typedef struct _Ecore_Pipe Ecore_Pipe; /**< @brief A handle for pipes */
2677
2678/**
2679 * @typedef Ecore_Pipe_Cb Ecore_Pipe_Cb
2680 * @brief Called to send data written to the pipe.
2681 */
2682typedef void (*Ecore_Pipe_Cb)(void *data, void *buffer, unsigned int nbyte);
2683
2684/**
2685 * @brief Create two file descriptors (sockets on Windows).
2686 *
2687 * @details Add a callback that will be called when the file descriptor that
2688 * is listened receives data. An event is also put in the event
2689 * queue when data is received.
2690 *
2691 * @since_tizen 2.3
2692 *
2693 * @param[in] handler The handler called when data is received.
2694 * @param[in] data Data to pass to @p handler when it is called.
2695 * @return A newly created Ecore_Pipe object if successful.
2696 * @c NULL otherwise.
2697 */
2698EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data);
2699
2700/**
2701 * @brief Free an Ecore_Pipe object created with ecore_pipe_add().
2702 *
2703 * @since_tizen 2.3
2704 *
2705 * @param[in] p The Ecore_Pipe object to be freed.
2706 * @return The pointer to the private data
2707 */
2708EAPI void *ecore_pipe_del(Ecore_Pipe *p);
2709
2710/**
2711 * @brief Write on the file descriptor the data passed as parameter.
2712 *
2713 * @since_tizen 2.3
2714 *
2715 * @param[in] p The Ecore_Pipe object.
2716 * @param[in] buffer The data to write into the pipe.
2717 * @param[in] nbytes The size of the @p buffer in bytes
2718 * @return #EINA_TRUE on a successful write, @c EINA_FALSE on error.
2719 */
2720EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes);
2721
2722/**
2723 * @brief Close the write end of an Ecore_Pipe object created with ecore_pipe_add().
2724 *
2725 * @since_tizen 2.3
2726 *
2727 * @param[in] p The Ecore_Pipe object.
2728 */
2729EAPI void ecore_pipe_write_close(Ecore_Pipe *p);
2730
2731/**
2732 * @brief Close the read end of an Ecore_Pipe object created with
2733 * ecore_pipe_add().
2734 *
2735 * @since_tizen 2.3
2736 *
2737 * @param[in] p The Ecore_Pipe object.
2738 */
2739EAPI void ecore_pipe_read_close(Ecore_Pipe *p);
2740
2741/**
2742 * @brief Start monitoring again the pipe for reading. See ecore_pipe_freeze()
2743 * for stopping the monitoring activity. This will not work if
2744 * ecore_pipe_read_close() was previously called on the same pipe.
2745 *
2746 * @since 1.1
2747 *
2748 * @since_tizen 2.3
2749 *
2750 * @param[in] p The Ecore_Pipe object.
2751 */
2752EAPI void ecore_pipe_thaw(Ecore_Pipe *p);
2753
2754/**
2755 * @brief Stop monitoring if necessary the pipe for reading.
2756 * @since 1.1
2757 *
2758 * @since_tizen 2.3
2759 *
2760 * @param[in] p The Ecore_Pipe object.
2761 *
2762 * @see ecore_pipe_thaw() for monitoring it again.
2763 *
2764 */
2765EAPI void ecore_pipe_freeze(Ecore_Pipe *p);
2766
2767/**
2768 * @brief Wait from another thread on the read side of a pipe.
2769 * @since 1.1
2770 *
2771 * @since_tizen 2.3
2772 *
2773 * @remarks Negative value for @p wait means infite wait.
2774 *
2775 * @param[in] p The pipe to watch on.
2776 * @param[in] message_count The minimal number of message to wait before exiting.
2777 * @param[in] wait The amount of time in second to wait before exiting.
2778 * @return the number of message catched during that wait call.
2779 *
2780 */
2781EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait);
2782
2783/**
2784 * @}
2785 */
2786
2787/**
2788 * @internal
2789 * @defgroup Ecore_Throttle_Group Ecore Throttle
2790 * @ingroup Ecore_Main_Loop_Group
2791 *
2792 * @{
2793 */
2794
2795/**
2796 * @brief Increase throttle amount
2797 *
2798 * @details This will increase or decrease (if @p amount is positive or negative) the
2799 * amount of "voluntary throttling" ecore will do to its main loop while
2800 * running. This is intended to be used to limit animations and wakeups when
2801 * in a strict power management state. The higher the current throttle value
2802 * (which can be retrieved by ecore_throttle_get() ), the more throttling
2803 * takes place. If the current throttle value is 0, then no throttling takes
2804 * place at all.
2805 *
2806 * @remarks The value represents how long the ecore main loop will sleep (in seconds)
2807 * before it goes into a fully idle state waiting for events, input or
2808 * timing events to wake it up. For example, if the current throttle level
2809 * is 0.5, then after every time the main loop cycles and goes into idle
2810 * affter processing all events, the main loop will explicitly sleep for 0.5
2811 * seconds before sitting and waiting for incoming events or timeouts, thus
2812 * preventing animation, async IO and network handling etc. for that period
2813 * of time. Of course these events, data and timeouts will be buffered,
2814 * thus not losing anything, simply delaying when they get handled by the
2815 * throttle value.
2816 *
2817 * Example:
2818 * @code
2819 * void enter_powersave(void) {
2820 * ecore_throttle_adjust(0.2);
2821 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
2822 * }
2823 *
2824 * void enter_deep_powersave(void) {
2825 * ecore_throttle_adjust(0.5);
2826 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
2827 * }
2828 *
2829 * void exit_powersave(void) {
2830 * ecore_throttle_adjust(-0.2);
2831 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
2832 * }
2833 *
2834 * void exit_deep_powersave(void) {
2835 * ecore_throttle_adjust(-0.5);
2836 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get());
2837 * }
2838 * @endcode
2839 *
2840 * @param[in] amount Amount (in seconds) to adjust by
2841 */
2842
2843EAPI void ecore_throttle_adjust(double amount);
2844
2845/**
2846 * @brief Get current throttle level
2847 *
2848 * @remarks This gets the current throttling level, which can be adjusted by
2849 * ecore_throttle_adjust(). The value is in seconds.
2850 *
2851 * @return The current throttle level
2852 *
2853 * @see ecore_throttle_adjust() for more information.
2854 *
2855 */
2856EAPI double ecore_throttle_get(void);
2857
2858/**
2859 * @}
2860 */
2861
2862/**
2863 * @defgroup Ecore_Poller_Group Ecore Poller
2864 * @ingroup Ecore_Main_Loop_Group
2865 *
2866 * @brief Ecore poller provides infrastructure for the creation of pollers.
2867 *
2868 * Pollers are, in essence, callbacks that share a single timer per type. Because not
2869 * all pollers need to be called at the same frequency the user may specify the
2870 * frequency in ticks(each expiration of the shared timer is called a tick, in
2871 * ecore poller parlance) for each added poller. Ecore pollers should only be
2872 * used when the poller doesn't have specific requirements on the exact times
2873 * to poll.
2874 *
2875 * This architecture means that the main loop is only woken up once to handle
2876 * all pollers of that type, this saves power as the CPU has more of a
2877 * chance to go into a low power state the longer it is asleep, so this
2878 * should be used in situations where power usage is a concern.
2879 *
2880 * For now only 1 core poller type is supported: @c ECORE_POLLER_CORE.
2881 * The default interval for @c ECORE_POLLER_CORE is @c 0.125(or 1/8th) second.
2882 *
2883 * The creation of a poller is extremely simple and only requires one line:
2884 * @code
2885 * ecore_poller_add(ECORE_POLLER_CORE, 1, my_poller_function, NULL);
2886 * @endcode
2887 * This sample creates a poller to call @a my_poller_function at every tick with
2888 * @c NULL as data.
2889 *
2890 * @{
2891 */
2892
2893/**
2894 * @enum _Ecore_Poller_Type
2895 * @brief Enumeration that defines the frequency of ticks for the poller.
2896 */
2897enum _Ecore_Poller_Type /* Poller types */
2898{
2899 ECORE_POLLER_CORE = 0, /**< The core poller interval */
2900#ifdef __linux
2901 ECORE_POLLER_LAZY = 1, /**< Core poller based on timerfd,
2902 timer is deferrable in case the kernel supports it (no fire at IDLE time) */
359#endif 2903#endif
2904 ECORE_POLLER_TYPE_MAX
2905};
2906
2907/**
2908 * @brief typedef to enum _Ecore_Poller_Type
2909 */
2910typedef enum _Ecore_Poller_Type Ecore_Poller_Type;
2911
2912typedef struct _Ecore_Poller Ecore_Poller; /**< @brief A handle for pollers */
2913
2914/**
2915 * @brief Sets the time(in seconds) between ticks for the given poller type.
2916 *
2917 * @details This adjusts the time between ticks of the given timer type defined by
2918 * @a type to the time period defined by @a poll_time.
2919 *
2920 * @since_tizen 2.3
2921 *
2922 * @param[in] type The poller type to adjust
2923 * @param[in] poll_time The time(in seconds) between ticks of the timer
2924 *
2925 */
2926EAPI void ecore_poller_poll_interval_set(Ecore_Poller_Type type, double poll_time);
2927
2928/**
2929 * @brief Gets the time(in seconds) between ticks for the given poller type.
2930 *
2931 * @details This gets the time between ticks of the specified poller timer.
2932 *
2933 * @since_tizen 2.3
2934 *
2935 * @param[in] type The poller type to query
2936 * @return The time in seconds between ticks of the poller timer
2937 *
2938 */
2939EAPI double ecore_poller_poll_interval_get(Ecore_Poller_Type type);
2940
2941/**
2942 * @brief Changes the polling interval rate of @a poller.
2943 *
2944 * @details This allows the changing of a poller's polling interval. It is useful when
2945 * you want to alter a poll rate without deleting and re-creating a poller.
2946 *
2947 * @since_tizen 2.3
2948 *
2949 * @param[in] poller The Ecore_Poller to change the interval of
2950 * @param[in] interval The tick interval to set, must be a power of 2 and <= 32768
2951 * @return @c true on success, otherwise @c false on failure
2952 *
2953 */
2954EAPI Eina_Bool ecore_poller_poller_interval_set(Ecore_Poller *poller, int interval);
2955
2956/**
2957 * @brief Gets the polling interval rate of @a poller.
2958 *
2959 * @details This returns a poller's polling interval, otherwise @c 0 on error.
2960 *
2961 * @since_tizen 2.3
2962 *
2963 * @param[in] poller The Ecore_Poller to change the interval of
2964 * @return The interval, in ticks, that @a poller polls at
2965 *
2966 */
2967EAPI int ecore_poller_poller_interval_get(Ecore_Poller *poller);
2968
2969/**
2970 * @brief Creates a poller to call the given function at a particular tick interval.
2971 *
2972 * @details This function adds @a func as a poller callback that is called every @a
2973 * interval ticks together with other pollers of type @a type. @a func is
2974 * passed the @a data pointer as a parameter.
2975 *
2976 * @since_tizen 2.3
2977 *
2978 * @remarks The @a interval must be between @c 1 and @c 32768 inclusive, and must be a power of
2979 * @c 2 (i.e. 1, 2, 4, 8, 16, ... 16384, 32768). The exact tick in which @a func
2980 * is called is undefined, as only the interval between calls can be
2981 * defined. Ecore endeavors to keep pollers synchronized and calls as
2982 * many in 1 wakeup event as possible. If @a interval is not a power of @c 2, the
2983 * closest power of @c 2 greater than @a interval is used.
2984 *
2985 * @remarks When the poller @a func is called, it must return a value of either
2986 * @c ECORE_CALLBACK_RENEW(or @c 1) or @c ECORE_CALLBACK_CANCEL(or @c 0). If it
2987 * returns @c 1, it is called again at the next tick, or if it returns
2988 * @c 0 it is deleted automatically making any references/handles for it
2989 * invalid.
2990 *
2991 * @param[in] type The ticker type to attach the poller to \n
2992 * Must be @c ECORE_POLLER_CORE.
2993 * @param[in] interval The poll interval
2994 * @param[in] func The poller function
2995 * @param[in] data The data to pass to @a func when it is called
2996 * @return A poller object on success,
2997 * otherwise @c NULL on failure
2998 *
2999 */
3000EAPI Ecore_Poller *ecore_poller_add(Ecore_Poller_Type type, int interval, Ecore_Task_Cb func, const void *data);
3001
3002/**
3003 * @brief Deletes the specified poller from the timer list.
3004 *
3005 * @since_tizen 2.3
3006 *
3007 * @remarks @a poller must be a valid handle. If the poller function has already
3008 * returned @c 0, the handle is no longer valid (and does not need to be deleted).
3009 *
3010 * @param[in] poller The poller to delete
3011 * @return The data pointer set for the timer when @ref ecore_poller_add is called on success,
3012 * otherwise @c NULL on failure
3013 */
3014EAPI void *ecore_poller_del(Ecore_Poller *poller);
3015
3016/**
3017 * @}
3018 */
3019
3020/**
3021 * @defgroup Ecore_Animator_Group Ecore Animator
3022 * @ingroup Ecore_Main_Loop_Group
3023 *
3024 * @brief Ecore animators are a helper to simplify creating animations.
3025 *
3026 * Creating an animation is as simple as saying for how long it
3027 * should be run and having a callback that does the animation,
3028 * something like this:
3029 * @code
3030 * static Eina_Bool
3031 * _do_animation(void *data, double pos)
3032 * {
3033 * evas_object_move(data, 100 * pos, 100 * pos);
3034 * ... do some more animating ...
3035 * }
3036 * ...
3037 * ecore_animator_timeline_add(2, _do_animation, my_evas_object);
3038 * @endcode
3039 *
3040 * In the sample above we create an animation to move
3041 * @c my_evas_object from position (0,0) to (100,100) in @c 2 seconds.
3042 *
3043 * If your animation runs for an unspecified amount of time you
3044 * can use ecore_animator_add(), which is like using
3045 * ecore_timer_add() with the interval being the
3046 * @ref ecore_animator_frametime_set "framerate". Note that this has
3047 * tangible benefits of creating a timer for each animation in terms
3048 * of performance.
3049 *
3050 * @{
3051 */
3052
3053/**
3054 * @brief handle for ecore animator.
3055 */
3056typedef struct _Ecore_Animator Ecore_Animator;
3057
3058/**
3059 * @enum _Ecore_Pos_Map
3060 * @brief Enumeration that defines the position mappings for the animation.
3061 */
3062enum _Ecore_Pos_Map /* Position mappings */
3063{
3064 ECORE_POS_MAP_LINEAR, /**< Linear 0.0 -> 1.0 */
3065 ECORE_POS_MAP_ACCELERATE, /**< Start slow then speed up */
3066 ECORE_POS_MAP_DECELERATE, /**< Start fast then slow down */
3067 ECORE_POS_MAP_SINUSOIDAL, /**< Start slow, speed up then slow down at the end */
3068 ECORE_POS_MAP_ACCELERATE_FACTOR, /**< Start slow then speed up, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal accelerate, @c 2.0 being much more pronounced accelerate (squared), @c 3.0 being cubed, and so on */
3069 ECORE_POS_MAP_DECELERATE_FACTOR, /**< Start fast then slow down, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal decelerate, @c 2.0 being much more pronounced decelerate (squared), @c 3.0 being cubed, and so on */
3070 ECORE_POS_MAP_SINUSOIDAL_FACTOR, /**< Start slow, speed up then slow down at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being normal sinusoidal, @c 2.0 being much more pronounced sinusoidal (squared), @c 3.0 being cubed, and so on */
3071 ECORE_POS_MAP_DIVISOR_INTERP, /**< Start at gradient * v1, interpolated via power of v2 curve */
3072 ECORE_POS_MAP_BOUNCE, /**< Start at @c 0.0 then "drop" like a ball bouncing to the ground at @c 1.0, and bounce v2 times, with decay factor of v1 */
3073 ECORE_POS_MAP_SPRING /**< Start at @c 0.0 then "wobble" like a spring with rest position @c 1.0, and wobble v2 times, with decay factor of v1 */
3074};
3075
3076/**
3077 * @brief typedef to enum _Ecore_Pos_Map
3078 */
3079typedef enum _Ecore_Pos_Map Ecore_Pos_Map;
3080
3081/**
3082 * @enum _Ecore_Animator_Source
3083 * @brief Enumeration that defines the timing sources for animators.
3084 */
3085enum _Ecore_Animator_Source /* Timing sources for animators */
3086{
3087 ECORE_ANIMATOR_SOURCE_TIMER, /**< The default system clock/timer based animator that ticks every "frametime" seconds */
3088 ECORE_ANIMATOR_SOURCE_CUSTOM /**< A custom animator trigger which ticks when you call ecore_animator_trigger() */
3089};
3090
3091/**
3092 * @brief typedef to enum _Ecore_Animator_Source
3093 */
3094typedef enum _Ecore_Animator_Source Ecore_Animator_Source;
3095
3096/**
3097 * @typedef Ecore_Timeline_Cb Ecore_Timeline_Cb
3098 * @brief The boolean type for a callback run for a task (animators with runtimes)
3099 */
3100typedef Eina_Bool (*Ecore_Timeline_Cb)(void *data, double pos);
3101
3102/**
3103 * @brief Adds an animator to call @a func at every animation tick during main
3104 * loop execution.
3105 *
3106 * @details This function adds an animator and returns its handle on success, and @c NULL
3107 * on failure. The function @a func is called every N seconds where N is
3108 * the @a frametime interval set by ecore_animator_frametime_set(). The
3109 * function is passed the @a data pointer as its parameter.
3110 *
3111 * @since_tizen 2.3
3112 *
3113 * @remarks When the animator @a func is called, it must return a value of either @c 1 or
3114 * @c 0. If it returns @c 1 (or @c ECORE_CALLBACK_RENEW), it is called again at
3115 * the next tick, or if it returns @c 0 (or @c ECORE_CALLBACK_CANCEL) it is
3116 * deleted automatically making any references/handles for it invalid.
3117 *
3118 * @remarks The default @a frametime value is 1/30th of a second.
3119 *
3120 * @param[in] func The function to call when it ticks off
3121 * @param[in] data The data to pass to the function
3122 * @return A handle to the new animator
3123 *
3124 * @see ecore_animator_timeline_add()
3125 * @see ecore_animator_frametime_set()
3126 */
3127EAPI Ecore_Animator *ecore_animator_add(Ecore_Task_Cb func, const void *data);
3128
3129/**
3130 * @brief Adds an animator that runs for a limited time.
3131 *
3132 * @details This function is just like ecore_animator_add() except that the animator only
3133 * runs for a limited time specified in seconds by @a runtime. Once the
3134 * runtime of the animator has elapsed (animator finished) it is automatically
3135 * deleted. The callback function @a func can return @c ECORE_CALLBACK_RENEW
3136 * to keep the animator running or @c ECORE_CALLBACK_CANCEL to stop it and have
3137 * it deleted automatically at any time.
3138 *
3139 * @since 1.1.0
3140 *
3141 * @since_tizen 2.3
3142 *
3143 * @remarks The @a func is ALSO passed a position parameter that has a value
3144 * from @c 0.0 to @c 1.0 to indicate where along the timeline (@c 0.0 for start, @c 1.0 for end)
3145 * is the animator run at. If the callback wishes not to have a linear
3146 * transition it can "map" this value to one of the several curves and mappings
3147 * via ecore_animator_pos_map().
3148 *
3149 * @remarks The default @a frametime value is 1/30th of a second.
3150 *
3151 * @param[in] runtime The time to run in seconds
3152 * @param[in] func The function to call when it ticks off
3153 * @param[in] data The data to pass to the function
3154 * @return A handle to the new animator
3155 *
3156 * @see ecore_animator_add()
3157 * @see ecore_animator_pos_map()
3158 */
3159EAPI Ecore_Animator *ecore_animator_timeline_add(double runtime, Ecore_Timeline_Cb func, const void *data);
3160
3161/**
3162 * @brief Deletes the specified animator from the animator list.
3163 *
3164 * @details This deletes the specified @a animator from the set of animators that are
3165 * executed during main loop execution. This function returns the data
3166 * parameter that is being passed to the callback on success, otherwise @c NULL on
3167 * failure. After this call returns the specified animator object @a animator
3168 * is invalid and should not be used again. It does not get called again after
3169 * deletion.
3170 *
3171 * @since_tizen 2.3
3172 *
3173 * @param[in] animator The animator to delete
3174 * @return The data pointer set for the animator on add
3175 *
3176 */
3177EAPI void *ecore_animator_del(Ecore_Animator *animator);
3178
3179/**
3180 * @brief Suspends the specified animator.
3181 *
3182 * @since_tizen 2.3
3183 *
3184 * @remarks The specified @a animator is temporarily removed from the set of
3185 * animators that are executed during the main loop.
3186 *
3187 * @remarks Freezing an animator doesn't freeze accounting of how long that
3188 * animator has been running. Therefore if the animator is created with
3189 * ecore_animator_timeline_add() the @a pos argument given to the callback
3190 * increases as if the animator hadn't been frozen and the animator may
3191 * have its execution halted if @a runtime elapses.
3192 *
3193 * @param[in] animator The animator to delete
3194 *
3195 */
3196EAPI void ecore_animator_freeze(Ecore_Animator *animator);
3197
3198/**
3199 * @brief Restores execution of the specified animator.
3200 *
3201 * @since_tizen 2.3
3202 *
3203 * @remarks The specified @a animator is put back in the set of animators that are
3204 * executed during the main loop.
3205 *
3206 * @param[in] animator The animator to delete
3207 *
3208 */
3209EAPI void ecore_animator_thaw(Ecore_Animator *animator);
3210
3211/**
3212 * @brief Sets the animator call interval in seconds.
3213 *
3214 * @details This function sets the time interval (in seconds) between animator ticks.
3215 * At every tick the callback of every existing animator is called.
3216 *
3217 * @since_tizen 2.3
3218 *
3219 * @remarks Too small a value may cause performance issues and too high a
3220 * value may cause your animation to look "jerky".
3221 *
3222 * @remarks The default @a frametime value is 1/30th of a second.
3223 *
3224 * @param[in] frametime The time in seconds between animator ticks
3225 *
3226 */
3227EAPI void ecore_animator_frametime_set(double frametime);
3228
3229/**
3230 * @brief Gets the animator call interval in seconds.
3231 *
3232 * @details This function retrieves the time in seconds between animator ticks.
3233 *
3234 * @since_tizen 2.3
3235 *
3236 * @return The time in seconds between animator ticks
3237 *
3238 * @see ecore_animator_frametime_set()
3239 */
3240EAPI double ecore_animator_frametime_get(void);
3241
3242/**
3243 * @brief Maps an input position from @c 0.0 to @c 1.0 along a timeline to a
3244 * position in a different curve.
3245 *
3246 * @details This takes an input position (@c 0.0 to @c 1.0) and maps it to a new position (normally
3247 * between @c 0.0 and @c 1.0, but it may go above/below @c 0.0 or @c 1.0 to show that it
3248 * has "overshot" the mark) using some interpolation (mapping) algorithm.
3249 *
3250 * @since_tizen 2.3
3251 *
3252 * @remarks This function is useful to create non-linear animations. It offers a variety
3253 * of possible animation curves to be used:
3254 * @li ECORE_POS_MAP_LINEAR - Linear, returns @a pos.
3255 * @li ECORE_POS_MAP_ACCELERATE - Start slow then speed up.
3256 * @li ECORE_POS_MAP_DECELERATE - Start fast then slow down.
3257 * @li ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at the end.
3258 * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a
3259 * power factor, @c 0.0 being linear, @c 1.0 being @c ECORE_POS_MAP_ACCELERATE, @c 2.0
3260 * being much more pronounced accelerate (squared), @c 3.0 being cubed, and so on.
3261 * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a
3262 * power factor, @c 0.0 being linear, @c 1.0 being @c ECORE_POS_MAP_DECELERATE, @c 2.0
3263 * being much more pronounced decelerate (squared), @c 3.0 being cubed, and so on.
3264 * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down
3265 * at the end, v1 being a power factor, @c 0.0 being linear, @c 1.0 being
3266 * @c ECORE_POS_MAP_SINUSOIDAL, @c 2.0 being much more pronounced sinusoidal
3267 * (squared), @c 3.0 being cubed, and so on.
3268 * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via
3269 * power of v2 curve.
3270 * @li ECORE_POS_MAP_BOUNCE - Start at @c 0.0 then "drop" like a ball bouncing to
3271 * the ground at @c 1.0, and bounce v2 times, with decay factor of v1.
3272 * @li ECORE_POS_MAP_SPRING - Start at @c 0.0 then "wobble" like a spring with rest
3273 * position @c 1.0, and wobble v2 times, with decay factor of v1
3274 * @remarks When not listed v1 and v2 have no effect.
3275 *
3276 * @image html ecore-pos-map.png
3277 * @image latex ecore-pos-map.eps "ecore pos map" width=\textwidth
3278 *
3279 * @remarks One way to use this would be:
3280 * @code
3281 * double pos; // input position in a timeline from 0.0 to 1.0
3282 * double out; // output position after mapping
3283 * int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position
3284 * int x, y; // x & y are the calculated position
3285 *
3286 * out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7);
3287 * x = (x1 * out) + (x2 * (1.0 - out));
3288 * y = (y1 * out) + (y2 * (1.0 - out));
3289 * move_my_object_to(myobject, x, y);
3290 * @endcode
3291 * This makes an animation that bounces @c 7 diminish each time by a
3292 * factor of @c 1.8.
3293 *
3294 * @param[in] pos The input position to map
3295 * @param[in] map The mapping to use
3296 * @param[in] v1 A parameter used by the mapping (pass @c 0.0 if not used)
3297 * @param[in] v2 A parameter used by the mapping (pass @c 0.0 if not used)
3298 * @return The mapped value
3299 *
3300 * @see _Ecore_Pos_Map
3301 *
3302 * @since 1.1.0
3303 */
3304EAPI double ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2);
3305
3306/**
3307 * @brief Sets the source of the animator ticks for the mainloop.
3308 *
3309 * @details This sets the source of the animator ticks. When an animator is active the
3310 * mainloop will "tick" over frame by frame calling all animators that are
3311 * registered until none are left. The mainloop ticks at a given rate based
3312 * on the animator source. The default source is the system clock timer
3313 * source - @c ECORE_ANIMATOR_SOURCE_TIMER. This source uses the system clock
3314 * to tick over every N seconds (specified by ecore_animator_frametime_set(),
3315 * with the default being 1/30th of a second unless set otherwise). You can
3316 * set a custom tick source by setting the source to
3317 * @c ECORE_ANIMATOR_SOURCE_CUSTOM and then driving it yourself based on some input
3318 * tick source (like another application via ipc, some vertical blanking
3319 * interrupt and so on) using ecore_animator_custom_source_tick_begin_callback_set() and
3320 * ecore_animator_custom_source_tick_end_callback_set() to set the functions
3321 * that are called to start and stop the ticking source, which when
3322 * gets a "tick" should call ecore_animator_custom_tick() to make the "tick" over @c 1
3323 * frame.
3324 *
3325 * @since_tizen 2.3
3326 *
3327 * @param[in] source The source of the animator ticks to use
3328 *
3329 */
3330EAPI void ecore_animator_source_set(Ecore_Animator_Source source);
3331
3332/**
3333 * @brief Gets the animator source currently set.
3334 *
3335 * @details This gets the current animator source.
3336 *
3337 * @since_tizen 2.3
3338 *
3339 * @return The current animator source
3340 *
3341 * @see ecore_animator_source_set()
3342 */
3343EAPI Ecore_Animator_Source ecore_animator_source_get(void);
3344
3345/**
3346 * @brief Sets the function that begins a custom animator tick source.
3347 *
3348 * @since_tizen 2.3
3349 *
3350 * @remarks The Ecore Animator infrastructure handles tracking of whether animators are needed
3351 * and which ones need to be called and when, but when the tick source
3352 * is custom, you have to provide a tick source by calling
3353 * ecore_animator_custom_tick() to indicate that a frame tick happened. In order
3354 * to allow the source of ticks to be dynamically enabled or disabled as
3355 * needed, @a func when set is called to enable the tick source to
3356 * produce tick events that call ecore_animator_custom_tick(). If @a func
3357 * is @c NULL then no function is called to begin custom ticking.
3358 *
3359 * @param[in] func The function to call when ticking is to begin
3360 * @param[in] data The data passed to the tick begin function as its parameter
3361 *
3362 * @see ecore_animator_source_set()
3363 * @see ecore_animator_custom_source_tick_end_callback_set()
3364 * @see ecore_animator_custom_tick()
3365 */
3366EAPI void ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data);
3367
3368/**
3369 * @brief Sets the function that ends a custom animator tick source.
3370 *
3371 * @since_tizen 2.3
3372 *
3373 * @remarks This function is a matching pair to the function set by
3374 * ecore_animator_custom_source_tick_begin_callback_set() and is called
3375 * when ticking is to stop. If @a func is @c NULL then no function is
3376 * called to stop ticking. For more information see
3377 * ecore_animator_custom_source_tick_begin_callback_set().
3378 *
3379 * @param[in] func The function to call when ticking is to end
3380 * @param[in] data The data passed to the tick end function as its parameter
3381 *
3382 * @see ecore_animator_source_set()
3383 * @see ecore_animator_custom_source_tick_begin_callback_set()
3384 * @see ecore_animator_custom_tick()
3385 */
3386EAPI void ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data);
3387
3388/**
3389 * @brief Triggers a custom animator tick.
3390 *
3391 * @since_tizen 2.3
3392 *
3393 * @remarks When animator source is set to @c ECORE_ANIMATOR_SOURCE_CUSTOM, then calling
3394 * this function triggers a run of all animators currently registered with
3395 * Ecore as this indicates that a "frame tick" happened. This does nothing if
3396 * the animator source(set by ecore_animator_source_set()) is not set to
3397 * @c ECORE_ANIMATOR_SOURCE_CUSTOM.
3398 *
3399 * @see ecore_animator_source_set()
3400 * @see ecore_animator_custom_source_tick_begin_callback_set
3401 * @see ecore_animator_custom_source_tick_end_callback_set()()
3402 */
3403EAPI void ecore_animator_custom_tick(void);
3404
3405/**
3406 * @}
3407 */
3408
3409/**
3410 * @defgroup Ecore_Job_Group Ecore Job
3411 * @ingroup Ecore_Main_Loop_Group
3412 *
3413 * @brief You can queue jobs that are to be done by the main loop when the
3414 * current event is dealt with.
3415 *
3416 * Jobs are processed by the main loop in a manner which is similar to events. They
3417 * are also executed in the order in which they are added.
3418 *
3419 * A good use for them is when you don't want to execute an action
3420 * immediately, but want to give the control back to the main loop
3421 * so that it calls your job callback when jobs start being
3422 * processed (and if there are other jobs added before yours, they
3423 * are processed first). This also gives a chance to other
3424 * actions in your program to cancel the job before it is started.
3425 *
3426 * @{
3427 */
3428
3429typedef struct _Ecore_Job Ecore_Job; /**< @brief A job handle */
3430
3431/**
3432 * @brief Add a job to the event queue.
3433 *
3434 * @since_tizen 2.3
3435 *
3436 * @remarks Once the job has been executed, the job handle is invalid.
3437 *
3438 * @param[in] func The function to call when the job gets handled.
3439 * @param[in] data Data pointer to be passed to the job function when the job is
3440 * handled.
3441 * @return The handle of the job. @c NULL is returned if the job could not be
3442 * added to the queue.
3443 */
3444EAPI Ecore_Job *ecore_job_add(Ecore_Cb func, const void *data);
3445
3446/**
3447 * @brief Delete a queued job that has not yet been executed.
3448 *
3449 * @since_tizen 2.3
3450 *
3451 * @param[in] job Handle of the job to delete.
3452 * @return The data pointer that was to be passed to the job.
3453 */
3454EAPI void *ecore_job_del(Ecore_Job *job);
3455
3456/**
3457 * @}
3458 */
360 3459
361#ifdef __cplusplus 3460#ifdef __cplusplus
362} 3461}
diff --git a/src/lib/ecore/Ecore_Getopt.h b/src/lib/ecore/Ecore_Getopt.h
index a20cc98e02..33661e4e90 100644
--- a/src/lib/ecore/Ecore_Getopt.h
+++ b/src/lib/ecore/Ecore_Getopt.h
@@ -31,168 +31,121 @@
31#endif /* ! _WIN32 */ 31#endif /* ! _WIN32 */
32 32
33/** 33/**
34 * @defgroup Ecore_Getopt_Group Ecore Getopt 34 * @internal
35 * @ingroup Ecore 35 * @file Ecore_Getopt.h
36 * 36 * @brief Contains powerful getopt replacement.
37 * This group contains powerful getopt replacement.
38 * 37 *
39 * This replacement handles both short (-X) or long options (--ABC) 38 * This replacement handles both short (-X) or long options (--ABC)
40 * options, with various actions supported, like storing one value and 39 * options, with various actions supported, like storing one value and
41 * already converting to required type, counting number of 40 * already converting to required type, counting number of
42 * occurrences, setting true or false values, show help, license, 41 * occurrences, setting true or false values, showing help, license,
43 * copyright and even support user-defined callbacks. 42 * copyright, and even supporting user-defined callbacks.
44 * 43 *
45 * It is provided a set of C Pre Processor macros so definition is 44 * It is provided a set of C Pre Processor macros. So definition is
46 * straightforward. 45 * straightforward.
47 * 46 *
48 * Values will be stored elsewhere indicated by an array of pointers 47 * Values are stored elsewhere indicated by an array of pointers
49 * to values, it is given in separate to parser description so you can 48 * to values. It is given separately to parser description. So you can
50 * use multiple values with the same parser. 49 * use multiple values with the same parser.
51 *
52 * @{
53 */ 50 */
54 51
55#ifdef __cplusplus 52#ifdef __cplusplus
56extern "C" { 53extern "C" {
57#endif 54#endif
58 55
59/**
60 * @typedef Ecore_Getopt_Action
61 * @brief Enumeration that defines the actions to do when parsing command line
62 * parameters.
63 */
64typedef enum { 56typedef enum {
65 ECORE_GETOPT_ACTION_STORE, /**< Store a value */ 57 ECORE_GETOPT_ACTION_STORE,
66 ECORE_GETOPT_ACTION_STORE_CONST, /**< Store a const */ 58 ECORE_GETOPT_ACTION_STORE_CONST,
67 ECORE_GETOPT_ACTION_STORE_TRUE, /**< Store TRUE */ 59 ECORE_GETOPT_ACTION_STORE_TRUE,
68 ECORE_GETOPT_ACTION_STORE_FALSE, /**< Store FALSE */ 60 ECORE_GETOPT_ACTION_STORE_FALSE,
69 ECORE_GETOPT_ACTION_CHOICE, /**< Store a choice between several values */ 61 ECORE_GETOPT_ACTION_CHOICE,
70 ECORE_GETOPT_ACTION_APPEND, /**< Allocate and store a new value of type Ecore_Getopt_Type */ 62 ECORE_GETOPT_ACTION_APPEND,
71 ECORE_GETOPT_ACTION_COUNT, /**< Store a count number */ 63 ECORE_GETOPT_ACTION_COUNT,
72 ECORE_GETOPT_ACTION_CALLBACK, /**< Call a callback */ 64 ECORE_GETOPT_ACTION_CALLBACK,
73 ECORE_GETOPT_ACTION_HELP, /**< Show help text */ 65 ECORE_GETOPT_ACTION_HELP,
74 ECORE_GETOPT_ACTION_VERSION, /**< Show version */ 66 ECORE_GETOPT_ACTION_VERSION,
75 ECORE_GETOPT_ACTION_COPYRIGHT, /**< Show copyright */ 67 ECORE_GETOPT_ACTION_COPYRIGHT,
76 ECORE_GETOPT_ACTION_LICENSE, /**< Show license */ 68 ECORE_GETOPT_ACTION_LICENSE
77 ECORE_GETOPT_ACTION_BREAK, /**< Stop parsing options */
78 ECORE_GETOPT_ACTION_CATEGORY
79} Ecore_Getopt_Action; 69} Ecore_Getopt_Action;
80 70
81/**
82 * @typedef Ecore_Getopt_Type
83 * @brief Enumeration that defines the type of the values to store when using
84 * append action.
85 */
86typedef enum { 71typedef enum {
87 ECORE_GETOPT_TYPE_STR, /**< Value of type string */ 72 ECORE_GETOPT_TYPE_STR,
88 ECORE_GETOPT_TYPE_BOOL, /**< Value of type boolean */ 73 ECORE_GETOPT_TYPE_BOOL,
89 ECORE_GETOPT_TYPE_SHORT, /**< Value of type short */ 74 ECORE_GETOPT_TYPE_SHORT,
90 ECORE_GETOPT_TYPE_INT, /**< Value of type int */ 75 ECORE_GETOPT_TYPE_INT,
91 ECORE_GETOPT_TYPE_LONG, /**< Value of type long */ 76 ECORE_GETOPT_TYPE_LONG,
92 ECORE_GETOPT_TYPE_USHORT, /**< Value of type unsigned short */ 77 ECORE_GETOPT_TYPE_USHORT,
93 ECORE_GETOPT_TYPE_UINT, /**< Value of type unsigned int */ 78 ECORE_GETOPT_TYPE_UINT,
94 ECORE_GETOPT_TYPE_ULONG, /**< Value of type unsigned long */ 79 ECORE_GETOPT_TYPE_ULONG,
95 ECORE_GETOPT_TYPE_DOUBLE /**< Value of type double */ 80 ECORE_GETOPT_TYPE_DOUBLE
96} Ecore_Getopt_Type; 81} Ecore_Getopt_Type;
97 82
98/**
99