Kea: isc::asiolink::ProcessSpawn Class Reference

| Kea 3.0.2-git

isc::asiolink::ProcessSpawn Class Reference

Utility class for spawning new processes. More...

`#include <process_spawn.h>`

Inheritance diagram for isc::asiolink::ProcessSpawn:
[legend]

## Public Types
enum | SpawnMode { ASYNC , SYNC }
| The spawn type. More...

## Public Member Functions
| ProcessSpawn (const SpawnMode mode, const std::string &executable, const ProcessArgs &args=ProcessArgs(), const ProcessEnvVars &vars=ProcessEnvVars(), const bool inherit_env=false)
| Constructor.
| ~ProcessSpawn ()=default
| Destructor.
void | clearState (const pid_t pid)
| Removes the status of the process with a specified PID.
std::string | getCommandLine () const
| Returns full command line, including arguments, for the process.
int | getExitStatus (const pid_t pid) const
| Returns exit status of the process.
bool | isAnyRunning () const
| Checks if any of the spawned processes is still running.
bool | isRunning (const pid_t pid) const
| Checks if the process is still running.
pid_t | spawn (bool dismiss=false)
| Spawn the new process.

## Static Public Member Functions
static isc::asiolink::IOServicePtr | getIOService ()
| Get the I/O service.
static void | setIOService (isc::asiolink::IOServicePtr io_service)
| Set the I/O service.

## 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 `execve` 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.

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.

Note
  The ProcessSpawn uses full path for the program to execute.

Definition at line 61 of file process_spawn.h.

## Member Enumeration Documentation

## ◆ SpawnMode

enum isc::asiolink::ProcessSpawn::SpawnMode

The spawn type.

Enumerator
ASYNC |
SYNC |

Definition at line 65 of file process_spawn.h.

## Constructor & Destructor Documentation

## ◆ ProcessSpawn()

isc::asiolink::ProcessSpawn::ProcessSpawn | ( | const SpawnMode | mode,
|  | const std::string & | executable,
|  | const ProcessArgs & | args = ProcessArgs(),
|  | const ProcessEnvVars & | vars = ProcessEnvVars(),
|  | const bool | inherit_env = false )

Constructor.

Parameters

  mode | specifies synchronous or asynchronous mode.
  executable | A full path to the program to be executed.
  args | Arguments for the program to be executed.
  vars | Environment variables for the program to be executed.
  inherit_env | whether the spawned process will inherit the environment before adding 'vars' on top.

Definition at line 483 of file process_spawn.cc.

## ◆ ~ProcessSpawn()

isc::asiolink::ProcessSpawn::~ProcessSpawn | ( |  | ) |
| default

Destructor.

## Member Function Documentation

## ◆ clearState()

void isc::asiolink::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 517 of file process_spawn.cc.

## ◆ getCommandLine()

std::string isc::asiolink::ProcessSpawn::getCommandLine | ( |  | ) | const

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

Definition at line 492 of file process_spawn.cc.

Referenced by isc::db::MySqlConnection::initializeSchema(), and isc::db::PgSqlConnection::initializeSchema().

## ◆ getExitStatus()

int isc::asiolink::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 512 of file process_spawn.cc.

Referenced by isc::db::MySqlConnection::initializeSchema(), and isc::db::PgSqlConnection::initializeSchema().

## ◆ getIOService()

isc::asiolink::IOServicePtr isc::asiolink::ProcessSpawn::getIOService | ( |  | ) |
| inlinestatic

Get the I/O service.

Returns
  the I/O service.

Definition at line 152 of file process_spawn.h.

Referenced by isc::asiolink::ProcessSpawnImpl::spawn().

## ◆ isAnyRunning()

bool isc::asiolink::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 507 of file process_spawn.cc.

## ◆ isRunning()

bool isc::asiolink::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 502 of file process_spawn.cc.

Referenced by isc::db::MySqlConnection::initializeSchema(), and isc::db::PgSqlConnection::initializeSchema().

## ◆ setIOService()

void isc::asiolink::ProcessSpawn::setIOService | ( | isc::asiolink::IOServicePtr | io_service | ) |
| inlinestatic

Set the I/O service.

Parameters

  io_service | the I/O service.

Definition at line 159 of file process_spawn.h.

Referenced by isc::dhcp::ControlledDhcpv4Srv::ControlledDhcpv4Srv(), and isc::dhcp::ControlledDhcpv6Srv::ControlledDhcpv6Srv().

## ◆ spawn()

pid_t isc::asiolink::ProcessSpawn::spawn | ( | bool | dismiss = false | ) |

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.

Parameters

  dismiss | The flag which indicated if the process status can be disregarded.

Exceptions

  ProcessSpawnError | if forking a current process failed.

Definition at line 497 of file process_spawn.cc.

Referenced by isc::db::MySqlConnection::initializeSchema(), and isc::db::PgSqlConnection::initializeSchema().

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

- process_spawn.h
- process_spawn.cc