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

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.

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:

Generated by  doxygen 1.6.2