Dv::Util::Process Class Reference

A class representing a process. More...

#include <process.h>

Inheritance diagram for Dv::Util::Process:

[legend]

Collaboration diagram for Dv::Util::Process:

[legend]

List of all members.

Public Types
enum	{ NO_EXIT_STATUS = -2 }
enum	Status { DEAD, RUNNING, FINISHED, STOPPED, SIGNALED, CONTINUING }
	Process status. More...
Public Member Functions
	Process (const std::string &command="", unsigned int min_debug_level=1)
	Create a new process object.
int	start () throw (std::runtime_error, std::logic_error)
	Start up a new process.
pid_t	pid () const
const std::string &	command () const
int	exit_status () const
int	signaled () const
bool	killed () const
bool	stopped () const
void	signal (int signal, const std::string &error_message) const throw (std::runtime_error)
	Send a signal to this process.
void	stop () const throw (std::runtime_error)
	Send a SIGSTOP signal to this process.
void	resume () const throw (std::runtime_error)
	Send a SIGCONT signal to this process.
void	kill () const throw (std::runtime_error)
	Send a SIGKILL signal to this process.
Status	wait () const
	Wait for process to finish.
Status	status () const
	Return current process status.
virtual	~Process ()
	Destructor.
Protected Member Functions
Status	status (int s) const
	Convert a status provided by `waitpid` to a Status, possibly setting exit_status_ and signal_.
Status	wait (bool nohang) const
	Wrapper around `waitpid`.
Protected Attributes
pid_t	pid_
	This is protected so that subclasses can set it.
Private Member Functions
	Process (const Process &)
Process &	operator= (const Process &)
Private Attributes
std::string	command_
int	exit_status_
int	signal_

Detailed Description

A class representing a process.

It supports signaling and obtaining status. Note that the constructor does not start up the process, for that one should implement a subclass, with a constructor doing the fork() etc. An example function that can be used to do this is available in Dv::Util::Process:start.

Example:

 Dv::Util::Process proc("ping www.bla.com");
 proc.start();
 std::cout << proc.status() << std::endl;
 sleep(2);
 proc.stop(); // stop (not kill) the process by sending STOP signal
 sleep(2);
 proc.resume(); // resume the process
 sleep(2);
 if (impatient)
   proc.kill(); // send KILL signal
 else
   proc.wait(); // wait for process to actually finish

Definition at line 35 of file process.h.

Member Enumeration Documentation

anonymous enum

Enumerator:

NO_EXIT_STATUS

Definition at line 37 of file process.h.

enum Dv::Util::Process::Status

Process status.

Enumerator:

DEAD	doesn't exist anymore
RUNNING	also after resuming
FINISHED	finished normally, exit_status available
STOPPED	received SIGSTOP signal See also: Process::stop()
SIGNALED	e.g. using SIGKILL, See also: Process:kill()
CONTINUING	unused, could be supported under Linux 2.6

Definition at line 40 of file process.h.

Constructor & Destructor Documentation

Dv::Util::Process::Process	(	const std::string &	command = `""`,
		unsigned int	min_debug_level = `1`
	)

Create a new process object.

This function does not start up the process; this job is left to subclasses or, alternatively, to Dv::Util::Process::start. It simply stores the command to be executed. Example:

 Dv::Util::Process proc("ping www.bla.com");
 proc.start();

Parameters:

	command	to be executed by the process. If empty, one can use Dv::Util::Process:start to have the process execute a function in the current program.
	min_debug_level	for when the object is connected to a debug master

See also:: Dv::Util::Process:start; Dv::Debugable

virtual Dv::Util::Process::~Process ( ) [virtual]

Destructor.

If the process is still RUNNING or STOPPED, it will be killed.

Dv::Util::Process::Process ( const Process & ) [private]

Member Function Documentation

int Dv::Util::Process::start ( ) throw (std::runtime_error, std::logic_error)

Start up a new process.

Returns:: pid iff the process is running; 0 in the child process if the process is not running a command

Exceptions:

	std::runtime_error	if `fork()` failed.
	std::runtime_error	if `execl()` failed.
	std::logic_error	if the process is already running

If the process command is not empty, it will be executed using

   /bin/sh -c exec command

Example:

   Dv::Util::Process proc("ping www.bla.com");
   proc.start();

If the process command is empty, a fork() will be executed and the function will return false in the child process. This supports code such as the following.
```
   Dv::Util::Process p;
   if (! p.start())
     return f(...); // in the child
   p.wait(); // in the parent
```
See also:
Dv::Util::Process::Process

Reimplemented in Dv::Util::iopstream.

pid_t Dv::Util::Process::pid ( ) const [inline]

Returns:: process id of this process

Definition at line 95 of file process.h.

References pid_.

const std::string& Dv::Util::Process::command ( ) const [inline]

Returns:: command executed by this process

Definition at line 98 of file process.h.

References command_.

int Dv::Util::Process::exit_status ( ) const [inline]

Returns:: exit status (-1..255) of a process that terminated normally (i.e. was not signaled).

Warning:: If the process did not return normally or is still running, NO_EXIT_STATUS will be returned.

Definition at line 105 of file process.h.

References exit_status_.

int Dv::Util::Process::signaled ( ) const [inline]

Returns:: signal that killed a process.; -1 if the process returned normally or is still running,

Definition at line 110 of file process.h.

References signal_.

bool Dv::Util::Process::killed ( ) const

Returns:: true iff the process was killed using a SIGKILL signal

See also:: Dv::Util::Process:kill

bool Dv::Util::Process::stopped ( ) const

Returns:: true iff the process was stopped using a SIGSTOP signal

See also:: Process::stop

void Dv::Util::Process::signal	(	int	signal,
		const std::string &	error_message
	)			const throw (std::runtime_error)

Send a signal to this process.

Parameters:

	signal	to send
	error_message	to be used when throwing an exception

Exceptions:

std::runtime_error if kill(_,_) returns -1, e.g. if the process does not exist anymore because it has already been killed or waited upon.

void Dv::Util::Process::stop ( ) const throw (std::runtime_error)

Send a SIGSTOP signal to this process.

Exceptions:

std::runtime_error

inherited from Dv::Util::Process::signal

See also:: Dv::Util::Process::signal

void Dv::Util::Process::resume ( ) const throw (std::runtime_error)

Send a SIGCONT signal to this process.

Exceptions:

std::runtime_error

inherited from Dv::Util::Process::signal

See also:: Dv::Util::Process::signal

void Dv::Util::Process::kill ( ) const throw (std::runtime_error)

Send a SIGKILL signal to this process.

Exceptions:

std::runtime_error

inherited from Dv::Util::Process::signal

See also:: Dv::Util::Process::signal

Status Dv::Util::Process::wait ( ) const [inline]

Wait for process to finish.

Returns:: process status, one of FINISHED, DEAD, SIGNALED

See also:: Dv::Util::Process::wait(bool)

Definition at line 153 of file process.h.

References wait().

Referenced by status(), and wait().

Status Dv::Util::Process::status ( ) const [inline]

Return current process status.

Warning:: There may be some delay between sending a signal and the corresponding change of status.

See also:: Dv::Util::Process::wait(bool)

Definition at line 160 of file process.h.

References wait().

Status Dv::Util::Process::status ( int s ) const [protected]

Convert a status provided by waitpid to a Status, possibly setting exit_status_ and signal_.

Parameters:

s status provided by waitpid

Returns:: status of process

Status Dv::Util::Process::wait ( bool nohang ) const [protected]

Wrapper around waitpid.

Parameters:

nohang

if true, waitpid will not wait for the process to finish but just report the latest status change, if any.

Returns:: current process status

Process& Dv::Util::Process::operator= ( const Process & ) [private]

Member Data Documentation

pid_t Dv::Util::Process::pid_ [protected]

This is protected so that subclasses can set it.

Definition at line 181 of file process.h.

Referenced by pid().

std::string Dv::Util::Process::command_ [private]

Definition at line 185 of file process.h.

Referenced by command().

int Dv::Util::Process::exit_status_ [private]

Definition at line 186 of file process.h.

Referenced by exit_status().

int Dv::Util::Process::signal_ [private]

Definition at line 187 of file process.h.

Referenced by signaled().

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

process.h

Dv::Util::Process Class Reference

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation