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

PrevUpHomeNext

Struct template basic_process

boost::process::v2::basic_process — A class managing a subprocess.

Synopsis

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

template<typename Executor = boost::asio::any_io_executor> 
struct basic_process {
  // types
  typedef Executor                                 executor_type;       // The executor of the process. 
  typedef basic_process_handle< executor_type >    handle_type;         // The non-closing handle type. 
  typedef typename handle_type::native_handle_type native_handle_type;  // Provides access to underlying operating system facilities. 

  // member classes/structs/unions

  struct async_wait_op_ {

    // public member functions
    template<typename Self> void operator()(Self &&);
    template<typename Self> 
      void operator()(Self &&, error_code, native_exit_code_type);

    // public data members
    basic_process_handle< Executor > & handle;
    native_exit_code_type & res;
  };

  // Rebinds the process_handle to another executor.
  template<typename Executor1> 
  struct rebind_executor {
    // types
    typedef basic_process< Executor1 > other;  // The socket type when rebound to the specified executor. 
  };

  // construct/copy/destruct
  basic_process() = default;
  basic_process(const basic_process &) = delete;
  basic_process(basic_process &&) = default;
  template<typename Executor1> basic_process(basic_process< Executor1 > &&);
  template<typename ... Inits> 
    explicit basic_process(executor_type, const filesystem::path &, 
                           std::initializer_list< string_view >, Inits &&...);
  template<typename ... Inits> 
    explicit basic_process(executor_type, const filesystem::path &, 
                           std::initializer_list< wstring_view >, 
                           Inits &&...);
  template<typename Args, typename ... Inits> 
    explicit basic_process(executor_type, const filesystem::path &, Args &&, 
                           Inits &&...);
  template<typename ExecutionContext, typename ... Inits> 
    explicit basic_process(ExecutionContext &, 
                           typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, const filesystem::path & >::type, 
                           std::initializer_list< string_view >, Inits &&...);
  template<typename ExecutionContext, typename Args, typename ... Inits> 
    explicit basic_process(ExecutionContext &, 
                           typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, const filesystem::path & >::type, 
                           Args &&, Inits &&...);
  explicit basic_process(executor_type, pid_type);
  explicit basic_process(executor_type, pid_type, native_handle_type);
  explicit basic_process(executor_type);
  template<typename ExecutionContext> 
    explicit basic_process(ExecutionContext &, pid_type, 
                           typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
  template<typename ExecutionContext> 
    explicit basic_process(ExecutionContext &, pid_type, native_handle_type, 
                           typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
  template<typename ExecutionContext> 
    explicit basic_process(ExecutionContext &, 
                           typename std::enable_if< is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
  basic_process & operator=(const basic_process &) = delete;
  basic_process & operator=(basic_process &&) = default;
  ~basic_process();

  // public member functions
  executor_type get_executor();
  handle_type & handle();
  const handle_type & handle() const;
  void interrupt();
  void interrupt(error_code &);
  void request_exit();
  void request_exit(error_code &);
  void suspend(error_code &);
  void suspend();
  void resume(error_code &);
  void resume();
  void terminate();
  void terminate(error_code &);
  int wait();
  int wait(error_code &);
  handle_type detach();
  native_handle_type native_handle();
  int exit_code() const;
  pid_type id() const;
  native_exit_code_type native_exit_code() const;
  bool running();
  bool running(error_code &) noexcept;
  bool is_open() const;
  template<Token WaitHandler DEFAULT_TYPE>  async_wait(WaitHandler &&handler );
};

Description

basic_process public construct/copy/destruct

  1. basic_process() = default;

    An empty process is similar to a default constructed thread. It holds an empty handle and is a place holder for a process that is to be launched later.

  2. basic_process(const basic_process &) = delete;
  3. basic_process(basic_process && lhs) = default;
    Move construct the process. It will be detached from lhs.
  4. template<typename Executor1> basic_process(basic_process< Executor1 > && lhs);
    Move construct and rebind the executor.
  5. template<typename ... Inits> 
      explicit basic_process(executor_type executor, const filesystem::path & exe, 
                             std::initializer_list< string_view > args, 
                             Inits &&... inits);
    Construct a child from a property list and launch it using the default launcher..
  6. template<typename ... Inits> 
      explicit basic_process(executor_type executor, const filesystem::path & exe, 
                             std::initializer_list< wstring_view > args, 
                             Inits &&... inits);
    Construct a child from a property list and launch it using the default launcher..
  7. template<typename Args, typename ... Inits> 
      explicit basic_process(executor_type executor, const filesystem::path & exe, 
                             Args && args, Inits &&... inits);
    Construct a child from a property list and launch it using the default launcher..
  8. template<typename ExecutionContext, typename ... Inits> 
      explicit basic_process(ExecutionContext & context, 
                             typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, const filesystem::path & >::type exe, 
                             std::initializer_list< string_view > args, 
                             Inits &&... inits);
    Construct a child from a property list and launch it using the default launcher..
  9. template<typename ExecutionContext, typename Args, typename ... Inits> 
      explicit basic_process(ExecutionContext & context, 
                             typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, const filesystem::path & >::type exe, 
                             Args && args, Inits &&... inits);
    Construct a child from a property list and launch it using the default launcher.
  10. explicit basic_process(executor_type exec, pid_type pid);
    Attach to an existing process.
  11. explicit basic_process(executor_type exec, pid_type pid, 
                           native_handle_type native_handle);
    Attach to an existing process and the internal handle.
  12. explicit basic_process(executor_type exec);
    Create an invalid handle.
  13. template<typename ExecutionContext> 
      explicit basic_process(ExecutionContext & context, pid_type pid, 
                             typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
    Attach to an existing process.
  14. template<typename ExecutionContext> 
      explicit basic_process(ExecutionContext & context, pid_type pid, 
                             native_handle_type native_handle, 
                             typename std::enable_if< std::is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
    Attach to an existing process and the internal handle.
  15. template<typename ExecutionContext> 
      explicit basic_process(ExecutionContext & context, 
                             typename std::enable_if< is_convertible< ExecutionContext &, boost::asio::execution_context & >::value, void * >::type = nullptr);
    Create an invalid handle.
  16. basic_process & operator=(const basic_process &) = delete;
  17. basic_process & operator=(basic_process && lhs) = default;
    Move assign a process. It will be detached from lhs.
  18. ~basic_process();
    Destruct the handle and terminate the process if it wasn't detached.

basic_process public member functions

  1. executor_type get_executor();
    Get the executor of the process.
  2. handle_type & handle();
    Get the underlying non-closing handle.
  3. const handle_type & handle() const;
    Get the underlying non-closing handle.
  4. void interrupt();
    Sends the process a signal to ask for an interrupt, which the process may interpret as a shutdown.

    Maybe be ignored by the subprocess.

  5. void interrupt(error_code & ec);
    Throwing.

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

  6. void request_exit();
    Throwing.

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

  7. void request_exit(error_code & ec);
    Sends the process a signal to ask for a graceful shutdown. Maybe be ignored by the subprocess.
  8. void suspend(error_code & ec);
    Send the process a signal requesting it to stop. This may rely on undocumented functions.
  9. void suspend();
    Send the process a signal requesting it to stop. This may rely on undocumented functions.
  10. void resume(error_code & ec);
    Send the process a signal requesting it to resume. This may rely on undocumented functions.
  11. void resume();
    Send the process a signal requesting it to resume. This may rely on undocumented functions.
  12. void terminate();
    Throwing.

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

  13. void terminate(error_code & ec);
    Unconditionally terminates the process and stores the exit code in exit_status.
  14. int wait();
    Throwing.

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

  15. int wait(error_code & ec);
    Waits for the process to exit, store the exit code internally and return it.
  16. handle_type detach();
    Detach the process.
  17. native_handle_type native_handle();
  18. int exit_code() const;
  19. pid_type id() const;
    Get the id of the process;.
  20. native_exit_code_type native_exit_code() const;
    The native handle of the process.

    This might be undefined on posix systems that only support signals

  21. bool running();
    Checks if the current process is running.

    If it has already completed the exit code will be stored internally and can be obtained by calling `exit_code.

  22. bool running(error_code & ec) noexcept;
    Throwing.

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

  23. bool is_open() const;
    Check if the process is referring to an existing process.

    Note that this might be a process that already exited.

  24. template<Token WaitHandler DEFAULT_TYPE> 
       async_wait(WaitHandler &&handler  DEFAULT);
    Asynchronously wait for the process to exit and deliver the portable exit-code in the completion handler.

PrevUpHomeNext