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