| Home | Libraries | People | FAQ | More

## 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
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
   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
   It's only defined with winapi-version equal or higher than 6.