Process and BaseProcess

The Process library provides solution to execute a command, to control its execution, to redirect its outputs and input.

Note: Since version 17.01, there is a SCOOP-capable library BaseProcess that does not yet have all functionalities of the Process library.

BaseProcess library

Warning: This solution supports all kind of concurrency (none, thread, and SCOOP), but does not yet offer all the functionalities of the previous Process library. It is recommended to use BaseProcess, unless you badly need the missing features.

Creation of process handlers

The main interfaces are BASE_PROCESS_FACTORY and BASE_PROCESS. The factory helps to instantiate a BASE_PROCESS object, which is the execution controller. The BASE_PROCESS object is used to configure the execution, to launch the execution, and check for the termination. It could also terminate the execution if wanted.

The factory interface provides 2 useful functions creating a BASE_PROCESS object:

  • process_launcher takes as parameters the file name of the executable, then the arguments as a list of strings, and an optional working directory.
  • process_launcher_with_command_line is similar to process_launcher, but takes the full command line, instead of executable filename and arguments.

The advantage of process_launcher is that you do not have to care about quoting the argument values.

Output redirection

On the BASE_PROCESS object, it is possible to configure the execution.

  • It is possible to redirect the standard and error output, and also the input, for instance:
    • redirect_output_to_file is used to record the execution output in a file
    • redirect_error_to_same_as_output is used to redirect the error output with the standard output
    • redirect_input_to_file is used to take the input from a file.
    • check other redirect_* routines.

Platform-specific settings

Feature Description
Only for Unix
is_terminal_control_enabled If True, the launched process will have terminal control over standard input, output and error.

Note: Has effect only when is_launched_in_new_process_group is True.

Only for Windows
hidden If True, the process will be launched silently (no console window will prompt out).
separate_console If True, the process will be launched with a new console instead of inheriting parent's console.
detached_console If True, the process will be launched without any console.

Execution control

Feature Description
launch Launch the execution.
terminate Terminate launched execution. Check last_termination_successful after to see if terminate succeeded.

Note: terminate executes asynchronously. After calling terminate, call wait_to_exit to wait for process to exit.

terminate_tree Terminate process tree starting from current launched process. Check last_termination_successful after to see if terminate_tree succeeded. terminate_tree executes asynchronously. After calling terminate, call wait_to_exit to wait for process to exit.

Note: On Unix, this feature can terminate whole process tree only when is_launched_in_new_process_group is set to True before new process is launched.

wait_for_exit Wait until process has exited.

Note: Child processes of launched process are not guaranteed to have exited after wait_for_exit returns.

wait_for_exit_with_timeout (timeout: INTEGER) Wait launched process to exit for at most timeout milliseconds. Check has_exited after to see if launched process has exited.

Note: Child processes of launched process are not guaranteed to have exited even if has_exited is True after wait_for_exit_with_timeout.

close Close handles associated with child process. The process may continue running. If there is any input/output redirection to/from current process, it will be closed.

Execution status

Feature Description
id Identifier of the last launched process.
exit_code Exit code of child process. It should be called after the process has exited.
platform It is a facility to know which is the current platform.
launched Has the process been launched? Check after a call to launch.
is_running Is the process still running (i.e launched and not exited)?
has_exited Has launched process exited and have allocated resources been cleaned up?

Process library

Warning: This solution requires multi-threading. In other concurrency modes (none and SCOOP), your project will compile fine but at the execution, it can not be used since your system is not thread-capable.

The Process library is an extension of the BaseProcess library, the main interfaces are

  • PROCESS_FACTORY which inherits from BASE_PROCESS_FACTORY and creates PROCESS objects.
  • PROCESS which inherits from BASE_PROCESS and add agent based redirection.

The agent based redirections can be useful to process the execution output as it comes, and also to send data to the input.