process/v1/async.hpp

0001 // Copyright (c) 2016 Klemens D. Morgenstern
0002 //
0003 // Distributed under the Boost Software License, Version 1.0. (See accompanying
0004 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
0005
0006 /** \file boost/process/async.hpp
0007
0008 The header which provides the basic asynchronous features.
0009 It provides the on_exit property, which allows callbacks when the process exits.
0010 It also implements the necessary traits for passing an boost::asio::io_context,
0011 which is needed for asynchronous communication.
0012
0013 It also pulls the [boost::asio::buffer](http://www.boost.org/doc/libs/release/doc/html/boost_asio/reference/buffer.html)
0014 into the boost::process namespace for convenience.
0015
0016 \xmlonly
0017 <programlisting>
0018 namespace boost {
0019   namespace process {
0020     namespace v1 {
0021       <emphasis>unspecified</emphasis> <ulink url="http://www.boost.org/doc/libs/1_61_0/doc/html/boost_asio/reference/buffer.html">buffer</ulink>;
0022       <emphasis>unspecified</emphasis> <globalname alt="boost::process::v1::on_exit">on_exit</globalname>;
0023     }
0024   }
0025 }
0026 </programlisting>
0027
0028 \endxmlonly
0029   */
0030
0031 #ifndef BOOST_PROCESS_ASYNC_HPP_
0032 #define BOOST_PROCESS_ASYNC_HPP_
0033
0034 #include <boost/process/v1/detail/traits.hpp>
0035 #include <boost/process/v1/detail/on_exit.hpp>
0036
0037 #include <boost/asio/io_context.hpp>
0038 #include <boost/asio/streambuf.hpp>
0039 #include <boost/asio/buffer.hpp>
0040 #include <type_traits>
0041 #include <boost/fusion/iterator/deref.hpp>
0042
0043 #if defined(BOOST_POSIX_API)
0044 #include <boost/process/v1/detail/posix/io_context_ref.hpp>
0045 #include <boost/process/v1/detail/posix/async_in.hpp>
0046 #include <boost/process/v1/detail/posix/async_out.hpp>
0047 #include <boost/process/v1/detail/posix/on_exit.hpp>
0048
0049 #elif defined(BOOST_WINDOWS_API)
0050 #include <boost/process/v1/detail/windows/io_context_ref.hpp>
0051 #include <boost/process/v1/detail/windows/async_in.hpp>
0052 #include <boost/process/v1/detail/windows/async_out.hpp>
0053 #include <boost/process/v1/detail/windows/on_exit.hpp>
0054 #endif
0055
0056 namespace boost { namespace process { BOOST_PROCESS_V1_INLINE namespace v1 { namespace detail {
0057
0058 struct async_tag;
0059
0060 template<typename T>
0061 struct is_io_context : std::false_type {};
0062 template<>
0063 struct is_io_context<api::io_context_ref> : std::true_type {};
0064
0065 template<typename Tuple>
0066 inline asio::io_context& get_io_context(const Tuple & tup)
0067 {
0068     auto& ref = *boost::fusion::find_if<is_io_context<boost::mpl::_>>(tup);
0069     return ref.get();
0070 }
0071
0072 struct async_builder
0073 {
0074     boost::asio::io_context * ios;
0075
0076     void operator()(boost::asio::io_context & ios_) {this->ios = &ios_;};
0077
0078     typedef api::io_context_ref result_type;
0079     api::io_context_ref get_initializer() {return api::io_context_ref (*ios);};
0080 };
0081
0082
0083 template<>
0084 struct initializer_builder<async_tag>
0085 {
0086     typedef async_builder type;
0087 };
0088
0089 }
0090
0091 using ::boost::asio::buffer;
0092
0093
0094 #if defined(BOOST_PROCESS_DOXYGEN)
0095 /** When an io_context is passed, the on_exit property can be used, to be notified
0096     when the child process exits.
0097
0098
0099 The following syntax is valid
0100
0101 \code{.cpp}
0102 on_exit=function;
0103 on_exit(function);
0104 \endcode
0105
0106 with `function` being a callable object with the signature `(int, const std::error_code&)` or an
0107 `std::future<int>`.
0108
0109 \par Example
0110
0111 \code{.cpp}
0112 io_context ios;
0113
0114 child c("ls", ios, on_exit=[](int exit, const std::error_code& ec_in){});
0115
0116 std::future<int> exit_code;
0117 chlid c2("ls", ios, on_exit=exit_code);
0118
0119 \endcode
0120
0121 \note The handler is not invoked when the launch fails.
0122 \warning When used \ref ignore_error it might get invoked on error.
0123 \warning `on_exit` uses `boost::asio::signal_set` to listen for `SIGCHLD` on posix, and so has the
0124 same restrictions as that class (do not register a handler for `SIGCHLD` except by using
0125 `boost::asio::signal_set`).
0126  */
0127 constexpr static ::boost::process::v1::detail::on_exit_ on_exit{};
0128 #endif
0129
0130 }}}
0131
0132
0133
0134 #endif /* INCLUDE_BOOST_PROCESS_DETAIL_ASYNC_HPP_ */