Encapsulates a process, that was launched from the current process. More...

#include <platform/Process.h>

Inheritance diagram for Process:

Classes
class	Environment
	Holds the environment variables that can be passed to a process. More...

Public Types
enum	ExitStatus { NORMALEXIT, CRASHED, KILLED }

enum	CreationFlags { noflags = 0x00, interruptChildOnParentDeath = 0x01, shutdownRecursively = 0x02 }

enum	RedirectionFlags { none = 0x00, in = 0x01, out = 0x02, err = 0x04 }

typedef boost::iostreams::stream< boost::iostreams::file_descriptor_sink >	ostream

typedef boost::iostreams::stream< boost::iostreams::file_descriptor_source >	istream

Public Member Functions
	Process ()
	Creates an invalid process object. More...

	~Process ()
	Destructor, which will terminate the process, if it is still running. More...

	Process (Process &&other) noexcept

Process &	operator= (Process &&other) noexcept

void	swap (Process &other)
	Swaps the ownership of the process context within this and other. More...

bool	wait (Duration maxWait=Duration::infinity())
	Blocks the current thread of the calling process, until the process that is represented by this Process object has terminated or maxWait is reached. More...

int	getExitCode ()
	Return the exit code of the process. More...

ExitStatus	getExitStatus ()
	Returns the exit status of the process only valid if not running. More...

bool	isRunning ()
	Returns if the process that is represented by this Process object is still running. More...

void	interrupt ()
	Stops (e.g. More...

void	terminate ()
	Terminates (e.g. More...

void	kill ()
	Kills (e.g. More...

void	setRecursiveShutdown (bool recursive)
	Enable recursive shutdown. More...

void	shutdown (Duration timeout=Duration::seconds(5))
	Performs an orderly shutdown by executing the following steps. More...

uint32	getPID () const
	Returns the process id (pid) of the process. More...

ostream &	cin ()
	Output stream for writing to the stdin of the child process. More...

istream &	cout ()
	Input stream for reading from the stdout of the child process. More...

istream &	cerr ()
	Input stream for reading from the stderr of the child process. More...

Static Public Member Functions
static Process	createProcess (const std::string &commandLine, CreationFlags flags, RedirectionFlags streamRedirection=none)
	Spawns a new process and executes the given command line. More...

static Process	createProcess (const std::string &commandLine, RedirectionFlags streamRedirection=none)
	Same as above but the flags can be omitted. More...

static Process	createProcess (const std::string &applicationName, const std::vector< std::string > &args, CreationFlags flags=noflags, RedirectionFlags streamRedirection=none, boost::optional< Environment > env=boost::optional< Environment >())
	Same as above, but a more advanced interface to create a new process. More...

Protected Member Functions
bool	wait (int pid, std::vector< int > &children, Duration timeout=Duration::seconds(5))

std::vector< int >	getRecursiveChildProcesses (int pid, int maxDepth=-1)

bool	interrupt (int pid)

bool	terminate (int pid)

bool	kill (int pid)

void	shutdown (int pid, Duration timeout=Duration::seconds(5))

Detailed Description

Encapsulates a process, that was launched from the current process.

A new process can be spawned using the createProcess() method, which returns an object to the created process. The process object can be used to terminate the process and to check its current status.

Note, that Process objects can not be copied. Use the move semantic and std::move() to pass instances of this class.

Member Typedef Documentation

◆ ostream

typedef boost::iostreams::stream<boost::iostreams::file_descriptor_sink> ostream

◆ istream

typedef boost::iostreams::stream<boost::iostreams::file_descriptor_source> istream

Member Enumeration Documentation

◆ ExitStatus

enum ExitStatus

Enumerator
NORMALEXIT
CRASHED
KILLED

◆ CreationFlags

enum CreationFlags

Enumerator
noflags
interruptChildOnParentDeath	Will send the SIGINT signal to the child when the parent gets killed.
shutdownRecursively	If true, shutdown will determine the complete progeny of the spawned process and eradicate it (top down), using the same interrupt/terminate/kill sequence for each process.

◆ RedirectionFlags

enum RedirectionFlags

Enumerator
none
in
out
err

Constructor & Destructor Documentation

◆ Process() [1/2]

Process ( )

Creates an invalid process object.

◆ ~Process()

~Process ( )

Destructor, which will terminate the process, if it is still running.

◆ Process() [2/2]

Process ( Process && other )

noexcept

Member Function Documentation

◆ operator=()

Process& operator= ( Process && other )

noexcept

◆ swap()

void swap ( Process & other )

Swaps the ownership of the process context within this and other.

◆ createProcess() [1/3]

static Process createProcess	(	const std::string &	commandLine,
		CreationFlags	flags,
		RedirectionFlags	streamRedirection = `none`
	)

static

Spawns a new process and executes the given command line.

The command line may contain parameters that are separated by white characters.

On Windows the application is searched in the following paths:

The directory from which the application loaded.
The current directory for the parent process.
The Windows system directory.
The directories that are listed in the PATH environment variable.

On Linux the application is searched within:

The directories that are listed in the PATH environment variable.

Parameters

flags Allows to specify some flags that control the creation and termination of the created process.

See also: CreationFlags.

Parameters

streamRedirection Allows to specify which streams (stdin, stdout, etc) should be redirected in order to access them from the parent process via the cin(), cout(), cerr() stream method (see below).

Returns: Returns the Process object that can be used to wait for the process to terminate, etc.

Exceptions

XRuntime	If the process can not be forked
XFileNotFound	If the given executable can not be found
XInvalidParameter	If the execution of the given application fails

◆ createProcess() [2/3]

static Process createProcess	(	const std::string &	commandLine,
		RedirectionFlags	streamRedirection = `none`
	)

static

Same as above but the flags can be omitted.

◆ createProcess() [3/3]

static Process createProcess	(	const std::string &	applicationName,
		const std::vector< std::string > &	args,
		CreationFlags	flags = `noflags`,
		RedirectionFlags	streamRedirection = `none`,
		boost::optional< Environment >	env = `boost::optional< Environment >()`
	)

static

Same as above, but a more advanced interface to create a new process.

Here, the arguments can be specified separately as vector of strings. Moreover, the environment of the new process (containing the environment variables) can be specified.

◆ wait() [1/2]

bool wait ( Duration maxWait = Duration::infinity() )

Blocks the current thread of the calling process, until the process that is represented by this Process object has terminated or maxWait is reached.

Returns: true if process has terminated, false if not or maxWait has been reached

◆ getExitCode()

int getExitCode ( )

Return the exit code of the process.

Only valid if not running and exit status is NORMALEXIT.

◆ getExitStatus()

ExitStatus getExitStatus ( )

Returns the exit status of the process only valid if not running.

◆ isRunning()

bool isRunning ( )

Returns if the process that is represented by this Process object is still running.

◆ interrupt() [1/2]

void interrupt ( )

Stops (e.g.

using SIGINT) the process that is represented by this Process object.

◆ terminate() [1/2]

void terminate ( )

Terminates (e.g.

using SIGTERM) the process that is represented by this Process object.

◆ kill() [1/2]

void kill ( )

Kills (e.g.

using SIGKILL) the process that is represented by this Process object.

◆ setRecursiveShutdown()

void setRecursiveShutdown ( bool recursive )

Enable recursive shutdown.

Can be used to change this setting after createProcess().

See also: shutdownRecursively

◆ shutdown() [1/2]

void shutdown ( Duration timeout = Duration::seconds(5) )

Performs an orderly shutdown by executing the following steps.

looks if process has already ended - returns
sends interrupt request and waits until timeout. if process has ended - returns
sends terminate request and waits until timeout. if process has ended - returns
sends kill request and waits until process has ended

This method blocks until the process that is represented by this Process object has terminated.

Parameters

timeout Timeout used for waiting for process to terminate in the above steps

◆ getPID()

uint32 getPID ( ) const

Returns the process id (pid) of the process.

Or 0, if no process was started.

◆ cin()

ostream& cin ( )

Output stream for writing to the stdin of the child process.

This stream is available only, if the appropriate redirection flag was set in createProcess().

◆ cout()

istream& cout ( )

Input stream for reading from the stdout of the child process.

This stream is available only, if the appropriate redirection flag was set in createProcess().

◆ cerr()

istream& cerr ( )

Input stream for reading from the stderr of the child process.

This stream is available only, if the appropriate redirection flag was set in createProcess().

◆ wait() [2/2]

bool wait	(	int	pid,
		std::vector< int > &	children,
		Duration	timeout = `Duration::seconds(5)`
	)

protected

◆ getRecursiveChildProcesses()

std::vector<int> getRecursiveChildProcesses	(	int	pid,
		int	maxDepth = `-1`
	)

protected

◆ interrupt() [2/2]

bool interrupt ( int pid )

protected

◆ terminate() [2/2]

bool terminate ( int pid )

protected

◆ kill() [2/2]

bool kill ( int pid )

protected

◆ shutdown() [2/2]

void shutdown	(	int	pid,
		Duration	timeout = `Duration::seconds(5)`
	)

protected

The documentation for this class was generated from the following file:

base/include/platform/Process.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ ostream

◆ istream

Member Enumeration Documentation

◆ ExitStatus

◆ CreationFlags

◆ RedirectionFlags

Constructor & Destructor Documentation

◆ Process() [1/2]

◆ ~Process()

◆ Process() [2/2]

Member Function Documentation

◆ operator=()

◆ swap()

◆ createProcess() [1/3]

◆ createProcess() [2/3]

◆ createProcess() [3/3]

◆ wait() [1/2]

◆ getExitCode()

◆ getExitStatus()

◆ isRunning()

◆ interrupt() [1/2]

◆ terminate() [1/2]

◆ kill() [1/2]

◆ setRecursiveShutdown()

◆ shutdown() [1/2]

◆ getPID()

◆ cin()

◆ cout()

◆ cerr()

◆ wait() [2/2]

◆ getRecursiveChildProcesses()

◆ interrupt() [2/2]

◆ terminate() [2/2]

◆ kill() [2/2]

◆ shutdown() [2/2]