Boost C++ Libraries

...one of the most highly regarded and expertly designed C++ library projects in the world. Herb Sutter and Andrei Alexandrescu, C++ Coding Standards

This is the documentation for an old version of Boost. Click here to view this page for the latest version.
PrevUpHomeNext

Struct template windows_executor

boost::process::extend::windows_executor — The windows executor type.

Synopsis

// In header: <boost/process/extend.hpp>

template<typename Char, typename Sequence> 
struct windows_executor {
  // types
  typedef unspecified startup_info_t;     // The type of the startup-info, depending on the char-type. 
  typedef unspecified startup_info_ex_t;  // The type of the extended startup-info, depending the char-type; only defined with winapi-version equal or higher than 6. 

  // public member functions
  const std::error_code & error() const;
  void set_error(const std::error_code &, const std::string &);
  void set_error(const std::error_code &, const char *);
  void set_startup_info_ex();

  // public data members
  Sequence & seq;  // A reference to the actual initializer-sequence. 
  const Char * exe;  // A pointer to the name of the executable. It's null by default. 
  char Char * cmd_line;  // A pointer to the argument-vector. Must be set by some initializer. 
  char Char * env;  // A pointer to the environment variables. It's null by default. 
  const Char * work_dir;  // A pointer to the working directory. It's null by default. 
  unspecified proc_attrs;  // A pointer to the process-attributes of type SECURITY_ATTRIBUTES. It's null by default. 
  unspecified thread_attrs;  // A pointer to the thread-attributes of type SECURITY_ATTRIBUTES. It' null by default. 
  unspecified inherit_handles;  // A logical bool value setting whether handles shall be inherited or not. 
  unspecified proc_info;  // The element holding the process-information after process creation. The type is PROCESS_INFORMATION
  std::shared_ptr< std::atomic< int > > exit_status;  // This shared-pointer holds the exit code. It's done this way, so it can be shared between an asio::io_context and child. 
  unspecified creation_flags;  // The creation flags of the process. 
  startup_info_t startup_info;  // This element is an instance or a reference (if startup_info_ex exists) to the startup-info for the process. 
  startup_info_ex_t startup_info_ex;  // This element is the instance of the extended startup-info. It is only available with a winapi-version equal or highter than 6. 
};

Description

This type represents the posix executor and can be used for overloading in a custom handler.

[Note] Note

It is an alias for the implementation on posix, and a forward-declaration on windows.

As information for extension development, here is the structure of the process launching (in pseudo-code and uml)

for (auto & s : seq)
    s.on_setup(*this);

if (error())
{
    for (auto & s : seq)
       s.on_error(*this, error());
    return child();
}
int err_code = CreateProcess(
         exe,
         cmd_line,
         proc_attrs,
         thread_attrs,
         creation_flags,
         env,
         work_dir,
         startup_info,
         proc_info);

child c(proc_info, exit_code);

if (error())
    for (auto & s : seq)
        s.on_error(*this, error());
else
    for (auto & s : seq)
        s.on_success(*this);

//now we check again, because a on_success handler might've errored.
if (error())
{
    for (auto & s : seq)
        s.on_error(*this, error());
    return child();
}
else
    return c;

The sequence for windows process creation.

Template Parameters

  1. typename Char

    The used char-type, either char or wchar_t.

  2. typename Sequence

    The used initializer-sequence, it is fulfills the boost.fusion sequence concept.

windows_executor public member functions

  1. const std::error_code & error() const;
    This function returns a const reference to the error state of the executor.
  2. void set_error(const std::error_code & ec, const std::string & msg);

    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 might throw an exception.

    [Note] Note

    This is the required way to handle errors in initializers.

  3. void set_error(const std::error_code & ec, const char * msg);

    This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

  4. void set_startup_info_ex();
    This function switches the information, so that the extended structure is used.
    [Note] Note

    It's only defined with winapi-version equal or higher than 6.


PrevUpHomeNext