<html>
<head>
<title>Ecore: The Ecore Main Loop</title>
<meta http-equiv="content-type" content="text/html;charset=UTF-8">
<meta name="author" content="Andres Blanc" >
<link rel="icon" href="img/favicon.png" type="image/x-icon">
<link rel="shortcut icon" href="img/favicon.png" type="image/x-icon">
<link rel="icon" href="img/favicon.png" type="image/ico">
<link rel="shortcut icon" href="img/favicon.png" type="image/ico">
<link rel="stylesheet" type="text/css" href="e.css">
<link rel="stylesheet" type="text/css" href="edoxy.css">
</head>
<body>
<div id="container">
<div id="header">
<div class="layout">
<h1><span>Enlightenment</span></h1>
<h2><span>Beauty at your fingertips</span></h2>
<table cellspacing="0" cellpadding="0" width="100%"><tr>
<td id="header_logo">
<a href="http://www.enlightenment.org"></a>
</td>
<td id="header_menu">
<table cellspacing="0" cellpadding="0" align="right"><tr>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=home">Home</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=news">News</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=about">About</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=download">Download</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=support">Support</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=contribute">Contribute</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=contact">Contact</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://trac.enlightenment.org/e">Tracker</a></td>
<td class="nav_passive"><a class="nav_passive" href="http://www.enlightenment.org/p.php?p=docs">Docs</a></td>
</tr></table>
</td>
<td id="header_last"></td>
</tr></table>
<div class="doxytitle">
Ecore Documentation <small>at 2 Jul 2010</small>
</div>
<div class="menu-container">
<div class="submenu">
<ul class="current">
<li><a href="files.html">Files</a></li>
<li><a href="annotated.html">Data Structures</a></li>
<li><a href="globals.html">Globals</a></li>
<li><a href="modules.html">Modules</a></li>
<li><a href="pages.html">Related Pages</a></li>
<li class="current"><a href="index.html">Main Page</a></li>
</ul>
</div>
</div>
<div class="clear"></div>
</div>
</div>
<div id="content">
<div class="layout">
<!-- Generated by Doxygen 1.6.2-20100208 -->
<div class="contents">
<h1><a class="anchor" id="Ecore_Main_Loop_Page">The Ecore Main Loop </a></h1><h2><a class="anchor" id="intro">
What is Ecore?</a></h2>
<p>Ecore is a clean and tiny event loop library with many modules to do lots of convenient things for a programmer, to save time and effort.</p>
<p>It's small and lean, designed to work on embedded systems all the way to large and powerful multi-cpu workstations. It serialises all system signals, events etc. into a single event queue, that is easily processed without needing to worry about concurrency. A properly written, event-driven program using this kind of programming doesn't need threads, nor has to worry about concurrency. It turns a program into a state machine, and makes it very robust and easy to follow.</p>
<p>Ecore gives you other handy primitives, such as timers to tick over for you and call specified functions at particular times so the programmer can use this to do things, like animate, or time out on connections or tasks that take too long etc.</p>
<p>Idle handlers are provided too, as well as calls on entering an idle state (often a very good time to update the state of the program). All events that enter the system are passed to specific callback functions that the program sets up to handle those events. Handling them is simple and other Ecore modules produce more events on the queue, coming from other sources such as file descriptors etc.</p>
<p>Ecore also lets you have functions called when file descriptors become active for reading or writing, allowing for streamlined, non-blocking IO.</p>
<p>Here is an exmaple of a simple program and its basic event loop flow:</p>
<div align="center">
<img src="prog_flow.png" alt="prog_flow.png"/>
</div>
<h2><a class="anchor" id="work">
How does Ecore work?</a></h2>
<p>Ecore is very easy to learn and use. All the function calls are designed to be easy to remember, explicit in describing what they do, and heavily name-spaced. Ecore programs can start and be very simple.</p>
<p>For example:</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="Ecore_8h.html" title="The file that provides the program utility, main loop and timer functions.">Ecore.h</a>></span>
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keyword">const</span> <span class="keywordtype">char</span> **argv)
{
ecore_init();
<a class="code" href="Ecore_8h.html#aeb02de014af9bfbe960c9f70b085e229" title="Set up the programs command-line arguments.">ecore_app_args_set</a>(argc, argv);
<a class="code" href="group__Ecore__Main__Loop__Group.html#ga04daa7648a9d027bed25d27c150fdda7" title="Runs the application main loop.">ecore_main_loop_begin</a>();
ecore_shutdown();
<span class="keywordflow">return</span> 0;
}
</pre></div><p>This program is very simple and does't check for errors, but it does start up and begin a main loop waiting for events or timers to tick off. This program doesn't set up any, but now we can expand on this simple program a little more by adding some event handlers and timers.</p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <<a class="code" href="Ecore_8h.html" title="The file that provides the program utility, main loop and timer functions.">Ecore.h</a>></span>
<a class="code" href="Ecore_8h.html#a3663e895743d49c90122725fb1ceaebc" title="A handle for timers.">Ecore_Timer</a> *timer1 = NULL;
<a class="code" href="Ecore_8h.html#a252a2566c9c7c9094964ab8e157f0521" title="A handle for an event handler.">Ecore_Event_Handler</a> *handler1 = NULL;
<span class="keywordtype">double</span> start_time = 0.0;
<span class="keywordtype">int</span> timer_func(<span class="keywordtype">void</span> *data)
{
printf(<span class="stringliteral">"Tick timer. Sec: %3.2f\n"</span>, <a class="code" href="group__Ecore__Time__Group.html#ga43846b079394bb4d098abf5c16dfc544" title="Retrieves the current system time as a floating point value in seconds.">ecore_time_get</a>() - start_time);
<span class="keywordflow">return</span> 1;
}
<span class="keywordtype">int</span> exit_func(<span class="keywordtype">void</span> *data, <span class="keywordtype">int</span> ev_type, <span class="keywordtype">void</span> *ev)
{
<a class="code" href="struct__Ecore__Event__Signal__Exit.html" title="Exit request event.">Ecore_Event_Signal_Exit</a> *e;
e = (<a class="code" href="struct__Ecore__Event__Signal__Exit.html" title="Exit request event.">Ecore_Event_Signal_Exit</a> *)ev;
<span class="keywordflow">if</span> (e-><a class="code" href="struct__Ecore__Event__Signal__Exit.html#a1d0b2794e857a548bbd86ecc78c869fc" title="Set if the exit request was an interrupt signal.">interrupt</a>) printf(<span class="stringliteral">"Exit: interrupt\n"</span>);
<span class="keywordflow">else</span> <span class="keywordflow">if</span> (e-><a class="code" href="struct__Ecore__Event__Signal__Exit.html#aa89f51e1690caa1cceb33ee29d489f04" title="set if the exit request was a quit signal">quit</a>) printf(<span class="stringliteral">"Exit: quit\n"</span>);
<span class="keywordflow">else</span> <span class="keywordflow">if</span> (e-><a class="code" href="struct__Ecore__Event__Signal__Exit.html#a6bec0a82c044a5f8ffa84dc0c3387a27" title="Set if the exit request was a terminate singal.">terminate</a>) printf(<span class="stringliteral">"Exit: terminate\n"</span>);
<a class="code" href="group__Ecore__Main__Loop__Group.html#ga329898ea4b32333c12c34cfde48326fd" title="Quits the main loop once all the events currently on the queue have been processed...">ecore_main_loop_quit</a>();
<span class="keywordflow">return</span> 1;
}
<span class="keywordtype">int</span> main(<span class="keywordtype">int</span> argc, <span class="keyword">const</span> <span class="keywordtype">char</span> **argv)
{
ecore_init();
<a class="code" href="Ecore_8h.html#aeb02de014af9bfbe960c9f70b085e229" title="Set up the programs command-line arguments.">ecore_app_args_set</a>(argc, argv);
start_time = <a class="code" href="group__Ecore__Time__Group.html#ga43846b079394bb4d098abf5c16dfc544" title="Retrieves the current system time as a floating point value in seconds.">ecore_time_get</a>();
handler1 = <a class="code" href="Ecore_8h.html#a2f2a52b06e720932685c1d408db0a17d" title="Add an event handler.">ecore_event_handler_add</a>(<a class="code" href="Ecore_8h.html#a0dd1e36930ae8fa8decc97564d57f310" title="Exit signal event.">ECORE_EVENT_SIGNAL_EXIT</a>, exit_func, NULL);
timer1 = <a class="code" href="group__Ecore__Time__Group.html#gaa3ed1b744e32f1131bee2fc52afd73de" title="Creates a timer to call the given function in the given period of time.">ecore_timer_add</a>(0.5, timer_func, NULL);
<a class="code" href="group__Ecore__Main__Loop__Group.html#ga04daa7648a9d027bed25d27c150fdda7" title="Runs the application main loop.">ecore_main_loop_begin</a>();
ecore_shutdown();
<span class="keywordflow">return</span> 0;
}
</pre></div><p>In the previous example, we initialize our application and get the time at which our program has started so we can calculate an offset. We set up a timer to tick off in 0.5 seconds, and since it returns 1, will keep ticking off every 0.5 seconds until it returns 0, or is deleted by hand. An event handler is set up to call a function - exit_func(), whenever an event of type ECORE_EVENT_SIGNAL_EXIT is received (CTRL-C on the command line will cause such an event to happen). If this event occurs it tells you what kind of exit signal was received, and asks the main loop to quit when it is finished by calling <a class="el" href="group__Ecore__Main__Loop__Group.html#ga329898ea4b32333c12c34cfde48326fd" title="Quits the main loop once all the events currently on the queue have been processed...">ecore_main_loop_quit()</a>.</p>
<p>The handles returned by <a class="el" href="group__Ecore__Time__Group.html#gaa3ed1b744e32f1131bee2fc52afd73de" title="Creates a timer to call the given function in the given period of time.">ecore_timer_add()</a> and <a class="el" href="Ecore_8h.html#a2f2a52b06e720932685c1d408db0a17d" title="Add an event handler.">ecore_event_handler_add()</a> are only stored here as an example. If you don't need to address the timer or event handler again you don't need to store the result, so just call the function, and don't assign the result to any variable.</p>
<p>This program looks slightly more complex than needed to do these simple things, but in principle, programs don't get any more complex. You add more event handlers, for more events, will have more timers and such, BUT it all follows the same principles as shown in this example. </p>
</div>
<div id="push"></div>
</div> <!-- #content -->
</div> <!-- .layout -->
</div> <!-- #container -->
<div id="footer">
<table><tr>
<td class="copyright">Copyright ©2010 Enlightenment</td>
<td class="generated">Docs generated Fri Jul 2 12:11:49 2010</td>
</tr></table>
</div>
</body>
</html>
