blocxx
Classes | Public Types | Public Member Functions | Protected Member Functions | Private Member Functions | Private Attributes

BLOCXX_NAMESPACE::Process Class Reference

Class for communicating with and managing a child process. More...

#include <Process.hpp>

Inheritance diagram for BLOCXX_NAMESPACE::Process:
BLOCXX_NAMESPACE::IntrusiveCountableBase

List of all members.

Classes

class  Status
 Portable process status. More...

Public Types

enum  ETerminationSelectionFlag { E_TERMINATE_PROCESS_GROUP, E_TERMINATE_PROCESS_ONLY }

Public Member Functions

 Process (UnnamedPipeRef const &in, UnnamedPipeRef const &out, UnnamedPipeRef const &err, ProcId pid)
 Process (ProcId pid)
void release ()
 Releases ownership of the ProcId and UnnamedPipes held by this object.
virtual ~Process ()
 If release has been called on this object, does nothing.
UnnamedPipeRef in () const
 Stdin for the child process.
UnnamedPipeRef out () const
 Stdout for the child process.
UnnamedPipeRef err () const
 Stderr for the child process.
ProcId pid () const
 Process ID for the child process.
Status processStatus ()
void waitCloseTerm (const Timeout &wait_initial=Timeout::relative(5.0), const Timeout &wait_close=Timeout::relative(10.0), const Timeout &wait_term=Timeout::relative(15.0), ETerminationSelectionFlag terminationSelectionFlag=E_TERMINATE_PROCESS_GROUP)
 Waits for the child process to terminate, taking increasingly severe measures to ensure that this happens.
void waitCloseTerm (float wait_initial, float wait_close, float wait_term)
 Waits for the child process to terminate, taking increasingly severe measures to ensure that this happens.

Protected Member Functions

 Process (const ProcessImplRef &impl, UnnamedPipeRef const &in, UnnamedPipeRef const &out, UnnamedPipeRef const &err, ProcId pid)
 Constructor for derived classes that allow them to override the implementation.

Private Member Functions

bool terminatesWithin (const Timeout &wait_time)
ProcId getCurProcessId ()
bool killWait (const Timeout &wait_time, int sig, char const *signame, ETerminationSelectionFlag terminationSelectionFlag)
 Process (Process const &)
 Copying not allowed (private)
void operator= (Process const &)
 Assignment not allowed (private)

Private Attributes

ProcessImplRef m_impl
UnnamedPipeRef m_in
UnnamedPipeRef m_out
UnnamedPipeRef m_err
ProcId m_pid
Status m_status

Detailed Description

Class for communicating with and managing a child process.

Definition at line 61 of file Process.hpp.


Member Enumeration Documentation

Enumerator:
E_TERMINATE_PROCESS_GROUP 

The process and any descendent processes which are in the process group will be terminated.

E_TERMINATE_PROCESS_ONLY 

The process will be terminated.

Definition at line 209 of file Process.hpp.


Constructor & Destructor Documentation

BLOCXX_NAMESPACE::Process::Process ( UnnamedPipeRef const &  in,
UnnamedPipeRef const &  out,
UnnamedPipeRef const &  err,
ProcId  pid 
)
Precondition:
: pid is the process ID for a child process whose standard input is in, standard output is out, and standard error is err.

Definition at line 327 of file Process.cpp.

BLOCXX_NAMESPACE::Process::Process ( const ProcessImplRef impl,
UnnamedPipeRef const &  in,
UnnamedPipeRef const &  out,
UnnamedPipeRef const &  err,
ProcId  pid 
) [protected]

Constructor for derived classes that allow them to override the implementation.

This is necessary because destructors shouldn't call virtual functions (it's undefined behavior), so instead of this class having virtual functions, that is moved to ProcessImpl.

Precondition:
: pid is the process ID for a child process whose standard input is in, standard output is out, and standard error is err.

Definition at line 340 of file Process.cpp.

BLOCXX_NAMESPACE::Process::Process ( ProcId  pid)
Precondition:
: pid is the process ID for a child process.
Postcondition:
: in(), out(), and err() are all null.

Definition at line 354 of file Process.cpp.

BLOCXX_NAMESPACE::Process::~Process ( ) [virtual]

If release has been called on this object, does nothing.

Otherwise, closes pipes and waits for process to die, killing it if necessary,

Definition at line 364 of file Process.cpp.

BLOCXX_NAMESPACE::Process::Process ( Process const &  ) [private]

Copying not allowed (private)


Member Function Documentation

UnnamedPipeRef BLOCXX_NAMESPACE::Process::err ( ) const

Stderr for the child process.

The default timeout is set to 10 minutes.

Definition at line 415 of file Process.cpp.

ProcId BLOCXX_NAMESPACE::Process::getCurProcessId ( ) [private]

Definition at line 684 of file Process.cpp.

Referenced by waitCloseTerm().

UnnamedPipeRef BLOCXX_NAMESPACE::Process::in ( ) const

Stdin for the child process.

The default timeout is set to 10 minutes.

Definition at line 405 of file Process.cpp.

bool BLOCXX_NAMESPACE::Process::killWait ( const Timeout wait_time,
int  sig,
char const *  signame,
ETerminationSelectionFlag  terminationSelectionFlag 
) [private]

Definition at line 662 of file Process.cpp.

References BLOCXX_THROW_ERRNO_MSG, BLOCXX_NAMESPACE::Format::c_str(), m_pid, and processStatus().

Referenced by waitCloseTerm().

void BLOCXX_NAMESPACE::Process::operator= ( Process const &  ) [private]

Assignment not allowed (private)

UnnamedPipeRef BLOCXX_NAMESPACE::Process::out ( ) const

Stdout for the child process.

The default timeout is set to 10 minutes.

Definition at line 410 of file Process.cpp.

ProcId BLOCXX_NAMESPACE::Process::pid ( ) const

Process ID for the child process.

Definition at line 420 of file Process.cpp.

Process::Status BLOCXX_NAMESPACE::Process::processStatus ( )
Returns:
Status of child process.
Note:
Does not wait for child to terminate.
Exceptions:
ProcessErrorException

Definition at line 425 of file Process.cpp.

References m_impl, m_pid, and m_status.

Referenced by killWait(), and waitCloseTerm().

void BLOCXX_NAMESPACE::Process::release ( )

Releases ownership of the ProcId and UnnamedPipes held by this object.

Postcondition:
in(), out(), and err() are all null; pid() < 0; the dtor does nothing. Only the above-mentioned methods may be called on this object.

Definition at line 397 of file Process.cpp.

bool BLOCXX_NAMESPACE::Process::terminatesWithin ( const Timeout wait_time) [private]

Definition at line 532 of file Process.cpp.

Referenced by waitCloseTerm().

void BLOCXX_NAMESPACE::Process::waitCloseTerm ( float  wait_initial,
float  wait_close,
float  wait_term 
)

Waits for the child process to terminate, taking increasingly severe measures to ensure that this happens.

All times are measured from the start of the function. The following steps are taken in order until termination is detected:

  1. If wait_initial > 0, waits wait_initial seconds for the process to terminate on its own.
  2. If wait_close > 0, closes the input and output FileHandles and then waits until wait_close seconds have passed for the process to die.
  3. If wait_term > 0, sends process a SIGTERM signal and waits until wait_term seconds have passed for it to die.
  4. Sends the process a SIGKILL signal.

In steps 1-3 the function returns as soon as termination is detected. If this function is called a second time it is a no-op, because it immediately sees that the process has already terminated.

Note:
If wait_close <= 0 then the FileHandles are NOT closed, and if wait_term <= 0 then no SIGTERM signal is sent.
Exceptions:
ProcessErrorException

Definition at line 446 of file Process.cpp.

void BLOCXX_NAMESPACE::Process::waitCloseTerm ( const Timeout wait_initial = Timeout::relative(5.0),
const Timeout wait_close = Timeout::relative(10.0),
const Timeout wait_term = Timeout::relative(15.0),
ETerminationSelectionFlag  terminationSelectionFlag = E_TERMINATE_PROCESS_GROUP 
)

Waits for the child process to terminate, taking increasingly severe measures to ensure that this happens.

All timeouts are measured from the start of the function. The following steps are taken in order until termination is detected:

  1. If wait_initial.getRelative() > 0, waits until wait_initial expires for the process to terminate on its own.
  2. If wait_close.getRelative() > 0, closes the input and output FileHandles and then waits until wait_close expires for the process to die.
  3. If wait_term.getRelative() > 0, sends process a SIGTERM signal and waits until wait_term expires for it to die.
  4. Sends the process a SIGKILL signal.

In steps 1-3 the function returns as soon as termination is detected. If this function is called a second time it is a no-op, because it immediately sees that the process has already terminated.

Note:
If wait_close <= 0 then the FileHandles are NOT closed, and if wait_term <= 0 then no SIGTERM signal is sent.
Exceptions:
ProcessErrorException

Definition at line 451 of file Process.cpp.

References BLOCXX_NAMESPACE::TimeoutTimer::asAbsoluteTimeout(), BLOCXX_THROW, BLOCXX_NAMESPACE::Timeout::E_RELATIVE, getCurProcessId(), BLOCXX_NAMESPACE::Timeout::getRelative(), BLOCXX_NAMESPACE::Timeout::getType(), killWait(), m_err, m_in, m_out, m_pid, m_status, processStatus(), BLOCXX_NAMESPACE::Timeout::relative(), BLOCXX_NAMESPACE::Process::Status::terminated(), and terminatesWithin().


Member Data Documentation

Definition at line 288 of file Process.hpp.

Referenced by waitCloseTerm().

Definition at line 285 of file Process.hpp.

Referenced by processStatus().

Definition at line 286 of file Process.hpp.

Referenced by waitCloseTerm().

Definition at line 287 of file Process.hpp.

Referenced by waitCloseTerm().

Definition at line 289 of file Process.hpp.

Referenced by killWait(), processStatus(), and waitCloseTerm().

Definition at line 290 of file Process.hpp.

Referenced by processStatus(), and waitCloseTerm().


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