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 an 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.

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

  3. void set_error(const std::error_code & ec, const char * msg);
  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