src/support/syscall.h

   1 // -*- C++ -*-
   2 #include <sys/types.h>
   3
   4 #include "LString.h"
   5
   6 #ifdef __GNUG__
   7 #pragma interface
   8 #endif
   9
  10 /**
  11   This class can be used to start child processes.
  12
  13   An instance of the class represents a child process.
  14   You should use this class if you need to start an external program in LyX.
  15   If you wish, you can have a callback function executed when the process
  16   finishes.
  17   You can chose between three kinds of child processes:
  18   1) System processes, which are initiated with the "system" call,
  19      where the main thread waits for the system call to return.
  20   2) Wait for child process, which are forked, but the main thread waits for
  21      the child to end.
  22   3) Don't wait, which are forked, but the main thread is not stopped.
  23      The process can be considered a background process.
  24      A timer will make sure that any callback function is called when
  25      the child process ends.
  26
  27   Notice that any callback associated with a process is called whatever
  28   the kind of child process.
  29   */
  30 class Systemcalls {
  31 public:
  32         ///
  33         enum Starttype {
  34                 /// Uses system() which uses /bin/sh
  35                 System,
  36                 /// Uses system() which uses /bin/sh
  37                 SystemDontWait,
  38                 /// Uses fork() and execvp()
  39                 Wait,
  40                 /// Uses fork() and execvp()
  41                 DontWait
  42         };
  43
  44         /// Callback function gets commandline and return value from child
  45         typedef void (*Callbackfct)(string cmd, int retval);
  46
  47         ///
  48         Systemcalls();
  49
  50         /** Generate instance and start child process.
  51             The string "what" contains a commandline with arguments separated
  52             by spaces.
  53             When the requested program finishes, the callback-function is
  54             called with the commandline and the return value from the program.
  55             The instance is automatically added to a timer check if starttype
  56             is DontWait (i.e. background execution). When a background child
  57             finishes, the timer check will automatically call the callback
  58             function.
  59         */
  60         Systemcalls(Starttype how, string const & what, Callbackfct call = 0);
  61
  62         ///
  63         ~Systemcalls();
  64
  65         /** Start childprocess. "what" contains a command at system level.
  66             This is for reuse of the Systemcalls instance.
  67         */
  68         int startscript(Starttype how, string const & what,
  69                         Callbackfct call = 0);
  70
  71         /** gets PID of childprocess.
  72             Used by timer
  73         */
  74         pid_t getpid() { return pid; }
  75
  76         /// Start callback
  77         void callback() { if (cbk) cbk(command, retval); }
  78
  79         /** Set return value. Used by timer */
  80         void setRetValue(int r) { retval = r; }
  81
  82         /** Kill child prematurely.
  83             First, a SIGHUP is sent to the child.
  84             If that does not end the child process within "tolerance"
  85             seconds, the SIGKILL signal is sent to the child.
  86             When the child is dead, the callback is called.
  87         */
  88         void kill(int tolerance = 5);
  89
  90 private:
  91         /// Type of execution: system, wait for child or background
  92         Starttype start;
  93
  94         /// Callback function
  95         Callbackfct cbk;
  96
  97         /// Commmand line
  98         string command;
  99
 100         /// Process ID of child
 101         pid_t pid;
 102
 103         /// Return value from child
 104         int retval;
 105
 106         ///
 107         int startscript();
 108
 109         ///
 110         pid_t fork();
 111
 112         /// Wait for child process to finish. Updates returncode from child.
 113         void waitForChild();
 114 };