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