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