OksSystem::Process Class Reference

Wrapper for process manipulation. More...

#include <Process.hpp>

Collaboration diagram for OksSystem::Process:

Public Member Functions
	Process ()
	Builds a process representing the current process.
	Process (const Process &other)
	copy constructor
	Process (pid_t pid)
	Builds a process with process id pid.
	Process (pid_t pid, const std::string &name)
	Builds a process with process id and process name.
	~Process () throw ()
	Destructor
	operator pid_t () const throw ()
	Cast operator to pid.
int	join (bool throw_non_zero=false) const
	Waits for the process to terminate.
void	signal (int signal) const
	Sends a signal to the process.
bool	exists () const
	Does the process exist?
bool	equals (const Process &other) const throw ()
	Comparison method.
void	terminate () const
	Terminate the process.
pid_t	process_id () const throw ()
	the id of the process
std::string	to_string () const throw ()
	String conversion method.

Static Public Member Functions
static const char *	exit_text (int return_value)
	the textual description of standard exit codes
static std::string	exit_pretty (int return_value)
static const Process *	instance () throw ()
static void	set_name (const std::string &name) throw ()

Protected Attributes
pid_t	m_process_id
	process identifier
std::string	m_process_name
	process name - only to be used for display

Static Protected Attributes
static const char *const	SYS_EXITS_NAMES []
	names for standard system exit values
static const char *const	TEST_EXITS_NAMES [] = { "undefined test", "test failed", "test unresolved", "test untested", "unsupported test" }
	names for testing exit values
static const char *const	OK_EXIT_NAME = "ok"
	string to describe 0 exit value
static const char *const	SIGNAL_EXIT_NAME
	string to describe signal exited value
static const int	TEST_BASE_VALUE = 182
	first value for test manager exit codes
static const int	TEST_MAX_VALUE = 186
	last value for test manager exit codes
static const int	TERMINATION_WAIT = 100000
	wait time before deciding a termination signal did not work
static Process *	s_instance = 0
	singleton instance

Detailed Description

Wrapper for process manipulation.

This class represents a process It offers basic methods to manipulate a process

Author

Matthias Wiesmann

Version

1.0

Definition at line 25 of file Process.hpp.

Constructor & Destructor Documentation

Process() [1/4]

OksSystem::Process::Process

(

)

Builds a process representing the current process.

Constructor from current process For the current process, the singleton factory method instance should be used

Definition at line 93 of file Process.cpp.

                          {
    m_process_id = ::getpid();
} // Process

Process() [2/4]

OksSystem::Process::Process

(

const Process &

other

)

copy constructor

Copy constructor

Parameters

other

original instance

Definition at line 101 of file Process.cpp.

                                              {
    m_process_id = other.m_process_id;
    m_process_name = other.m_process_name;
} // Process

Process() [3/4]

OksSystem::Process::Process

(

pid_t

id

)

Builds a process with process id pid.

Constructor for pid

Parameters

id	pid of the process

Definition at line 110 of file Process.cpp.

                                 {
    m_process_id = id;
} // Process 

Process() [4/4]

OksSystem::Process::Process	(	pid_t	id,
		const std::string &	name )

Builds a process with process id and process name.

Constructor from pid and process name

Parameters

id	pid of the process
name	display name of the process

Definition at line 119 of file Process.cpp.

                                                         {
    m_process_id = id;
    m_process_name = name;
} 

~Process()

OksSystem::Process::~Process	(		)
throw	(	)

Destructor

Destructor

Definition at line 128 of file Process.cpp.

                                   {
    m_process_id = 0;
} // ~Process

Member Function Documentation

equals()

bool OksSystem::Process::equals	(	const Process &	other	)	const
throw	(	)

Comparison method.

Checks if two process are equal

Parameters

other

the process to compare this process to

Returns

true if both proceses are equal (same pid).

Definition at line 193 of file Process.cpp.

                                                                {
    return m_process_id == other.m_process_id;
} // equals

exists()

bool OksSystem::Process::exists

(

)

const

Does the process exist?

Checks if the process actually exists on the host

Returns

true if the process exists

Note

currently the check is done by sending signal 0 to the process in case of failure, we know process does not exist

Definition at line 183 of file Process.cpp.

                                    {
    const int status = ::kill(m_process_id,0);
    return (status>=0);
} // exists

exit_pretty()

std::string OksSystem::Process::exit_pretty ( int return_value )

static

Builds a pretty string for an exit value

Parameters

return_value

the integer returned by a program

Returns

if the code is recognised by exit_text, this text and the number between parenthesis if not, the return_value converter into a string

Definition at line 55 of file Process.cpp.

                                                        {
    std::ostringstream stream;
    const char* text = OksSystem::Process::exit_text(return_value);
    if (text) {
    stream << text << '(' << return_value << ')';
    } else {
    stream << return_value ;
    }
    return stream.str(); 
} // exit_string

exit_text()

const char * OksSystem::Process::exit_text ( int return_value )

static

the textual description of standard exit codes

Gives textual representation of exit values. This method recognises return codes from sysexits and the values returned by the text-manager

Parameters

return_value

the integer returned by a program

Returns

a pointer to the string desribing the code, or a null pointer if the code is not recognised

Definition at line 42 of file Process.cpp.

                                                        {
    if ( 0==return_value) return OK_EXIT_NAME;
    if ((return_value >= EX__BASE)  && (return_value <= EX__MAX)) return SYS_EXITS_NAMES[return_value-EX__BASE];
    if ((return_value >= TEST_BASE_VALUE) && (return_value <= TEST_MAX_VALUE)) return TEST_EXITS_NAMES[return_value-TEST_BASE_VALUE];
    return 0;
} // return_text

instance()

const OksSystem::Process * OksSystem::Process::instance ( ) throw (  )

static

Default current process instance If needed the instance is created

Returns

singleton instance for current process

Definition at line 72 of file Process.cpp.

                                                           {
    if (0==s_instance) {
    s_instance = new OksSystem::Process(); 
    } // if
    return s_instance;
} // instance

join()

int OksSystem::Process::join

(

bool

throw_non_zero = false

)

const

Waits for the process to terminate.

Waits for a process to terminate. If the process terminates normally, the return value is the termination status of the process. If the process stops or is signaled, an SignalIssue is thrown.

Returns

the termination status of the process

Definition at line 146 of file Process.cpp.

                                                    {
    ERS_PRECONDITION(! equals(*instance())); 
    int status;
    errno = 0;
    pid_t pid = ::waitpid(m_process_id,&status,0); 
    if (pid!=m_process_id) {
        std::string message = "on process " + this->to_string();
    throw OksSystem::OksSystemCallIssue( ERS_HERE, errno, "waitpid", message.c_str() ); 
    } // if 
    if (WIFEXITED(status)) {
    int exit_status = WEXITSTATUS(status);
    if ((throw_non_zero==false) || (exit_status==0)) return exit_status;
    throw OksSystem::TerminationIssue(ERS_HERE, errno, exit_status);
    } // exit status
    if (WIFSIGNALED(status)) throw OksSystem::SignalIssue(ERS_HERE,errno,WTERMSIG(status));
    if (WIFSTOPPED(status)) throw OksSystem::SignalIssue(ERS_HERE,errno,WSTOPSIG(status));
    return WEXITSTATUS(status);
} // join

operator pid_t()

OksSystem::Process::operator pid_t	(		)	const
throw	(	)

Cast operator to pid.

Cast operator - converts to process-id

Definition at line 135 of file Process.cpp.

                                               {
    return m_process_id;
} // operator pid_t

process_id()

pid_t OksSystem::Process::process_id	(		)	const
throw	(	)

the id of the process

Returns

the process id for the process

Definition at line 244 of file Process.cpp.

{ return m_process_id;} 

set_name()

void OksSystem::Process::set_name ( const std::string & name ) throw (  )

static

Sets the process name of the current process

Definition at line 83 of file Process.cpp.

                                                             {
    (void) instance();
    s_instance->m_process_name = name;
} // set_name

signal()

void OksSystem::Process::signal

(

int

signal_number

)

const

Sends a signal to the process.

Sends a signal to the process

Parameters

signal_number

number of the signal

Definition at line 169 of file Process.cpp.

                                                     {
    const int status = ::kill(m_process_id,signal_number);
    if (status < 0) {
      std::string message = "on process " + this->to_string();
      throw OksSystem::OksSystemCallIssue(ERS_HERE, errno, "kill", message.c_str());
    }
} // signal

terminate()

void OksSystem::Process::terminate

(

)

const

Terminate the process.

Terminates a process Termination is implemented by

• sending the TERM signal

Definition at line 202 of file Process.cpp.

                                       {
  /*
    struct timespec wait_time;
    struct timespec remain_time;
    wait_time.tv_sec = 0;
    wait_time.tv_nsec = TERMINATION_WAIT;
  */
    if (exists()) {
    signal(SIGTERM);
    }
    return;
} 

to_string()

std::string OksSystem::Process::to_string	(		)	const
throw	(	)

String conversion method.

Builds a string description of the process

Returns

textual description

Definition at line 232 of file Process.cpp.

                                                    {
    std::ostringstream stream;
    if (! m_process_name.empty()) {
    stream << m_process_name << ' ';
    } 
    stream << "pid: " << m_process_id;
    return stream.str(); 
} // to_string

Member Data Documentation

m_process_id

pid_t OksSystem::Process::m_process_id

protected

process identifier

Definition at line 27 of file Process.hpp.

m_process_name

std::string OksSystem::Process::m_process_name

protected

process name - only to be used for display

Definition at line 28 of file Process.hpp.

OK_EXIT_NAME

const char *const OksSystem::Process::OK_EXIT_NAME = "ok"

staticprotected

string to describe 0 exit value

Definition at line 31 of file Process.hpp.

s_instance

OksSystem::Process * OksSystem::Process::s_instance = 0

staticprotected

singleton instance

Definition at line 36 of file Process.hpp.

SIGNAL_EXIT_NAME

const char* const OksSystem::Process::SIGNAL_EXIT_NAME

staticprotected

string to describe signal exited value

Definition at line 32 of file Process.hpp.

SYS_EXITS_NAMES

const char *const OksSystem::Process::SYS_EXITS_NAMES

staticprotected

Initial value:

= { "command line usage error", "data format error", "cannot open input", "addressee unknown", "host name unknown", "service unavailable", "internal software error", "okssystem error", 
    "critical OS file missing", "can't create (user) output file", "input/output error", "temp failure; user is invited to retry", "remote error in protocol", "permission denied ", "configuration error" }

names for standard system exit values

Definition at line 29 of file Process.hpp.

      :
    static const char* exit_text(int return_value) ;     
    static std::string exit_pretty(int return_value) ; 
    static const Process *instance() throw() ;
    static void set_name(const std::string &name) throw() ; 
    Process();                                           
    Process(const Process &other) ;                      
    Process(pid_t pid) ;                                 
    Process(pid_t pid, const std::string &name);         
    ~Process() throw() ;                                 
    operator pid_t() const throw() ;                     
    int join(bool throw_non_zero=false) const ;          
    void signal(int signal) const ;                      
    bool exists() const ;                                
    bool equals(const Process &other) const throw() ;    
    void terminate() const ;                             
    pid_t process_id() const throw();                    
    std::string to_string() const throw();               
    } ; // Process
    
} // OksSystem
 
std::ostream& operator<<(std::ostream& stream, const OksSystem::Process &proc) ;        
bool operator ==(const OksSystem::Process &a, const OksSystem::Process &b)  throw(); 
bool operator !=(const OksSystem::Process &a, const OksSystem::Process &b)  throw(); 
 
#endif

TERMINATION_WAIT

const int OksSystem::Process::TERMINATION_WAIT = 100000

staticprotected

wait time before deciding a termination signal did not work

Wait time before deciding a termination signal did not work (in nanoseconds)

Definition at line 35 of file Process.hpp.

TEST_BASE_VALUE

const int OksSystem::Process::TEST_BASE_VALUE = 182

staticprotected

first value for test manager exit codes

Lowest value for test manager result code

Definition at line 33 of file Process.hpp.

TEST_EXITS_NAMES

const char *const OksSystem::Process::TEST_EXITS_NAMES = { "undefined test", "test failed", "test unresolved", "test untested", "unsupported test" }

staticprotected

names for testing exit values

Definition at line 31 of file Process.hpp.

TEST_MAX_VALUE

const int OksSystem::Process::TEST_MAX_VALUE = 186

staticprotected

last value for test manager exit codes

Highest value for test manager result code

Definition at line 34 of file Process.hpp.

---

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

• /github/workspace/dunedaq/sourcecode/okssystem/include/okssystem/Process.hpp
• /github/workspace/dunedaq/sourcecode/okssystem/src/Process.cpp