boost/process/extend.hpp

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