Poco

class ProcessRunner

File Information

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, 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 virtual

~ProcessRunner();

Destroys the ProcessRunner.

Member Functions

cmdLine

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.

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

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.