class ProcessRunner

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


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.


Direct Base Classes: Runnable

All Base Classes: Runnable

Member Summary

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

Inherited Functions: run

Types Aliases


using Args = Poco::Process::Args;


using PID = Poco::ProcessHandle::PID;



    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.


~ProcessRunner virtual


Destroys the ProcessRunner.

Member Functions


std::string cmdLine() const;

Returns process full command line.

pid inline

PID pid() const;

Returns the process PID.

pidFile inline

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 inline

int result() const;

Returns process return code.

runCount inline

int runCount() const;

Returns the number of times the process has been executed.

running inline

bool running() const;

Returns true if process is running.


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.


void stop();

Stops the process.

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


NO_OUT static


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