[[Property:uuid|479D1DED-2E7B-4202-BE21-D2A1757398B9]]
[[Property:weight|0]]
[[Property:title|Process and BaseProcess]]
[[Property:link_title|External processes]]
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 ==

{| class="wikitable" style="width: auto; margin: 0px auto;"
|-
! style="border-style: solid; text-align: center; font-weight: 500;" ! Feature
! style="border-style: solid; text-align: center; font-weight: 500;" ! Description
|-
| colspan="2" | {{Inline-Info|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.}}
|-
| colspan="2" | {{Inline-Info|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 ==
{| class="wikitable" style="width: auto; margin: 0px auto;"
|-
! style="border-style: solid; text-align: center; font-weight: 500;" ! Feature
! style="border-style: solid; text-align: center; font-weight: 500;" ! 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 ==
{| class="wikitable" style="width: auto; margin: 0px auto;"
|-
! style="border-style: solid; text-align: center; font-weight: 500;" ! Feature
! style="border-style: solid; text-align: center; font-weight: 500;" ! 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.