MIRA
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | List of all members
Process Class Reference

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

#include <platform/Process.h>

Inheritance diagram for Process:
Inheritance graph
[legend]

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
 
Processoperator= (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...
 
ostreamcin ()
 Output stream for writing to the stdin of the child process. More...
 
istreamcout ()
 Input stream for reading from the stdout of the child process. More...
 
istreamcerr ()
 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

std::map< int, std::vector< int > > getProcessAncestry ()
 
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

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

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:

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

On Linux the application is searched within:

  1. The directories that are listed in the PATH environment variable.
Parameters
flagsAllows to specify some flags that control the creation and termination of the created process.
See also
CreationFlags.
Parameters
streamRedirectionAllows 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
XRuntimeIf the process can not be forked
XFileNotFoundIf the given executable can not be found
XInvalidParameterIf 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.

  1. looks if process has already ended - returns
  2. sends interrupt request and waits until timeout. if process has ended - returns
  3. sends terminate request and waits until timeout. if process has ended - returns
  4. 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
timeoutTimeout 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().

◆ getProcessAncestry()

std::map<int, std::vector<int> > getProcessAncestry ( )
protected

◆ 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: