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