Ecore - Main Loop and Job Functions.

The file that provides the program utility, main loop and timer functions. More...

Data Structures

struct  _Ecore_Event_Signal_User
 User signal event. More...
struct  _Ecore_Event_Signal_Hup
 Hup signal event. More...
struct  _Ecore_Event_Signal_Exit
 Exit request event. More...
struct  _Ecore_Event_Signal_Power
 Power event. More...
struct  _Ecore_Event_Signal_Realtime
 Realtime event. More...
struct  _Ecore_Exe_Event_Add
 Process add event. More...
struct  _Ecore_Exe_Event_Del
 Process exit event. More...
struct  _Ecore_Exe_Event_Data_Line
 < Lines from a child process More...
struct  _Ecore_Exe_Event_Data
 Data from a child process event. More...

Modules

 Ecore initialisation and shutdown functions.
 Ecore Animator functions
 Ecore Application functions
 Ecore Event functions
 Process Spawning Functions
 

Functions that deal with and send signals to spawned processes.


 Ecore Idle functions
 

Callbacks that are called when the program enters or exits an idle state.


 Ecore Job functions
 

You can queue jobs that are to be done by the main loop when the current event is dealt with.


 Ecore Main Loop functions
 

These functions control the Ecore event handling loop.


 Pipe wrapper
 

These functions wrap the pipe / write / read functions to easily integrate a loop that is in its own thread to the ecore main loop.


 Ecore Poll functions
 

These functions are for the need to poll information, but provide a shared abstracted API to pool such polling to minimise wakeup and ensure all the polling happens in as few spots as possible areound a core poll interval.


 Ecore Thread functions
 

These functions allow for ecore-managed threads which integrate with ecore's main loop.


 Ecore Time functions
 

Functions that deal with time.


Defines

#define ECORE_CALLBACK_CANCEL   EINA_FALSE
 Return value to remove a callback.
#define ECORE_CALLBACK_RENEW   EINA_TRUE
 Return value to keep a callback.
#define ECORE_CALLBACK_PASS_ON   EINA_TRUE
 Return value to pass event to next handler.
#define ECORE_CALLBACK_DONE   EINA_FALSE
 Return value to stop event handling.
#define ECORE_EVENT_SIGNAL_USER   1
 User signal event.
#define ECORE_EVENT_SIGNAL_HUP   2
 Hup signal event.
#define ECORE_EVENT_SIGNAL_EXIT   3
 Exit signal event.
#define ECORE_EVENT_SIGNAL_POWER   4
 Power signal event.
#define ECORE_EVENT_SIGNAL_REALTIME   5
 Realtime signal event.

Typedefs

typedef struct _Ecore_Exe Ecore_Exe
 A handle for spawned processes.
typedef struct _Ecore_Timer Ecore_Timer
 A handle for timers.
typedef struct _Ecore_Idler Ecore_Idler
 A handle for idlers.
typedef struct _Ecore_Idle_Enterer Ecore_Idle_Enterer
 A handle for idle enterers.
typedef struct _Ecore_Idle_Exiter Ecore_Idle_Exiter
 A handle for idle exiters.
typedef struct _Ecore_Fd_Handler Ecore_Fd_Handler
 A handle for Fd handlers.
typedef struct _Ecore_Win32_Handler Ecore_Win32_Handler
 A handle for HANDLE handlers on Windows.
typedef struct _Ecore_Event_Handler Ecore_Event_Handler
 A handle for an event handler.
typedef struct _Ecore_Event_Filter Ecore_Event_Filter
 A handle for an event filter.
typedef struct _Ecore_Event Ecore_Event
 A handle for an event.
typedef struct _Ecore_Animator Ecore_Animator
 A handle for animators.
typedef struct _Ecore_Pipe Ecore_Pipe
 A handle for pipes.
typedef struct _Ecore_Poller Ecore_Poller
 A handle for pollers.
typedef struct
_Ecore_Event_Signal_User 
Ecore_Event_Signal_User
 User signal event.
typedef struct
_Ecore_Event_Signal_Hup 
Ecore_Event_Signal_Hup
 Hup signal event.
typedef struct
_Ecore_Event_Signal_Exit 
Ecore_Event_Signal_Exit
 Exit signal event.
typedef struct
_Ecore_Event_Signal_Power 
Ecore_Event_Signal_Power
 Power signal event.
typedef struct
_Ecore_Event_Signal_Realtime 
Ecore_Event_Signal_Realtime
 Realtime signal event.
typedef struct _Ecore_Exe_Event_Add Ecore_Exe_Event_Add
 Spawned Exe add event.
typedef struct _Ecore_Exe_Event_Del Ecore_Exe_Event_Del
 Spawned Exe exit event.
typedef struct
_Ecore_Exe_Event_Data_Line 
Ecore_Exe_Event_Data_Line
 Lines from a child process.
typedef struct
_Ecore_Exe_Event_Data 
Ecore_Exe_Event_Data
 Data from a child process.
typedef void *(* Ecore_Data_Cb )(void *data)
 A callback which is used to return data to the main function.
typedef Eina_Bool(* Ecore_Filter_Cb )(void *data, void *loop_data, int type, void *event)
 A callback used for filtering events from the main loop.
typedef void(* Ecore_End_Cb )(void *user_data, void *func_data)
 This is the callback which is called at the end of a function, usually for cleanup purposes.
typedef void(* Ecore_Pipe_Cb )(void *data, void *buffer, unsigned int nbyte)
 The callback that data written to the pipe is sent to.
typedef void(* Ecore_Exe_Cb )(void *data, const Ecore_Exe *exe)
 A callback to run with the associated Ecore_Exe, usually for cleanup purposes.
typedef Eina_Bool(* Ecore_Event_Handler_Cb )(void *data, int type, void *event)
 A callback used by the main loop to handle events of a specified type.
typedef void(* Ecore_Thread_Cb )(void *data, Ecore_Thread *thread)
 A callback used by Ecore_Thread helper.
typedef void(* Ecore_Thread_Notify_Cb )(void *data, Ecore_Thread *thread, void *msg_data)
 A callback used by the main loop to receive data sent by an Ecore Thread functions.
typedef Eina_Bool(* Ecore_Task_Cb )(void *data)
 A callback run for a task (timer, idler, poller, animater, etc).
typedef void(* Ecore_Cb )(void *data)
 A generic callback called as a hook when a certain point in execution is reached.
typedef Eina_Bool(* Ecore_Fd_Cb )(void *data, Ecore_Fd_Handler *fd_handler)
 A callback used by an Ecore_Fd_Handler.
typedef void(* Ecore_Fd_Prep_Cb )(void *data, Ecore_Fd_Handler *fd_handler)
 A callback used by an Ecore_Fd_Handler.
typedef Eina_Bool(* Ecore_Win32_Handle_Cb )(void *data, Ecore_Win32_Handler *wh)
 A callback used by an Ecore_Win32_Handler.
typedef struct _Ecore_Job Ecore_Job
 A job handle.

Enumerations

enum  _Ecore_Fd_Handler_Flags {
  ECORE_FD_READ = 1,
  ECORE_FD_WRITE = 2,
  ECORE_FD_ERROR = 4
}
enum  _Ecore_Exe_Flags {
  ECORE_EXE_NONE = 0,
  ECORE_EXE_PIPE_READ = 1,
  ECORE_EXE_PIPE_WRITE = 2,
  ECORE_EXE_PIPE_ERROR = 4,
  ECORE_EXE_PIPE_READ_LINE_BUFFERED = 8,
  ECORE_EXE_PIPE_ERROR_LINE_BUFFERED = 16,
  ECORE_EXE_PIPE_AUTO = 32,
  ECORE_EXE_RESPAWN = 64,
  ECORE_EXE_USE_SH = 128,
  ECORE_EXE_NOT_LEADER = 256
}
enum  _Ecore_Exe_Win32_Priority {
  ECORE_EXE_WIN32_PRIORITY_IDLE,
  ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL,
  ECORE_EXE_WIN32_PRIORITY_NORMAL,
  ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL,
  ECORE_EXE_WIN32_PRIORITY_HIGH,
  ECORE_EXE_WIN32_PRIORITY_REALTIME
}
enum  _Ecore_Poller_Type { ECORE_POLLER_CORE = 0 }

Functions

EAPI int ecore_init (void)
 Set up connections, signal handlers, sockets etc.
EAPI int ecore_shutdown (void)
 Shut down connections, signal handlers sockets etc.
EAPI Ecore_Pipeecore_pipe_add (Ecore_Pipe_Cb handler, const void *data)
 Create two file descriptors (sockets on Windows).
EAPI void * ecore_pipe_del (Ecore_Pipe *p)
 Free an Ecore_Pipe object created with ecore_pipe_add().
EAPI void ecore_pipe_read_close (Ecore_Pipe *p)
 Close the read end of an Ecore_Pipe object created with ecore_pipe_add().
EAPI void ecore_pipe_write_close (Ecore_Pipe *p)
 Close the write end of an Ecore_Pipe object created with ecore_pipe_add().
EAPI Eina_Bool ecore_pipe_write (Ecore_Pipe *p, const void *buffer, unsigned int nbytes)
 Write on the file descriptor the data passed as parameter.

Variables

EAPI int ECORE_EXE_EVENT_ADD
 A child process has been added.
EAPI int ECORE_EXE_EVENT_DEL
 A child process has been deleted (it exited, naming consistent with the rest of ecore).
EAPI int ECORE_EXE_EVENT_DATA
 Data from a child process.
EAPI int ECORE_EXE_EVENT_ERROR
 Errors from a child process.

Detailed Description

The file that provides the program utility, main loop and timer functions.

This header provides the Ecore event handling loop. For more details, see Ecore Main Loop functions.

For the main loop to be of any use, you need to be able to add events and event handlers. Events for file descriptor events are covered in File Event Handling Functions.

Time functions are covered in Ecore Time functions.

There is also provision for callbacks for when the loop enters or exits an idle state. See Idle_Group for more information.

Functions are also provided for spawning child processes using fork. See Process Spawning Functions for more details.


Enumeration Type Documentation

Enumerator:
ECORE_EXE_NONE 

No exe flags at all.

ECORE_EXE_PIPE_READ 

Exe Pipe Read mask.

ECORE_EXE_PIPE_WRITE 

Exe Pipe Write mask.

ECORE_EXE_PIPE_ERROR 

Exe Pipe error mask.

ECORE_EXE_PIPE_READ_LINE_BUFFERED 

Reads are buffered until a newline and delivered 1 event per line.

ECORE_EXE_PIPE_ERROR_LINE_BUFFERED 

Errors are buffered until a newline and delivered 1 event per line.

ECORE_EXE_PIPE_AUTO 

stdout and stderr are buffered automatically

ECORE_EXE_RESPAWN 

FIXME: Exe is restarted if it dies.

ECORE_EXE_USE_SH 

Use /bin/sh to run the command.

ECORE_EXE_NOT_LEADER 

Do not use setsid() to have the executed process be its own session leader.

Enumerator:
ECORE_EXE_WIN32_PRIORITY_IDLE 

Idle priority, for monitoring the system.

ECORE_EXE_WIN32_PRIORITY_BELOW_NORMAL 

Below default priority.

ECORE_EXE_WIN32_PRIORITY_NORMAL 

Default priority.

ECORE_EXE_WIN32_PRIORITY_ABOVE_NORMAL 

Above default priority.

ECORE_EXE_WIN32_PRIORITY_HIGH 

High priority, use with care as other threads in the system will not get processor time.

ECORE_EXE_WIN32_PRIORITY_REALTIME 

Realtime priority, should be almost never used as it can interrupt system threads that manage mouse input, keyboard input, and background disk flushing.

Enumerator:
ECORE_FD_READ 

Fd Read mask.

ECORE_FD_WRITE 

Fd Write mask.

ECORE_FD_ERROR 

Fd Error mask.

Enumerator:
ECORE_POLLER_CORE 

The core poller interval.


Function Documentation

EAPI int ecore_init ( void   ) 

Set up connections, signal handlers, sockets etc.

Returns:
1 or greater on success, 0 otherwise

This function sets up all singal handlers and the basic event loop. If it succeeds, 1 will be returned, otherwise 0 will be returned.

 #include <Ecore.h>

 int main(int argc, char **argv)
 {
   if (!ecore_init())
   {
     printf("ERROR: Cannot init Ecore!\n");
     return -1;
   }
   ecore_main_loop_begin();
   ecore_shutdown();
 }

References ecore_animator_add(), and ecore_main_loop_glib_integrate().

Referenced by ecore_evas_init(), ecore_imf_init(), and ecore_x_init().

EAPI Ecore_Pipe* ecore_pipe_add ( Ecore_Pipe_Cb  handler,
const void *  data 
)

Create two file descriptors (sockets on Windows).

Add a callback that will be called when the file descriptor that is listened receives data. An event is also put in the event queue when data is received.

Parameters:
handler The handler called when data is received.
data Data to pass to handler when it is called.
Returns:
A newly created Ecore_Pipe object if successful. NULL otherwise.

References ECORE_FD_READ, and ecore_main_fd_handler_add().

Referenced by ecore_thread_feedback_run().

EAPI void* ecore_pipe_del ( Ecore_Pipe p  ) 

Free an Ecore_Pipe object created with ecore_pipe_add().

Parameters:
p The Ecore_Pipe object to be freed.
Returns:
The pointer to the private data

References ecore_main_fd_handler_del().

Referenced by ecore_thread_feedback_run().

EAPI void ecore_pipe_read_close ( Ecore_Pipe p  ) 

Close the read end of an Ecore_Pipe object created with ecore_pipe_add().

Parameters:
p The Ecore_Pipe object.

References ecore_main_fd_handler_del().

EAPI Eina_Bool ecore_pipe_write ( Ecore_Pipe p,
const void *  buffer,
unsigned int  nbytes 
)

Write on the file descriptor the data passed as parameter.

Parameters:
p The Ecore_Pipe object.
buffer The data to write into the pipe.
nbytes The size of the buffer in bytes
Returns:
Returns EINA_TRUE on a successful write, EINA_FALSE on an error

Referenced by ecore_thread_feedback().

EAPI void ecore_pipe_write_close ( Ecore_Pipe p  ) 

Close the write end of an Ecore_Pipe object created with ecore_pipe_add().

Parameters:
p The Ecore_Pipe object.
EAPI int ecore_shutdown ( void   ) 

Shut down connections, signal handlers sockets etc.

This function shuts down all things set up in ecore_init() and cleans up all event queues, handlers, filters, timers, idlers, idle enterers/exiters etc. set up after ecore_init() was called.

Do not call this function from any callback that may be called from the main loop, as the main loop will then fall over and not function properly.

Referenced by ecore_evas_init(), ecore_evas_shutdown(), ecore_imf_init(), ecore_imf_shutdown(), and ecore_x_init().


Variable Documentation

Data from a child process.

A child process has been deleted (it exited, naming consistent with the rest of ecore).

Errors from a child process.