# Poco

# class ProcessRunner

Library: Foundation
Package: Processes
Header: Poco/ProcessRunner.h

## Description

ProcessRunner is a wrapper class for Poco::ProcessHandle. It starts and terminates a process with enabled or disabled (default) `stdio` pipes, and optionally waits for process PID to be created before returning control to the caller. The process is spawned from an internal thread. Starting/stopping the process may block up to a certain (configurable) period of time.

ProcessRunner can hold and control only one process at a time, which can be started/stopped multiple times during the ProcessRunner lifetime.

## Inheritance

Direct Base Classes: Runnable

All Base Classes: Runnable

## Member Summary

Member Functions: cmdLine, error, pid, pidFile, result, runCount, running, start, stop

Inherited Functions: run

## Types Aliases

### Args

using Args = Poco::Process::Args;

### PID

using PID = Poco::ProcessHandle::PID;

## Constructors

### ProcessRunner

ProcessRunner(
const std::string & cmd,
const Args & args,
const std::string & pidFile = "",
int options = NO_OUT,
int timeout = 10,
bool startProcess = true,
const Args & pidArgFmt = pidArgFormat ()
);

Creates the ProcessRunner.

If `pidFile` is not empty, the starting of the process waits until the pid file has been updated with the new pid, and the stopping of the process waits until the pid file is gone. Waiting is terminated after timeout seconds.

If `pidFile` is empty and `pidArgFmt` is not empty, autodetect of PID file from `args` is attempted; the default PID file argument format corresponds to the one used by `Poco::Util::Application`

The `options` are passed to the process, defaulting to closed stdio output pipes.

The `timeout` in seconds determines how long the ProcessRunner waits for the process to start; if PID file name is provided or autodetected from arguments, ProcessRunner will wait until the file exists and contains the process PID or timeout expires (in which case a TimeoutException is thrown).

If `startProcess` is true, the process is started on object creation.

## Destructor

### ~ProcessRunner

~ProcessRunner() override;

Destroys the ProcessRunner.

## Member Functions

### cmdLine

std::string cmdLine() const;

Returns process full command line.

### error

const std::string & error() const;

Returns the error message.

### pid

PID pid() const;

Returns the process PID.

### pidFile

const std::string & pidFile() const;

Returns the process PID filename. Returns empty string when pid filename is not specified at construction, either explicitly, or implicitly through command line argument.

### result

int result() const;

Returns process return code.

### runCount

int runCount() const;

Returns the number of times the process has been executed.

### running

bool running() const;

Returns true if process is running.

### start

void start();

Starts the process and waits for it to be fully initialized. Process initialization completion is indicated by a new pid in the pid file (if specified at construction, otherwise there is no wating for pid). If pid file is not specified, there is no waiting.

Attempting to start a started process results in Poco::InvalidAccessException being thrown.

### stop

void stop();

Stops the process.

Calling stop() on a stopped process is a no-op.

## Variables

### NO_OUT

static const int NO_OUT = Poco::PROCESS_CLOSE_STDOUT | Poco::PROCESS_CLOSE_STDERR;

Constant to prevent std out and err from being received from the process.