src/support/ForkedCalls.h

   1 // -*- C++ -*-
   2 /**
   3  * \file ForkedCalls.h
   4  * This file is part of LyX, the document processor.
   5  * Licence details can be found in the file COPYING.
   6  *
   7  * \author Asger Alstrup
   8  * \author Angus Leeming
   9  * \author Alfredo Braunstein
  10  *
  11  * Full author contact details are available in file CREDITS.
  12  */
  13
  14 #ifndef FORKEDCALLS_H
  15 #define FORKEDCALLS_H
  16
  17 #include <boost/shared_ptr.hpp>
  18 #include <boost/signal.hpp>
  19
  20 #ifdef HAVE_SYS_TYPES_H
  21 # include <sys/types.h>
  22 #endif
  23
  24 #include <string>
  25
  26 namespace lyx {
  27 namespace support {
  28
  29 class ForkedProcess {
  30 public:
  31         ///
  32         enum Starttype {
  33                 ///
  34                 Wait,
  35                 ///
  36                 DontWait
  37         };
  38
  39         ///
  40         ForkedProcess();
  41         ///
  42         virtual ~ForkedProcess() {}
  43         ///
  44         virtual boost::shared_ptr<ForkedProcess> clone() const = 0;
  45
  46         /** A SignalType signal can be emitted once the forked process
  47          *  has finished. It passes:
  48          *  the PID of the child and;
  49          *  the return value from the child.
  50          *
  51          *  We use a signal rather than simply a callback function so that
  52          *  we can return easily to C++ methods, rather than just globally
  53          *  accessible functions.
  54          */
  55         typedef boost::signal<void(pid_t, int)> SignalType;
  56
  57         /** The signal is connected in the calling routine to the desired
  58          *  slot. We pass a shared_ptr rather than a reference to the signal
  59          *  because it is eminently possible for the instance of the calling
  60          *  class (and hence the signal) to be destructed before the forked
  61          *  call is complete.
  62          *
  63          *  It doesn't matter if the slot disappears, SigC takes care of that.
  64          */
  65         typedef boost::shared_ptr<SignalType> SignalTypePtr;
  66
  67         /** Invoking the following methods makes sense only if the command
  68          *  is running asynchronously!
  69          */
  70
  71         /** gets the PID of the child process.
  72          *  Used by the timer.
  73          */
  74         pid_t pid() const { return pid_; }
  75
  76         /** Emit the signal.
  77          *  Used by the timer.
  78          */
  79         void emitSignal();
  80
  81         /** Set the return value of the child process.
  82          *  Used by the timer.
  83          */
  84         void setRetValue(int r) { retval_ = r; }
  85
  86         /// Returns the identifying command (for display in the GUI perhaps).
  87         std::string const & command() const { return command_; }
  88
  89         /// is the process running ?
  90         bool running() const;
  91
  92         /** Kill child prematurely.
  93          *  First, a SIGHUP is sent to the child.
  94          *  If that does not end the child process within "tolerance"
  95          *  seconds, the SIGKILL signal is sent to the child.
  96          *  When the child is dead, the callback is called.
  97          */
  98         void kill(int tolerance = 5);
  99
 100         /// Returns true if this is a child process
 101         static bool iAmAChild() { return IAmAChild; }
 102
 103 protected:
 104         /** Spawn the child process.
 105          *  Returns returncode from child.
 106          */
 107         int run(Starttype type);
 108
 109         /// implement our own version of fork()
 110         /// it just returns -1 if ::fork() is not defined
 111         /// otherwise, it forks and sets the global child-process
 112         /// boolean IAmAChild
 113         pid_t fork();
 114
 115         /// Callback function
 116         SignalTypePtr signal_;
 117
 118         /// identifying command (for display in the GUI perhaps).
 119         std::string command_;
 120
 121         /// Process ID of child
 122         pid_t pid_;
 123
 124         /// Return value from child
 125         int retval_;
 126 private:
 127         /// generate child in background
 128         virtual int generateChild() = 0;
 129
 130         ///
 131         static bool IAmAChild;
 132
 133         /// Wait for child process to finish. Updates returncode from child.
 134         int waitForChild();
 135 };
 136
 137
 138 /*
 139  * An instance of class ForkedCall represents a single child process.
 140  *
 141  * Class ForkedCall uses fork() and execvp() to lauch the child process.
 142  *
 143  * Once launched, control is returned immediately to the parent process
 144  * but a Signal can be emitted upon completion of the child.
 145  *
 146  * The child process is not killed when the ForkedCall instance goes out of
 147  * scope, but it can be killed by an explicit invocation of the kill() member
 148  * function.
 149  */
 150
 151 class ForkedCall : public ForkedProcess {
 152 public:
 153         ///
 154         virtual boost::shared_ptr<ForkedProcess> clone() const {
 155                 return boost::shared_ptr<ForkedProcess>(new ForkedCall(*this));
 156         }
 157
 158         /** Start the child process.
 159          *
 160          *  The command "what" is passed to execvp() for execution.
 161          *
 162          *  There are two startScript commands available. They differ in that
 163          *  the second receives a signal that is executed on completion of
 164          *  the command. This makes sense only for a command executed
 165          *  in the background, ie DontWait.
 166          *
 167          *  The other startscript command can be executed either blocking
 168          *  or non-blocking, but no signal will be emitted on finishing.
 169          */
 170         int startScript(Starttype, std::string const & what);
 171
 172         ///
 173         int startScript(std::string const & what, SignalTypePtr);
 174
 175 private:
 176         ///
 177         virtual int generateChild();
 178 };
 179
 180
 181 /**
 182  * This interfaces a queue of forked processes. In order not to
 183  * hose the system with multiple processes running simultaneously, you can
 184  * request the addition of your process to this queue and it will be
 185  * executed when its turn comes.
 186  *
 187  */
 188
 189 namespace ForkedCallQueue {
 190
 191 ForkedCall::SignalTypePtr add(std::string const & process);
 192 /// Query whether the queue is running a forked process now.
 193 bool running();
 194
 195 }
 196
 197
 198 /**
 199  * Control of child processes launched using fork() and execvp().
 200  */
 201
 202 namespace ForkedCallsController {
 203
 204 /// Add a new child process to the list of controlled processes.
 205 void addCall(ForkedProcess const &);
 206
 207 /** Those child processes that are found to have finished are removed
 208  *  from the list and their callback function is passed the final
 209  *  return state.
 210  */
 211 void handleCompletedProcesses();
 212
 213 /** Kill this process prematurely and remove it from the list.
 214  *  The process is killed within tolerance secs.
 215  *  See forkedcall.[Ch] for details.
 216  */
 217 void kill(pid_t, int tolerance = 5);
 218
 219 } // namespace ForkedCallsController
 220
 221
 222 #if defined(_WIN32)
 223 // a wrapper for GetLastError() and FormatMessage().
 224 std::string const getChildErrorMessage();
 225 #endif
 226
 227 } // namespace support
 228 } // namespace lyx
 229
 230 #endif // FORKEDCALLS_H