xorg-gtest  0.1
Xorg testing extension to Google Test
xorg::testing::Process Class Reference

Class that abstracts child process creation and termination. More...

#include <xorg/gtest/xorg-gtest-process.h>

Inheritance diagram for xorg::testing::Process:
xorg::testing::XServer

Public Types

enum  State {
  ERROR, NONE, RUNNING, FINISHED_SUCCESS,
  FINISHED_FAILURE, TERMINATED
}
 Describes the state of a process as seen by this library. More...
 

Public Member Functions

 Process ()
 Creates a child-process that is in a terminated state. More...
 
pid_t Fork ()
 Fork manually. More...
 
void Start (const std::string &program, const std::vector< std::string > &args)
 Starts a program as a child process. More...
 
void Start (const std::string &program, va_list *args)
 Starts a program as a child process. More...
 
void Start (const std::string &program,...) _X_SENTINEL(0)
 Starts a program as a child process. More...
 
virtual bool Terminate (unsigned int timeout=0)
 Terminates (SIGTERM) this child process and waits a given timeout for the process to terminate. More...
 
virtual bool Kill (unsigned int timeout=0)
 Kills (SIGKILL) this child process and waits a given timeout for the process to terminate. More...
 
pid_t Pid () const
 Accesses the pid of the child process. More...
 
enum Process::State GetState ()
 Return the state of the process. More...
 

Static Public Member Functions

static void SetEnv (const std::string &name, const std::string &value, bool overwrite)
 Helper function to adjust the environment of the current process. More...
 
static std::string GetEnv (const std::string &name, bool *exists=NULL)
 Helper function to query the environment of the current process. More...
 

Detailed Description

Class that abstracts child process creation and termination.

This class allows for forking, running and terminating child processes. In addition, manipulation of the child process' environment is supported. For example, starting an X server instance on display port 133 as a child process can be realized with the following code snippet:

Process xorgServer;
try {
xorgServer.Start("Xorg", "Xorg", ":133");
} catch (const std::runtime_error&e) {
std::cerr << "Problem starting the X server: " << e.what() << std::endl;
}
...
if (!xorgServer.Terminate()) {
std::cerr << "Problem terminating server ... killing now ..." << std::endl;
if (!xorgServer.Kill())
std::cerr << "Problem killing server" << std::endl;
}

Member Enumeration Documentation

◆ State

Describes the state of a process as seen by this library.

This state changes some behaviors inside the library, most notably:

  • A process in state ERROR or NONE will fail to Kill() or Terminate()
  • A process in state FINISHED_SUCCESS or FINISHED_FAILURE will always succeed to Kill() or Terminate()
  • A process in state TERMINATED may change state to FINISHED_SUCCESS or FINISHED_FAILURE when queried again.
Enumerator
ERROR 

An error has occured, state is now unknown.

NONE 

The process has not been started yet.

RUNNING 

The process has been started.

FINISHED_SUCCESS 

The process finished with an exit code of 0.

FINISHED_FAILURE 

The process finished with a non-zero exit code.

TERMINATED 

The process was successfully terminated by this library but it's state is currently unknown.

Constructor & Destructor Documentation

◆ Process()

xorg::testing::Process::Process ( )

Creates a child-process that is in a terminated state.

Member Function Documentation

◆ Fork()

pid_t xorg::testing::Process::Fork ( )

Fork manually.

Usually, fork() is called as part of Start() but for use-cases where the parent process and the child process need special processing before the child is replaced by an execvp call Fork() may be called manually.

A process may only be forked once.

The state of both the parent and the child after a Fork() is Process::RUNNING. If Fork() is called directly, Start() may only be called on the child process.

Exceptions
std::runtime_erroron failure.
Returns
The pid of the child, or 0 for the child process.

◆ GetEnv()

static std::string xorg::testing::Process::GetEnv ( const std::string &  name,
bool *  exists = NULL 
)
static

Helper function to query the environment of the current process.

Parameters
[in]nameThe name of the environment variable.
[out]existsIf not NULL, the variable will be set to true if the environment variable exists and to false otherwise.
Returns
The value of the environment variable, or an empty string.

◆ GetState()

enum Process::State xorg::testing::Process::GetState ( )

Return the state of the process.

Returns
The current state of the process
Examples
xorg-gtest-example.cpp.

◆ Kill()

virtual bool xorg::testing::Process::Kill ( unsigned int  timeout = 0)
virtual

Kills (SIGKILL) this child process and waits a given timeout for the process to terminate.

Parameters
[in]timeoutThe timeout in millis to wait for the process to terminate. A timeout of 0 implies not to wait but return immediately.
Exceptions
std::runtime_errorif child tries to kill itself.
Returns
true if kill succeeded and, if a timout is given, the process shut down within that timeout. false otherwise.
Postcondition
If successful: Child process killed.
If successful: Subsequent calls to Pid() return -1.

Reimplemented in xorg::testing::XServer.

◆ Pid()

pid_t xorg::testing::Process::Pid ( ) const

Accesses the pid of the child process.

Returns
The pid of the child process or -1.

◆ SetEnv()

static void xorg::testing::Process::SetEnv ( const std::string &  name,
const std::string &  value,
bool  overwrite 
)
static

Helper function to adjust the environment of the current process.

Parameters
[in]nameName of the environment variable.
[in]valueValue of the environment variable.
[in]overwriteWhether to overwrite the value of existing env variables.
Exceptions
std::runtime_errorif adjusting the environment does not succeed.

◆ Start() [1/3]

void xorg::testing::Process::Start ( const std::string &  program,
const std::vector< std::string > &  args 
)

Starts a program as a child process.

See 'man execvp' for further information on the elements in the vector.

If Fork() was called previously, Start() may only be called on the child process.

Parameters
programThe program to start.
argsVector of arguments passed to the program.
Exceptions
std::runtime_erroron failure.
Postcondition
If successful: Child process forked and program started.
If successful: Subsequent calls to Pid() return child process pid.

◆ Start() [2/3]

void xorg::testing::Process::Start ( const std::string &  program,
va_list *  args 
)

Starts a program as a child process.

See 'man execvp' for further information on the variadic argument list.

If Fork() was called previously, Start() may only be called on the child process.

Parameters
programThe program to start.
argsPointer to a variadic list of arguments passed to the program. This list must end with NULL.
Exceptions
std::runtime_erroron failure.
Postcondition
If successful: Child process forked and program started.
If successful: Subsequent calls to Pid() return child process pid.

◆ Start() [3/3]

void xorg::testing::Process::Start ( const std::string &  program,
  ... 
)

Starts a program as a child process.

Takes a variadic list of arguments passed to the program. This list must end with NULL. See 'man execvp' for further information on the variadic argument list.

If Fork() was called previously, Start() may only be called on the child process.

Parameters
programThe program to start.
Exceptions
std::runtime_erroron failure.
Postcondition
If successful: Child process forked and program started.
If successful: Subsequent calls to Pid() return child process pid.

◆ Terminate()

virtual bool xorg::testing::Process::Terminate ( unsigned int  timeout = 0)
virtual

Terminates (SIGTERM) this child process and waits a given timeout for the process to terminate.

Parameters
[in]timeoutThe timeout in millis to wait for the process to terminate. A timeout of 0 implies not to wait but return immediately.
Exceptions
std::runtime_errorif child tries to terminate itself.
Returns
true if termination succeeded and, if a timout is given, the process shut down within that timeout. false otherwise.
Postcondition
If successful: Child process terminated.
If successful: Subsequent calls to Pid() return -1.

Reimplemented in xorg::testing::XServer.


The documentation for this class was generated from the following file:
xorg::testing::Process::Process
Process()
Creates a child-process that is in a terminated state.