<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Class Process - Class Process</title>
<link href="faldoc.css" rel="stylesheet" type="text/css"/>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
</head>
<body class="faldoc_body">
<div class="navitop">
<div class="tabs">
<ul>
<li><a href="./index.html"><span>Main</span></a></li>
<li><a href="./modules.html"><span>Modules</span></a></li>
<li><a href="./pages.html"><span>Related pages</span></a></li>
<li><a href="./groups.html"><span>Groups</span></a></li>
<li><a href="./classes.html"><span>Classes</span></a></li>
<li><a href="./objects.html"><span>Objects</span></a></li>
<li><a href="./functions.html"><span>All functions</span></a></li>
<li><a href="./enum.html"><span>Enumerations</span></a></li>
</ul>
</div>
</div>
<hr/>
<h1 class="faldoc_title">Class Process<span class="faldoc_belong"><a href="./module_feather_process.html">[in Process]</a></p></h1>
<p class="faldoc_brief">Execute and control child processes. </p>
<p class="faldoc_funcdecl">
<b>class</b> Process( command, [flags] )
</p>
<p class="faldoc_brief"><a href="#more">more...</a></p>
<h2 class="faldoc_title">Summary</h2>
<table class="faldoc_list">
<tr><td><a href="#getAux">getAux()</a></td><td>Returns the process auxiliary output stream. </td></tr>
<tr><td><a href="#getInput">getInput()</a></td><td>Returns the process input stream. </td></tr>
<tr><td><a href="#getOutput">getOutput()</a></td><td>Returns the process output stream. </td></tr>
<tr><td><a href="#terminate">terminate()</a></td><td>Terminate a child process. </td></tr>
<tr><td><a href="#value">value()</a></td><td>Retreives exit value of the child process (and close its handles). </td></tr>
<tr><td><a href="#wait">wait()</a></td><td>Waits for a child process to terminate. </td></tr>
</table>
<a name="more"><h2 class="faldoc_title">Detailed description</h2></a>
<p class="faldoc_funcdecl">
<b>class</b> Process( command, [flags] )
</p>
<table class="faldoc_function">
<tr><td class="faldoc_param">command</td><td class="faldoc_paramdesc">A string representing the program to be executed and its arguments, or an array whose first element is the program, and the others are the arguments. </td></tr>
<tr><td class="faldoc_optparam">flags</td><td class="faldoc_optparamdesc">process open flags. </td></tr>
</table>
<br/>
<p class="item_brief">Execute and control child processes. </p>
<p class="faldoc_text">This class is meant for finer control of child processes and inter process comunication. </p>
<p class="faldoc_text"> The process named in the <b>command</b> argument is started. It is possible to provide either a string containing a complete command line, with the process name and its arguments, or an array whose first element is the process name, and the other elements are the parameters that will be provided to the process. </p>
<p class="faldoc_text"> The optional <b>flags</b> parameter can control the behavior of the started process, and may be a combination of the followings: </p>
<ul>
<li>PROCESS_SINK_INPUT: prevent the child process to wait for input from us. </li><li>PROCESS_SINK_OUTPUT: destroy all the child process output. </li><li>PROCESS_SINK_AUX: destroy all the child process auxiliary stream output. </li><li>PROCESS_MERGE_AUX: merge output and auxiliary stream so that they are read by just reading the output stream. </li><li>PROCESS_BG: Put the process in background/hidden mode. </li><li>PROCESS_USE_SHELL: Use host system shell to launch the process or execute the command. </li>
</ul>
<h2 class="faldoc_title">Methods</h2>
<h3 class="faldoc_funcname"><a name="getAux">getAux()</a></h3>
<p class="item_brief">Returns the process auxiliary output stream. </p>
<p class="faldoc_funcdecl">Process.getAux( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The child process auxiliary output stream (read-only) </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream can be used as a Falcon stream, but it supports only read operations. </p>
<p class="faldoc_text"> If the process has been opened with the PROCESS_SINK_AUX or PROCESS_MERGE_AUX, this method will return nil. In the latter case, all the output that should usually go into this stream will be sent to the output stream, and it will be possible to read it from the stream handle returned by <a href="./class_Process.html#getOutput">Process.getOutput</a>. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function should be called only once per Process class; be sure to cache its value. </p>
</p>
<h3 class="faldoc_funcname"><a name="getInput">getInput()</a></h3>
<p class="item_brief">Returns the process input stream. </p>
<p class="faldoc_funcdecl">Process.getInput( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The child process input stream (write-only) </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream can be used as a Falcon stream, but it supports only write operations. </p>
<p class="faldoc_text">If the process has been opened with the PROCESS_SINK_IN, the function will return nil. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function should be called only once per Process class; be sure to cache its value. </p>
</p>
<h3 class="faldoc_funcname"><a name="getOutput">getOutput()</a></h3>
<p class="item_brief">Returns the process output stream. </p>
<p class="faldoc_funcdecl">Process.getOutput( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">The child process output stream (read-only) </td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">The returned stream can be used as a Falcon stream, but it supports only read operations. </p>
<p class="faldoc_text">If the process has been opened with the PROCESS_SINK_OUTPUT flag, the function will return nil. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> This function should be called only once per Process class; be sure to cache its value. </p>
</p>
<h3 class="faldoc_funcname"><a name="terminate">terminate()</a></h3>
<p class="item_brief">Terminate a child process. </p>
<p class="faldoc_funcdecl">Process.terminate( [severe] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">severe</td><td class="faldoc_optparamdesc">If given and true, use the maximum severity. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text"> Terminates the child process, sending it a request to exit as soon as possible. The call returns immediately; it is then necessary to wait for the process to actually exit and free its resources through <a href="./class_Process.html#value">Process.value</a>. </p>
<p class="faldoc_text"> If the <b>severe</b> parameter is true, then the maximum severity allowed for the host system is used. On UNIX, a KILL signal is sent to the child process, while a TERM signal is sent if severe is not specified or false. </p>
</p>
<h3 class="faldoc_funcname"><a name="value">value()</a></h3>
<p class="item_brief">Retreives exit value of the child process (and close its handles). </p>
<p class="faldoc_funcdecl">Process.value( [wait] )</p>
<table class="faldoc_function">
<tr><td class="faldoc_optparam">wait</td><td class="faldoc_optparamdesc">if given and true, the wait for the child process to be completed. </td></tr>
<tr><td class="faldoc_funcreturn">Returns:</td><td class="faldoc_funcreturndesc">On success, the exit value of the child process, or -1 if the child process is not yet terminated. </td></tr>
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">on system error. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Checks whether the child process has completed its execution, eventually returning its exit code. If the process is still active, nil will be returned. If a true value is provided as parameter, the function will block the VM execution until the child process is completed. </p>
<p class="faldoc_text">After value() returns, there may still be some data to be read from the child output and auxiliary streams; they should be read until they return 0. </p>
</p>
<h3 class="faldoc_funcname"><a name="wait">wait()</a></h3>
<p class="item_brief">Waits for a child process to terminate. </p>
<p class="faldoc_funcdecl">Process.wait( )</p>
<table class="faldoc_function">
<tr><td class="faldoc_raise">Raises:</td><td class="faldoc_raisedesc">
<table class="faldoc_raise">
<tr><td class="faldoc_raiseitem"><a href="./class_ProcessError.html">ProcessError</a></td><td class="faldoc_raisedesc">on system errors or wait failed. </td></tr>
</table>
</td></tr>
</table>
<p class="faldoc_text"><p class="faldoc_text">Waits for the child process to terminate cleanly. </p>
<p class="faldoc_text"> The thread in which the VM runs will be blocked until the child process terminates its execution. After this call, the script should also call the <a href="./class_Process.html#value">Process.value</a> method to free the system data associated with the child process. Use the Processs.value method to test periodically for the child process to be completed while the Falcon program continues its execution. </p>
<p class="faldoc_note"><span class="faldoc_notetype">Note:</span> At the moment this function doesn't respect the VM interruption protocol, but this feature shall be introduced shortly. Until this feature is available, the <a href="./class_Process.html#value">Process.value</a> method can be used to check if the child process terminated at time intervals. </p>
</p>
<hr/>
<div class="navibottom">
<center>
<a href="./index.html">Main</a> - <a href="./modules.html">Modules</a> - <a href="./pages.html">Related pages</a> - <a href="./groups.html">Groups</a> - <a href="./classes.html">Classes</a> - <a href="./objects.html">Objects</a> - <a href="./functions.html">All functions</a> - <a href="./enum.html">Enumerations</a>
</center>
</div>
</div>
<div class="faldoc_signature">Made with <a href="http://www.falconpl.org">faldoc 2.2.0</div>
</body>
</html>
