Skip to content

Commit

Permalink
moved v1 to v1 inline namespace.
Browse files Browse the repository at this point in the history
  • Loading branch information
klemens-morgenstern committed Jul 2, 2024
1 parent bcdd911 commit 55e2460
Show file tree
Hide file tree
Showing 150 changed files with 1,002 additions and 933 deletions.
6 changes: 3 additions & 3 deletions doc/v1/design.qbk
Original file line number Diff line number Diff line change
Expand Up @@ -75,9 +75,9 @@ but the one of the launching process, not the one passed to the child process.]
The simplest form to extend functionality is to provide another handler, which
will be called on the respective events on process launching. The names are:

*`boost::process::on_setup`
*`boost::process::on_error`
*`boost::process::on_success`
*`boost::process::v1::on_setup`
*`boost::process::v1::on_error`
*`boost::process::v1::on_success`


As an example:
Expand Down
52 changes: 26 additions & 26 deletions doc/v1/extend.qbk
Original file line number Diff line number Diff line change
@@ -1,44 +1,44 @@
[def __on_exit__ [globalref boost::process::on_exit on_exit]]
[def __on_success__ [globalref boost::process::extend::on_success ex::on_success]]
[def __child__ [classref boost::process::child child]]
[def __handler__ [classref boost::process::extend::handler handler]]
[def __on_success__ [memberref boost::process::extend::handler::on_success on_success]]
[def __posix_executor__ [classref boost::process::extend::posix_executor ex::posix_executor]]
[def __windows_executor__ [classref boost::process::extend::windows_executor ex::windows_executor]]
[def __on_exit__ [globalref boost::process::v1::on_exit on_exit]]
[def __on_success__ [globalref boost::process::v1::extend::on_success ex::on_success]]
[def __child__ [classref boost::process::v1::child child]]
[def __handler__ [classref boost::process::v1::extend::handler handler]]
[def __on_success__ [memberref boost::process::v1::extend::handler::on_success on_success]]
[def __posix_executor__ [classref boost::process::v1::extend::posix_executor ex::posix_executor]]
[def __windows_executor__ [classref boost::process::v1::extend::windows_executor ex::windows_executor]]
[def __io_context__ [@http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/io_context.html boost::asio::io_context]]
[def __require_io_context__ [classref boost::process::extend::require_io_context ex::require_io_context]]
[def __async_handler__ [classref boost::process::extend::async_handler ex::async_handler]]
[def __get_io_context__ [funcref boost::process::extend::get_io_context ex::get_io_context]]
[def __require_io_context__ [classref boost::process::v1::extend::require_io_context ex::require_io_context]]
[def __async_handler__ [classref boost::process::v1::extend::async_handler ex::async_handler]]
[def __get_io_context__ [funcref boost::process::v1::extend::get_io_context ex::get_io_context]]

[section:extend Extensions]
To extend the library, the header [headerref boost/process/extend.hpp extend] is provided.

It only provides the explicit style for custom properties, but no implicit style.

What this means is, that a custom initializer can be implemented, a reference which can be passed to one of the launching functions.
If a class inherits [classref boost::process::extend::handler] it will be regarded as an initializer and thus directly put into the sequence
If a class inherits [classref boost::process::v1::extend::handler] it will be regarded as an initializer and thus directly put into the sequence
the executor gets passed.

[section:structure Structure]

The executor calls different handlers of the initializers during the process launch.
The basic structure consists of three functions, as given below:

* [globalref boost::process::extend::on_setup on_setup]
* [globalref boost::process::extend::on_error on_error]
* [globalref boost::process::extend::on_success on_success]
* [globalref boost::process::v1::extend::on_setup on_setup]
* [globalref boost::process::v1::extend::on_error on_error]
* [globalref boost::process::v1::extend::on_success on_success]

'''
<imagedata fileref="boost_process/windows_exec.svg"/>
'''

Additionally posix provides three more handlers, listed below:

* [globalref boost::process::extend::on_fork_error on_fork_error]
* [globalref boost::process::extend::on_exec_setup on_exec_setup]
* [globalref boost::process::extend::on_exec_error on_exec_error]
* [globalref boost::process::v1::extend::on_fork_error on_fork_error]
* [globalref boost::process::v1::extend::on_exec_setup on_exec_setup]
* [globalref boost::process::v1::extend::on_exec_error on_exec_error]

For more information see the reference of [classref boost::process::extend::posix_executor posix_executor].
For more information see the reference of [classref boost::process::v1::extend::posix_executor posix_executor].

[endsect]
[section:simple Simple extensions]
Expand All @@ -55,8 +55,8 @@ __child__ c("foo", __on_success__=[](auto & exec) {std::cout << "hello world" <<

Considering that lambdas can also capture values, data can easily be shared between handlers.

To see which members the executor has, refer to [classref boost::process::extend::windows_executor windows_executor]
and [classref boost::process::extend::posix_executor posix_executor].
To see which members the executor has, refer to [classref boost::process::v1::extend::windows_executor windows_executor]
and [classref boost::process::v1::extend::posix_executor posix_executor].

[note Combined with __on_exit__ this can also handle the process exit.]

Expand All @@ -67,7 +67,7 @@ and [classref boost::process::extend::posix_executor posix_executor].
[section:handler Handler Types]

Since the previous example is in a functional style, it is not very reusable.
To solve that problem, the [classref boost::process::extend::handler handler] has an alias in the `boost::process::extend` namespace, to be inherited.
To solve that problem, the [classref boost::process::v1::extend::handler handler] has an alias in the `boost::process::v1::extend` namespace, to be inherited.
So let's implement the hello world example in a class.

```
Expand All @@ -86,7 +86,7 @@ __child__ c("foo", hello_world());

[note The implementation is done via overloading, not overriding.]

Every handler not implemented defaults to [classref boost::process::extend::handler handler], where an empty handler is defined for each event.
Every handler not implemented defaults to [classref boost::process::v1::extend::handler handler], where an empty handler is defined for each event.

[endsect]

Expand All @@ -108,11 +108,11 @@ struct async_foo : __handler__, __require_io_context__
}
};
```
[note Inheriting [globalref boost::process::extend::require_io_context require_io_context] is necessary, so [funcref boost::process::system system] provides one.]
[note Inheriting [globalref boost::process::v1::extend::require_io_context require_io_context] is necessary, so [funcref boost::process::v1::system system] provides one.]

Additionally the handler can provide a function that is invoked when the child process exits. This is done through __async_handler__.

[note [globalref boost::process::extend::async_handler async_handler] implies [globalref boost::process::extend::require_io_context require_io_context] .]
[note [globalref boost::process::v1::extend::async_handler async_handler] implies [globalref boost::process::v1::extend::require_io_context require_io_context] .]

```
struct async_bar : __handler, __async_handler__
Expand All @@ -131,7 +131,7 @@ struct async_bar : __handler, __async_handler__
```


[caution `on_exit_handler` does not default and is always required when [classref boost::process::extend::async_handler async_handler] is inherited. ]
[caution `on_exit_handler` does not default and is always required when [classref boost::process::v1::extend::async_handler async_handler] is inherited. ]

[caution `on_exit_handler` uses `boost::asio::signal_set` to listen for SIGCHLD on posix. The application must not also register a signal handler for SIGCHLD using functions such as `signal()` or `sigaction()` (but using `boost::asio::signal_set` is fine). ]

Expand All @@ -156,7 +156,7 @@ auto set_error = [](auto & exec)
__child__ c("foo", on_setup=set_error);
```

Since we do not specify the error-handling mode in this example, this will throw [classref boost::process::process_error process_error].
Since we do not specify the error-handling mode in this example, this will throw [classref boost::process::v1::process_error process_error].

[endsect]

Expand Down
8 changes: 4 additions & 4 deletions doc/v1/introduction.qbk
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ Boost.Process is a library to manage system processes. It can be used to:

Here's a simple example of how to start a program with Boost.Process:

[def ipstream [classref boost::process::ipstream ipstream]]
[def system [funcref boost::process::system system]]
[def std_out [globalref boost::process::std_out std_out]]
[def child [globalref boost::process::child child]]
[def ipstream [classref boost::process::v1::ipstream ipstream]]
[def system [funcref boost::process::v1::system system]]
[def std_out [globalref boost::process::v1::std_out std_out]]
[def child [globalref boost::process::v1::child child]]
[def boost/process.hpp [headerref boost/process.hpp boost/process.hpp]]
[def std::string [@http://en.cppreference.com/w/cpp/string/basic_string std::string]]
[def std::getline [@http://en.cppreference.com/w/cpp/string/basic_string/getline std::getline]]
Expand Down
40 changes: 20 additions & 20 deletions doc/v1/posix_pseudocode.xml
Original file line number Diff line number Diff line change
@@ -1,59 +1,59 @@
<?xml version="1.0" standalone="yes"?>
<programlisting>
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_setup">on_setup</methodname>(*this);
s.<methodname alt="boost::process::v1::extend::handler::on_setup">on_setup</methodname>(*this);

if (<methodname alt="boost::process::extend::posix_executor::error">error</methodname>())
if (<methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>())
{
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::posix_executor::error">error</methodname>());
return <classname alt="boost::process::child">child</classname>();
s.<methodname alt="boost::process::v1::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>());
return <classname alt="boost::process::v1::child">child</classname>();
}

pid = <ulink url="http://pubs.opengroup.org/onlinepubs/009695399/functions/fork.html">fork()</ulink>
<methodname alt="boost::process::extend::handler::on_setup">on_setup</methodname>(*this);
<methodname alt="boost::process::v1::extend::handler::on_setup">on_setup</methodname>(*this);

if (pid == -1) //fork error
{
<methodname alt="boost::process::extend::posix_executor::set_error">set_error</methodname>(<functionname alt="boost::process::extend::get_last_error">get_last_error</functionname>());
<methodname alt="boost::process::v1::extend::posix_executor::set_error">set_error</methodname>(<functionname alt="boost::process::v1::extend::get_last_error">get_last_error</functionname>());
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_fork_error">on_fork_error</methodname>(*this, <methodname alt="boost::process::extend::posix_executor::error">error</methodname>());
s.<methodname alt="boost::process::v1::extend::handler::on_fork_error">on_fork_error</methodname>(*this, <methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>());
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::posix_executor::error">error</methodname>());
return <classname alt="boost::process::child">child</classname>()
s.<methodname alt="boost::process::v1::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>());
return <classname alt="boost::process::v1::child">child</classname>()
}
else if (pid == 0) //child process
{
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_exec_setup">on_exec_setup</methodname>(*this);
s.<methodname alt="boost::process::v1::extend::handler::on_exec_setup">on_exec_setup</methodname>(*this);
<ulink url="http://pubs.opengroup.org/onlinepubs/009695399/functions/exec.html">execve</ulink>(exe, cmd_line, env);
auto ec = <functionname alt="boost::process::extend::get_last_error">get_last_error</functionname>();
auto ec = <functionname alt="boost::process::v1::extend::get_last_error">get_last_error</functionname>();
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_exec_error">on_exec_error</methodname>(*this);
s.<methodname alt="boost::process::v1::extend::handler::on_exec_error">on_exec_error</methodname>(*this);

<emphasis>unspecified();</emphasis>//here the error is sent to the father process internally

<ulink url="http://en.cppreference.com/w/cpp/utility/program/exit">std::exit</ulink>(<ulink url="http://en.cppreference.com/w/c/program/EXIT_status">EXIT_FAILURE</ulink>);
return <classname alt="boost::process::child">child</classname>(); //for C++ compliance
return <classname alt="boost::process::v1::child">child</classname>(); //for C++ compliance
}

<classname alt="boost::process::child">child</classname> c(pid, exit_code);
<classname alt="boost::process::v1::child">child</classname> c(pid, exit_code);

<emphasis>unspecified();</emphasis>//here, we read the error from the child process

if (<methodname alt="boost::process::extend::posix_executor::error">error</methodname>())
if (<methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>())
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::posix_executor::error">error</methodname>());
s.<methodname alt="boost::process::v1::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>());
else
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_error">on_success</methodname>(*this);
s.<methodname alt="boost::process::v1::extend::handler::on_error">on_success</methodname>(*this);

//now we check again, because an on_success handler might've errored.
if (<methodname alt="boost::process::extend::posix_executor::error">error</methodname>())
if (<methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>())
{
for (auto &amp; s : seq)
s.<methodname alt="boost::process::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::extend::posix_executor::error">error</methodname>());
return <classname alt="boost::process::child">child</classname>();
s.<methodname alt="boost::process::v1::extend::handler::on_error">on_error</methodname>(*this, <methodname alt="boost::process::v1::extend::posix_executor::error">error</methodname>());
return <classname alt="boost::process::v1::child">child</classname>();
}
else
return c;
Expand Down
Loading

0 comments on commit 55e2460

Please sign in to comment.