Execute and control child processes.
class Process( command, [flags] )
| getAux() | Returns the process auxiliary output stream. |
| getInput() | Returns the process input stream. |
| getOutput() | Returns the process output stream. |
| terminate() | Terminate a child process. |
| value() | Retreives exit value of the child process (and close its handles). |
| wait() | Waits for a child process to terminate. |
class Process( command, [flags] )
| command | 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. |
| flags | process open flags. |
Execute and control child processes.
This class is meant for finer control of child processes and inter process comunication.
The process named in the command 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.
The optional flags parameter can control the behavior of the started process, and may be a combination of the followings:
Returns the process auxiliary output stream.
Process.getAux( )
| Returns: | The child process auxiliary output stream (read-only) |
The returned stream can be used as a Falcon stream, but it supports only read operations.
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 Process.getOutput.
Note: This function should be called only once per Process class; be sure to cache its value.
Returns the process input stream.
Process.getInput( )
| Returns: | The child process input stream (write-only) |
The returned stream can be used as a Falcon stream, but it supports only write operations.
If the process has been opened with the PROCESS_SINK_IN, the function will return nil.
Note: This function should be called only once per Process class; be sure to cache its value.
Returns the process output stream.
Process.getOutput( )
| Returns: | The child process output stream (read-only) |
The returned stream can be used as a Falcon stream, but it supports only read operations.
If the process has been opened with the PROCESS_SINK_OUTPUT flag, the function will return nil.
Note: This function should be called only once per Process class; be sure to cache its value.
Terminate a child process.
Process.terminate( [severe] )
| severe | If given and true, use the maximum severity. | ||
| Raises: |
|
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 Process.value.
If the severe 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.
Retreives exit value of the child process (and close its handles).
Process.value( [wait] )
| wait | if given and true, the wait for the child process to be completed. | ||
| Returns: | On success, the exit value of the child process, or -1 if the child process is not yet terminated. | ||
| Raises: |
|
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.
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.
Waits for a child process to terminate.
Process.wait( )
| Raises: |
|
Waits for the child process to terminate cleanly.
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 Process.value 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.
Note: 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 Process.value method can be used to check if the child process terminated at time intervals.