1 // Copyright (c) 2016 Klemens D. Morgenstern 2 // 3 // Distributed under the Boost Software License, Version 1.0. (See accompanying 4 // file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) 5 6 #ifndef BOOST_PROCESS_EXTENSIONS_HPP_ 7 #define BOOST_PROCESS_EXTENSIONS_HPP_ 8 9 #include <boost/process/detail/handler.hpp> 10 #include <boost/process/detail/used_handles.hpp> 11 12 #if defined(BOOST_WINDOWS_API) 13 #include <boost/process/detail/windows/executor.hpp> 14 #include <boost/process/detail/windows/async_handler.hpp> 15 #include <boost/process/detail/windows/asio_fwd.hpp> 16 #else 17 #include <boost/process/detail/posix/executor.hpp> 18 #include <boost/process/detail/posix/async_handler.hpp> 19 #include <boost/process/detail/posix/asio_fwd.hpp> 20 #endif 21 22 23 /** \file boost/process/extend.hpp 24 * 25 * This header which provides the types and functions provided for custom extensions. 26 * 27 * \xmlonly 28 Please refer to the <link linkend="boost_process.extend">tutorial</link> for more details. 29 \endxmlonly 30 */ 31 32 33 namespace boost { 34 namespace process { 35 namespace detail { 36 template<typename Tuple> 37 inline asio::io_context& get_io_context(const Tuple & tup); 38 } 39 40 41 ///Namespace for extensions \attention This is experimental. 42 namespace extend { 43 44 #if defined(BOOST_WINDOWS_API) 45 46 template<typename Char, typename Sequence> 47 using windows_executor = ::boost::process::detail::windows::executor<Char, Sequence>; 48 template<typename Sequence> 49 struct posix_executor; 50 51 #elif defined(BOOST_POSIX_API) 52 53 template<typename Sequence> 54 using posix_executor = ::boost::process::detail::posix::executor<Sequence>; 55 template<typename Char, typename Sequence> 56 struct windows_executor; 57 58 #endif 59 60 using ::boost::process::detail::handler; 61 using ::boost::process::detail::api::require_io_context; 62 using ::boost::process::detail::api::async_handler; 63 using ::boost::process::detail::get_io_context; 64 using ::boost::process::detail::get_last_error; 65 using ::boost::process::detail::throw_last_error; 66 using ::boost::process::detail::uses_handles; 67 using ::boost::process::detail::foreach_used_handle; 68 using ::boost::process::detail::get_used_handles; 69 70 ///This handler is invoked before the process in launched, to setup parameters. The required signature is `void(Exec &)`, where `Exec` is a template parameter. 71 constexpr boost::process::detail::make_handler_t<boost::process::detail::on_setup_> on_setup; 72 ///This handler is invoked if an error occured. The required signature is `void(auto & exec, const std::error_code&)`, where `Exec` is a template parameter. 73 constexpr boost::process::detail::make_handler_t<boost::process::detail::on_error_> on_error; 74 ///This handler is invoked if launching the process has succeeded. The required signature is `void(auto & exec)`, where `Exec` is a template parameter. 75 constexpr boost::process::detail::make_handler_t<boost::process::detail::on_success_> on_success; 76 77 #if defined(BOOST_POSIX_API) || defined(BOOST_PROCESS_DOXYGEN) 78 ///This handler is invoked if the fork failed. The required signature is `void(auto & exec)`, where `Exec` is a template parameter. \note Only available on posix. 79 constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_fork_error_ > on_fork_error; 80 ///This handler is invoked if the fork succeeded. The required signature is `void(Exec &)`, where `Exec` is a template parameter. \note Only available on posix. 81 constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_exec_setup_ > on_exec_setup; 82 ///This handler is invoked if the exec call errored. The required signature is `void(auto & exec)`, where `Exec` is a template parameter. \note Only available on posix. 83 constexpr ::boost::process::detail::make_handler_t<::boost::process::detail::posix::on_exec_error_ > on_exec_error; 84 #endif 85 86 #if defined(BOOST_PROCESS_DOXYGEN) 87 ///Helper function to get the last error code system-independent 88 inline std::error_code get_last_error(); 89 90 ///Helper function to get and throw the last system error. 91 /// \throws boost::process::process_error 92 /// \param msg A message to add to the error code. 93 inline void throw_last_error(const std::string & msg); 94 ///\overload void throw_last_error(const std::string & msg) 95 inline void throw_last_error(); 96 97 98 /** This function gets the io_context from the initializer sequence. 99 * 100 * \attention Yields a compile-time error if no `io_context` is provided. 101 * \param seq The Sequence of the initializer. 102 */ 103 template<typename Sequence> 104 inline asio::io_context& get_io_context(const Sequence & seq); 105 106 /** This class is the base for every initializer, to be used for extensions. 107 * 108 * The usage is done through compile-time polymorphism, so that the required 109 * functions can be overloaded. 110 * 111 * \note None of the function need to be `const`. 112 * 113 */ 114 struct handler 115 { 116 ///This function is invoked before the process launch. \note It is not required to be const. 117 template <class Executor> on_setupboost::process::extend::handler118 void on_setup(Executor&) const {} 119 120 /** This function is invoked if an error occured while trying to launch the process. 121 * \note It is not required to be const. 122 */ 123 template <class Executor> on_errorboost::process::extend::handler124 void on_error(Executor&, const std::error_code &) const {} 125 126 /** This function is invoked if the process was successfully launched. 127 * \note It is not required to be const. 128 */ 129 template <class Executor> on_successboost::process::extend::handler130 void on_success(Executor&) const {} 131 132 /**This function is invoked if an error occured during the call of `fork`. 133 * \note This function will only be called on posix. 134 */ 135 template<typename Executor> on_fork_errorboost::process::extend::handler136 void on_fork_error (Executor &, const std::error_code&) const {} 137 138 /**This function is invoked if the call of `fork` was successful, before 139 * calling `execve`. 140 * \note This function will only be called on posix. 141 * \attention It will be invoked from the new process. 142 */ 143 template<typename Executor> on_exec_setupboost::process::extend::handler144 void on_exec_setup (Executor &) const {} 145 146 /**This function is invoked if the call of `execve` failed. 147 * \note This function will only be called on posix. 148 * \attention It will be invoked from the new process. 149 */ 150 template<typename Executor> on_exec_errorboost::process::extend::handler151 void on_exec_error (Executor &, const std::error_code&) const {} 152 153 }; 154 155 156 /** Inheriting the class will tell the launching process that an `io_context` is 157 * needed. This should always be used when \ref get_io_context is used. 158 * 159 */ 160 struct require_io_context {}; 161 /** Inheriting this class will tell the launching function, that an event handler 162 * shall be invoked when the process exits. This automatically does also inherit 163 * \ref require_io_context. 164 * 165 * You must add the following function to your implementation: 166 * 167 \code{.cpp} 168 template<typename Executor> 169 std::function<void(int, const std::error_code&)> on_exit_handler(Executor & exec) 170 { 171 auto handler_ = this->handler; 172 return [handler_](int exit_code, const std::error_code & ec) 173 { 174 handler_(static_cast<int>(exit_code), ec); 175 }; 176 177 } 178 \endcode 179 180 The callback will be obtained by calling this function on setup and it will be 181 invoked when the process exits. 182 183 * 184 * \warning Cannot be used with \ref boost::process::spawn 185 */ 186 struct async_handler : handler, require_io_context 187 { 188 189 }; 190 191 ///The posix executor type. 192 /** This type represents the posix executor and can be used for overloading in a custom handler. 193 * \note It is an alias for the implementation on posix, and a forward-declaration on windows. 194 * 195 * \tparam Sequence The used initializer-sequence, it is fulfills the boost.fusion [sequence](http://www.boost.org/doc/libs/master/libs/fusion/doc/html/fusion/sequence.html) concept. 196 197 198 \xmlonly 199 As information for extension development, here is the structure of the process launching (in pseudo-code and uml) 200 <xi:include href="posix_pseudocode.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> 201 202 <mediaobject> 203 <caption> 204 <para>The sequence if when no error occurs.</para> 205 </caption> 206 <imageobject> 207 <imagedata fileref="boost_process/posix_success.svg"/> 208 </imageobject> 209 </mediaobject> 210 211 <mediaobject> 212 <caption> 213 <para>The sequence if the execution fails.</para> 214 </caption> 215 <imageobject> 216 <imagedata fileref="boost_process/posix_exec_err.svg"/> 217 </imageobject> 218 </mediaobject> 219 220 <mediaobject> 221 <caption> 222 <para>The sequence if the fork fails.</para> 223 </caption> 224 <imageobject> 225 <imagedata fileref="boost_process/posix_fork_err.svg"/> 226 </imageobject> 227 </mediaobject> 228 229 \endxmlonly 230 231 232 \note Error handling if execve fails is done through a pipe, unless \ref ignore_error is used. 233 234 */ 235 template<typename Sequence> 236 struct posix_executor 237 { 238 ///A reference to the actual initializer-sequence 239 Sequence & seq; 240 ///A pointer to the name of the executable. 241 const char * exe = nullptr; 242 ///A pointer to the argument-vector. 243 char *const* cmd_line = nullptr; 244 ///A pointer to the environment variables, as default it is set to [environ](http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap08.html) 245 char **env = ::environ; 246 ///The pid of the process - it will be -1 before invoking [fork](http://pubs.opengroup.org/onlinepubs/009695399/functions/fork.html), and after forking either 0 for the new process or a positive value if in the current process. */ 247 pid_t pid = -1; 248 ///This shared-pointer holds the exit code. It's done this way, so it can be shared between an `asio::io_context` and \ref child. 249 std::shared_ptr<std::atomic<int>> exit_status = std::make_shared<std::atomic<int>>(still_active); 250 251 ///This function returns a const reference to the error state of the executor. 252 const std::error_code & error() const; 253 254 ///This function can be used to report an error to the executor. This will be handled according to the configuration of the executor, i.e. it 255 /// might throw an exception. \note This is the required way to handle errors in initializers. 256 void set_error(const std::error_code &ec, const std::string &msg); 257 ///\overload void set_error(const std::error_code &ec, const std::string &msg); 258 void set_error(const std::error_code &ec, const char* msg); 259 }; 260 261 ///The windows executor type. 262 /** This type represents the posix executor and can be used for overloading in a custom handler. 263 * 264 * \note It is an alias for the implementation on posix, and a forward-declaration on windows. 265 * \tparam Sequence The used initializer-sequence, it is fulfills the boost.fusion [sequence](http://www.boost.org/doc/libs/master/libs/fusion/doc/html/fusion/sequence.html) concept. 266 * \tparam Char The used char-type, either `char` or `wchar_t`. 267 * 268 269 \xmlonly 270 As information for extension development, here is the structure of the process launching (in pseudo-code and uml)<xi:include href="windows_pseudocode.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/> 271 <mediaobject> 272 <caption> 273 <para>The sequence for windows process creation.</para> 274 </caption> 275 <imageobject> 276 <imagedata fileref="boost_process/windows_exec.svg"/> 277 </imageobject> 278 </mediaobject> 279 \endxmlonly 280 281 */ 282 283 template<typename Char, typename Sequence> 284 struct windows_executor 285 { 286 ///A reference to the actual initializer-sequence 287 Sequence & seq; 288 289 ///A pointer to the name of the executable. It's null by default. 290 const Char * exe = nullptr; 291 ///A pointer to the argument-vector. Must be set by some initializer. 292 char Char* cmd_line = nullptr; 293 ///A pointer to the environment variables. It's null by default. 294 char Char* env = nullptr; 295 ///A pointer to the working directory. It's null by default. 296 const Char * work_dir = nullptr; 297 298 ///A pointer to the process-attributes of type [SECURITY_ATTRIBUTES](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379560.aspx). It's null by default. 299 ::boost::detail::winapi::LPSECURITY_ATTRIBUTES_ proc_attrs = nullptr; 300 ///A pointer to the thread-attributes of type [SECURITY_ATTRIBUTES](https://msdn.microsoft.com/en-us/library/windows/desktop/aa379560.aspx). It' null by default. 301 ::boost::detail::winapi::LPSECURITY_ATTRIBUTES_ thread_attrs = nullptr; 302 ///A logical bool value setting whether handles shall be inherited or not. 303 ::boost::detail::winapi::BOOL_ inherit_handles = false; 304 305 ///The element holding the process-information after process creation. The type is [PROCESS_INFORMATION](https://msdn.microsoft.com/en-us/library/windows/desktop/ms684873.aspx) 306 ::boost::detail::winapi::PROCESS_INFORMATION_ proc_info{nullptr, nullptr, 0,0}; 307 308 309 ///This shared-pointer holds the exit code. It's done this way, so it can be shared between an `asio::io_context` and \ref child. 310 std::shared_ptr<std::atomic<int>> exit_status = std::make_shared<std::atomic<int>>(still_active); 311 312 ///This function returns a const reference to the error state of the executor. 313 const std::error_code & error() const; 314 315 ///This function can be used to report an error to the executor. This will be handled according to the configuration of the executor, i.e. it 316 /// might throw an exception. \note This is the required way to handle errors in initializers. 317 void set_error(const std::error_code &ec, const std::string &msg); 318 ///\overload void set_error(const std::error_code &ec, const std::string &msg); 319 void set_error(const std::error_code &ec, const char* msg); 320 321 ///The creation flags of the process 322 ::boost::detail::winapi::DWORD_ creation_flags; 323 ///The type of the [startup-info](https://msdn.microsoft.com/en-us/library/windows/desktop/ms686331.aspx), depending on the char-type. 324 typedef typename detail::startup_info<Char>::type startup_info_t; 325 ///The type of the [extended startup-info](https://msdn.microsoft.com/de-de/library/windows/desktop/ms686329.aspx), depending the char-type; only defined with winapi-version equal or higher than 6. 326 typedef typename detail::startup_info_ex<Char>::type startup_info_ex_t; 327 ///This function switches the information, so that the extended structure is used. \note It's only defined with winapi-version equal or higher than 6. 328 void set_startup_info_ex(); 329 ///This element is an instance or a reference (if \ref startup_info_ex exists) to the [startup-info](https://msdn.microsoft.com/en-us/library/windows/desktop/ms686331.aspx) for the process. 330 startup_info_t startup_info; 331 ///This element is the instance of the [extended startup-info](https://msdn.microsoft.com/de-de/library/windows/desktop/ms686329.aspx). It is only available with a winapi-version equal or highter than 6. 332 startup_info_ex_t startup_info_ex; 333 }; 334 335 336 337 #endif 338 339 } 340 } 341 } 342 343 #endif 344
