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

#include <Process.hpp>

Inheritance diagram for BLOCXX_NAMESPACE::Process:

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. More...

virtual	~Process ()
	If `release` has been called on this object, does nothing. More...

UnnamedPipeRef	in () const
	Stdin for the child process. More...

UnnamedPipeRef	out () const
	Stdout for the child process. More...

UnnamedPipeRef	err () const
	Stderr for the child process. More...

ProcId	pid () const
	Process ID for the child process. More...

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. More...

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. More...

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. More...

Protected Member Functions inherited from BLOCXX_NAMESPACE::IntrusiveCountableBase
	IntrusiveCountableBase ()

	IntrusiveCountableBase (const IntrusiveCountableBase &)

IntrusiveCountableBase &	operator= (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) More...

void	operator= (Process const &)
	Assignment not allowed (private) More...

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 91 of file Process.hpp.

Member Enumeration Documentation

◆ ETerminationSelectionFlag

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 239 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 356 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 369 of file Process.cpp.

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

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

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

◆ ~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 393 of file Process.cpp.

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

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

◆ getCurProcessId()

ProcId BLOCXX_NAMESPACE::Process::getCurProcessId ( )

private

Definition at line 713 of file Process.cpp.

◆ in()

UnnamedPipeRef BLOCXX_NAMESPACE::Process::in ( ) const

Stdin for the child process.

The default timeout is set to 10 minutes.

Definition at line 434 of file Process.cpp.

◆ killWait()

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

private

Definition at line 691 of file Process.cpp.

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

◆ pid()

ProcId BLOCXX_NAMESPACE::Process::pid ( ) const

Process ID for the child process.

Definition at line 449 of file Process.cpp.

References m_pid.

Referenced by BLOCXX_NAMESPACE::Process::Status::toString().

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

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

References m_impl, m_pid, m_status, and BLOCXX_NAMESPACE::ProcessImpl::pollStatus().

◆ terminatesWithin()

bool BLOCXX_NAMESPACE::Process::terminatesWithin ( const Timeout & wait_time )

private

Definition at line 561 of file Process.cpp.

◆ 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:

If wait_initial.getRelative() > 0, waits until wait_initial expires for the process to terminate on its own.
If wait_close.getRelative() > 0, closes the input and output FileHandles and then waits until wait_close expires for the process to die.
If wait_term.getRelative() > 0, sends process a SIGTERM signal and waits until wait_term expires for it to die.
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 480 of file Process.cpp.

Referenced by err(), 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:

If wait_initial > 0, waits wait_initial seconds for the process to terminate on its own.
If wait_close > 0, closes the input and output FileHandles and then waits until wait_close seconds have passed for the process to die.
If wait_term > 0, sends process a SIGTERM signal and waits until wait_term seconds have passed for it to die.
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 475 of file Process.cpp.

Member Data Documentation

◆ m_err

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_err

private

Definition at line 318 of file Process.hpp.

◆ m_impl

ProcessImplRef BLOCXX_NAMESPACE::Process::m_impl

private

Definition at line 315 of file Process.hpp.

Referenced by Process(), and release().

◆ m_in

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_in

private

Definition at line 316 of file Process.hpp.

◆ m_out

UnnamedPipeRef BLOCXX_NAMESPACE::Process::m_out

private

Definition at line 317 of file Process.hpp.

◆ m_pid

ProcId BLOCXX_NAMESPACE::Process::m_pid

private

Definition at line 319 of file Process.hpp.

Referenced by pid(), Process(), and release().

◆ m_status

Status BLOCXX_NAMESPACE::Process::m_status

private

Definition at line 320 of file Process.hpp.

Referenced by BLOCXX_NAMESPACE::Process::Status::exitStatus(), BLOCXX_NAMESPACE::Process::Status::exitTerminated(), Process(), release(), BLOCXX_NAMESPACE::Process::Status::running(), BLOCXX_NAMESPACE::Process::Status::Status(), and BLOCXX_NAMESPACE::Process::Status::terminated().

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

Classes

Public Types

Public Member Functions

Protected Member Functions

Private Member Functions

Private Attributes

Detailed Description

Member Enumeration Documentation

◆ ETerminationSelectionFlag

Constructor & Destructor Documentation

◆ Process() [1/4]

◆ Process() [2/4]

◆ Process() [3/4]

◆ ~Process()

◆ Process() [4/4]

Member Function Documentation

◆ err()

◆ getCurProcessId()

◆ in()

◆ killWait()

◆ operator=()

◆ out()

◆ pid()

◆ processStatus()

◆ release()

◆ terminatesWithin()

◆ waitCloseTerm() [1/2]

◆ waitCloseTerm() [2/2]

Member Data Documentation

◆ m_err

◆ m_impl

◆ m_in

◆ m_out

◆ m_pid

◆ m_status