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();
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.