1 #ifndef _ECORE_COMMON_H 2 #define _ECORE_COMMON_H 3 4 #include <Efl_Config.h> 5 6 /** 7 * @defgroup Ecore_Init_Group Ecore initialization, shutdown functions and reset on fork. 8 * @ingroup Ecore 9 * @{ 10 */ 11 12 /** 13 * Sets up connections, signal handlers, sockets etc. 14 * @return @c 1 or greater on success, @c 0 otherwise. 15 * 16 * This function sets up all singal handlers and the basic event loop. If it 17 * succeeds, @c 1 will be returned, otherwise @c 0 will be returned. 18 * 19 * @code 20 * #include <Ecore.h> 21 * 22 * int main(int argc, char **argv) 23 * { 24 * if (!ecore_init()) 25 * { 26 * printf("ERROR: Cannot init Ecore!\n"); 27 * return -1; 28 * } 29 * ecore_main_loop_begin(); 30 * ecore_shutdown(); 31 * } 32 * @endcode 33 * 34 * This function is affected by some environment variables: 35 * 36 * @li @c ECORE_NO_SYSTEM_MODULES=1 may be used to temporarily 37 * disable system modules, often useful for debug. 38 * 39 * @li @c ECORE_FPS_DEBUG=1 prints frames per second, usefult to 40 * detect lags and blocking calls. 41 * 42 * @li @c ECORE_MEM_STAT=1 will generate @c ecore_mem_stat.${PID} 43 * file with memory statistics. 44 * 45 * @li @c ECORE_ERROR_ABORT=1 will abort on errors. 46 * 47 * This function will call eina_init(), so other environment variables 48 * may apply. 49 */ 50 EAPI int ecore_init(void); 51 52 /** 53 * Shuts down connections, signal handlers sockets etc. 54 * 55 * @return @c 0 if ecore shuts down, greater than @c 0 otherwise. 56 * This function shuts down all things set up in ecore_init() and cleans up all 57 * event queues, handlers, filters, timers, idlers, idle enterers/exiters 58 * etc. set up after ecore_init() was called. 59 * 60 * Do not call this function from any callback that may be called from the main 61 * loop, as the main loop will then fall over and not function properly. 62 */ 63 EAPI int ecore_shutdown(void); 64 65 /** 66 * This function will propagate the events on the main loop. So you 67 * should call ecore_init() first, then register your callback on 68 * @c EFL_LOOP_EVENT_ARGUMENTS and finally call ecore_init_ex(). 69 * 70 * Once you are shuting down your program, you should symmetrically 71 * call ecore_shutdown_ex(). 72 */ 73 EAPI unsigned int ecore_init_ex(int argc, char **argv); 74 75 /** 76 * Shuts down connections, signal handlers sockets etc. 77 * 78 * @return @c 0 if ecore shuts down, greater than @c 0 otherwise. 79 * This function shuts down all things set up in ecore_init_ex() and cleans 80 * up all event queues, handlers, filters, timers, idlers, idle enterers/exiters 81 * etc. set up after ecore_init_ex() was called. 82 * 83 * Do not call this function from any callback that may be called from the main 84 * loop, as the main loop will then fall over and not function properly. 85 * 86 * Note: This function should be called in symetric to ecore_init_ex() 87 */ 88 EAPI unsigned int ecore_shutdown_ex(void); 89 90 /** 91 * @brief Inform EFL of the version this application was built for. 92 * 93 * This is transparently called from $EFL_MAIN(). 94 * 95 * @since 1.18 (as beta) 96 */ 97 EWAPI void efl_build_version_set(int vmaj, int vmin, int vmic, int revision, const char *flavor, const char *build_id); 98 99 /** 100 * @} 101 */ 102 103 /** 104 * @ingroup Ecore 105 * @defgroup Ecore_Main_Loop_Group Ecore main loop 106 * 107 * This group discusses functions that are acting on Ecore's main loop itself or 108 * on events and infrastructure directly linked to it. Most programs only need 109 * to start and end the main loop, the rest of the functions discussed here are 110 * meant to be used in special situations, and with great care. 111 * 112 * For details on the usage of ecore's main loop and how it interacts with other 113 * ecore facilities see: @ref Ecore_Main_Loop_Page. 114 * 115 * @{ 116 */ 117 118 #define ECORE_VERSION_MAJOR EFL_VERSION_MAJOR /**< Ecore version major number */ 119 #define ECORE_VERSION_MINOR EFL_VERSION_MINOR /**< Ecore version minor number */ 120 121 /** 122 * @typedef Ecore_Version 123 * 124 * This is the Ecore version information structure that can be used at 125 * runtime to detect which version of ecore is being used and adapt 126 * appropriately as follows for example: 127 * 128 * @code 129 * #if defined(ECORE_VERSION_MAJOR) && (ECORE_VERSION_MAJOR >= 1) && defined(ECORE_VERSION_MINOR) && (ECORE_VERSION_MINOR > 0) 130 * printf("Ecore version: %i.%i.%i\n", 131 * ecore_version->major, 132 * ecore_version->minor, 133 * ecore_version->micro); 134 * if (ecore_version->revision > 0) 135 * { 136 * printf(" Built from Git revision # %i\n", ecore_version->revision); 137 * } 138 * #endif 139 * @endcode 140 * 141 */ 142 typedef struct _Ecore_Version 143 { 144 int major; /** < major (binary or source incompatible changes) */ 145 int minor; /** < minor (new features, bugfixes, major improvements version) */ 146 int micro; /** < micro (bugfix, internal improvements, no new features version) */ 147 int revision; /** < git revision (0 if a proper release or the git revision number Ecore is built from) */ 148 } Ecore_Version; 149 150 EAPI extern Ecore_Version *ecore_version; 151 152 #define ECORE_CALLBACK_CANCEL EINA_FALSE /**< Return value to remove a callback */ 153 #define ECORE_CALLBACK_RENEW EINA_TRUE /**< Return value to keep a callback */ 154 155 #define ECORE_CALLBACK_PASS_ON EINA_TRUE /**< Return value to pass event to next handler */ 156 #define ECORE_CALLBACK_DONE EINA_FALSE /**< Return value to stop event handling */ 157 158 /** 159 * @typedef Ecore_Task_Cb Ecore_Task_Cb 160 * A callback run for a task (timer, idler, poller, animator, etc). 161 */ 162 typedef Eina_Bool (*Ecore_Task_Cb)(void *data); 163 164 /** 165 * @typedef Ecore_Select_Function 166 * A function which can be used to replace select() in the main loop. 167 */ 168 typedef int (*Ecore_Select_Function)(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout); 169 170 /** 171 * Runs a single iteration of the main loop to process everything on the 172 * queue. 173 * 174 * It does everything that is already done inside an @c Ecore main loop, like 175 * checking for expired timers, idlers, etc. But it will do it only once and 176 * return, instead of keeping watch for new events. 177 * 178 * DO NOT use this function unless you are the person God comes to ask for 179 * advice when He has trouble managing the Universe. 180 * 181 * @see ecore_main_loop_iterate_may_block() 182 */ 183 EAPI void ecore_main_loop_iterate(void); 184 185 /** 186 * Runs a single iteration of the main loop to process everything on the 187 * queue with blocking/non-blocking status. 188 * 189 * @param may_block A flag if the main loop has a possibility of blocking. 190 * (@c EINA_TRUE = may block/@c EINA_FALSE = non block) 191 * 192 * This is an extension API for ecore_main_loop_iterate() with additional 193 * parameter. It does everything that is already done inside an 194 * @c Ecore main loop, like checking for expired timers, idlers, etc. But it 195 * will do it only once and return, instead of keep watching for new events. 196 * 197 * DO NOT use this function unless you are the person God comes to ask for 198 * advice when He has trouble managing the Universe. 199 * 200 * @return @c 1 if event exists, else @c 0. 201 * @see ecore_main_loop_iterate() 202 */ 203 EAPI int ecore_main_loop_iterate_may_block(int may_block); 204 205 /** 206 * Sets the function to use when monitoring multiple file descriptors, 207 * and waiting until one of more of the file descriptors are ready 208 * for some class of I/O operation. 209 * 210 * This function will be used instead of the system call select and 211 * could possibly be used to integrate the Ecore event loop with an 212 * external event loop. 213 * 214 * @warning you don't know how to use, don't even try to use it. 215 * 216 * @param func The function to be used. 217 */ 218 EAPI void ecore_main_loop_select_func_set(Ecore_Select_Function func); 219 220 /** 221 * Gets the select function set by ecore_select_func_set(), 222 * or the native select function if none was set. 223 * 224 * @return A function which can be used to replace select() in the main loop. 225 * 226 */ 227 EAPI Ecore_Select_Function ecore_main_loop_select_func_get(void); 228 229 /** 230 * Requests ecore to integrate GLib's main loop. 231 * 232 * This will add a small overhead during every main loop interaction 233 * by checking GLib's default main context (used by its main loop). 234 * If it have events to be checked (timers, file descriptors or idlers), 235 * then these will be polled alongside with Ecore's own events, then 236 * dispatched before Ecore's. This is done by calling 237 * ecore_main_loop_select_func_set(). 238 * 239 * This will cooperate with previously set 240 * ecore_main_loop_select_func_set() by calling the old function. 241 * Similarly, if you want to override 242 * ecore_main_loop_select_func_set() after main loop is integrated, 243 * call the new select function set by this call (get it by calling 244 * ecore_main_loop_select_func_get() right after 245 * ecore_main_loop_glib_integrate()). 246 * 247 * This is useful to use GMainLoop libraries, like GTK, GUPnP, 248 * LibSoup, GConf and more. Adobe Flash plugin and other plugins 249 * systems depend on this as well. 250 * 251 * Once initialized/integrated, it will be valid until Ecore is 252 * completely shut down. 253 * 254 * Example of use: 255 * @code 256 * 257 * int main(void) 258 * { 259 * ecore_init(); 260 * ecore_main_loop_glib_integrate(); 261 * 262 * // some code here 263 * 264 * ecore_main_loop_begin(); 265 * 266 * ecore_shutdown(); 267 * 268 * return 0; 269 * } 270 * 271 * @endcode 272 * @return @c EINA_TRUE on success of, 273 * @c EINA_FALSE if it failed likely due to no GLib support in Ecore. 274 * @note This is only available if Ecore was compiled with GLib support. 275 * @note You don't need to call this function if Ecore was compiled with. 276 * --with-glib=always. 277 * 278 */ 279 EAPI Eina_Bool ecore_main_loop_glib_integrate(void); 280 281 /** 282 * Disables always integrating GLib. 283 * 284 * If ecore is compiled with --with-glib=always (to always call 285 * ecore_main_loop_glib_integrate() when ecore_init() is called), then calling 286 * this before calling ecore_init() will disable the integration. 287 * This is for apps that explicitly do not want this to happen for whatever 288 * reasons they may have. 289 */ 290 EAPI void ecore_main_loop_glib_always_integrate_disable(void); 291 292 /** 293 * Runs the application main loop. 294 * 295 * This function will not return until @ref ecore_main_loop_quit is called. It 296 * will check for expired timers, idlers, file descriptors being watched by fd 297 * handlers, etc. Once everything is done, before entering again on idle state, 298 * any callback set as @c Idle_Enterer will be called. 299 * 300 * This function should be called once only from the same thread that 301 * initted ecore, eina etc. (ecore_init(), eina_init(), ...) and should never 302 * be nested. Never call it from within an instance of itself. 303 * 304 * Each main loop iteration is done by calling ecore_main_loop_iterate() 305 * internally. 306 * 307 * The polling (select) function used can be changed with 308 * ecore_main_loop_select_func_set(). 309 * 310 * The function used to check for file descriptors, events, and that has a 311 * timeout for the timers can be changed using 312 * ecore_main_loop_select_func_set(). 313 */ 314 EAPI void ecore_main_loop_begin(void); 315 316 /** 317 * Quits the main loop once all the events currently on the queue have 318 * been processed. 319 * 320 * This function returns immediately, but if called inside the main loop 321 * it will mark the ecore_main_loop_begin() function to return at the 322 * end of the current main loop iteration. 323 * 324 */ 325 EAPI void ecore_main_loop_quit(void); 326 327 /** 328 * Returns if an animator has ticked off during this loop iteration. 329 * 330 * @return @c EINA_TRUE if an animator has been called, @c EINA_FALSE otherwise. 331 * 332 * There should be little need for anyone to use this - ever. 333 * 334 * @since 1.9 335 */ 336 EAPI Eina_Bool ecore_main_loop_animator_ticked_get(void); 337 338 /** 339 * Returns if the ecore_main_loop is running. 340 * 341 * @return An integer specifying if the ecore_main_loop is running, 342 * @c 0 if not running, 343 * > @c 0 if running 344 * 345 * @since 1.13 346 */ 347 EAPI int ecore_main_loop_nested_get(void); 348 349 /** 350 * @typedef Ecore_Cb Ecore_Cb 351 * A generic callback called as a hook when a certain point in 352 * execution is reached. 353 */ 354 typedef void (*Ecore_Cb)(void *data); 355 356 /** 357 * @typedef Ecore_Data_Cb Ecore_Data_Cb 358 * A callback which is used to return data to the main function 359 */ 360 typedef void *(*Ecore_Data_Cb)(void *data); 361 362 /** 363 * Adds a function to be called by ecore_fork_reset(). 364 * 365 * @param func The function to add. 366 * @param data The data to pass to this function. 367 * 368 * This queues @p func to be called (and passed @p data as its argument) when 369 * ecore_fork_reset() is called. This allows other libraries and subsystems 370 * to also reset their internal state after a fork. 371 * 372 * @return @c EINA_TRUE on success, else @c EINA_FALSE. 373 * @since 1.7 374 */ 375 EAPI Eina_Bool ecore_fork_reset_callback_add(Ecore_Cb func, const void *data); 376 377 /** 378 * This removes the callback specified. 379 * 380 * @param func The function to delete. 381 * @param data The data passed to this function. 382 * 383 * This deletes the callback added by ecore_fork_reset_callback_add() using 384 * the function and data pointer to specify which to remove. 385 * 386 * @return @c EINA_TRUE on success, else @c EINA_FALSE. 387 * @since 1.7 388 */ 389 EAPI Eina_Bool ecore_fork_reset_callback_del(Ecore_Cb func, const void *data); 390 391 /** 392 * Resets the ecore internal state after a fork. 393 * 394 * Ecore maintains internal data that can be affected by the fork() system call 395 * which creates a duplicate of the current process. This also duplicates 396 * file descriptors which is problematic in that these file descriptors still 397 * point to their original sources. This function makes ecore reset internal 398 * state (e.g. pipes used for signalling between threads) so they function 399 * correctly afterwards. 400 * 401 * It is highly suggested that you call this function after any fork() 402 * system call inside the child process if you intend to use ecore features 403 * after this point and not call any exec() family functions. Not doing so 404 * will cause possible misbehaviour. 405 * 406 * @since 1.7 407 */ 408 EAPI void ecore_fork_reset(void); 409 410 /** 411 * @brief Calls callback asynchronously in the main loop. 412 * @since 1.1.0 413 * 414 * @param callback The callback to call in the main loop 415 * @param data The data to give to that call back 416 * 417 * For all calls that need to happen in the main loop (most EFL functions do), 418 * this helper function provides the infrastructure needed to do it safely 419 * by avoiding dead lock, race condition and properly wake up the main loop. 420 * 421 * Remember after that function call, you should never touch again the @p data 422 * in the thread, it is owned by the main loop and your callback should take 423 * care of freeing it if necessary. 424 */ 425 EAPI void ecore_main_loop_thread_safe_call_async(Ecore_Cb callback, void *data); 426 427 /** 428 * @brief Calls callback synchronously in the main loop. 429 * @since 1.1.0 430 * 431 * @param callback The callback to call in the main loop 432 * @param data The data to give to that call back 433 * @return The value returned by the callback in the main loop. 434 * 435 * For all calls that need to happen in the main loop (most EFL functions do), 436 * this helper function provides the infrastructure needed to do it safely 437 * by avoiding dead lock, race condition and properly wake up the main loop. 438 * 439 * Remember this function will block until the callback is executed in the 440 * main loop. It can take time and you have no guaranty about the timeline. 441 */ 442 EAPI void *ecore_main_loop_thread_safe_call_sync(Ecore_Data_Cb callback, void *data); 443 444 /** 445 * @brief Waits for the next thread call in the main loop. 446 * @since 1.13.0 447 * 448 * @param wait How long to wait for this callback to be called. 449 * 450 * Note: This function should only be called in the main loop 451 * and will actually block the main loop until either a call 452 * is triggered from a thread or the time specified by wait has 453 * passed. 454 */ 455 EAPI void ecore_main_loop_thread_safe_call_wait(double wait); 456 457 /** 458 * @brief This function suspends the main loop in a know state. 459 * @since 1.1.0 460 * 461 * @result The number of time ecore_thread_main_loop_begin() has been called 462 * in this thread, if the main loop was suspended correctly. If not, it return @c -1. 463 * 464 * This function suspend the main loop in a know state, this let you 465 * use any EFL call you want after it return. Be carefully, the main loop 466 * is blocked until you call ecore_thread_main_loop_end(). This is 467 * the only sane way to achieve pseudo thread safety. 468 * 469 * Notice that until the main loop is blocked, the thread is blocked 470 * and their is noway around that. 471 * 472 * We still advise you, when possible, to use ecore_main_loop_thread_safe_call_async() 473 * as it will not block the thread nor the main loop. 474 */ 475 EAPI int ecore_thread_main_loop_begin(void); 476 477 /** 478 * @brief Unlocks the main loop. 479 * @since 1.1.0 480 * 481 * @result The number of time ecore_thread_main_loop_end() need to be called before 482 * the main loop is unlocked again. @c -1 will be returned if you are trying to unlock 483 * when there wasn't enough call to ecore_thread_main_loop_begin(). 484 * 485 * After a call to ecore_thread_main_loop_begin(), you need to absolutely 486 * call ecore_thread_main_loop_end(), or you application will stay frozen. 487 */ 488 EAPI int ecore_thread_main_loop_end(void); 489 490 /** 491 * @} 492 */ 493 494 /** 495 * @ingroup Ecore_Main_Loop_Group 496 * @defgroup Ecore_Event_Group Ecore Event functions 497 * 498 * Ecore events provide two main features that are of use to those using ecore: 499 * creating events and being notified of events. Those two will usually be used 500 * in different contexts, creating events is mainly done by libraries wrapping 501 * some system functionality while being notified of events is mainly a 502 * necessity of applications. 503 * 504 * For a program to be notified of events it's interested in it needs to have a 505 * function to process the event and to register that function as the callback 506 * to the event, that's all: 507 * @code 508 * ecore_event_handler_add(EVENT_TYPE, _my_event_handler, some_data); 509 * ... 510 * static Eina_Bool 511 * _my_event_handler(void *data, int type, void *event) 512 * { 513 * //data is some_data 514 * //event is provided by whoever created the event 515 * //Do really cool stuff with event 516 * } 517 * @endcode 518 * 519 * One very important thing to note here is the @c EVENT_TYPE, to register a 520 * handler for an event you must know its type before hand. Ecore provides 521 * the following events which are emitted in response to POSIX 522 * signals(https://en.wikipedia.org/wiki/Signal_%28computing%29): 523 * @li @b ECORE_EVENT_SIGNAL_USER 524 * @li @b ECORE_EVENT_SIGNAL_HUP 525 * @li @b ECORE_EVENT_SIGNAL_POWER 526 * @li @b ECORE_EVENT_SIGNAL_EXIT 527 * 528 * @warning Don't override these using the @c signal or @c sigaction calls. 529 * These, however, aren't the only signals one can handle. Many 530 * libraries(including ecore modules) have their own signals that can be 531 * listened for and handled, to do that one only needs to know the type of the 532 * event. This information can be found on the documentation of the library 533 * emitting the signal, so, for example, for events related to windowing one 534 * would look in @ref Ecore_Evas_Group. 535 * 536 * Examples of libraries that integrate into ecore's main loop by providing 537 * events are @ref Ecore_Con_Group, @ref Ecore_Evas_Group and @ref 538 * Ecore_Exe_Group, amongst others. This usage can be divided into two parts, 539 * setup and adding events. The setup is very simple, all that needs doing is 540 * getting a type id for the event: 541 * @code 542 * int MY_EV_TYPE = ecore_event_type_new(); 543 * @endcode 544 * @note This variable should be declared in the header since it'll be needed by 545 * anyone wishing to register a handler to your event. 546 * 547 * The complexity of adding of an event to the queue depends on whether that 548 * event sends uses @c event, if it doesn't it a one-liner: 549 * @code 550 * ecore_event_add(MY_EV_TYPE, NULL, NULL, NULL); 551 * @endcode 552 * The usage when an @c event is needed is not that much more complex and can be 553 * seen in @ref ecore_event_add. 554 * 555 * Examples that deals with events: 556 * @li @ref ecore_event_example_01_c 557 * @li @ref ecore_event_example_02_c 558 * 559 * @{ 560 */ 561 562 #define ECORE_EVENT_NONE 0 /**< None event */ 563 #define ECORE_EVENT_SIGNAL_USER 1 /**< User signal event */ 564 #define ECORE_EVENT_SIGNAL_HUP 2 /**< Hup signal event */ 565 #define ECORE_EVENT_SIGNAL_EXIT 3 /**< Exit signal event */ 566 #define ECORE_EVENT_SIGNAL_POWER 4 /**< Power signal event */ 567 #define ECORE_EVENT_SIGNAL_REALTIME 5 /**< Realtime signal event */ 568 #define ECORE_EVENT_MEMORY_STATE 6 /**< Memory state changed, see ecore_memory_state_get() */ 569 #define ECORE_EVENT_POWER_STATE 7 /**< Power state changed, see ecore_power_state_get() */ 570 #define ECORE_EVENT_LOCALE_CHANGED 8 /**< Locale changed */ 571 #define ECORE_EVENT_HOSTNAME_CHANGED 9 /**< Hostname changed */ 572 #define ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED 10 /**< Time or Date changed */ 573 #define ECORE_EVENT_COUNT 11 /**< Number of events */ 574 575 typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler; /**< A handle for HANDLE handlers on Windows */ 576 typedef struct _Ecore_Event_Handler Ecore_Event_Handler; /**< A handle for an event handler */ 577 typedef struct _Ecore_Event_Filter Ecore_Event_Filter; /**< A handle for an event filter */ 578 typedef struct _Ecore_Event Ecore_Event; /**< A handle for an event */ 579 typedef struct _Ecore_Event_Signal_User Ecore_Event_Signal_User; /**< User signal event */ 580 typedef struct _Ecore_Event_Signal_Hup Ecore_Event_Signal_Hup; /**< Hup signal event */ 581 typedef struct _Ecore_Event_Signal_Exit Ecore_Event_Signal_Exit; /**< Exit signal event */ 582 typedef struct _Ecore_Event_Signal_Power Ecore_Event_Signal_Power; /**< Power signal event */ 583 typedef struct _Ecore_Event_Signal_Realtime Ecore_Event_Signal_Realtime; /**< Realtime signal event */ 584 585 /** 586 * @typedef Ecore_Filter_Cb 587 * A callback used for filtering events from the main loop. 588 */ 589 typedef Eina_Bool (*Ecore_Filter_Cb)(void *data, void *loop_data, int type, void *event); 590 591 /** 592 * @typedef Ecore_End_Cb Ecore_End_Cb 593 * This is the callback which is called at the end of a function, 594 * usually for cleanup purposes. 595 */ 596 typedef void (*Ecore_End_Cb)(void *user_data, void *func_data); 597 598 /** 599 * @typedef Ecore_Event_Handler_Cb Ecore_Event_Handler_Cb 600 * A callback used by the main loop to handle events of a specified 601 * type. 602 */ 603 typedef Eina_Bool (*Ecore_Event_Handler_Cb)(void *data, int type, void *event); 604 605 /** 606 * @struct _Ecore_Event_Signal_User 607 * @brief A structure that stores information of a User signal event. 608 */ 609 struct _Ecore_Event_Signal_User 610 { 611 int number; /**< The signal number. Either 1 or 2 */ 612 void *ext_data; /**< Extension data - not used */ 613 614 #if !defined (_WIN32) && !defined (__lv2ppu__) 615 siginfo_t data; /**< Signal info */ 616 #endif 617 }; 618 619 /** 620 * @struct _Ecore_Event_Signal_Hup 621 * @brief A structure that stores information of a Hup signal event. 622 */ 623 struct _Ecore_Event_Signal_Hup 624 { 625 void *ext_data; /**< Extension data - not used */ 626 627 #if !defined (_WIN32) && !defined (__lv2ppu__) 628 siginfo_t data; /**< Signal info */ 629 #endif 630 }; 631 632 /** 633 * @struct _Ecore_Event_Signal_Exit 634 * @brief A structure that stores information of an Exit request event. 635 */ 636 struct _Ecore_Event_Signal_Exit 637 { 638 Eina_Bool interrupt : 1; /**< Set if the exit request was an interrupt signal*/ 639 Eina_Bool quit : 1; /**< set if the exit request was a quit signal */ 640 Eina_Bool terminate : 1; /**< Set if the exit request was a terminate signal */ 641 void *ext_data; /**< Extension data - not used */ 642 643 #if !defined (_WIN32) && !defined (__lv2ppu__) 644 siginfo_t data; /**< Signal info */ 645 #endif 646 }; 647 648 /** 649 * @struct _Ecore_Event_Signal_Power 650 * @brief A structure that stores information of a Power event. 651 */ 652 struct _Ecore_Event_Signal_Power 653 { 654 void *ext_data; /**< Extension data - not used */ 655 656 #if !defined (_WIN32) && !defined (__lv2ppu__) 657 siginfo_t data; /**< Signal info */ 658 #endif 659 }; 660 661 /** 662 * @struct _Ecore_Event_Signal_Realtime 663 * @brief A structure that stores information of a Realtime event. 664 */ 665 struct _Ecore_Event_Signal_Realtime 666 { 667 int num; /**< The realtime signal's number */ 668 669 #if !defined (_WIN32) && !defined (__lv2ppu__) 670 siginfo_t data; /**< Signal info */ 671 #endif 672 }; 673 674 /** 675 * @brief Adds an event handler. 676 * @param type The type of the event this handler will get called for 677 * @param func The function to call when the event is found in the queue 678 * @param data A data pointer to pass to the called function @p func 679 * @return A new Event handler, or @c NULL on failure. 680 * 681 * Add an event handler to the list of handlers. This will, on success, return 682 * a handle to the event handler object that was created, that can be used 683 * later to remove the handler using ecore_event_handler_del(). The @p type 684 * parameter is the integer of the event type that will trigger this callback 685 * to be called. The callback @p func is called when this event is processed 686 * and will be passed the event type, a pointer to the private event 687 * structure that is specific to that event type, and a data pointer that is 688 * provided in this call as the @p data parameter. 689 * 690 * When the callback @p func is called, it must return @c 1 or @c 0. If it returns 691 * @c 1 (or @c ECORE_CALLBACK_PASS_ON), It will keep being called as per normal, for 692 * each handler set up for that event type. If it returns @c 0 (or 693 * @c ECORE_CALLBACK_DONE), it will cease processing handlers for that particular 694 * event, so all handler set to handle that event type that have not already 695 * been called, will not be. 696 */ 697 EAPI Ecore_Event_Handler *ecore_event_handler_add(int type, Ecore_Event_Handler_Cb func, const void *data); 698 699 /** 700 * @brief Adds an event handler to the beginning of the handler list. 701 * @param type The type of the event this handler will get called for 702 * @param func The function to call when the event is found in the queue 703 * @param data A data pointer to pass to the called function @p func 704 * @return A new Event handler, or @c NULL on failure. 705 * 706 * This function is identical to ecore_event_handler_add() except that it 707 * creates the handler at the start of the list. Do not use this function. 708 * @since 1.21 709 */ 710 EAPI Ecore_Event_Handler *ecore_event_handler_prepend(int type, Ecore_Event_Handler_Cb func, const void *data); 711 712 /** 713 * @brief Deletes an event handler. 714 * @param event_handler Event handler handle to delete 715 * @return Data passed to handler 716 * 717 * Delete a specified event handler from the handler list. On success this will 718 * delete the event handler and return the pointer passed as @p data when the 719 * handler was added by ecore_event_handler_add(). On failure @c NULL will be 720 * returned. Once a handler is deleted it will no longer be called. 721 */ 722 EAPI void *ecore_event_handler_del(Ecore_Event_Handler *event_handler); 723 724 /** 725 * @brief Adds an event to the event queue. 726 * @param type The event type to add to the end of the event queue 727 * @param ev The data structure passed as @c event to event handlers 728 * @param func_free The function to be called to free @a ev 729 * @param data The data pointer to be passed to the free function 730 * @return A Handle for that event on success, otherwise NULL 731 * 732 * If it succeeds, an event of type @a type will be added to the queue for 733 * processing by event handlers added by ecore_event_handler_add(). The @a ev 734 * parameter will be passed as the @c event parameter of the handler. When the 735 * event is no longer needed, @a func_free will be called and passed @a ev for 736 * cleaning up. If @p func_free is NULL, free() will be called with the private 737 * structure pointer. 738 */ 739 EAPI Ecore_Event *ecore_event_add(int type, void *ev, Ecore_End_Cb func_free, void *data); 740 741 /** 742 * @brief Deletes an event from the queue. 743 * @param event The event handle to delete 744 * @return The data pointer originally set for the event free function 745 * 746 * This deletes the event @p event from the event queue, and returns the 747 * @p data parameter originally set when adding it with ecore_event_add(). This 748 * does not immediately call the free function, and it may be called later on 749 * cleanup, and so if the free function depends on the data pointer to work, 750 * you should defer cleaning of this till the free function is called later. 751 */ 752 EAPI void *ecore_event_del(Ecore_Event *event); 753 754 /** 755 * @brief Gets the data associated with an #Ecore_Event_Handler. 756 * @param eh The event handler 757 * @return The data 758 * 759 * This function returns the data previously associated with @p eh by 760 * ecore_event_handler_add(). 761 */ 762 EAPI void *ecore_event_handler_data_get(Ecore_Event_Handler *eh); 763 764 /** 765 * @brief Sets the data associated with an #Ecore_Event_Handler. 766 * @param eh The event handler 767 * @param data The data to associate 768 * @return The previous data 769 * 770 * This function sets @p data to @p eh and returns the old data pointer 771 * which was previously associated with @p eh by ecore_event_handler_add(). 772 */ 773 EAPI void *ecore_event_handler_data_set(Ecore_Event_Handler *eh, const void *data); 774 775 /** 776 * @brief Allocates a new event type id sensibly and returns the new id. 777 * @return A new event type id. 778 * 779 * This function allocates a new event type id and returns it. Once an event 780 * type has been allocated it can never be de-allocated during the life of 781 * the program. There is no guarantee of the contents of this event ID, or how 782 * it is calculated, except that the ID will be unique to the current instance 783 * of the process. 784 */ 785 EAPI int ecore_event_type_new(void); 786 787 /** 788 * @brief Forcefully flush all pending type without processing them 789 * @param type Ecore_Event. 790 * @param ... Serie of Ecore_Event finished by ECORE_EVENT_NONE. 791 * 792 * This function is to be called before calling ecore_shutdown() if any event 793 * has still a chance to be in the ecore event queue. 794 */ 795 EAPI void ecore_event_type_flush_internal(int type, ...); 796 797 /** 798 * @brief Forcefully flush all pending type without processing them 799 * @param ... Serie of Ecore_Event. 800 * 801 * This function is to be called before calling ecore_shutdown() if any event 802 * has still a chance to be in the ecore event queue. 803 */ 804 #define ecore_event_type_flush(...) \ 805 ecore_event_type_flush_internal(__VA_ARGS__, ECORE_EVENT_NONE); 806 807 808 /** 809 * @brief Adds a filter the current event queue. 810 * 811 * @param func_start Function to call just before filtering and return data 812 * @param func_filter Function to call on each event 813 * @param func_end Function to call after the queue has been filtered 814 * @param data Data to pass to the filter functions 815 * @return A filter handle on success, @c NULL otherwise. 816 * 817 * Adds a callback to filter events from the event queue. Filters are called on 818 * the queue just before Event handler processing to try and remove redundant 819 * events. Just as processing is about to start @a func_start is called and 820 * passed the @a data pointer, the return value of this functions is passed to 821 * @a func_filter as loop_data. @a func_filter is also passed @a data and the 822 * event type and event structure. If this @a func_filter returns 823 * @c EINA_FALSE, the event is removed from the queue, if it returns 824 * @c EINA_TRUE, the event is kept. When processing is finished @p func_end is 825 * called and is passed the loop_data(returned by @c func_start) and @p data 826 * pointer to clean up. 827 */ 828 EAPI Ecore_Event_Filter *ecore_event_filter_add(Ecore_Data_Cb func_start, Ecore_Filter_Cb func_filter, Ecore_End_Cb func_end, const void *data); 829 830 /** 831 * @brief Deletes an event filter. 832 * @param ef The event filter handle 833 * @return The data set for the filter on success, @c NULL otherwise. 834 * 835 * Delete a filter that has been added by its @p ef handle. 836 */ 837 EAPI void *ecore_event_filter_del(Ecore_Event_Filter *ef); 838 839 /** 840 * @brief Returns the current event type being handled. 841 * @return The current event type being handled if inside a handler callback, 842 * @c ECORE_EVENT_NONE otherwise. 843 * 844 * If the program is currently inside an Ecore event handler callback this 845 * will return the type of the current event being processed. 846 * 847 * This is useful when certain Ecore modules such as Ecore_Evas "swallow" 848 * events and not all the original information is passed on. In special cases 849 * this extra information may be useful or needed and using this call can let 850 * the program know if the event type being handled is one it wants to get more 851 * information about. 852 */ 853 EAPI int ecore_event_current_type_get(void); 854 855 /** 856 * @brief Returns the current event type pointer handled. 857 * @return The current event pointer being handled if inside a handler callback, 858 * @c NULL otherwise. 859 * 860 * If the program is currently inside an Ecore event handler callback this 861 * will return the pointer of the current event being processed. 862 * 863 * This is useful when certain Ecore modules such as Ecore_Evas "swallow" 864 * events and not all the original information is passed on. In special cases 865 * this extra information may be useful or needed and using this call can let 866 * the program access the event data if the type of the event is handled by 867 * the program. 868 */ 869 EAPI void *ecore_event_current_event_get(void); 870 871 /** 872 * @} 873 */ 874 875 /** 876 * @ingroup Ecore_Event_Group 877 * @defgroup Ecore_System_Events System Events 878 * 879 * Ecore is aware of some system events that one may be interested, they are described below: 880 * 881 * @li #ECORE_EVENT_MEMORY_STATE indicates system changed its free 882 * memory status, going to or being back from "low memory" 883 * state. When going to low memory state the libraries and 884 * applications may help the system by reducing memory usage, 885 * dropping caches and unused resources. The event carries no 886 * information, the current state should be queried with 887 * ecore_low_memory_get(). 888 * @li #ECORE_EVENT_POWER_STATE indicates system changed its battery 889 * level, going to or being back from "low battery" state. When 890 * going to low battery state the libraries and applications may 891 * help the system by reducing number of wake ups and processing, 892 * increasing @ref Ecore_Animator frame time values, reducing the 893 * number of @ref Ecore_Timer and @ref Ecore_Idler or even going 894 * to extreme of trading quality over speed to finish tasks 895 * sooner. The event carries no information, the current state 896 * should be queried with ecore_low_battery_get(). 897 * @li #ECORE_EVENT_LOCALE_CHANGED indicates the system locale and/or 898 * language changed. This event carries no information and there 899 * is no ecore specific call to get the new locale. It is advised 900 * that the emitter of this event to set the new locale, for 901 * instance in POSIX one should call setlocale() before adding the 902 * event. Libraries and applications should then reload their 903 * resources and reformat their strings to use the new values. 904 * @li #ECORE_EVENT_HOSTNAME_CHANGED indicates the system hostname 905 * changed. This event carries no information and the new value 906 * should be queried with platform specific calls, such as 907 * gethostname() on POSIX. 908 * @li #ECORE_EVENT_SYSTEM_TIMEDATE_CHANGED indicates the system time 909 * or date changed. This may happen as result of Daylight Saving 910 * changes, NTP fixing the clock, changing timezones or user 911 * setting a new date manually. This event carries no information 912 * and the new value should be queried with ecore_time_unix_get() 913 * or platform specific such as gettimeofday() 914 * @{ 915 */ 916 917 /** 918 * @enum _Ecore_Memory_State 919 * Indicates current system memory state. 920 * @since 1.8 921 */ 922 enum _Ecore_Memory_State /* Memory state */ 923 { 924 ECORE_MEMORY_STATE_NORMAL, /**< The normal memory usage state. No need to do anything special here - operation as normal. */ 925 ECORE_MEMORY_STATE_LOW /**< The system is low on memory resources. This would indicate that it may be a good idea to free memory you don't need and minimize footprint to avoid general system problems. */ 926 }; 927 typedef enum _Ecore_Memory_State Ecore_Memory_State; 928 929 /** 930 * @brief Gets the current status of memory on the system. 931 * @return The current memory state for the system as a whole. 932 * @since 1.8 933 */ 934 EAPI Ecore_Memory_State ecore_memory_state_get(void); 935 936 /** 937 * @brief Sets the memory state. 938 * @param state The memory state to set. 939 * 940 * This function will store information about the current 941 * memory state and if it changed will automatically create an 942 * #ECORE_EVENT_MEMORY_STATE event. 943 * 944 * @note This function should not be called by user, instead a 945 * monitoring entity that is system dependent. Usually an ecore module 946 * that is platform-specific. 947 * 948 * @since 1.8 949 */ 950 EAPI void ecore_memory_state_set(Ecore_Memory_State state); 951 952 953 /** 954 * @enum _Ecore_Power_State 955 * Indicates current system memory state. 956 * @since 1.8 957 */ 958 enum _Ecore_Power_State /* Power state */ 959 { 960 ECORE_POWER_STATE_MAINS, /**< The system is connected to a mains supply of power, thus there is no need to limit processing to save battery life at all. */ 961 ECORE_POWER_STATE_BATTERY, /**< The system is running off battery power, but is otherwise running normally. */ 962 ECORE_POWER_STATE_LOW, /**< The system is low on power (on battery) and the process should do its best to conserve power. For example it may reduce or suspend polling of network resources, turn off animations or reduce framerate etc. */ 963 //ECORE_POWER_STATE_CRITICAL, /**< The system is very low on power (on battery) and the process should begin taking even more conservative action @since 1.13*/ 964 //ECORE_POWER_STATE_EMERGENCY /**< The system is extremely low on power (on battery) and the process should prepare for suspend/hibernate/power loss @since 1.13 */ 965 }; 966 typedef enum _Ecore_Power_State Ecore_Power_State; 967 968 /** 969 * @brief Gets the current power state. 970 * @return The current power state for the system. 971 * @since 1.8 972 */ 973 EAPI Ecore_Power_State ecore_power_state_get(void); 974 975 /** 976 * @brief Sets the power state. 977 * @param state The power state to set. 978 * 979 * This function will store information about the current power 980 * state and if it changed will automatically create an 981 * #ECORE_EVENT_POWER_STATE event. 982 * 983 * @note This function should not be called by user, instead a 984 * monitoring entity that is system dependent. Usually an ecore module 985 * that is platform-specific. 986 * 987 * @since 1.8 988 */ 989 EAPI void ecore_power_state_set(Ecore_Power_State state); 990 991 /** 992 * @} 993 */ 994 995 996 997 /** 998 * @ingroup Ecore_Main_Loop_Group 999 * @defgroup Ecore_Exe_Group Process Spawning Functions 1000 * 1001 * This module is responsible for managing portable processes using Ecore. 1002 * With this module you're able to spawn processes and you also can pause, 1003 * quit your spawned processes. 1004 * An interaction between your process and those spawned is possible 1005 * using pipes or signals. 1006 * 1007 * Example 1008 * @li @ref Ecore_exe_simple_example_c 1009 * 1010 * 1011 * @{ 1012 */ 1013 1014 /** Inherit priority from parent process */ 1015 #define ECORE_EXE_PRIORITY_INHERIT 9999 1016 1017 EAPI extern int ECORE_EXE_EVENT_ADD; /**< A child process has been added */ 1018 EAPI extern int ECORE_EXE_EVENT_DEL; /**< A child process has been deleted (it exited, naming consistent with the rest of ecore). */ 1019 EAPI extern int ECORE_EXE_EVENT_DATA; /**< Data from a child process. */ 1020 EAPI extern int ECORE_EXE_EVENT_ERROR; /**< Errors from a child process. */ 1021 1022 /** 1023 * @enum _Ecore_Exe_Win32_Priority 1024 * Defines the priority of the process. 1025 */ 1026 enum _Ecore_Exe_Win32_Priority 1027 { 1028 ECORE_EXE_WIN32_PRIORITY_IDLE, /**< Idle priority, for monitoring the system */ 1029 ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL, /**< Below default priority */ 1030 ECORE_EXE_WIN32_PRIORITY_NORMAL, /**< Default priority */ 1031 ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL, /**< Above default priority */ 1032 ECORE_EXE_WIN32_PRIORITY_HIGH, /**< High priority, use with care as other threads in the system will not get processor time */ 1033 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 */ 1034 }; 1035 typedef enum _Ecore_Exe_Win32_Priority Ecore_Exe_Win32_Priority; 1036 1037 #include "ecore_exe_eo.legacy.h" 1038 1039 #define _ECORE_EXE_EO_CLASS_TYPE 1040 1041 /** 1042 * @typedef Ecore_Exe_Cb Ecore_Exe_Cb 1043 * A callback to run with the associated @ref Ecore_Exe, usually 1044 * for cleanup purposes. 1045 */ 1046 typedef void (*Ecore_Exe_Cb)(void *data, const Ecore_Exe *exe); 1047 1048 typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add; /**< Spawned Exe add event */ 1049 typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del; /**< Spawned Exe exit event */ 1050 1051 /** 1052 * @struct _Ecore_Exe_Event_Add 1053 * @brief Definition for a structure that stores information of a Process add event. 1054 */ 1055 struct _Ecore_Exe_Event_Add 1056 { 1057 Ecore_Exe *exe; /**< The handle to the added process */ 1058 void *ext_data; /**< Extension data - not used */ 1059 }; 1060 1061 /** 1062 * @struct _Ecore_Exe_Event_Del 1063 * @brief Definition for a structure that stores information of a Process exit event. 1064 */ 1065 struct _Ecore_Exe_Event_Del 1066 { 1067 pid_t pid; /**< The process ID of the process that exited */ 1068 int exit_code; /**< The exit code of the process */ 1069 Ecore_Exe *exe; /**< The handle to the exited process, or @c NULL if not found */ 1070 int exit_signal; /**< The signal that caused the process to exit */ 1071 Eina_Bool exited : 1; /**< Set to 1 if the process exited of its own accord */ 1072 Eina_Bool signalled : 1; /**< Set to 1 if the process exited due to uncaught signal */ 1073 void *ext_data; /**< Extension data - not used */ 1074 #if !defined (_WIN32) && !defined (__lv2ppu__) 1075 siginfo_t data; /**< Signal info */ 1076 #endif 1077 }; 1078 1079 /** 1080 * Sets the priority at which to launch processes. 1081 * 1082 * This sets the priority of processes run by ecore_exe_run() and 1083 * ecore_exe_pipe_run(). 1084 * @li On Windows, the child process is created by default with the 1085 * @ref ECORE_EXE_WIN32_PRIORITY_NORMAL priority, unless the calling 1086 * process is in @ref ECORE_EXE_WIN32_PRIORITY_IDLE or 1087 * @ref ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL priority. In that case, the 1088 * child process inherits this priority. 1089 * @li On other platforms, if set to @ref ECORE_EXE_PRIORITY_INHERIT child 1090 * processes inherits the priority of their parent. This is the default. 1091 * 1092 * @param pri Value an Ecore_Exe_Win32_Priority value on Windows, @c -20 1093 * to @c 19 or @ref ECORE_EXE_PRIORITY_INHERIT on other OS. 1094 * 1095 */ 1096 EAPI void ecore_exe_run_priority_set(int pri); 1097 1098 /** 1099 * Gets the priority at which to launch processes. 1100 * 1101 * This gets the priority of launched processes. See 1102 * ecore_exe_run_priority_set() for details. This just returns the value set 1103 * by this call. 1104 * 1105 * @return The value set by ecore_exe_run_priority_set() 1106 */ 1107 EAPI int ecore_exe_run_priority_get(void); 1108 1109 /** 1110 * Spawns a child process. 1111 * 1112 * This is now just a thin wrapper around ecore_exe_pipe_run() 1113 * @param exe_cmd The command to run with @c /bin/sh. 1114 * @param data Data to attach to the returned process handle. 1115 * @return A process handle to the spawned process. 1116 * @note When you use this function you will have no permissions 1117 * to write or read on the pipe that connects you with the spawned process. 1118 * If you need to do that use ecore_exe_pipe_run() with the 1119 * appropriated flags. 1120 * 1121 */ 1122 EAPI Ecore_Exe *ecore_exe_run(const char *exe_cmd, const void *data); 1123 1124 /** 1125 * Spawns a child process with its stdin/out available for communication. 1126 * 1127 * This function forks and runs the given command using @c /bin/sh. 1128 * 1129 * Note that the process handle is only valid until a child process 1130 * terminated event is received. After all handlers for the child process 1131 * terminated event have been called, the handle will be freed by Ecore. 1132 * 1133 * This function does the same thing as ecore_exe_run(), but also makes the 1134 * standard in and/or out as well as stderr from the child process available 1135 * for reading or writing. To write use ecore_exe_send(). To read listen to 1136 * ECORE_EXE_EVENT_DATA or ECORE_EXE_EVENT_ERROR events (set up handlers). 1137 * Ecore may buffer read and error data until a newline character if asked 1138 * for with the @p flags. All data will be included in the events (newlines 1139 * will be replaced with NULLS if line buffered). ECORE_EXE_EVENT_DATA events 1140 * will only happen if the process is run with ECORE_EXE_PIPE_READ enabled 1141 * in the flags. The same with the error version. Writing will only be 1142 * allowed with ECORE_EXE_PIPE_WRITE enabled in the flags. 1143 * 1144 * @param exe_cmd The command to run with @c /bin/sh. 1145 * @param flags The flag parameters for how to deal with inter-process I/O 1146 * @param data Data to attach to the returned process handle. 1147 * @return A process handle to the spawned process. 1148 */ 1149 EAPI Ecore_Exe *ecore_exe_pipe_run(const char *exe_cmd, Ecore_Exe_Flags flags, const void *data); 1150 1151 /** 1152 * Defines a function to be called before really freeing the handle data. 1153 * 1154 * This might be useful for language bindings such as Python and Perl 1155 * that need to deallocate wrappers associated with this handle. 1156 * 1157 * This handle should never be modified by this call. It should be 1158 * considered informative only. All getters are valid when the given 1159 * function is called back. 1160 * 1161 * @param exe The child process to attach the pre_free function. 1162 * @param func The function to call before @a exe is freed. 1163 */ 1164 EAPI void ecore_exe_callback_pre_free_set(Ecore_Exe *exe, Ecore_Exe_Cb func); 1165 1166 /** 1167 * Sends data to the given child process which it receives on stdin. 1168 * 1169 * This function writes to a child processes standard in, with unlimited 1170 * buffering. This call will never block. It may fail if the system runs out 1171 * of memory. 1172 * 1173 * @param exe The child process to send to 1174 * @param data The data to send 1175 * @param size The size of the data to send, in bytes 1176 * @return @c EINA_TRUE if successful, @c EINA_FALSE on failure. 1177 */ 1178 EAPI Eina_Bool ecore_exe_send(Ecore_Exe *exe, const void *data, int size); 1179 1180 /** 1181 * The stdin of the given child process will close when the write buffer is empty. 1182 * 1183 * @param exe The child process 1184 */ 1185 EAPI void ecore_exe_close_stdin(Ecore_Exe *exe); 1186 1187 /** 1188 * Sets the auto pipe limits for the given process handle. On Windows 1189 * this function does nothing. 1190 * 1191 * @param exe The given process handle. 1192 * @param start_bytes Limit of bytes at start of output to buffer. 1193 * @param end_bytes Limit of bytes at end of output to buffer. 1194 * @param start_lines Limit of lines at start of output to buffer. 1195 * @param end_lines Limit of lines at end of output to buffer. 1196 * 1197 */ 1198 EAPI void ecore_exe_auto_limits_set(Ecore_Exe *exe, int start_bytes, int end_bytes, int start_lines, int end_lines); 1199 1200 /** 1201 * Gets the auto pipe data for the given process handle 1202 * 1203 * @param exe The given process handle. 1204 * @param flags Is this a ECORE_EXE_PIPE_READ or ECORE_EXE_PIPE_ERROR? 1205 * @return The event data. 1206 */ 1207 EAPI Ecore_Exe_Event_Data *ecore_exe_event_data_get(Ecore_Exe *exe, Ecore_Exe_Flags flags); 1208 1209 /** 1210 * Frees the given event data. 1211 * 1212 * @param data The given event data. 1213 */ 1214 EAPI void ecore_exe_event_data_free(Ecore_Exe_Event_Data *data); 1215 1216 /** 1217 * Frees the given process handle. 1218 * 1219 * Note that the process that the handle represents is unaffected by this 1220 * function. 1221 * 1222 * @param exe The given process handle. 1223 * @return The data attached to the handle when @ref ecore_exe_run was 1224 * called. 1225 */ 1226 EAPI void *ecore_exe_free(Ecore_Exe *exe); 1227 1228 /** 1229 * Retrieves the process ID of the given spawned process. 1230 * @param exe Handle to the given spawned process. 1231 * @return The process ID on success, @c -1 otherwise. 1232 */ 1233 EAPI pid_t ecore_exe_pid_get(const Ecore_Exe *exe); 1234 1235 /** 1236 * Sets the string tag for the given process handle. 1237 * 1238 * @param exe The given process handle. 1239 * @param tag The string tag to set on the process handle. 1240 */ 1241 EAPI void ecore_exe_tag_set(Ecore_Exe *exe, const char *tag); 1242 1243 /** 1244 * Retrieves the tag attached to the given process handle. There is no need to 1245 * free it as it just returns the internal pointer value. This value is only 1246 * valid as long as the @p exe is valid or until the tag is set to something 1247 * else on this @p exe. 1248 * 1249 * @param exe The given process handle. 1250 * @return The string attached to @p exe. It is a handle to existing 1251 * internal string and should not be modified, use 1252 * ecore_exe_tag_set() to change it. It might be @c NULL. 1253 */ 1254 EAPI const char *ecore_exe_tag_get(const Ecore_Exe *exe); 1255 1256 /** 1257 * Retrieves the command of the given spawned process. 1258 * @param exe Handle to the given spawned process. 1259 * @return The command on success, @c NULL otherwise. This string is the 1260 * pointer to the internal value and must not be modified in 1261 * any way. 1262 */ 1263 EAPI const char *ecore_exe_cmd_get(const Ecore_Exe *exe); 1264 1265 /** 1266 * Retrieves the data attached to the given process handle. 1267 * @param exe The given process handle. 1268 * @return The data pointer attached to @p exe Given to 1269 * ecore_exe_run() or ecore_exe_pipe_run() 1270 */ 1271 EAPI void *ecore_exe_data_get(const Ecore_Exe *exe); 1272 1273 /** 1274 * Sets the data attached to the given process handle. 1275 * @param exe The given process handle. 1276 * @param data The pointer to attach. 1277 * @return The data pointer previously attached to @p exe with 1278 * ecore_exe_run(), ecore_exe_pipe_run(), or ecore_exe_data_set() 1279 * @since 1.1 1280 */ 1281 EAPI void *ecore_exe_data_set(Ecore_Exe *exe, void *data); 1282 1283 /** 1284 * Retrieves the flags attached to the given process handle. 1285 * @param exe The given process handle. 1286 * @return The flags attached to @p exe. 1287 */ 1288 EAPI Ecore_Exe_Flags ecore_exe_flags_get(const Ecore_Exe *exe); 1289 1290 /** 1291 * Pauses the given process by sending it a @c SIGSTOP signal. 1292 * @param exe Process handle to the given process. 1293 */ 1294 EAPI void ecore_exe_pause(Ecore_Exe *exe); 1295 1296 /** 1297 * Continues the given paused process by sending it a @c SIGCONT signal. 1298 * @param exe Process handle to the given process. 1299 */ 1300 EAPI void ecore_exe_continue(Ecore_Exe *exe); 1301 1302 /** 1303 * Sends the given spawned process a interrupt (@c SIGINT) signal. 1304 * @param exe Process handle to the given process. 1305 */ 1306 EAPI void ecore_exe_interrupt(Ecore_Exe *exe); 1307 1308 /** 1309 * Sends the given spawned process a quit (@c SIGQUIT) signal. 1310 * @param exe Process handle to the given process. 1311 */ 1312 EAPI void ecore_exe_quit(Ecore_Exe *exe); 1313 1314 /** 1315 * Sends the given spawned process a terminate (@c SIGTERM) signal. 1316 * @param exe Process handle to the given process. 1317 */ 1318 EAPI void ecore_exe_terminate(Ecore_Exe *exe); 1319 1320 /** 1321 * Kills the given spawned process by sending it a @c SIGKILL signal. 1322 * @param exe Process handle to the given process. 1323 */ 1324 EAPI void ecore_exe_kill(Ecore_Exe *exe); 1325 1326 /** 1327 * Sends a @c SIGUSR signal to the given spawned process. 1328 * @param exe Process handle to the given process. 1329 * @param num The number user signal to send. Must be either @c 1 or @c 2, or 1330 * the signal will be ignored. 1331 */ 1332 EAPI void ecore_exe_signal(Ecore_Exe *exe, int num); 1333 1334 /** 1335 * Sends a @c SIGHUP signal to the given spawned process. 1336 * @param exe Process handle to the given process. 1337 */ 1338 EAPI void ecore_exe_hup(Ecore_Exe *exe); 1339 1340 /** 1341 * @} 1342 */ 1343 1344 /** 1345 * @ingroup Ecore_Main_Loop_Group 1346 * @defgroup Ecore_FD_Handler_Group File Descriptor Handling Functions 1347 * 1348 * @brief Definition for functions that deal with file descriptor handlers. 1349 * 1350 * File descriptor handlers facilitate reading, writing and checking for errors 1351 * without blocking the program or doing expensive pooling. This can be used to 1352 * monitor a socket, pipe, or other stream for which an FD can be had. 1353 * 1354 * @warning File descriptor handlers can't be used to monitor for file creation, 1355 * modification or deletion, see @ref Ecore_File_Group for this. 1356 * 1357 * One common FD to be monitored is the standard input(stdin), monitoring it for 1358 * reading requires a single call: 1359 * @code 1360 * static Eina_Bool 1361 * _my_cb_func(void *data, Ecore_Fd_Handler *handler) 1362 * { 1363 * char c; 1364 * scanf("%c", &c); //Guaranteed not to block 1365 * ... do stuff with c ... 1366 * } 1367 * ecore_main_fd_handler_add(STDIN_FILENO, ECORE_FD_READ, _my_cb_func, NULL, NULL, NULL); 1368 * @endcode 1369 * 1370 * When using a socket, pipe or other stream it's important to remember that 1371 * errors may occur and as such to monitor not only for reading/writing but also 1372 * for errors using the @ref ECORE_FD_ERROR flag. 1373 * 1374 * Example of use of a file descriptor handler: 1375 * @li @ref ecore_fd_handler_example_c 1376 * 1377 * @{ 1378 */ 1379 1380 typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler; /**< A handle for Fd handlers */ 1381 1382 /** 1383 * @enum _Ecore_Fd_Handler_Flags 1384 * What to monitor the file descriptor for: reading, writing or error. 1385 */ 1386 enum _Ecore_Fd_Handler_Flags 1387 { 1388 ECORE_FD_READ = 1, /**< Fd Read mask */ 1389 ECORE_FD_WRITE = 2, /**< Fd Write mask */ 1390 ECORE_FD_ERROR = 4, /**< Fd Error mask */ 1391 /* ECORE_FD_ALWAYS is intended to fix a problem with wayland 1392 * and threads. It causes the fd handler to be called 1393 * in any state, so wayland libs can call read_cancel 1394 * if nothing is available to read. Everyone else should 1395 * stay away. */ 1396 ECORE_FD_ALWAYS = 8, /**< Fd Always mask - DO NOT USE! */ 1397 }; 1398 typedef enum _Ecore_Fd_Handler_Flags Ecore_Fd_Handler_Flags; 1399 1400 /** 1401 * @typedef Ecore_Fd_Cb Ecore_Fd_Cb 1402 * A callback used by an @ref Ecore_Fd_Handler. 1403 */ 1404 typedef Eina_Bool (*Ecore_Fd_Cb)(void *data, Ecore_Fd_Handler *fd_handler); 1405 1406 /** 1407 * @typedef Ecore_Fd_Prep_Cb Ecore_Fd_Prep_Cb 1408 * A callback used by an @ref Ecore_Fd_Handler. 1409 */ 1410 typedef void (*Ecore_Fd_Prep_Cb)(void *data, Ecore_Fd_Handler *fd_handler); 1411 1412 /** 1413 * @typedef Ecore_Win32_Handle_Cb Ecore_Win32_Handle_Cb 1414 * A callback used by an @ref Ecore_Win32_Handler. 1415 */ 1416 typedef Eina_Bool (*Ecore_Win32_Handle_Cb)(void *data, Ecore_Win32_Handler *wh); 1417 1418 /** 1419 * @brief Adds a callback for activity on the given file descriptor. 1420 * 1421 * @param fd The file descriptor to watch. 1422 * @param flags To monitor it for reading use @c ECORE_FD_READ, for writing @c 1423 * ECORE_FD_WRITE, and for error @c ECORE_FD_ERROR. Values by |(ored). 1424 * @param func The callback function. 1425 * @param data The data to pass to the callback. 1426 * @param buf_func The function to call to check if any data has been buffered 1427 * and already read from the fd. May be @c NULL. 1428 * @param buf_data The data to pass to the @p buf_func function. 1429 * @return A fd handler handle on success, @c NULL otherwise. 1430 * 1431 * @a func will be called during the execution of @ref Ecore_Main_Loop_Page 1432 * when the file descriptor is available for reading, writing, or there has been 1433 * an error(depending on the given @a flags). 1434 * 1435 * When @a func returns @c ECORE_CALLBACK_CANCEL, it indicates that the 1436 * handler should be marked for deletion (identical to calling @ref 1437 * ecore_main_fd_handler_del). 1438 * 1439 * @warning @a buf_func is meant for @b internal use only and should be @b 1440 * avoided. 1441 * 1442 * The return value of @a buf_func has a different meaning, when it returns 1443 * ECORE_CALLBACK_CANCEL, it indicates that @a func @b shouldn't be called, and 1444 * when it returns ECORE_CALLBACK_RENEW it indicates @a func should be called. 1445 * The return value of @a buf_func will not cause the FD handler to be deleted. 1446 * 1447 * @a buf_func is called during event loop handling to check if data that has 1448 * been read from the file descriptor is in a buffer and is available to read. 1449 * Some systems, notably xlib, handle their own buffering, and would otherwise 1450 * not work with select(). These systems should use a @a buf_func. This is a 1451 * most annoying hack, only ecore_x uses it, so refer to that for an example. 1452 * 1453 * @warning This function should @b not be used for monitoring "normal" files, like text files. 1454 * 1455 */ 1456 EAPI Ecore_Fd_Handler *ecore_main_fd_handler_add(int fd, Ecore_Fd_Handler_Flags flags, Ecore_Fd_Cb func, const void *data, Ecore_Fd_Cb buf_func, const void *buf_data); 1457 1458 /** 1459 * @brief Adds a callback for activity on the given file descriptor. 1460 * 1461 * @param fd The file descriptor to watch. 1462 * @param flags To monitor it for reading use @c ECORE_FD_READ, for writing @c 1463 * ECORE_FD_WRITE, and for error @c ECORE_FD_ERROR. Values by |(ored). 1464 * @param func The callback function. 1465 * @param data The data to pass to the callback. 1466 * @param buf_func The function to call to check if any data has been buffered 1467 * and already read from the fd. May be @c NULL. 1468 * @param buf_data The data to pass to the @p buf_func function. 1469 * @return A fd handler handle on success, @c NULL otherwise. 1470 * 1471 * This function is identical to ecore_main_fd_handler_add, except that it supports regular files. 1472 * @warning This function should ONLY be called with ECORE_FD_ERROR, otherwise it will call the fd 1473 * handler constantly. 1474 * @warning Do not use this function unless you know what you are doing. 1475 * 1476 * @since 1.7 1477 */ 1478 EAPI 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); 1479 1480 /** 1481 * @brief Sets the prepare callback with data for a given #Ecore_Fd_Handler. 1482 * 1483 * @param fd_handler The fd handler 1484 * @param func The prep function 1485 * @param data The data to pass to the prep function 1486 * 1487 * This function will be called prior to any fd handler's callback function 1488 * (even the other fd handlers), before entering the main loop select function. 1489 * 1490 * @note Once a prepare callback is set for a fd handler, it cannot be changed. 1491 * You need to delete the fd handler and create a new one, to set another 1492 * callback. 1493 * @note You probably don't need this function. It is only necessary for very 1494 * uncommon cases that need special behavior. 1495 */ 1496 EAPI void ecore_main_fd_handler_prepare_callback_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Prep_Cb func, const void *data); 1497 /** 1498 * @brief Marks an FD handler for deletion. 1499 * @param fd_handler The FD handler. 1500 * @return The data pointer set using @ref ecore_main_fd_handler_add, for 1501 * @a fd_handler on success, @c NULL otherwise. 1502 * This function marks an fd handler to be deleted during an iteration of the 1503 * main loop. It does NOT close the associated fd! 1504 * 1505 * @warning If the underlying fd is already closed ecore may complain if the 1506 * main loop is using epoll internally, and also in some rare cases this may 1507 * cause crashes and instability. Remember to delete your fd handlers before the 1508 * fds they listen to are closed. 1509 */ 1510 EAPI void *ecore_main_fd_handler_del(Ecore_Fd_Handler *fd_handler); 1511 /** 1512 * @brief Retrieves the file descriptor that the given handler is handling. 1513 * @param fd_handler The given FD handler. 1514 * @return The file descriptor the handler is watching. 1515 */ 1516 EAPI int ecore_main_fd_handler_fd_get(Ecore_Fd_Handler *fd_handler); 1517 /** 1518 * @brief Gets which flags are active on an FD handler. 1519 * @param fd_handler The given FD handler. 1520 * @param flags The flags, @c ECORE_FD_READ, @c ECORE_FD_WRITE or 1521 * @c ECORE_FD_ERROR to query. 1522 * @return @c EINA_TRUE if any of the given flags are active, @c EINA_FALSE 1523 * otherwise. 1524 */ 1525 EAPI Eina_Bool ecore_main_fd_handler_active_get(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); 1526 /** 1527 * @brief Sets what active streams the given FD handler should be monitoring. 1528 * @param fd_handler The given FD handler. 1529 * @param flags The flags to be watching. 1530 */ 1531 EAPI void ecore_main_fd_handler_active_set(Ecore_Fd_Handler *fd_handler, Ecore_Fd_Handler_Flags flags); 1532 1533 /** 1534 * @brief Creates a Ecore_Win32_Handler object and add it to the win32_handlers list. 1535 * @param h The win32 handler. 1536 * @param func The function to add as a callback. 1537 * @param data The data to pass to the callback when it is called. 1538 */ 1539 EAPI Ecore_Win32_Handler *ecore_main_win32_handler_add(void *h, Ecore_Win32_Handle_Cb func, const void *data); 1540 /** 1541 * @brief Sets Ecore_Win32_Handler object to delete state. 1542 * The handler will be deleted in the _ecore_main_win32_handlers_cleanup function. 1543 * 1544 * @param win32_handler The Ecore_Win32_Handler object. 1545 */ 1546 EAPI void *ecore_main_win32_handler_del(Ecore_Win32_Handler *win32_handler); 1547 1548 /** 1549 * @} 1550 */ 1551 1552 /** 1553 * @ingroup Ecore 1554 * @defgroup Ecore_Time_Group Ecore time functions 1555 * 1556 * These are function to retrieve time in a given format. 1557 * 1558 * Examples: 1559 * @li @ref ecore_time_functions_example_c 1560 * @{ 1561 */ 1562 1563 /** 1564 * Retrieves the current system time as a floating point value in seconds. 1565 * 1566 * This uses a monotonic clock and thus never goes back in time while 1567 * machine is live (even if user changes time or timezone changes, 1568 * however it may be reset whenever the machine is restarted). 1569 * 1570 * @return The number of seconds. Start time is not defined (it may be 1571 * when the machine was booted, unix time, etc), all it is 1572 * defined is that it never goes backwards (unless you got big critical 1573 * messages when the application started). 1574 * 1575 * @see ecore_loop_time_get(). 1576 * @see ecore_time_unix_get(). 1577 */ 1578 EAPI double ecore_time_get(void); 1579 1580 /** 1581 * Retrieves the current UNIX time as a floating point value in seconds. 1582 * 1583 * @see ecore_time_get(). 1584 * @see ecore_loop_time_get(). 1585 * 1586 * @return The number of seconds since 12.00AM 1st January 1970. 1587 */ 1588 EAPI double ecore_time_unix_get(void); 1589 1590 /** 1591 * Retrieves the time at which the last loop stopped waiting for timeouts or 1592 * events. 1593 * 1594 * This gets the time that the main loop ceased waiting for timouts and/or 1595 * events to come in or for signals or any other interrupt source. This should 1596 * be considered a reference point for all time based activity that should 1597 * calculate its timepoint from the return of ecore_loop_time_get(). Use this 1598 * UNLESS you absolutely must get the current actual timepoint - then use 1599 * ecore_time_get(). Note that this time is meant to be used as relative to 1600 * other times obtained on this run. If you need absolute time references, use 1601 * ecore_time_unix_get() instead. 1602 * 1603 * This function can be called before any loop has ever been run, but either 1604 * ecore_init() or ecore_time_get() must have been called once. 1605 * 1606 * @return The number of seconds. Start time is not defined (it may be 1607 * when the machine was booted, unix time, etc), all it is 1608 * defined is that it never goes backwards (unless you got big critical 1609 * messages when the application started). 1610 */ 1611 EAPI double ecore_loop_time_get(void); 1612 1613 /** 1614 * Sets the loop time. 1615 * 1616 * @param t The new loop time 1617 * 1618 * You should never need/call this, unless you are implementing a custom 1619 * tick source for an ecore animator. Only then inside your function that 1620 * calls ecore_animator_custom_tick(), just before it, if you are able to 1621 * get accurate timing information as to when the source of your tick 1622 * woke up, use this to adjust the ecore loop time to be perfectly 1623 * accurate. It is not a requirement, but makes things smoother. You should 1624 * not use it otherwise as it could harm timeline handling throughout the 1625 * application. Also note that the time point must match whatever zero time 1626 * you get from ecore_time_get() and ecore_loop_time_get() (same 0 point). 1627 * What this point is is undefined, sou unless your source uses the same 1628 * 0 time, then you may have to adjust and do some guessing. 1629 * 1630 * @see ecore_animator_custom_tick() 1631 * @see ecore_loop_time_get() 1632 * @since 1.11 1633 */ 1634 EAPI void ecore_loop_time_set(double t); 1635 1636 /** 1637 * @} 1638 */ 1639 1640 /** 1641 * @ingroup Ecore_Main_Loop_Group 1642 * @defgroup Ecore_Thread_Group Ecore Thread functions 1643 * 1644 * Facilities to run heavy tasks in different threads to avoid blocking 1645 * the main loop. 1646 * 1647 * The EFL is, for the most part, not thread safe. This means that if you 1648 * have some task running in another thread and you have, for example, an 1649 * Evas object to show the status progress of this task, you cannot update 1650 * the object from within the thread. This can only be done from the main 1651 * thread, the one running the main loop. This problem can be solved 1652 * by running a thread that sends messages to the main one using an 1653 * @ref Ecore_Pipe_Group "Ecore_Pipe", but when you need to handle other 1654 * things like cancelling the thread, your code grows in complexity and gets 1655 * much harder to maintain. 1656 * 1657 * Ecore Thread is here to solve that problem. It is @b not a simple wrapper 1658 * around standard POSIX threads (or the equivalent in other systems) and 1659 * it's not meant to be used to run parallel tasks throughout the entire 1660 * duration of the program, especially when these tasks are performance 1661 * critical, as Ecore manages these tasks using a pool of threads based on 1662 * system configuration. 1663 * 1664 * What Ecore Thread does, is make it a lot easier to dispatch a worker 1665 * function to perform some heavy task and then get the result once it 1666 * completes, without blocking the application's UI. In addition, cancelling 1667 * and rescheduling comes practically for free and the developer needs not 1668 * worry about how many threads are launched, since Ecore will schedule 1669 * them according to the number of processors the system has and maximum 1670 * amount of concurrent threads set for the application. 1671 * 1672 * At the system level, Ecore will start a new thread on an as-needed basis 1673 * until the maximum set is reached. When no more threads can be launched, 1674 * new worker functions will be queued in a waiting list until a thread 1675 * becomes available. This way, system threads will be shared throughout 1676 * different worker functions, but running only one at a time. At the same 1677 * time, a worker function that is rescheduled may be run on a different 1678 * thread the next time. 1679 * 1680 * The ::Ecore_Thread handler has two meanings, depending on what context 1681 * it is on. The one returned when starting a worker with any of the 1682 * functions ecore_thread_run() or ecore_thread_feedback_run() is an 1683 * identifier of that specific instance of the function and can be used from 1684 * the main loop with the ecore_thread_cancel() and ecore_thread_check() 1685 * functions. This handler must not be shared with the worker function 1686 * function running in the thread. This same handler will be the one received 1687 * on the @c end, @c cancel and @c feedback callbacks. 1688 * 1689 * The worker function, that's the one running in the thread, also receives 1690 * an ::Ecore_Thread handler that can be used with ecore_thread_cancel() and 1691 *ecore_thread_check(), sharing the flag with the main loop. But this 1692 * handler is also associated with the thread where the function is running. 1693 * This has strong implications when working with thread local data. 1694 * 1695 * There are two kinds of worker threads Ecore handles: simple, or short, 1696 * workers and feedback workers. 1697 * 1698 * The first kind is for simple functions that perform a 1699 * usually small but time consuming task. Ecore will run this function in 1700 * a thread as soon as one becomes available and notify the calling user of 1701 * its completion once the task is done. 1702 * 1703 * The following image shows the flow of a program running four tasks on 1704 * a pool of two threads. 1705 * 1706 * @image html ecore_thread.png 1707 * @image rtf ecore_thread.png 1708 * @image latex ecore_thread.eps width=\\textwidth 1709 * 1710 * For larger tasks that may require continuous communication with the main 1711 * program, the feedback workers provide the same functionality plus a way 1712 * for the function running in the thread to send messages to the main 1713 * thread. 1714 * 1715 * The next diagram omits some details shown in the previous one regarding 1716 * how threads are spawned and tasks are queued, but illustrates how feedback 1717 * jobs communicate with the main loop and the special case of threads 1718 * running out of pool. 1719 * 1720 * @image html ecore_thread_feedback.png 1721 * @image rtf ecore_thread_feedback.png 1722 * @image latex ecore_thread_feedback.eps width=\\textwidth 1723 * 1724 * See an overview example in @ref ecore_thread_example_c. 1725 * 1726 * @{ 1727 */ 1728 1729 typedef struct _Ecore_Thread Ecore_Thread; /**< A handle for threaded jobs */ 1730 1731 /** 1732 * @typedef Ecore_Thread_Cb Ecore_Thread_Cb 1733 * A callback used by Ecore_Thread helper. 1734 */ 1735 typedef void (*Ecore_Thread_Cb)(void *data, Ecore_Thread *thread); 1736 1737 /** 1738 * @typedef Ecore_Thread_Notify_Cb Ecore_Thread_Notify_Cb 1739 * A callback used by the main loop to receive data sent by an 1740 * @ref Ecore_Thread_Group. 1741 */ 1742 typedef void (*Ecore_Thread_Notify_Cb)(void *data, Ecore_Thread *thread, void *msg_data); 1743 1744 /** 1745 * Schedules a task to run in a parallel thread to avoid locking the main loop. 1746 * 1747 * @param func_blocking The function that should run in another thread. 1748 * @param func_end Function to call from main loop when @p func_blocking 1749 * completes its task successfully (may be NULL) 1750 * @param func_cancel Function to call from main loop if the thread running 1751 * @p func_blocking is cancelled or fails to start (may be NULL) 1752 * @param data User context data to pass to all callbacks. 1753 * @return A new thread handler, or @c NULL on failure. 1754 * 1755 * This function will try to create a new thread to run @p func_blocking in, 1756 * or if the maximum number of concurrent threads has been reached, will 1757 * add it to the pending list, where it will wait until a thread becomes 1758 * available. The return value will be an ::Ecore_Thread handle that can 1759 * be used to cancel the thread before its completion. 1760 * 1761 * @note This function should always return immediately, but in the rare 1762 * case that Ecore is built with no thread support, @p func_blocking will 1763 * be called here, actually blocking the main loop. 1764 * 1765 * Once a thread becomes available, @p func_blocking will be run in it until 1766 * it finishes, then @p func_end is called from the thread containing the 1767 * main loop to inform the user of its completion. While in @p func_blocking, 1768 * no functions from the EFL can be used, except for those from Eina that are 1769 * marked to be thread-safe. Even for the latter, caution needs to be taken 1770 * if the data is shared across several threads. 1771 * 1772 * @p func_end will be called from the main thread when @p func_blocking ends, 1773 * so here it's safe to use anything from the EFL freely. 1774 * 1775 * The thread can also be cancelled before its completion calling 1776 *ecore_thread_cancel(), either from the main thread or @p func_blocking. 1777 * In this case, @p func_cancel will be called, also from the main thread 1778 * to inform of this happening. If the thread could not be created, this 1779 * function will be called and it's @c thread parameter will be NULL. It's 1780 * also safe to call any EFL function here, as it will be running in the 1781 * main thread. 1782 * 1783 * Inside @p func_blocking, it's possible to call ecore_thread_reschedule() 1784 * to tell Ecore that this function should be called again. 1785 * 1786 * Be aware that no assumptions can be made about the order in which the 1787 * @p func_end callbacks for each task will be called. Once the function is 1788 * running in a different thread, it's the OS that will handle its running 1789 * schedule, and different functions may take longer to finish than others. 1790 * Also remember that just starting several tasks together doesn't mean they 1791 * will be running at the same time. Ecore will schedule them based on the 1792 * number of threads available for the particular system it's running in, 1793 * so some of the jobs started may be waiting until another one finishes 1794 * before it can execute its own @p func_blocking. 1795 * 1796 * @see ecore_thread_feedback_run() 1797 * @see ecore_thread_cancel() 1798 * @see ecore_thread_reschedule() 1799 * @see ecore_thread_max_set() 1800 */ 1801 EAPI Ecore_Thread *ecore_thread_run(Ecore_Thread_Cb func_blocking, Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, const void *data); 1802 1803 /** 1804 * Launches a thread to run a task that can talk back to the main thread. 1805 * 1806 * @param func_heavy The function that should run in another thread. 1807 * @param func_notify Function that receives the data sent from the thread 1808 * @param func_end Function to call from main loop when @p func_heavy 1809 * completes its task successfully 1810 * @param func_cancel Function to call from main loop if the thread running 1811 * @p func_heavy is cancelled or fails to start 1812 * @param data User context data to pass to all callback. 1813 * @param try_no_queue If you want to run outside of the thread pool. 1814 * @return A new thread handler, or @c NULL on failure. 1815 * 1816 * See ecore_thread_run() for a general description of this function. 1817 * 1818 * The difference with the above is that ecore_thread_run() is meant for 1819 * tasks that don't need to communicate anything until they finish, while 1820 * this function is provided with a new callback, @p func_notify, that will 1821 * be called from the main thread for every message sent from @p func_heavy 1822 * with ecore_thread_feedback(). 1823 * 1824 * Like ecore_thread_run(), a new thread will be launched to run 1825 * @p func_heavy unless the maximum number of simultaneous threads has been 1826 * reached, in which case the function will be scheduled to run whenever a 1827 * running task ends and a thread becomes free. But if @p try_no_queue is 1828 * set, Ecore will first try to launch a thread outside of the pool to run 1829 * the task. If it fails, it will revert to the normal behaviour of using a 1830 * thread from the pool as if @p try_no_queue had not been set. 1831 * 1832 * Keep in mind that Ecore handles the thread pool based on the number of 1833 * CPUs available, but running a thread outside of the pool doesn't count for 1834 * this, so having too many of them may have drastic effects over the 1835 * program's performance. 1836 * 1837 * @see ecore_thread_feedback() 1838 * @see ecore_thread_run() 1839 * @see ecore_thread_cancel() 1840 * @see ecore_thread_reschedule() 1841 * @see ecore_thread_max_set() 1842 */ 1843 EAPI Ecore_Thread *ecore_thread_feedback_run(Ecore_Thread_Cb func_heavy, Ecore_Thread_Notify_Cb func_notify, 1844 Ecore_Thread_Cb func_end, Ecore_Thread_Cb func_cancel, 1845 const void *data, Eina_Bool try_no_queue); 1846 1847 /** 1848 * Cancels a running thread. 1849 * 1850 * @param thread The thread to cancel. 1851 * @return Will return @c EINA_TRUE if the thread has been cancelled, 1852 * @c EINA_FALSE if it is pending. 1853 * 1854 * This function can be called both in the main loop or in the running thread. 1855 * 1856 * This function cancels a running thread. If @p thread can be immediately 1857 * cancelled (it's still pending execution after creation or rescheduling), 1858 * then the @c cancel callback will be called, @p thread will be freed and 1859 * the function will return @c EINA_TRUE. 1860 * 1861 * If the thread is already running, then this function returns @c EINA_FALSE 1862 * after marking the @p thread as pending cancellation. For the thread to 1863 * actually be terminated, it needs to return from the user function back 1864 * into Ecore control. This can happen in several ways: 1865 * @li The function ends and returns normally. If it hadn't been cancelled, 1866 * @c func_end would be called here, but instead @c func_cancel will happen. 1867 * @li The function returns after requesting to be rescheduled with 1868 * ecore_thread_reschedule(). 1869 * @li The function is prepared to leave early by checking if 1870 * ecore_thread_check() returns @c EINA_TRUE. 1871 1872 * @li The function marks the thread as cancellable using 1873 * eina_thread_cancellable_set(), allowing the thread to be terminated 1874 * at explicit cancellation points defined with 1875 * eina_thread_cancel_checkpoint() or with syscalls mentioned at 1876 * man:pthreads(7). This allows blocking operations such as network or 1877 * disk access to be stopped without polling 1878 * ecore_thread_check(). Note that a cancelled thread may leak 1879 * resources if no cleanup function is registered with 1880 * EINA_THREAD_CLEANUP_PUSH(). Consider running such code using 1881 * eina_thread_cancellable_run(). 1882 * 1883 * The user function can cancel itself by calling ecore_thread_cancel(), but 1884 * it should always use the ::Ecore_Thread handle passed to it and never 1885 * share it with the main loop thread by means of shared user data or any 1886 * other way. 1887 * 1888 * @p thread will be freed and should not be used again if this function 1889 * returns @c EINA_TRUE or after the @c func_cancel callback returns. 1890 * 1891 * @see ecore_thread_check() 1892 * @see eina_thread_cancellable_run() 1893 */ 1894 EAPI Eina_Bool ecore_thread_cancel(Ecore_Thread *thread); 1895 1896 /** 1897 * @brief Blocks the main loop until the thread execution is over. 1898 * @since 1.13.0 1899 * 1900 * @param thread The thread to wait on. 1901 * @param wait Maximum time to wait before exiting anyway. 1902 * @return EINA_TRUE if the thread execution is over. 1903 * 1904 * Note: This function should only be called in the main loop. 1905 * 1906 */ 1907 EAPI Eina_Bool ecore_thread_wait(Ecore_Thread *thread, double wait); 1908 1909 /** 1910 * Checks if a thread is pending cancellation. 1911 * 1912 * @param thread The thread to test. 1913 * @return @c EINA_TRUE if the thread is pending cancellation, 1914 * @c EINA_FALSE if it is not. 1915 * 1916 * This function can be called both in the main loop or in the running thread. 1917 * 1918 * When ecore_thread_cancel() is called on an already running task, the 1919 * thread is marked as pending cancellation. This function returns @c EINA_TRUE 1920 * if this mark is set for the given @p thread and can be used from the 1921 * main loop thread to check if a still active thread has been cancelled, 1922 * or from the user function running in the thread to check if it should 1923 * stop doing what it's doing and return early, effectively cancelling the 1924 * task. 1925 * 1926 * @see ecore_thread_cancel() 1927 */ 1928 EAPI Eina_Bool ecore_thread_check(Ecore_Thread *thread); 1929 1930 /** 1931 * Sends data from the worker thread to the main loop. 1932 * 1933 * @param thread The current ::Ecore_Thread context to send data from 1934 * @param msg_data Data to be transmitted to the main loop 1935 * @return @c EINA_TRUE if @p msg_data was successfully sent to main loop, 1936 * @c EINA_FALSE if anything goes wrong. 1937 * 1938 * You should use this function only in the @c func_heavy call. 1939 * 1940 * Only the address to @p msg_data will be sent and once this function 1941 * returns @c EINA_TRUE, the job running in the thread should never touch the 1942 * contents of it again. The data sent should be malloc()'ed or something 1943 * similar, as long as it's not memory local to the thread that risks being 1944 * overwritten or deleted once it goes out of scope or the thread finishes. 1945 * 1946 * Care must be taken that @p msg_data is properly freed in the @c func_notify 1947 * callback set when creating the thread. 1948 * 1949 * @see ecore_thread_feedback_run() 1950 */ 1951 EAPI Eina_Bool ecore_thread_feedback(Ecore_Thread *thread, const void *msg_data); 1952 1953 /** 1954 * Asks for the function in the thread to be called again at a later time. 1955 * 1956 * @param thread The current ::Ecore_Thread context to rescheduled 1957 * @return @c EINA_TRUE if the task was successfully rescheduled, 1958 * @c EINA_FALSE if anything goes wrong. 1959 * 1960 * This function should be called only from the same function represented 1961 * by @p thread. 1962 * 1963 * Calling this function will mark the thread for a reschedule, so as soon 1964 * as it returns, it will be added to the end of the list of pending tasks. 1965 * If no other tasks are waiting or there are sufficient threads available, 1966 * the rescheduled task will be launched again immediately. 1967 * 1968 * This should never return @c EINA_FALSE, unless it was called from the wrong 1969 * thread or with the wrong arguments. 1970 * 1971 * The @c func_end callback set when the thread is created will not be 1972 * called until the function in the thread returns without being rescheduled. 1973 * Similarly, if the @p thread is cancelled, the reschedule will not take 1974 * effect. 1975 */ 1976 EAPI Eina_Bool ecore_thread_reschedule(Ecore_Thread *thread); 1977 1978 /** 1979 * Gets the number of active threads running jobs. 1980 * 1981 * @return Number of active threads running jobs 1982 * 1983 * This returns the number of threads currently running jobs of any type 1984 * through the Ecore_Thread API. 1985 * 1986 * @note Jobs started through the ecore_thread_feedback_run() function with 1987 * the @c try_no_queue parameter set to @c EINA_TRUE will not be accounted for 1988 * in the return of this function unless the thread creation fails and it 1989 * falls back to using one from the pool. 1990 */ 1991 EAPI int ecore_thread_active_get(void); 1992 1993 /** 1994 * Gets the number of short jobs waiting for a thread to run. 1995 * 1996 * @return Number of pending threads running "short" jobs 1997 * 1998 * This returns the number of tasks started with ecore_thread_run() that are 1999 * pending, waiting for a thread to become available to run them. 2000 */ 2001 EAPI int ecore_thread_pending_get(void); 2002 2003 /** 2004 * Gets the number of feedback jobs waiting for a thread to run. 2005 * 2006 * @return Number of pending threads running "feedback" jobs 2007 * 2008 * This returns the number of tasks started with ecore_thread_feedback_run() 2009 * that are pending, waiting for a thread to become available to run them. 2010 */ 2011 EAPI int ecore_thread_pending_feedback_get(void); 2012 2013 /** 2014 * Gets the total number of pending jobs. 2015 * 2016 * @return Number of pending threads running jobs 2017 * 2018 * Same as the sum of ecore_thread_pending_get() and 2019 *ecore_thread_pending_feedback_get(). 2020 */ 2021 EAPI int ecore_thread_pending_total_get(void); 2022 2023 /** 2024 * Gets the maximum number of threads that can run simultaneously. 2025 * 2026 * @return Max possible number of Ecore_Thread's running concurrently 2027 * 2028 * This returns the maximum number of Ecore_Thread's that may be running at 2029 * the same time. If this number is reached, new jobs started by either 2030 * ecore_thread_run() or ecore_thread_feedback_run() will be added to the 2031 * respective pending queue until one of the running threads finishes its 2032 * task and becomes available to run a new one. 2033 * 2034 * By default, this will be the proportional to the number of CPU cores 2035 * found, and will be at least 1 so at least 1 worker can run through 2036 * the quque of work to do. 2037 * 2038 * @see ecore_thread_max_set() 2039 * @see ecore_thread_max_reset() 2040 */ 2041 EAPI int ecore_thread_max_get(void); 2042 2043 /** 2044 * Sets the maximum number of threads allowed to run simultaneously. 2045 * 2046 * @param num The new maximum 2047 * 2048 * This sets a new value for the maximum number of concurrently running 2049 * Ecore_Thread's. It @b must an interger of at least 1 and may be limited 2050 * to a reasonable value as to not overload the system too much with 2051 * too many workers. This limit may change based on the number of CPU 2052 * cores detected. 2053 * 2054 * @see ecore_thread_max_get() 2055 * @see ecore_thread_max_reset() 2056 */ 2057 EAPI void ecore_thread_max_set(int num); 2058 2059 /** 2060 * Resets the maximum number of concurrently running threads to the default. 2061 * 2062 * This resets the value returned by ecore_thread_max_get() back to its 2063 * default. 2064 * 2065 * @see ecore_thread_max_get() 2066 * @see ecore_thread_max_set() 2067 */ 2068 EAPI void ecore_thread_max_reset(void); 2069 2070 /** 2071 * Gets the number of threads available for running tasks. 2072 * 2073 * @return The number of available threads 2074 * 2075 * Same as doing ecore_thread_max_get() - ecore_thread_active_get(). 2076 * 2077 * This function may return a negative number only in the case the user 2078 * changed the maximum number of running threads while other tasks are 2079 * running. 2080 */ 2081 EAPI int ecore_thread_available_get(void); 2082 2083 /** 2084 * Adds some data to a hash local to the thread. 2085 * 2086 * @param thread The thread context the data belongs to 2087 * @param key The name under which the data will be stored 2088 * @param value The data to add 2089 * @param cb Function to free the data when removed from the hash 2090 * @param direct If @c true, this will not copy the key string (like 2091 * eina_hash_direct_add()) 2092 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. 2093 * 2094 * Ecore Thread has a mechanism to share data across several worker functions 2095 * that run on the same system thread. That is, the data is stored per 2096 * thread and for a worker function to have access to it, it must be run 2097 * by the same thread that stored the data. 2098 * 2099 * When there are no more workers pending, the thread will be destroyed 2100 * along with the internal hash and any data left in it will be freed with 2101 * the @p cb function given. 2102 * 2103 * This set of functions is useful to share things around several instances 2104 * of a function when that thing is costly to create and can be reused, but 2105 * may only be used by one function at a time. 2106 * 2107 * For example, if you have a program doing requisitions to a database, 2108 * these requisitions can be done in threads so that waiting for the 2109 * database to respond doesn't block the UI. Each of these threads will 2110 * run a function, and each function will be dependent on a connection to 2111 * the database, which may not be able to handle more than one request at 2112 * a time so for each running function you will need one connection handle. 2113 * The options then are: 2114 * @li Each function opens a connection when it's called, does the work and 2115 * closes the connection when it finishes. This may be costly, wasting a lot 2116 * of time on resolving hostnames, negotiating permissions and allocating 2117 * memory. 2118 * @li Open the connections in the main loop and pass it to the threads 2119 * using the data pointer. Even worse, it's just as costly as before and now 2120 * it may even be kept with connections open doing nothing until a thread 2121 * becomes available to run the function. 2122 * @li Have a way to share connection handles, so that each instance of the 2123 * function can check if an available connection exists, and if it doesn't, 2124 * create one and add it to the pool. When no more connections are needed, 2125 * they are all closed. 2126 * 2127 * The last option is the most efficient, but it requires a lot of work to 2128 * implement properly. Using thread local data helps to achieve the same 2129 * result while avoiding doing all the tracking work on your code. The way 2130 * to use it would be, at the worker function, to ask for the connection 2131 * with ecore_thread_local_data_find() and if it doesn't exist, then open 2132 * a new one and save it with ecore_thread_local_data_add(). Do the work and 2133 * forget about the connection handle, when everything is done the function 2134 * just ends. The next worker to run on that thread will check if a 2135 * connection exists and find that it does, so the process of opening a 2136 * new one has been spared. When no more workers exist, the thread is 2137 * destroyed and the callback used when saving the connection will be called 2138 * to close it. 2139 * 2140 * This function adds the data @p value to the thread data under the given 2141 * @p key. 2142 * No other value in the hash may have the same @p key. If you need to 2143 * change the value under a @p key, or you don't know if one exists already, 2144 * you can use ecore_thread_local_data_set(). 2145 * 2146 * Neither @p key nor @p value may be @c NULL and @p key will be copied in the 2147 * hash, unless @p direct is set, in which case the string used should not 2148 * be freed until the data is removed from the hash. 2149 * 2150 * The @p cb function will be called when the data in the hash needs to be 2151 * freed, be it because it got deleted with ecore_thread_local_data_del() or 2152 * because @p thread was terminated and the hash destroyed. This parameter 2153 * may be NULL, in which case @p value needs to be manually freed after 2154 * removing it from the hash with either ecore_thread_local_data_del() or 2155 * ecore_thread_local_data_set(), but it's very unlikely that this is what 2156 * you want. 2157 * 2158 * This function, and all of the others in the @c ecore_thread_local_data 2159 * family of functions, can only be called within the worker function running 2160 * in the thread. Do not call them from the main loop or from a thread 2161 * other than the one represented by @p thread. 2162 * 2163 * @see ecore_thread_local_data_set() 2164 * @see ecore_thread_local_data_find() 2165 * @see ecore_thread_local_data_del() 2166 */ 2167 EAPI Eina_Bool ecore_thread_local_data_add(Ecore_Thread *thread, const char *key, void *value, 2168 Eina_Free_Cb cb, Eina_Bool direct); 2169 2170 /** 2171 * Sets some data in the hash local to the given thread. 2172 * 2173 * @param thread The thread context the data belongs to 2174 * @param key The name under which the data will be stored 2175 * @param value The data to add 2176 * @param cb Function to free the data when removed from the hash 2177 * 2178 * If no data exists in the hash under the @p key, this function adds 2179 * @p value in the hash under the given @p key and returns NULL. 2180 * The key itself is copied. 2181 * 2182 * If the hash already contains something under @p key, the data will be 2183 * replaced by @p value and the old value will be returned. 2184 * 2185 * @c NULL will also be returned if either @p key or @p value are @c NULL, or 2186 * if an error occurred. 2187 * 2188 * This function, and all of the others in the @c ecore_thread_local_data 2189 * family of functions, can only be called within the worker function running 2190 * in the thread. Do not call them from the main loop or from a thread 2191 * other than the one represented by @p thread. 2192 * 2193 * @see ecore_thread_local_data_add() 2194 * @see ecore_thread_local_data_del() 2195 * @see ecore_thread_local_data_find() 2196 */ 2197 EAPI void *ecore_thread_local_data_set(Ecore_Thread *thread, const char *key, void *value, Eina_Free_Cb cb); 2198 2199 /** 2200 * Gets data stored in the hash local to the given thread. 2201 * 2202 * @param thread The thread context the data belongs to 2203 * @param key The name under which the data is stored 2204 * @return The value under the given key, or @c NULL on error. 2205 * 2206 * Finds and return the data stored in the shared hash under the key @p key. 2207 * 2208 * This function, and all of the others in the @c ecore_thread_local_data 2209 * family of functions, can only be called within the worker function running 2210 * in the thread. Do not call them from the main loop or from a thread 2211 * other than the one represented by @p thread. 2212 * 2213 * @see ecore_thread_local_data_add() 2214 * @see ecore_thread_local_data_wait() 2215 */ 2216 EAPI void *ecore_thread_local_data_find(Ecore_Thread *thread, const char *key); 2217 2218 /** 2219 * Deletes from the thread's hash the data corresponding to the given key. 2220 * 2221 * @param thread The thread context the data belongs to 2222 * @param key The name under which the data is stored 2223 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. 2224 * 2225 * If there's any data stored associated with @p key in the global hash, 2226 * this function will remove it from it and return @c EINA_TRUE. If no data 2227 * exists or an error occurs, it returns @c EINA_FALSE. 2228 * 2229 * If the data was added to the hash with a free function, then it will 2230 * also be freed after removing it from the hash, otherwise it requires 2231 * to be manually freed by the user, which means that if no other reference 2232 * to it exists before calling this function, it will result in a memory 2233 * leak. 2234 * 2235 * This function, and all of the others in the @c ecore_thread_local_data 2236 * family of functions, can only be called within the worker function running 2237 * in the thread. Do not call them from the main loop or from a thread 2238 * other than the one represented by @p thread. 2239 * 2240 * @see ecore_thread_local_data_add() 2241 */ 2242 EAPI Eina_Bool ecore_thread_local_data_del(Ecore_Thread *thread, const char *key); 2243 2244 /** 2245 * Adds some data to a hash shared by all threads. 2246 * 2247 * @param key The name under which the data will be stored 2248 * @param value The data to add 2249 * @param cb Function to free the data when removed from the hash 2250 * @param direct If @c true, this will not copy the key string (like 2251 * eina_hash_direct_add()) 2252 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. 2253 * 2254 * Ecore Thread keeps a hash that can be used to share data across several 2255 * threads, including the main loop one, without having to manually handle 2256 * mutexes to do so safely. 2257 * 2258 * This function adds the data @p value to this hash under the given @p key. 2259 * No other value in the hash may have the same @p key. If you need to 2260 * change the value under a @p key, or you don't know if one exists already, 2261 * you can use ecore_thread_global_data_set(). 2262 * 2263 * Neither @p key nor @p value may be @c NULL and @p key will be copied in the 2264 * hash, unless @p direct is set, in which case the string used should not 2265 * be freed until the data is removed from the hash. 2266 * 2267 * The @p cb function will be called when the data in the hash needs to be 2268 * freed, be it because it got deleted with ecore_thread_global_data_del() or 2269 * because Ecore Thread was shut down and the hash destroyed. This parameter 2270 * may be NULL, in which case @p value needs to be manually freed after 2271 * removing it from the hash with either ecore_thread_global_data_del() or 2272 *ecore_thread_global_data_set(). 2273 * 2274 * Manually freeing any data that was added to the hash with a @p cb function 2275 * is likely to produce a segmentation fault, or any other strange 2276 * happenings, later on in the program. 2277 * 2278 * @see ecore_thread_global_data_del() 2279 * @see ecore_thread_global_data_set() 2280 * @see ecore_thread_global_data_find() 2281 */ 2282 EAPI Eina_Bool ecore_thread_global_data_add(const char *key, void *value, Eina_Free_Cb cb, Eina_Bool direct); 2283 2284 /** 2285 * Sets some data in the hash shared by all threads. 2286 * 2287 * @param key The name under which the data will be stored 2288 * @param value The data to add 2289 * @param cb Function to free the data when removed from the hash 2290 * 2291 * If no data exists in the hash under the @p key, this function adds 2292 * @p value in the hash under the given @p key and returns NULL. 2293 * The key itself is copied. 2294 * 2295 * If the hash already contains something under @p key, the data will be 2296 * replaced by @p value and the old value will be returned. 2297 * 2298 * @c NULL will also be returned if either @p key or @p value are @c NULL, or 2299 * if an error occurred. 2300 * 2301 * @see ecore_thread_global_data_add() 2302 * @see ecore_thread_global_data_del() 2303 * @see ecore_thread_global_data_find() 2304 */ 2305 EAPI void *ecore_thread_global_data_set(const char *key, void *value, Eina_Free_Cb cb); 2306 2307 /** 2308 * Gets data stored in the hash shared by all threads. 2309 * 2310 * @param key The name under which the data is stored 2311 * @return The value under the given key, or @c NULL on error. 2312 * 2313 * Finds and return the data stored in the shared hash under the key @p key. 2314 * 2315 * Keep in mind that the data returned may be used by more than one thread 2316 * at the same time and no reference counting is done on it by Ecore. 2317 * Freeing the data or modifying its contents may require additional 2318 * precautions to be considered, depending on the application's design. 2319 * 2320 * @see ecore_thread_global_data_add() 2321 * @see ecore_thread_global_data_wait() 2322 */ 2323 EAPI void *ecore_thread_global_data_find(const char *key); 2324 2325 /** 2326 * Deletes from the shared hash the data corresponding to the given key. 2327 * 2328 * @param key The name under which the data is stored 2329 * @return @c EINA_TRUE on success, @c EINA_FALSE on failure. 2330 * 2331 * If there's any data stored associated with @p key in the global hash, 2332 * this function will remove it from it and return @c EINA_TRUE. If no data 2333 * exists or an error occurs, it returns @c EINA_FALSE. 2334 * 2335 * If the data was added to the hash with a free function, then it will 2336 * also be freed after removing it from the hash, otherwise it requires 2337 * to be manually freed by the user, which means that if no other reference 2338 * to it exists before calling this function, it will result in a memory 2339 * leak. 2340 * 2341 * Note, also, that freeing data that other threads may be using will result 2342 * in a crash, so appropriate care must be taken by the application when 2343 * that possibility exists. 2344 * 2345 * @see ecore_thread_global_data_add() 2346 */ 2347 EAPI Eina_Bool ecore_thread_global_data_del(const char *key); 2348 2349 /** 2350 * Gets data stored in the shared hash, or wait for it if it doesn't exist. 2351 * 2352 * @param key The name under which the data is stored 2353 * @param seconds The amount of time in seconds to wait for the data. 2354 * @return The value under the given key, or @c NULL on error. 2355 * 2356 * Finds and return the data stored in the shared hash under the key @p key. 2357 * 2358 * If there's nothing in the hash under the given @p key, the function 2359 * will block and wait up to @p seconds seconds for some other thread to 2360 * add it with either ecore_thread_global_data_add() or 2361 * ecore_thread_global_data_set(). If after waiting there's still no data 2362 * to get, @c NULL will be returned. 2363 * 2364 * If @p seconds is 0, then no waiting will happen and this function works 2365 * like ecore_thread_global_data_find(). If @p seconds is less than 0, then 2366 * the function will wait indefinitely. 2367 * 2368 * Keep in mind that the data returned may be used by more than one thread 2369 * at the same time and no reference counting is done on it by Ecore. 2370 * Freeing the data or modifying its contents may require additional 2371 * precautions to be considered, depending on the application's design. 2372 * 2373 * @see ecore_thread_global_data_add() 2374 * @see ecore_thread_global_data_find() 2375 */ 2376 EAPI void *ecore_thread_global_data_wait(const char *key, double seconds); 2377 2378 /** 2379 * @} 2380 */ 2381 2382 /** 2383 * @ingroup Ecore_Main_Loop_Group 2384 * @defgroup Ecore_Pipe_Group Pipe wrapper 2385 * 2386 * These functions wrap the pipe / write / read functions to easily 2387 * integrate its use into ecore's main loop. 2388 * 2389 * The ecore_pipe_add() function creates file descriptors (sockets 2390 * on Windows) and attach a handle to the ecore main loop. That 2391 * handle is called when data is read in the pipe. To write data in 2392 * the pipe, just call ecore_pipe_write(). When you are done, just 2393 * call ecore_pipe_del(). 2394 * 2395 * For examples see here: 2396 * @li @ref tutorial_ecore_pipe_gstreamer_example 2397 * @li @ref tutorial_ecore_pipe_simple_example 2398 * 2399 * @{ 2400 */ 2401 2402 typedef struct _Ecore_Pipe Ecore_Pipe; /**< A handle for pipes */ 2403 2404 /** 2405 * @typedef Ecore_Pipe_Cb Ecore_Pipe_Cb 2406 * The callback that data written to the pipe is sent to. 2407 */ 2408 typedef void (*Ecore_Pipe_Cb)(void *data, void *buffer, unsigned int nbyte); 2409 2410 /** 2411 * Creates two file descriptors (sockets on Windows). Adds 2412 * a callback that will be called when the file descriptor that 2413 * is listened receives data. An event is also put in the event 2414 * queue when data is received. 2415 * 2416 * @param handler The handler called when data is received. 2417 * @param data Data to pass to @p handler when it is called. 2418 * @return A newly created Ecore_Pipe object if successful, 2419 * @c NULL otherwise. 2420 */ 2421 EAPI Ecore_Pipe *ecore_pipe_add(Ecore_Pipe_Cb handler, const void *data); 2422 2423 /** 2424 * Creates a pipe with more parameters. 2425 * 2426 * @param handler Same as ecore_pipe_add() 2427 * @param data Same as ecore_pipe_add() 2428 * @param fd_read An fd to use for reading or @c -1 otherwise 2429 * @param fd_write An fd to use for writing or @c -1 otherwise 2430 * @param read_survive_fork Should read fd survive a fork 2431 * @param write_survive_fork Should write fd survive a fork 2432 * 2433 * This is the same as ecore_pipe_add() but with some added parameters. 2434 * 2435 * @return A pointer to the new Ecore_Pipe object on success, else NULL. 2436 * @see ecore_pipe_add() 2437 */ 2438 EAPI Ecore_Pipe *ecore_pipe_full_add(Ecore_Pipe_Cb handler, 2439 const void *data, 2440 int fd_read, int fd_write, 2441 Eina_Bool read_survive_fork, 2442 Eina_Bool write_survive_fork); 2443 2444 /** 2445 * Frees an Ecore_Pipe object created with ecore_pipe_add(). 2446 * 2447 * @param p The Ecore_Pipe object to be freed. 2448 * @return The pointer to the private data 2449 */ 2450 EAPI void *ecore_pipe_del(Ecore_Pipe *p); 2451 2452 /** 2453 * Writes on the file descriptor the data passed as parameter. 2454 * 2455 * @param p The Ecore_Pipe object. 2456 * @param buffer The data to write into the pipe. 2457 * @param nbytes The size of the @p buffer in bytes. 2458 * @return @c EINA_TRUE on a successful write, @c EINA_FALSE on error. 2459 */ 2460 EAPI Eina_Bool ecore_pipe_write(Ecore_Pipe *p, const void *buffer, unsigned int nbytes); 2461 2462 /** 2463 * Closes the write end of an Ecore_Pipe object created with ecore_pipe_add(). 2464 * 2465 * @param p The Ecore_Pipe object. 2466 */ 2467 EAPI void ecore_pipe_write_close(Ecore_Pipe *p); 2468 2469 /** 2470 * Closes the read end of an Ecore_Pipe object created with ecore_pipe_add(). 2471 * 2472 * @param p The Ecore_Pipe object. 2473 */ 2474 EAPI void ecore_pipe_read_close(Ecore_Pipe *p); 2475 2476 /** 2477 * Gets the pipe read file descriptor. 2478 * 2479 * @param p The Ecore_Pipe object query. 2480 * @return The file descriptor, or @c -1 if none 2481 */ 2482 EAPI int ecore_pipe_read_fd(Ecore_Pipe *p); 2483 2484 /** 2485 * Gets the pipe write file descriptor. 2486 * 2487 * @param p The Ecore_Pipe object query. 2488 * @return The file descriptor, or @c -1 if none 2489 */ 2490 EAPI int ecore_pipe_write_fd(Ecore_Pipe *p); 2491 2492 /** 2493 * Starts monitoring again the pipe for reading. See ecore_pipe_freeze() for 2494 * stopping the monitoring activity. This will not work if 2495 * ecore_pipe_read_close() was previously called on the same pipe. 2496 * 2497 * @param p The Ecore_Pipe object. 2498 * @since 1.1 2499 */ 2500 EAPI void ecore_pipe_thaw(Ecore_Pipe *p); 2501 2502 /** 2503 * Stops monitoring if necessary the pipe for reading. See ecore_pipe_thaw() 2504 * for monitoring it again. 2505 * 2506 * @param p The Ecore_Pipe object. 2507 * @since 1.1 2508 */ 2509 EAPI void ecore_pipe_freeze(Ecore_Pipe *p); 2510 2511 /** 2512 * @brief Waits from another thread on the read side of a pipe. 2513 * 2514 * @param p The pipe to watch on. 2515 * @param message_count The minimum number of messages to wait for before exiting. 2516 * @param wait The amount of time in seconds to wait before exiting. 2517 * @return The number of message caught during the wait call. 2518 * @since 1.1 2519 * 2520 * Negative value for @p wait means infite wait. 2521 */ 2522 EAPI int ecore_pipe_wait(Ecore_Pipe *p, int message_count, double wait); 2523 2524 /** 2525 * @} 2526 */ 2527 2528 /** 2529 * @ingroup Ecore 2530 * @defgroup Ecore_Application_Group Ecore Application functions 2531 * 2532 * @{ 2533 */ 2534 2535 /** 2536 * Sets up the programs command-line arguments. 2537 * @param argc The same as passed as argc to the programs main() function 2538 * @param argv The same as passed as argv to the programs main() function 2539 * 2540 * A call to this function will store the programs command-line arguments 2541 * for later use by ecore_app_restart() or ecore_app_args_get(). 2542 */ 2543 EAPI void ecore_app_args_set(int argc, const char **argv); 2544 2545 /** 2546 * Returns the programs stored command-line arguments. 2547 * @param argc A pointer to the return value to hold argc 2548 * @param argv A pointer to the return value to hold argv 2549 * 2550 * When called, this function returns the arguments for the program stored by 2551 * ecore_app_args_set(). The integer pointed to by @p argc will be filled, if 2552 * the pointer is not NULL, and the string array pointer @p argv will be filled 2553 * also if the pointer is not NULL. The values they are filled with will be the 2554 * same set by ecore_app_args_set(). 2555 */ 2556 EAPI void ecore_app_args_get(int *argc, char ***argv); 2557 2558 /** 2559 * Restarts the program executable with the command-line arguments stored. 2560 * 2561 * This function will restart & re-execute this program in place of itself 2562 * using the command-line arguments stored by ecore_app_args_set(). This is 2563 * an easy way for a program to restart itself for cleanup purposes, 2564 * configuration reasons or in the event of a crash. 2565 */ 2566 EAPI void ecore_app_restart(void); 2567 2568 /** 2569 * @brief Do not load system modules for this application. 2570 * 2571 * Ecore will now load platform-specific system modules such as 2572 * power-management, time and locate monitors. 2573 * 2574 * Whenever this function is called @b before ecore_init(), ecore 2575 * won't load such modules. 2576 * 2577 * This may be useful to some command-line utilities, hardly will be 2578 * useful for end-user applications. 2579 * 2580 * The environment variable ECORE_NO_SYSTEM_MODULES=1 may be used 2581 * to temporarily disable system modules, often useful for debug. 2582 * 2583 * @since 1.8 2584 */ 2585 EAPI void ecore_app_no_system_modules(void); 2586 2587 /** 2588 * @} 2589 */ 2590 2591 /** 2592 * @ingroup Ecore_Main_Loop_Group 2593 * @defgroup Ecore_Throttle_Group Ecore Throttle functions 2594 * 2595 * @{ 2596 */ 2597 2598 /** 2599 * Increases throttle amount. 2600 * 2601 * This will increase or decrease (if @p amount is positive or negative) the 2602 * amount of "voluntary throttling" ecore will do to its main loop while 2603 * running. This is intended to be used to limit animations and wakeups when 2604 * in a strict power management state. The higher the current throttle value 2605 * (which can be retrieved by ecore_throttle_get() ), the more throttling 2606 * takes place. If the current throttle value is 0, then no throttling takes 2607 * place at all. 2608 * 2609 * The value represents how long the ecore main loop will sleep (in seconds) 2610 * before it goes into a fully idle state waiting for events, input or 2611 * timing events to wake it up. For example, if the current throttle level 2612 * is 0.5, then after every time the main loop cycles and goes into idle 2613 * after processing all events, the main loop will explicitly sleep for 0.5 2614 * seconds before sitting and waiting for incoming events or timeouts, thus 2615 * preventing animation, async IO and network handling etc. for that period 2616 * of time. Of course these events, data and timeouts will be buffered, 2617 * thus not losing anything, simply delaying when they get handled by the 2618 * throttle value. 2619 * 2620 * Example: 2621 * @code 2622 * void enter_powersave(void) { 2623 * ecore_throttle_adjust(0.2); 2624 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); 2625 * } 2626 * 2627 * void enter_deep_powersave(void) { 2628 * ecore_throttle_adjust(0.5); 2629 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); 2630 * } 2631 * 2632 * void exit_powersave(void) { 2633 * ecore_throttle_adjust(-0.2); 2634 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); 2635 * } 2636 * 2637 * void exit_deep_powersave(void) { 2638 * ecore_throttle_adjust(-0.5); 2639 * printf("Now at throttle level: %1.3f\n", ecore_throttle_get()); 2640 * } 2641 * @endcode 2642 * 2643 * @param amount Amount (in seconds) to adjust by 2644 */ 2645 EAPI void ecore_throttle_adjust(double amount); 2646 2647 /** 2648 * Gets current throttle level. 2649 * 2650 * This gets the current throttling level, which can be adjusted by 2651 * ecore_throttle_adjust(). The value is in seconds. Please see 2652 * ecore_throttle_adjust() for more information. 2653 * 2654 * @return The current throttle level. 2655 */ 2656 EAPI double ecore_throttle_get(void); 2657 2658 /** 2659 * @} 2660 */ 2661 2662 /** 2663 * @defgroup Ecore_Poller_Group Ecore Poll functions 2664 * @ingroup Ecore_Main_Loop_Group 2665 * 2666 * Ecore poller provides infrastructure for the creation of pollers. Pollers 2667 * are, in essence, callbacks that share a single timer per type. Because not 2668 * all pollers need to be called at the same frequency the user may specify the 2669 * frequency in ticks(each expiration of the shared timer is called a tick, in 2670 * ecore poller parlance) for each added poller. Ecore pollers should only be 2671 * used when the poller doesn't have specific requirements on the exact times 2672 * to poll. 2673 * 2674 * This architecture means that the main loop is only woken up once to handle 2675 * all pollers of that type, this will save power as the CPU has more of a 2676 * chance to go into a low power state the longer it is asleep for, so this 2677 * should be used in situations where power usage is a concern. 2678 * 2679 * For now only 1 core poller type is supported: ECORE_POLLER_CORE, the default 2680 * interval for ECORE_POLLER_CORE is 0.125(or 1/8th) second. 2681 * 2682 * The creation of a poller is extremely simple and only requires one line: 2683 * @code 2684 * ecore_poller_add(ECORE_POLLER_CORE, 1, my_poller_function, NULL); 2685 * @endcode 2686 * This sample creates a poller to call @c my_poller_function at every tick with 2687 * @c NULL as data. 2688 * 2689 * Example: 2690 * @li @ref ecore_poller_example_c 2691 * 2692 * @{ 2693 */ 2694 2695 /** 2696 * @} 2697 */ 2698 2699 /** 2700 * @ingroup Ecore_Main_Loop_Group 2701 * @defgroup Ecore_Animator_Group Ecore Animator functions 2702 * 2703 * @brief Ecore animators are a helper to simplify creating 2704 * animations. 2705 * 2706 * Creating an animation is as simple as saying for how long it 2707 * should be run and having a callback that does the animation, 2708 * something like this: 2709 * @code 2710 * static Eina_Bool 2711 * _do_animation(void *data, double pos) 2712 * { 2713 * evas_object_move(data, 100 * pos, 100 * pos); 2714 * ... do some more animating ... 2715 * } 2716 * ... 2717 * ecore_animator_timeline_add(2, _do_animation, my_evas_object); 2718 * @endcode 2719 * In the sample above we create an animation to move 2720 * @c my_evas_object from position (0,0) to (100,100) in 2 seconds. 2721 * 2722 * If your animation will run for an unspecified amount of time you 2723 * can use ecore_animator_add(), which is like using 2724 * ecore_timer_add() with the interval being the 2725 * @ref ecore_animator_frametime_set "framerate". Note that this has 2726 * tangible benefits to creating a timer for each animation in terms 2727 * of performance. 2728 * 2729 * For a more detailed example that show several animation see 2730 * @ref tutorial_ecore_animator. 2731 * 2732 * @{ 2733 */ 2734 2735 /** Defines the timing sources for animators. */ 2736 typedef enum 2737 { 2738 ECORE_ANIMATOR_SOURCE_TIMER, /**< The default system clock/timer based animator that ticks every "frametime" seconds */ 2739 ECORE_ANIMATOR_SOURCE_CUSTOM /**< A custom animator trigger that you need to call ecore_animator_custom_tick() to make it tick */ 2740 } Ecore_Animator_Source; 2741 2742 /** 2743 * @typedef Ecore_Timeline_Cb Ecore_Timeline_Cb 2744 * A callback run for a task (animators with runtimes) 2745 */ 2746 typedef Eina_Bool (*Ecore_Timeline_Cb)(void *data, double pos); 2747 2748 /** Defines the position mappings for the animation. */ 2749 typedef enum 2750 { 2751 ECORE_POS_MAP_LINEAR = 0, /**< Linear 0.0 -> 1.0 */ 2752 ECORE_POS_MAP_ACCELERATE, /**< Start slow then speed up */ 2753 ECORE_POS_MAP_DECELERATE, /**< Start fast then slow down */ 2754 ECORE_POS_MAP_SINUSOIDAL, /**< Start slow, speed up then slow down at end */ 2755 ECORE_POS_MAP_ACCELERATE_FACTOR, /**< Start slow then speed up, v1 being a 2756 * power factor, 0.0 being linear, 1.0 being 2757 * normal accelerate, 2.0 being much more 2758 * pronounced accelerate (squared), 3.0 2759 * being cubed, etc. */ 2760 ECORE_POS_MAP_DECELERATE_FACTOR, /**< Start fast then slow down, v1 being a 2761 * power factor, 0.0 being linear, 1.0 being 2762 * normal decelerate, 2.0 being much more 2763 * pronounced decelerate (squared), 3.0 2764 * being cubed, etc. */ 2765 ECORE_POS_MAP_SINUSOIDAL_FACTOR, /**< Start slow, speed up then slow down at 2766 * end, v1 being a power factor, 0.0 being 2767 * linear, 1.0 being normal sinusoidal, 2.0 2768 * being much more pronounced sinusoidal 2769 * (squared), 3.0 being cubed, etc. */ 2770 ECORE_POS_MAP_DIVISOR_INTERP, /**< Start at gradient * v1, interpolated via 2771 * power of v2 curve */ 2772 ECORE_POS_MAP_BOUNCE, /**< Start at 0.0 then "drop" like a ball bouncing to 2773 * the ground at 1.0, and bounce v2 times, with decay 2774 * factor of v1 */ 2775 ECORE_POS_MAP_SPRING, /**< Start at 0.0 then "wobble" like a spring rest 2776 * position 1.0, and wobble v2 times, with decay factor 2777 * of v1 */ 2778 ECORE_POS_MAP_CUBIC_BEZIER /**< Follow the cubic-bezier curve calculated with 2779 * the control points (x1, y1), (x2, y2) */ 2780 } Ecore_Pos_Map; 2781 2782 /* 2783 * @since 1.8 2784 */ 2785 2786 /** 2787 * @brief Sets the animator call interval in seconds. 2788 * 2789 * @param frametime The time in seconds in between animator ticks. 2790 * 2791 * This function sets the time interval (in seconds) between animator ticks. 2792 * At every tick the callback of every existing animator will be called. 2793 * 2794 * @warning Too small a value may cause performance issues and too high a 2795 * value may cause your animation to seem "jerky". 2796 * 2797 * @note The default @p frametime value is 1/60th of a second. 2798 */ 2799 EAPI void ecore_animator_frametime_set(double frametime); 2800 2801 /** 2802 * @brief Gets the animator call interval in seconds. 2803 * 2804 * @return The time in second in between animator ticks. 2805 * 2806 * This function retrieves the time in seconds between animator ticks. 2807 * 2808 * @see ecore_animator_frametime_set() 2809 */ 2810 EAPI double ecore_animator_frametime_get(void); 2811 2812 /** 2813 * @brief Maps an input position from 0.0 to 1.0 along a timeline to a 2814 * position in a different curve. 2815 * 2816 * @param pos The input position to map 2817 * @param map The mapping to use 2818 * @param v1 A parameter use by the mapping (pass 0.0 if not used) 2819 * @param v2 A parameter use by the mapping (pass 0.0 if not used) 2820 * @return The mapped value 2821 * 2822 * Takes an input position (0.0 to 1.0) and maps to a new position (normally 2823 * between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it 2824 * has "overshot" the mark) using some interpolation (mapping) algorithm. 2825 * 2826 * This function useful to create non-linear animations. It offers a variety 2827 * of possible animation curves to be used: 2828 * @li ECORE_POS_MAP_LINEAR - Linear, returns @p pos 2829 * @li ECORE_POS_MAP_ACCELERATE - Start slow then speed up 2830 * @li ECORE_POS_MAP_DECELERATE - Start fast then slow down 2831 * @li ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at end 2832 * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v1 being a 2833 * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 2834 * being much more pronounced accelerate (squared), 3.0 being cubed, etc. 2835 * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v1 being a 2836 * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 2837 * being much more pronounced decelerate (squared), 3.0 being cubed, etc. 2838 * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down 2839 * at end, v1 being a power factor, 0.0 being linear, 1.0 being 2840 * ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal 2841 * (squared), 3.0 being cubed, etc. 2842 * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v1, interpolated via 2843 * power of v2 curve 2844 * @li ECORE_POS_MAP_BOUNCE - Start at 0.0 then "drop" like a ball bouncing to 2845 * the ground at 1.0, and bounce v2 times, with decay factor of v1 2846 * @li ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring rest 2847 * position 1.0, and wobble v2 times, with decay factor of v1 2848 * @note When not listed v1 and v2 have no effect. 2849 * 2850 * @image html ecore-pos-map.png 2851 * @image latex ecore-pos-map.eps width=\\textwidth 2852 * 2853 * One way to use this would be: 2854 * @code 2855 * double pos; // input position in a timeline from 0.0 to 1.0 2856 * double out; // output position after mapping 2857 * int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position 2858 * int x, y; // x & y are the calculated position 2859 * 2860 * out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 1.8, 7); 2861 * x = (x1 * out) + (x2 * (1.0 - out)); 2862 * y = (y1 * out) + (y2 * (1.0 - out)); 2863 * move_my_object_to(myobject, x, y); 2864 * @endcode 2865 * This will make an animation that bounces 7 each times diminishing by a 2866 * factor of 1.8. 2867 * 2868 * @see Ecore_Pos_Map 2869 * 2870 * @since 1.1.0 2871 */ 2872 EAPI double ecore_animator_pos_map(double pos, Ecore_Pos_Map map, double v1, double v2); 2873 2874 /** 2875 * @brief Maps an input position from 0.0 to 1.0 along a timeline to a 2876 * position in a different curve. 2877 * 2878 * @param pos The input position to map 2879 * @param map The mapping to use 2880 * @param v_size The size of the v array. 2881 * @param v An array with the double parameters to be used by the mapping. 2882 * NULL if not used. 2883 * @return The mapped value 2884 * 2885 * Takes an input position (0.0 to 1.0) and maps to a new position (normally 2886 * between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it 2887 * has "overshot" the mark) using some interpolation (mapping) algorithm. 2888 * 2889 * This function useful to create non-linear animations. It offers a variety 2890 * of possible animation curves to be used: 2891 * @li ECORE_POS_MAP_LINEAR - Linear, returns @p pos 2892 * @li ECORE_POS_MAP_ACCELERATE - Start slow then speed up 2893 * @li ECORE_POS_MAP_DECELERATE - Start fast then slow down 2894 * @li ECORE_POS_MAP_SINUSOIDAL - Start slow, speed up then slow down at end 2895 * @li ECORE_POS_MAP_ACCELERATE_FACTOR - Start slow then speed up, v[0] being a 2896 * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_ACCELERATE, 2.0 2897 * being much more pronounced accelerate (squared), 3.0 being cubed, etc. 2898 * @li ECORE_POS_MAP_DECELERATE_FACTOR - Start fast then slow down, v[0] being a 2899 * power factor, 0.0 being linear, 1.0 being ECORE_POS_MAP_DECELERATE, 2.0 2900 * being much more pronounced decelerate (squared), 3.0 being cubed, etc. 2901 * @li ECORE_POS_MAP_SINUSOIDAL_FACTOR - Start slow, speed up then slow down 2902 * at end, v[0] being a power factor, 0.0 being linear, 1.0 being 2903 * ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal 2904 * (squared), 3.0 being cubed, etc. 2905 * @li ECORE_POS_MAP_DIVISOR_INTERP - Start at gradient * v[0], interpolated via 2906 * power of v2 curve 2907 * @li ECORE_POS_MAP_BOUNCE - Start at 0.0 then "drop" like a ball bouncing to 2908 * the ground at 1.0, and bounce v2 times, with decay factor of v[0] 2909 * @li ECORE_POS_MAP_SPRING - Start at 0.0 then "wobble" like a spring rest 2910 * position 1.0, and wobble v2 times, with decay factor of v[0] 2911 * @li ECORE_POS_MAP_CUBIC_BEZIER - Use an interpolated cubic-bezier curve 2912 * adjusted with parameters from v[0] to v[3]. 2913 * @note When not listed v has no effect. 2914 * 2915 * @image html ecore-pos-map.png 2916 * @image latex ecore-pos-map.eps width=\\textwidth 2917 * 2918 * One way to use this would be: 2919 * @code 2920 * double pos; // input position in a timeline from 0.0 to 1.0 2921 * double out; // output position after mapping 2922 * int x1, y1, x2, y2; // x1 & y1 are start position, x2 & y2 are end position 2923 * int x, y; // x & y are the calculated position 2924 * double v[2] = {1.8, 7}; 2925 * 2926 * out = ecore_animator_pos_map(pos, ECORE_POS_MAP_BOUNCE, 2, v); 2927 * x = (x1 * out) + (x2 * (1.0 - out)); 2928 * y = (y1 * out) + (y2 * (1.0 - out)); 2929 * move_my_object_to(myobject, x, y); 2930 * @endcode 2931 * This will make an animation that bounces 7 each times diminishing by a 2932 * factor of 1.8. 2933 * 2934 * @see Ecore_Pos_Map 2935 */ 2936 EAPI double ecore_animator_pos_map_n(double pos, Ecore_Pos_Map map, int v_size, double *v); 2937 2938 /** 2939 * @brief Sets the source of animator ticks for the mainloop. 2940 * 2941 * @param source The source of animator ticks to use 2942 * 2943 * This sets the source of animator ticks. When an animator is active the 2944 * mainloop will "tick" over frame by frame calling all animators that are 2945 * registered until none are. The mainloop will tick at a given rate based 2946 * on the animator source. The default source is the system clock timer 2947 * source - ECORE_ANIMATOR_SOURCE_TIMER. This source uses the system clock 2948 * to tick over every N seconds (specified by ecore_animator_frametime_set(), 2949 * with the default being 1/60th of a second unless set otherwise). You can 2950 * set a custom tick source by setting the source to 2951 * ECORE_ANIMATOR_SOURCE_CUSTOM and then drive it yourself based on some input 2952 * tick source (like another application via ipc, some vertical blanking 2953 * interrupt, and etc.) using 2954 * ecore_animator_custom_source_tick_begin_callback_set() and 2955 * ecore_animator_custom_source_tick_end_callback_set() to set the functions 2956 * that will be called to start and stop the ticking source, which when it 2957 * gets a "tick" should call ecore_animator_custom_tick() to make the "tick" 2958 * over 1 frame. 2959 * 2960 * @see ecore_animator_source_get() 2961 */ 2962 EAPI void ecore_animator_source_set(Ecore_Animator_Source source); 2963 2964 /** 2965 * @brief Gets the animator source currently set. 2966 * 2967 * @return The current animator source 2968 * 2969 * This gets the current animator source. 2970 * 2971 * @see ecore_animator_source_set() 2972 */ 2973 EAPI Ecore_Animator_Source ecore_animator_source_get(void); 2974 2975 /** 2976 * @brief Sets the function that begins a custom animator tick source. 2977 * 2978 * @param func The function to call when ticking is to begin 2979 * @param data The data passed to the tick begin function as its parameter 2980 * 2981 * The Ecore Animator infrastructure handles tracking if animators are needed 2982 * or not and which ones need to be called and when, but when the tick source 2983 * is custom, you have to provide a tick source by calling 2984 * ecore_animator_custom_tick() to indicate a frame tick happened. In order 2985 * to allow the source of ticks to be dynamically enabled or disabled as 2986 * needed, the @p func when set is called to enable the tick source to 2987 * produce tick events that call ecore_animator_custom_tick(). If @p func 2988 * is @c NULL then no function is called to begin custom ticking. 2989 * 2990 * @warning Do not use this function unless you know what you are doing. 2991 * 2992 * @see ecore_animator_source_set() 2993 * @see ecore_animator_custom_source_tick_end_callback_set() 2994 * @see ecore_animator_custom_tick() 2995 */ 2996 EAPI void ecore_animator_custom_source_tick_begin_callback_set(Ecore_Cb func, const void *data); 2997 2998 /** 2999 * @brief Sets the function that ends a custom animator tick source. 3000 * 3001 * @param func The function to call when ticking is to end 3002 * @param data The data passed to the tick end function as its parameter 3003 * 3004 * This function is a matching pair to the function set by 3005 * ecore_animator_custom_source_tick_begin_callback_set() and is called 3006 * when ticking is to stop. If @p func is @c NULL then no function will be 3007 * called to stop ticking. For more information please see 3008 * ecore_animator_custom_source_tick_begin_callback_set(). 3009 * 3010 * @warning Do not use this function unless you know what you are doing. 3011 * 3012 * @see ecore_animator_source_set() 3013 * @see ecore_animator_custom_source_tick_begin_callback_set() 3014 * @see ecore_animator_custom_tick() 3015 */ 3016 EAPI void ecore_animator_custom_source_tick_end_callback_set(Ecore_Cb func, const void *data); 3017 3018 /** 3019 * @brief Triggers a custom animator tick. 3020 * 3021 * When animator source is set to ECORE_ANIMATOR_SOURCE_CUSTOM, then calling 3022 * this function triggers a run of all animators currently registered with 3023 * Ecore as this indicates a "frame tick" happened. This will do nothing if 3024 * the animator source(set by ecore_animator_source_set()) is not set to 3025 * ECORE_ANIMATOR_SOURCE_CUSTOM. 3026 * 3027 * @warning Do not use this function unless you know what you are doing. 3028 * 3029 * @see ecore_animator_source_set() 3030 * @see ecore_animator_custom_source_tick_begin_callback_set 3031 * @see ecore_animator_custom_source_tick_end_callback_set()() 3032 */ 3033 EAPI void ecore_animator_custom_tick(void); 3034 3035 /** 3036 * @} 3037 */ 3038 3039 /** 3040 * @ingroup Ecore_Main_Loop_Group 3041 * @defgroup Ecore_Timer_Group Ecore Timer functions 3042 * 3043 * Ecore provides very flexible timer functionality. The basic usage of timers, 3044 * to call a certain function at a certain interval can be achieved with a 3045 * single line: 3046 * @code 3047 * Eina_Bool my_func(void *data) { 3048 * do_funky_stuff_with_data(data); 3049 * return ECORE_CALLBACK_RENEW; 3050 * } 3051 * ecore_timer_add(interval_in_seconds, my_func, data_given_to_function); 3052 * @endcode 3053 * @note If the function was to be executed only once simply return 3054 * @c ECORE_CALLBACK_CANCEL instead. 3055 * 3056 * An example that shows the usage of a lot of these: 3057 * @li @ref ecore_timer_example_c 3058 * 3059 * @{ 3060 */ 3061 3062 /* 3063 * @since 1.8 3064 */ 3065 typedef Eo Ecore_Timer; /**< A handle for timers */ 3066 3067 #define _ECORE_TIMER_EO_CLASS_TYPE 3068 3069 /** 3070 * Retrieves the current precision used by timer infrastructure. 3071 * @return Current precision. 3072 * @see ecore_timer_precision_set() 3073 */ 3074 EAPI double ecore_timer_precision_get(void); 3075 3076 /** 3077 * @brief Sets the precision to be used by timer infrastructure. 3078 * 3079 * @param precision Allowed introduced timeout delay, in seconds. 3080 * 3081 * This sets the precision for @b all timers. The precision determines how much 3082 * of an difference from the requested interval is acceptable. One common reason 3083 * to use this function is to @b increase the allowed timeout and thus @b 3084 * decrease precision of the timers, this is because less precise the timers 3085 * result in the system waking up less often and thus consuming less resources. 3086 * 3087 * Be aware that kernel may delay delivery even further, these delays 3088 * are always possible due other tasks having higher priorities or 3089 * other scheduler policies. 3090 * 3091 * Example: 3092 * We have 2 timers, one that expires in a 2.0s and another that 3093 * expires in 2.1s, if precision is 0.1s, then the Ecore will request 3094 * for the next expire to happen in 2.1s and not 2.0s and another one 3095 * of 0.1 as it would before. 3096 * 3097 * @note Ecore is smart enough to see if there are timers in the 3098 * precision range, if it does not, in our example if no second timer 3099 * in (T + precision) existed, then it would use the minimum timeout. 3100 */ 3101 EAPI void ecore_timer_precision_set(double precision); 3102 3103 /** 3104 * This function returns a human readable text-based log for Ecore_Timer events. 3105 * 3106 * @return A heap allocated string, or NULL. It MUST be freed manually by the 3107 * caller using `free`. 3108 * 3109 * It only contains an useful implementation if EFL is built in debug build 3110 * profile, but it's safe to call it for any build profile. 3111 */ 3112 EAPI char *ecore_timer_dump(void); 3113 3114 /** 3115 * @} 3116 */ 3117 3118 /** 3119 * @ingroup Ecore_Main_Loop_Group 3120 * @defgroup Ecore_Idle_Group Ecore Idle functions 3121 * 3122 * The idler functionality in Ecore allows for callbacks to be called when the 3123 * program isn't handling @ref Ecore_Event_Group "events", @ref Ecore_Timer_Group 3124 * "timers" or @ref Ecore_FD_Handler_Group "fd handlers". 3125 * 3126 * There are three types of idlers: Enterers, Idlers(proper) and Exiters. They 3127 * are called, respectively, when the program is about to enter an idle state, 3128 * when the program is in an idle state and when the program has just left an 3129 * idle state and will begin processing @ref Ecore_Event_Group "events", @ref 3130 * Ecore_Timer_Group "timers" or @ref Ecore_FD_Handler_Group "fd handlers". 3131 * 3132 * Enterer callbacks are good for updating your program's state, if 3133 * it has a state engine. Once all of the enterer handlers are 3134 * called, the program will enter a "sleeping" state. 3135 * 3136 * Idler callbacks are called when the main loop has called all 3137 * enterer handlers. They are useful for interfaces that require 3138 * polling and timers would be too slow to use. 3139 * 3140 * Exiter callbacks are called when the main loop wakes up from an idle state. 3141 * 3142 * If no idler callbacks are specified, then the process literally 3143 * goes to sleep. Otherwise, the idler callbacks are called 3144 * continuously while the loop is "idle", using as much CPU as is 3145 * available to the process. 3146 * 3147 * @note Idle state doesn't mean that the @b program is idle, but 3148 * that the <b>main loop</b> is idle. It doesn't have any timers, 3149 * events, fd handlers or anything else to process (which in most 3150 * <em>event driven</em> programs also means that the @b program is 3151 * idle too, but it's not a rule). The program itself may be doing 3152 * a lot of processing in the idler, or in another thread, for 3153 * example. 3154 * 3155 * Example with functions that deal with idle state: 3156 * 3157 * @li @ref ecore_idler_example_c 3158 * 3159 * @{ 3160 */ 3161 3162 /* 3163 * @since 1.8 3164 */ 3165 typedef struct _Ecore_Factorized_Idle Ecore_Idler; /**< A handle for idlers */ 3166 3167 /* 3168 * @since 1.8 3169 */ 3170 typedef struct _Ecore_Factorized_Idle Ecore_Idle_Enterer; /**< A handle for idle enterers */ 3171 3172 /* 3173 * @since 1.8 3174 */ 3175 typedef struct _Ecore_Factorized_Idle Ecore_Idle_Exiter; /**< A handle for idle exiters */ 3176 3177 /** 3178 * @} 3179 */ 3180 3181 /** 3182 * @ingroup Ecore_Main_Loop_Group 3183 * @defgroup Ecore_Job_Group Ecore Job functions 3184 * 3185 * You can queue jobs that are to be done by the main loop when the 3186 * current event is dealt with. 3187 * 3188 * Jobs are processed by the main loop similarly to events. They 3189 * also will be executed in the order in which they were added. 3190 * 3191 * A good use for them is when you don't want to execute an action 3192 * immediately, but want to give the control back to the main loop 3193 * so that it will call your job callback when jobs start being 3194 * processed (and if there are other jobs added before yours, they 3195 * will be processed first). This also gives the chance to other 3196 * actions in your program to cancel the job before it is started. 3197 * 3198 * Examples of using @ref Ecore_Job : 3199 * @li @ref ecore_job_example_c 3200 * 3201 * @{ 3202 */ 3203 3204 /** 3205 * @since 1.8 3206 */ 3207 typedef struct _Ecore_Job Ecore_Job; /**< A job handle */ 3208 3209 #define _ECORE_JOB_EO_CLASS_TYPE 3210 /** 3211 * @} 3212 */ 3213 3214 #endif 3215