Struct template basic_process_handle

boost::process::v2::basic_process_handle

Synopsis

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

template<typename Executor = boost::asio::any_io_executor> 
struct basic_process_handle {
  // types
  typedef implementation_defined native_handle_type;
  typedef Executor               executor_type;       // The executor_type of the process_handle. 

  // member classes/structs/unions

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

  // construct/copy/destruct
  template<typename ExecutionContext> basic_process_handle(ExecutionContext &);
  basic_process_handle(executor_type);
  basic_process_handle(executor_type, pid_type);
  basic_process_handle(executor_type, pid_type, native_handle_type);
  template<typename Executor1> 
    basic_process_handle(basic_process_handle< Executor1 > &&);

  // public member functions
  executor_type get_executor();
  pid_type id() const;
  void terminate_if_running(error_code &);
  void terminate_if_running();
  void wait(native_exit_code_type &, error_code &);
  void wait(native_exit_code_type &);
  void interrupt(error_code &);
  void interrupt();
  void request_exit(error_code &);
  void request_exit();
  void terminate(native_exit_code_type &);
  bool running(native_exit_code_type &, error_code &);
  bool running(native_exit_code_type &);
  bool is_open() const;
  template<Token WaitHandler DEFAULT_TYPE>  async_wait(WaitHandler &&handler );

  // public data members
  void error_code & ec;
};

Description

A process handle is an unmanaged version of a process. This means it does not terminate the proces on destruction and will not keep track of the exit-code.

Note that the exit code might be discovered early, during a call to running. Thus it can only be discovered that process has exited already.

`basic_process_handle` public types

typedef implementation_defined native_handle_type;

This might be undefined on posix systems that only support signals

`basic_process_handle` public construct/copy/destruct

```
template<typename ExecutionContext> 
  basic_process_handle(ExecutionContext & context);
```
Construct a basic_process_handle from an execution_context.

Template Parameters:

ExecutionContext

The context must fulfill the asio::execution_context requirements
```
basic_process_handle(executor_type executor);
```
Construct an empty process_handle from an executor.
```
basic_process_handle(executor_type executor, pid_type pid);
```
Construct an empty process_handle from an executor and bind it to a pid.
On NON-linux posix systems this call is not able to obtain a file-descriptor and will thus rely on signals.
```
basic_process_handle(executor_type executor, pid_type pid, 
                     native_handle_type process_handle);
```
Construct an empty process_handle from an executor and bind it to a pid and the native-handle.
On some non-linux posix systems this overload is not present.

template<typename Executor1> 
  basic_process_handle(basic_process_handle< Executor1 > && handle);

Move construct and rebind the executor.

`basic_process_handle` public member functions

```
executor_type get_executor();
```
Getter for the executor.
```
pid_type id() const;
```
Get the id of the process.
```
void terminate_if_running(error_code &);
```
Terminate the process if it's still running and ignore the result.
```
void terminate_if_running();
```
Throwing.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

void wait(native_exit_code_type & exit_status, error_code & ec);

wait for the process to exit and store the exit code in exit_status.

```
void wait(native_exit_code_type & exit_status);
```
Throwing.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
void interrupt(error_code & ec);
```
Sends the process a signal to ask for an interrupt, which the process may interpret as a shutdown.
Maybe be ignored by the subprocess.
```
void interrupt();
```
Throwing.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
void request_exit(error_code & ec);
```
Sends the process a signal to ask for a graceful shutdown. Maybe be ignored by the subprocess.
```
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.Unconditionally terminates the process and stores the exit code in exit_status.
```
void terminate(native_exit_code_type & exit_status);
```
Throwing.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
bool running(native_exit_code_type & exit_code, error_code & ec);
```
Checks if the current process is running.
If it has already completed, it assigns the exit code to exit_code.
```
bool running(native_exit_code_type & exit_code);
```
Throwing.
This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
```
bool is_open() const;
```
Check if the process handle is referring to an existing process.
```
template<Token WaitHandler DEFAULT_TYPE> 
   async_wait(WaitHandler &&handler  DEFAULT);
```
Asynchronously wait for the process to exit and deliver the native exit-code in the completion handler.

Boost C++ Libraries

Struct template basic_process_handle

Synopsis

Description

basic_process_handle public types

basic_process_handle public construct/copy/destruct

basic_process_handle public member functions

`basic_process_handle` public types

`basic_process_handle` public construct/copy/destruct

`basic_process_handle` public member functions