mirrors/eiffel-org
1
0
Fork 0
mirror of https://github.com/EiffelSoftware/eiffel-org.git synced 2025-12-06 14:52:03 +01:00
Code Issues Packages Projects Releases Wiki Activity

Update wikipage Process and BaseProcess. (Signed-off-by:alexk).

Browse Source 
git-svn-id: https://svn.eiffel.com/eiffel-org/trunk@1910 abb3cda0-5349-4a8f-a601-0c33ac3a8c38
This commit is contained in:
eiffel-org
2017-10-03 10:22:34 +00:00
parent e58ca95534
commit 852cd6e5b4
1 changed files with 50 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

78
documentation/trunk/solutions/basic-computing/EiffelProcess-and-EiffelBaseProcess.wiki
View File

@@ -1,24 +1,23 @@
[[Property:uuid|479D1DED-2E7B-4202-BE21-D2A1757398B9]]
[[Property:weight|0]]
[[Property:title|EiffelProcess and EiffelBaseProcess]]
[[Property:link_title|EiffelProcess]]
The EiffelProcess library provides solution to execute a command, to control its execution, to redirect its outputs and input.
[[Property:title|Process and BaseProcess]]
[[Property:link_title|Process]]
The Process library provides solution to execute a command, to control its execution, to redirect its outputs and input.
{{Note|Since version 17.11, there is a new SCOOP capable library named BaseProcess, for now it does not yet have all functionalities of EiffelProcess, but in the future it will.}}
{{Note|Since version 17.01, there is a SCOOP-capable library BaseProcess that does not yet have all functionalities of the Process library.}}
This documentation is focused on the Eiffel BaseProcess library, and then describes the additional functionalities available with previous EiffelProcess 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.}}
= Eiffel BaseProcess =
{{Warning|This solution supports all kind of concurrency (none, thread, and SCOOP), but does not yet offer all the functionalities of previous EiffelProcess library. It is recommended to use BaseProcess, unless you badly need the missing features.}}
== How to ==
=== 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 a 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.
* `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
@@ -26,6 +25,7 @@ On the `BASE_PROCESS` object, it is possible to configure the execution.
** `redirect_input_to_file (..)` is used to take the input from a file.
** check other `redirect_*` routines.
=== Platform-specific settings ===
There are also platform dependent settings, such as:
* Only for Unix
** `is_terminal_control_enabled: BOOLEAN`: If True, the launched process will have terminal control over standard input, output and error. (Has effect only when `is_launched_in_new_process_group' is True).
@@ -34,26 +34,48 @@ There are also platform dependent settings, such as:
** `separate_console: BOOLEAN`: if True, the process will be launched with a new console instead of inheriting parent's console.
** `detached_console: BOOLEAN`: if True, the process will be launched without any console ?
And the execution controls:
* `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 (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 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.
|}
Information about the executions:
* `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?
=== 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?
|}
= EiffelProcess =
{{Warning|WARNING: This solution requires 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.}}
= Process library =
{{Warning|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 EiffelProcess is an extension of BaseProcess, the main interfaces are
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.