mirror of
https://github.com/boostorg/process.git
synced 2026-01-19 04:22:15 +00:00
105 lines
2.7 KiB
Plaintext
105 lines
2.7 KiB
Plaintext
= Quickstart
|
|
|
|
A process needs four things to be launched:
|
|
|
|
* an asio execution_context / executor
|
|
* a path to an executable
|
|
* a list of arguments
|
|
* a variadic set of initializers
|
|
|
|
.example/quickstart.cpp:13-17
|
|
[source,cpp,indent=0]
|
|
----
|
|
include::../example/quickstart.cpp[tag=cp]
|
|
----
|
|
<1> The executor for the process handle
|
|
<2> The Path to the executable
|
|
<3> The argument list in the form of an `std::initializer_list`.
|
|
<4> Not additional initializers
|
|
|
|
The started process can then be awaited or terminated.
|
|
|
|
== Lifetime
|
|
|
|
If the process handle goes out of scope, it will terminate the subprocess.
|
|
You can prevent this, by calling `proc.detach()`; do however note that this
|
|
can lead to zombie processes.
|
|
|
|
A process that completed will deliver an exit-code,
|
|
which can be obtained by calling `.exit_code` on the exited process and which is
|
|
also returned from `.wait()`.
|
|
|
|
.example/quickstart.cpp:22-23
|
|
[source,cpp, indent=0]
|
|
----
|
|
include::../example/quickstart.cpp[tag=ls]
|
|
----
|
|
|
|
The normal exit-code is what the subprocess returned from `main`;
|
|
posix will however add additional information about the process.
|
|
This is called the `native_exit_code`.
|
|
|
|
|
|
The `.running()` function can be used to detect if the process is still active.
|
|
|
|
|
|
== Signalling the subprocess
|
|
|
|
The parent process can signal the subprocess demanding certain actions.
|
|
|
|
`.terminate` will cause the subprocess to exit immediately (`SIGKILL` on posix).
|
|
This is the only reliable & portable way to end a subprocess.
|
|
|
|
.example/quickstart.cpp:28-29
|
|
[source,cpp,indent=0]
|
|
----
|
|
include::../example/quickstart.cpp[tag=terminate]
|
|
----
|
|
|
|
`.request_exit` will ask the subprocess to shutdown (`SIGTERM` on posix),
|
|
which the subprocess might ignore.
|
|
|
|
.example/quickstart.cpp:34-36
|
|
[source,cpp]
|
|
----
|
|
include::../example/quickstart.cpp[tag=request_exit]
|
|
----
|
|
|
|
`.interrupt` will send an SIGINT to the subprocess, which a subprocess might
|
|
interpret as a signal for shutdown.
|
|
|
|
WARNING: interrupt requires the initializer `windows::create_new_process_group` to be set on windows
|
|
|
|
.example/quickstart.cpp:41-43
|
|
[source,cpp]
|
|
----
|
|
include::../example/quickstart.cpp[tag=interrupt]
|
|
----
|
|
|
|
[endsect]
|
|
|
|
[section:execute Execute functions]
|
|
|
|
Process v2 provides `execute` and `async_execute` functions that can be used for managed executions.
|
|
|
|
.example/quickstart.cpp:48
|
|
[source,cpp]
|
|
----
|
|
include::../example/quickstart.cpp[tag=execute]
|
|
----
|
|
|
|
The async version supports cancellation and will forward cancellation types as follows:
|
|
|
|
- `asio::cancellation_type::total` -> interrupt
|
|
- `asio::cancellation_type::partial` -> request_exit
|
|
- `asio::cancellation_type::terminal` -> terminate
|
|
|
|
.example/quickstart.cpp:53-56
|
|
[source,cpp]
|
|
----
|
|
include::../example/quickstart.cpp[tag=async_execute]
|
|
----
|
|
<1> After 10 seconds send a request_exit.
|
|
<2> After 20 seconds terminate
|
|
|