blocxx
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

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.
 
- Protected Member Functions inherited from BLOCXX_NAMESPACE::IntrusiveCountableBase
 IntrusiveCountableBase ()
 
 IntrusiveCountableBase (const IntrusiveCountableBase &)
 
IntrusiveCountableBaseoperator= (const IntrusiveCountableBase &)
 
virtual ~IntrusiveCountableBase ()
 

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

◆ 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

◆ Process() [1/4]

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.

◆ Process() [2/4]

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.

◆ Process() [3/4]

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.

◆ ~Process()

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, m_impl, m_pid, m_status, BLOCXX_NAMESPACE::Timeout::relative(), BLOCXX_NAMESPACE::Process::Status::terminated(), and waitCloseTerm().

◆ Process() [4/4]

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

Copying not allowed (private)

Member Function Documentation

◆ err()

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.

◆ getCurProcessId()

ProcId BLOCXX_NAMESPACE::Process::getCurProcessId ( )
private

Definition at line 682 of file Process.cpp.

Referenced by waitCloseTerm().

◆ in()

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.

◆ killWait()

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

◆ operator=()

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

Assignment not allowed (private)

◆ out()

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.

◆ pid()

ProcId BLOCXX_NAMESPACE::Process::pid ( ) const

Process ID for the child process.

Definition at line 418 of file Process.cpp.

References m_pid.

◆ processStatus()

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, BLOCXX_NAMESPACE::ProcessImpl::pollStatus(), and BLOCXX_NAMESPACE::Process::Status::terminated().

Referenced by killWait(), and waitCloseTerm().

◆ release()

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.

◆ terminatesWithin()

◆ waitCloseTerm() [1/2]

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(), and terminatesWithin().

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

◆ waitCloseTerm() [2/2]

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().

Member Data Documentation

◆ m_err

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_err
private

Definition at line 288 of file Process.hpp.

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

◆ m_impl

ProcessImplRef BLOCXX_NAMESPACE::Process::m_impl
private

Definition at line 285 of file Process.hpp.

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

◆ m_in

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_in
private

Definition at line 286 of file Process.hpp.

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

◆ m_out

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_out
private

Definition at line 287 of file Process.hpp.

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

◆ m_pid

ProcId BLOCXX_NAMESPACE::Process::m_pid
private

◆ m_status


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