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