<html>
<head>
<title>Embryo: Program Run Functions</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" media="screen" href="e.css">
<link rel="stylesheet" type="text/css" media="screen" 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>
<div class="menu-container">
<div class="menu">
<ul>
<li class="current"><a href="http://web.enlightenment.org/p.php?p=docs">Docs</a></li>
<li><a href="http://trac.enlightenment.org/e">Tracker</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=contact">Contact</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=contribute">Contribute</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=support">Support</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=download">Download</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=about">About</a></li>
<li><a href="http://www.enlightenment.org/p.php?p=news">News</a></li>
<li><a href="http://www.enlightenment.org/">Home</a></li>
</ul>
</div>
</div>
<div class="doxytitle">
Embryo Documentation <small>at Tue Feb 8 2011</small>
</div>
<div class="menu-container">
<div class="submenu">
<ul class="current">
<li><a href="todo.html">Todo</a></li>
<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.7.3 -->
</div>
<div class="header">
<div class="summary">
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<h1>Program Run Functions</h1> </div>
</div>
<div class="contents">
<p>Functions that are involved in actually running functions in an Embryo program.
<a href="#_details">More...</a></p>
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">EAPI int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__Embryo__Run__Group.html#ga4497fa4413a00d7f482772cdc6f7309d">embryo_program_recursion_get</a> (Embryo_Program *ep)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Returns the number of virtual machines are running for the given program. <a href="#ga4497fa4413a00d7f482772cdc6f7309d"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">EAPI Embryo_Status </td><td class="memItemRight" valign="bottom"><a class="el" href="group__Embryo__Run__Group.html#ga29c5d998350f875882c2672c9be617c6">embryo_program_run</a> (Embryo_Program *ep, Embryo_Function fn)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Runs the given function of the given Embryo program in the current virtual machine. <a href="#ga29c5d998350f875882c2672c9be617c6"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">EAPI Embryo_Cell </td><td class="memItemRight" valign="bottom"><a class="el" href="group__Embryo__Run__Group.html#ga91a7c05bafd22e94d776a117a297201d">embryo_program_return_value_get</a> (Embryo_Program *ep)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Retreives the return value of the last called function of the given program. <a href="#ga91a7c05bafd22e94d776a117a297201d"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">EAPI void </td><td class="memItemRight" valign="bottom"><a class="el" href="group__Embryo__Run__Group.html#ga493d2e507082b46cdbc57708a1f6e239">embryo_program_max_cycle_run_set</a> (Embryo_Program *ep, int max)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Sets the maximum number of abstract machine cycles any given program run can execute before being put to sleep and returning. <a href="#ga493d2e507082b46cdbc57708a1f6e239"></a><br/></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">EAPI int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__Embryo__Run__Group.html#ga2bf3e76b53faadccc60c11093c795425">embryo_program_max_cycle_run_get</a> (Embryo_Program *ep)</td></tr>
<tr><td class="mdescLeft"> </td><td class="mdescRight">Retreives the maximum number of abstract machine cycles a program is allowed to run. <a href="#ga2bf3e76b53faadccc60c11093c795425"></a><br/></td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Functions that are involved in actually running functions in an Embryo program. </p>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga2bf3e76b53faadccc60c11093c795425"></a><!-- doxytag: member="embryo_amx.c::embryo_program_max_cycle_run_get" ref="ga2bf3e76b53faadccc60c11093c795425" args="(Embryo_Program *ep)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">EAPI int embryo_program_max_cycle_run_get </td>
<td>(</td>
<td class="paramtype">Embryo_Program * </td>
<td class="paramname"><em>ep</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retreives the maximum number of abstract machine cycles a program is allowed to run. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">ep</td><td>The given program. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The number of cycles a run cycle is allowed to run for this program.</dd></dl>
<p>This returns the value set by <a class="el" href="group__Embryo__Run__Group.html#ga493d2e507082b46cdbc57708a1f6e239" title="Sets the maximum number of abstract machine cycles any given program run can execute before being put...">embryo_program_max_cycle_run_set()</a>. See <a class="el" href="group__Embryo__Run__Group.html#ga493d2e507082b46cdbc57708a1f6e239" title="Sets the maximum number of abstract machine cycles any given program run can execute before being put...">embryo_program_max_cycle_run_set()</a> for more information. </p>
</div>
</div>
<a class="anchor" id="ga493d2e507082b46cdbc57708a1f6e239"></a><!-- doxytag: member="embryo_amx.c::embryo_program_max_cycle_run_set" ref="ga493d2e507082b46cdbc57708a1f6e239" args="(Embryo_Program *ep, int max)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">EAPI void embryo_program_max_cycle_run_set </td>
<td>(</td>
<td class="paramtype">Embryo_Program * </td>
<td class="paramname"><em>ep</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>max</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Sets the maximum number of abstract machine cycles any given program run can execute before being put to sleep and returning. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">ep</td><td>The given program. </td></tr>
<tr><td class="paramname">max</td><td>The number of machine cycles as a limit.</td></tr>
</table>
</dd>
</dl>
<p>This sets the maximum number of abstract machine (virtual machine) instructions that a single run of an embryo function (even if its main) can use before embryo <a class="el" href="group__Embryo__Run__Group.html#ga29c5d998350f875882c2672c9be617c6" title="Runs the given function of the given Embryo program in the current virtual machine.">embryo_program_run()</a> reutrns with the value EMBRYO_PROGRAM_TOOLONG. If the function fully executes within this number of cycles, <a class="el" href="group__Embryo__Run__Group.html#ga29c5d998350f875882c2672c9be617c6" title="Runs the given function of the given Embryo program in the current virtual machine.">embryo_program_run()</a> will return as normal with either EMBRYO_PROGRAM_OK, EMBRYO_PROGRAM_FAIL or EMBRYO_PROGRAM_SLEEP. If the run exceeds this instruction count, then EMBRYO_PROGRAM_TOOLONG will be returned indicating the program exceeded its run count. If the app wishes to continue running this anyway - it is free to process its own events or whatever it wants and continue the function by calling embryo_program_run(program, EMBRYO_FUNCTION_CONT); which will start the run again until the instruction count is reached. This can keep being done to allow the calling program to still be able to control things outside the embryo function being called. If the maximum run cycle count is 0 then the program is allowed to run forever only returning when it is done.</p>
<p>It is important to note that abstract machine cycles are NOT the same as the host machine cpu cycles. They are not fixed in runtime per cycle, so this is more of a helper tool than a way to HARD-FORCE a script to only run for a specific period of time. If the cycle count is set to something low like 5000 or 1000, then every 1000 (or 5000) cycles control will be returned to the calling process where it can check a timer to see if a physical runtime limit has been elapsed and then abort running further assuming a "runaway script" or keep continuing the script run. This limits resolution to only that many cycles which do not take a determined amount of time to execute, as this varies from cpu to cpu and also depends on how loaded the system is. Making the max cycle run too low will impact performance requiring the abstract machine to do setup and teardown cycles too often comapred to cycles actually executed.</p>
<p>Also note it does NOT include nested abstract machines. IF this abstract machine run calls embryo script that calls a native function that in turn calls more embryo script, then the 2nd (and so on) levels are not included in this run count. They can set their own max instruction count values separately.</p>
<p>The default max cycle run value is 0 in any program until set with this function. </p>
</div>
</div>
<a class="anchor" id="ga4497fa4413a00d7f482772cdc6f7309d"></a><!-- doxytag: member="embryo_amx.c::embryo_program_recursion_get" ref="ga4497fa4413a00d7f482772cdc6f7309d" args="(Embryo_Program *ep)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">EAPI int embryo_program_recursion_get </td>
<td>(</td>
<td class="paramtype">Embryo_Program * </td>
<td class="paramname"><em>ep</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the number of virtual machines are running for the given program. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">ep</td><td>The given program. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>The number of virtual machines running. </dd></dl>
</div>
</div>
<a class="anchor" id="ga91a7c05bafd22e94d776a117a297201d"></a><!-- doxytag: member="embryo_amx.c::embryo_program_return_value_get" ref="ga91a7c05bafd22e94d776a117a297201d" args="(Embryo_Program *ep)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">EAPI Embryo_Cell embryo_program_return_value_get </td>
<td>(</td>
<td class="paramtype">Embryo_Program * </td>
<td class="paramname"><em>ep</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retreives the return value of the last called function of the given program. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">ep</td><td>The given program. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>An Embryo_Cell representing the return value of the function that was last called. </dd></dl>
</div>
</div>
<a class="anchor" id="ga29c5d998350f875882c2672c9be617c6"></a><!-- doxytag: member="embryo_amx.c::embryo_program_run" ref="ga29c5d998350f875882c2672c9be617c6" args="(Embryo_Program *ep, Embryo_Function fn)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">EAPI Embryo_Status embryo_program_run </td>
<td>(</td>
<td class="paramtype">Embryo_Program * </td>
<td class="paramname"><em>ep</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Embryo_Function </td>
<td class="paramname"><em>fn</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Runs the given function of the given Embryo program in the current virtual machine. </p>
<p>The parameter <code>fn</code> can be found using <a class="el" href="group__Embryo__Func__Group.html#ga8da497a811da37c0396eeeb6b9331679">embryo_program_function_find</a>.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>For Embryo to be able to run a function, it must have been declared <code>public</code> in the Small source code.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">ep</td><td>The given program. </td></tr>
<tr><td class="paramname">fn</td><td>The given function. Normally "main", in which case the constant <code>EMBRYO_FUNCTION_MAIN</code> can be used. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd><code>EMBRYO_PROGRAM_OK</code> on success. <code>EMBRYO_PROGRAM_SLEEP</code> if the program is halted by the Small <code>sleep</code> call. <code>EMBRYO_PROGRAM_FAIL</code> if there is an error. <code>EMBRYO_PROGRAM_TOOLONG</code> if the program executes for longer than it is allowed to in abstract machine instruction count. </dd></dl>
<p>References <a class="el" href="Embryo_8h.html#a570d5164a5f3d5d05f63e2e60c6ba7ad">EMBRYO_CELL_NONE</a>, <a class="el" href="group__Embryo__Data__String__Group.html#gaa9c6beeb074c4495711c4817874ce04e">embryo_data_address_get()</a>, <a class="el" href="group__Embryo__Heap__Group.html#ga9dc1279d6ed98dfd66bed904e2dfadec">embryo_data_heap_push()</a>, <a class="el" href="group__Embryo__Data__String__Group.html#ga2f1b7e5ce221aaada5663e46f2578815">embryo_data_string_set()</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afad1200d56dfe2e98968ce61777a5af9f6">EMBRYO_ERROR_BOUNDS</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afa009870011a7cea44365964152a6b659b">EMBRYO_ERROR_DIVIDE</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afa997ed7a24accd2628448fbe30cb326c7">EMBRYO_ERROR_HEAPLOW</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afac0dbf407bbc65088b5716d93998955d0">EMBRYO_ERROR_INDEX</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afa0dbd60236135b143ba940a2d6a6128e7">EMBRYO_ERROR_INIT</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afa53d0e4fbc67402def31c0e3263baa285">EMBRYO_ERROR_INVINSTR</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afa48ac8c79addef0c2a6b26c7f086a51bf">EMBRYO_ERROR_MEMACCESS</a>, <a class="el" href="Embryo_8h.html#a5d4619d0cbd0598cf9fd11110da3a3afad9575324537d4846b80ec4d3940b7531">EMBRYO_ERROR_SLEEP</a>, <a class="el" href="Embryo_8h.html#a7abc473f3832ce4cdd749e6dfe28b365">EMBRYO_FUNCTION_CONT</a>, and <a class="el" href="Embryo_8h.html#a7ceec6ab753bed546d061499a9e7eef9">EMBRYO_FUNCTION_MAIN</a>.</p>
</div>
</div>
</div>
<div id="push"></div>
</div> <!-- #content -->
</div> <!-- .layout -->
</div> <!-- #container -->
<div id="footer">
<table><tr>
<td class="poweredby"><img src="doxygen.png"></td>
<td class="copyright">Copyright ©2011 Enlightenment</td>
<td class="generated">Docs generated Tue Feb 8 2011 18:11:42</td>
</tr></table>
</div>
</body>
</html>
