# AgentWatcher Class Reference

Abstract base class for watching agent processes. More...

Inherited by HelperAgentWatcher, and LoggingAgentWatcher.

List of all members.

## Public Member Functions

virtual void | sendStartupInfo (MessageChannel &channel)=0
| Send the started agent process's startup information over the given channel, to the starter process.
virtual const char * | name () const =0
| Returns the name of the agent that this class is watching.
virtual pid_t | start ()
| Starts the agent process.
virtual void | startWatching ()
| Start watching the agent process.
virtual bool | forceShutdown ()
| Force the agent process to shut down.
string | getErrorMessage () const
| If the watcher thread has encountered an error, then the error message will be stored here.
string | getErrorBacktrace () const
| The error backtrace, if applicable.
const FileDescriptor | getFeedbackFd () const
| Returns the agent process feedback fd, or -1 if the agent process hasn't been started yet.

## Protected Member Functions

virtual string | getExeFilename () const =0
| Returns the filename of the agent process's executable.
virtual void | execProgram () const
| This method is to exec() the agent with the right arguments.
virtual void | sendStartupArguments (pid_t pid, FileDescriptor &fd)=0
| This method is to send startup arguments to the agent process through the given file descriptor, which is the agent process's feedback fd.
virtual bool | processStartupInfo (pid_t pid, FileDescriptor &fd, const vector< string > &args)=0
| This method is to process the startup info that the agent process has sent back.

## Static Protected Member Functions

static void | killAndWait (pid_t pid)
| Kill a process with SIGKILL, and attempt to kill its children too.
static int | timedWaitPid (pid_t pid, int *status, unsigned long long timeout)
| Behaves like `waitpid(pid, status, WNOHANG)`, but waits at most timeout miliseconds for the process to exit.

## Protected Attributes

pid_t | pid
| PID of the process we're watching.
string | threadExceptionMessage
| If the watcher thread threw an uncaught exception then its information will be stored here so that the main thread can check whether a watcher encountered an error.
FileDescriptor | feedbackFd
| The agent process's feedback fd.
boost::mutex | lock
| Lock for protecting the exchange of data between the main thread and the watcher thread.

## Detailed Description

Abstract base class for watching agent processes.

## Member Function Documentation

virtual void AgentWatcher::execProgram | ( |  | ) | const`[inline, protected, virtual]`

This method is to exec() the agent with the right arguments.

It is called from within a forked child process, so don't do any dynamic memory allocations in here. It must also not throw any exceptions. It must also preserve the value of errno after exec() is called.

virtual bool AgentWatcher::forceShutdown | ( |  | ) | `[inline, virtual]`

Force the agent process to shut down.

Returns true if it was shut down, or false if it wasn't started.

string AgentWatcher::getErrorMessage | ( |  | ) | const`[inline]`

If the watcher thread has encountered an error, then the error message will be stored here.

If the error message is empty then it means everything is still OK.

virtual string AgentWatcher::getExeFilename | ( |  | ) | const`[protected, pure virtual]`

Returns the filename of the agent process's executable.

This method may be called in a forked child process and may therefore not allocate memory.

const FileDescriptor AgentWatcher::getFeedbackFd | ( |  | ) | const`[inline]`

Returns the agent process feedback fd, or -1 if the agent process hasn't been started yet.

Can be used to check whether this agent process has exited without using waitpid().

static void AgentWatcher::killAndWait | ( | pid_t | pid | ) | `[inline, static, protected]`

Kill a process with SIGKILL, and attempt to kill its children too.

Then wait until it has quit.

virtual const char* AgentWatcher::name | ( |  | ) | const`[pure virtual]`

Returns the name of the agent that this class is watching.

virtual bool AgentWatcher::processStartupInfo | ( | pid_t | pid,
|  | FileDescriptor & | fd,
|  | const vector< string > & | args |
| ) |  |  | `[protected, pure virtual]`

This method is to process the startup info that the agent process has sent back.

May throw arbitrary exceptions.

virtual void AgentWatcher::sendStartupArguments | ( | pid_t | pid,
|  | FileDescriptor & | fd |
| ) |  |  | `[protected, pure virtual]`

This method is to send startup arguments to the agent process through the given file descriptor, which is the agent process's feedback fd.

May throw arbitrary exceptions.

virtual void AgentWatcher::sendStartupInfo | ( | MessageChannel & | channel | ) | `[pure virtual]`

Send the started agent process's startup information over the given channel, to the starter process.

May throw arbitrary exceptions.

Precondition:
  start() has been called and succeeded.

virtual pid_t AgentWatcher::start | ( |  | ) | `[inline, virtual]`

Starts the agent process.

May throw arbitrary exceptions.

virtual void AgentWatcher::startWatching | ( |  | ) | `[inline, virtual]`

Start watching the agent process.

Precondition:
  start() has been called and succeeded.
  This watcher isn't already watching.

Exceptions:

  | RuntimeException | If a precondition failed.
  | thread_interrupted |
  | thread_resource_error |

## Member Data Documentation

FileDescriptor AgentWatcher::feedbackFd`[protected]`

The agent process's feedback fd.

pid_t AgentWatcher::pid`[protected]`

PID of the process we're watching.

0 if no process is started at this time.

string AgentWatcher::threadExceptionMessage`[protected]`

If the watcher thread threw an uncaught exception then its information will be stored here so that the main thread can check whether a watcher encountered an error.

These are empty strings if everything is OK.

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

- Watchdog.cpp