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.

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

Classes

class  Status
 Portable process status. More...

Detailed Description

Class for communicating with and managing a child process.

Definition at line 61 of file Process.hpp.

Member Enumeration Documentation

enum BLOCXX_NAMESPACE::Process::ETerminationSelectionFlag

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 325 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 338 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 352 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 362 of file Process.cpp.

References BLOCXX_LOG_DEBUG, BLOCXX_NAMESPACE::COMPONENT_NAME, m_impl, m_pid, m_status, BLOCXX_NAMESPACE::Timeout::relative(), BLOCXX_NAMESPACE::Process::Status::terminated(), and waitCloseTerm().

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

Copying not allowed (private).

Member Function Documentation

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 395 of file Process.cpp.

References BLOCXX_INVALID_HANDLE, m_err, m_in, m_out, and m_pid.

UnnamedPipeRef BLOCXX_NAMESPACE::Process::in (  )  const

Stdin for the child process.

The default timeout is set to 10 minutes.

Definition at line 403 of file Process.cpp.

References m_in.

UnnamedPipeRef BLOCXX_NAMESPACE::Process::out (  )  const

Stdout for the child process.

The default timeout is set to 10 minutes.

Definition at line 408 of file Process.cpp.

References m_out.

UnnamedPipeRef BLOCXX_NAMESPACE::Process::err (  )  const

Stderr for the child process.

The default timeout is set to 10 minutes.

Definition at line 413 of file Process.cpp.

References m_err.

ProcId BLOCXX_NAMESPACE::Process::pid (  )  const

Process ID for the child process.

Definition at line 418 of file Process.cpp.

References m_pid.

Process::Status BLOCXX_NAMESPACE::Process::processStatus (  ) 

Returns:
Status of child process.
Note:
Does not wait for child to terminate.
Exceptions:
ProcessErrorException 

Definition at line 423 of file Process.cpp.

References m_impl, m_pid, m_status, and BLOCXX_NAMESPACE::Process::Status::terminated().

Referenced by killWait(), and waitCloseTerm().

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 449 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(), terminatesWithin(), and BLOCXX_NAMESPACE::upr_close().

Referenced by BLOCXX_NAMESPACE::handle_child_error(), waitCloseTerm(), and ~Process().

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 444 of file Process.cpp.

References BLOCXX_NAMESPACE::Timeout::relative(), and waitCloseTerm().

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

Definition at line 530 of file Process.cpp.

References BLOCXX_NAMESPACE::TimeoutTimer::expired(), BLOCXX_NAMESPACE::TimeoutTimer::loop(), m_impl, m_pid, m_status, BLOCXX_NAMESPACE::ThreadImpl::sleep(), and BLOCXX_NAMESPACE::Process::Status::terminated().

Referenced by killWait(), and waitCloseTerm().

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

Definition at line 682 of file Process.cpp.

Referenced by waitCloseTerm().

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

Definition at line 660 of file Process.cpp.

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

Referenced by waitCloseTerm().

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

Assignment not allowed (private).

Member Data Documentation

ProcessImplRef BLOCXX_NAMESPACE::Process::m_impl [private]

Definition at line 285 of file Process.hpp.

Referenced by killWait(), processStatus(), terminatesWithin(), and ~Process().

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_in [private]

Definition at line 286 of file Process.hpp.

Referenced by in(), release(), and waitCloseTerm().

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_out [private]

Definition at line 287 of file Process.hpp.

Referenced by out(), release(), and waitCloseTerm().

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_err [private]

Definition at line 288 of file Process.hpp.

Referenced by err(), release(), and waitCloseTerm().

ProcId BLOCXX_NAMESPACE::Process::m_pid [private]

Definition at line 289 of file Process.hpp.

Referenced by killWait(), pid(), processStatus(), release(), terminatesWithin(), waitCloseTerm(), and ~Process().

Status BLOCXX_NAMESPACE::Process::m_status [private]

Definition at line 290 of file Process.hpp.

Referenced by processStatus(), terminatesWithin(), waitCloseTerm(), and ~Process().

The documentation for this class was generated from the following files:
Generated on Wed Feb 25 19:05:08 2009 for blocxx by  doxygen 1.5.6