Utility class for spawning new processes. More...

#include <process_spawn.h>

Inheritance diagram for isc::util::ProcessSpawn:

Public Member Functions
	ProcessSpawn (const std::string &executable, const ProcessArgs &args=ProcessArgs())
	Constructor. More...

	~ProcessSpawn ()
	Destructor. More...

void	clearState (const pid_t pid)
	Removes the status of the process with a specified PID. More...

std::string	getCommandLine () const
	Returns full command line, including arguments, for the process. More...

int	getExitStatus (const pid_t pid) const
	Returns exit status of the process. More...

bool	isAnyRunning () const
	Checks if any of the spawned processes is still running. More...

bool	isRunning (const pid_t pid) const
	Checks if the process is still running. More...

pid_t	spawn ()
	Spawn the new process. More...

Detailed Description

Utility class for spawning new processes.

This class is used to spawn new process by Kea. It forks the current process and then uses the execvp function to execute the specified binary with parameters. The ProcessSpawn installs the handler for the SIGCHLD signal, which is executed when the child process ends. The handler checks the exit code returned by the process and records it. The exit code can be retrieved by the caller using the ProcessSpawn::getExitStatus method.

Warning: Only one instance of the ProcessSpawn class may exist at the given time. Creating additional instance would cause an attempt to register a new SIGCHLD signal handler and, as a consequence, the new ProcessSpawn object will fail to create.

This class is made noncopyable so that we don't have attempts to make multiple copies of an object. This avoid problems with multiple copies of objects for a single global resource such as the SIGCHLD signal handler. In addition making it noncopyable keeps the static check code from flagging the lack of a copy constructor as an issue.

Todo:: The SIGCHLD handling logic should be moved to the SignalSet class so as multiple instances of the ProcessSpawn use the same SIGCHLD signal handler.

Definition at line 60 of file process_spawn.h.

Constructor & Destructor Documentation

◆ ProcessSpawn()

isc::util::ProcessSpawn::ProcessSpawn	(	const std::string &	executable,
		const ProcessArgs &	args = `ProcessArgs()`
	)

Constructor.

Parameters

executable	A path to the program to be executed.
args	Arguments for the program to be executed.

Definition at line 331 of file process_spawn.cc.

◆ ~ProcessSpawn()

isc::util::ProcessSpawn::~ProcessSpawn ( )

Destructor.

Definition at line 336 of file process_spawn.cc.

Member Function Documentation

◆ clearState()

void isc::util::ProcessSpawn::clearState ( const pid_t pid )

Removes the status of the process with a specified PID.

This method removes the status of the process with a specified PID. If the process is still running, the status is not removed and the exception is thrown.

Note ProcessSpawn::isRunning must be called and have returned false before using clearState(). And of course ProcessSpawn::getExitStatus should be called first, if there is some interest in the status.

Parameters

pid	A process pid.

Definition at line 366 of file process_spawn.cc.

References isc::util::ProcessSpawnImpl::clearState().

Here is the call graph for this function:

◆ getCommandLine()

std::string isc::util::ProcessSpawn::getCommandLine ( ) const

Returns full command line, including arguments, for the process.

Definition at line 341 of file process_spawn.cc.

References isc::util::ProcessSpawnImpl::getCommandLine().

Here is the call graph for this function:

◆ getExitStatus()

int isc::util::ProcessSpawn::getExitStatus ( const pid_t pid ) const

Returns exit status of the process.

If the process is still running, the previous status is returned or 0, if the process is being ran for the first time.

Note: ProcessSpawn::isRunning should be called and have returned false before using ProcessSpawn::getExitStatus.

Parameters

pid	ID of the child process for which exit status should be returned.

Returns: Exit code of the process.

Definition at line 361 of file process_spawn.cc.

References isc::util::ProcessSpawnImpl::getExitStatus().

Here is the call graph for this function:

◆ isAnyRunning()

bool isc::util::ProcessSpawn::isAnyRunning ( ) const

Checks if any of the spawned processes is still running.

Returns: true if at least one child process is still running.

Definition at line 356 of file process_spawn.cc.

References isc::util::ProcessSpawnImpl::isAnyRunning().

Here is the call graph for this function:

◆ isRunning()

bool isc::util::ProcessSpawn::isRunning ( const pid_t pid ) const

Checks if the process is still running.

Note that only a negative (false) result is reliable as the child process can exit between the time its state is checked and this function returns.

Parameters

pid	ID of the child processes for which state should be checked.

Returns: true if the child process is running, false otherwise.

Definition at line 351 of file process_spawn.cc.

References isc::util::ProcessSpawnImpl::isRunning().

Here is the call graph for this function:

◆ spawn()

pid_t isc::util::ProcessSpawn::spawn ( )

Spawn the new process.

This method forks the current process and executes the specified binary with arguments within the child process.

The child process will return EXIT_FAILURE if the method was unable to start the executable, e.g. as a result of insufficient permissions or when the executable does not exist. If the process ends successfully the EXIT_SUCCESS is returned.

Exceptions

ProcessSpawnError if forking a current process failed.

Definition at line 346 of file process_spawn.cc.

References isc::util::ProcessSpawnImpl::spawn().

Here is the call graph for this function:

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ProcessSpawn()

◆ ~ProcessSpawn()

Member Function Documentation

◆ clearState()

◆ getCommandLine()

◆ getExitStatus()

◆ isAnyRunning()

◆ isRunning()

◆ spawn()