src/support/forkedcontr.C

   1 /**
   2  * \file forkedcontr.C
   3  * This file is part of LyX, the document processor.
   4  * Licence details can be found in the file COPYING.
   5  *
   6  * \author Asger Alstrup Nielsen
   7  * \author Angus Leeming
   8  *
   9  * Full author contact details are available in file CREDITS.
  10  *
  11  * A class for the control of child processes launched using
  12  * fork() and execvp().
  13  */
  14
  15 #include <config.h>
  16
  17 #include "support/forkedcontr.h"
  18 #include "support/forkedcall.h"
  19
  20 #include "debug.h"
  21
  22 #include <boost/bind.hpp>
  23 #include <boost/iterator/indirect_iterator.hpp>
  24
  25 #include <cerrno>
  26 #include <cstdlib>
  27 #include <unistd.h>
  28 #include <sys/wait.h>
  29
  30 using boost::bind;
  31
  32 using std::endl;
  33 using std::equal_to;
  34 using std::find_if;
  35
  36 using std::string;
  37 using std::vector;
  38
  39 #ifndef CXX_GLOBAL_CSTD
  40 using std::signal;
  41 using std::strerror;
  42 #endif
  43
  44
  45 namespace lyx {
  46 namespace support {
  47
  48 /* The forkedcall controller code handles finished child processes in a
  49    two-stage process.
  50
  51    1. It uses the SIGCHLD signal emitted by the system when the child process
  52       finishes to reap the resulting zombie. The handler routine also
  53       updates an internal list of completed children.
  54    2. The signals associated with these completed children are then emitted
  55       as part of the main LyX event loop.
  56
  57    The guiding philosophy is that zombies are a global resource that should
  58    be reaped as soon as possible whereas an internal list of dead children
  59    is not. Indeed, to emit the signals within the asynchronous handler
  60    routine would result in unsafe code.
  61
  62    The signal handler is guaranteed to be safe even though it may not be
  63    atomic:
  64
  65    int completed_child_status;
  66    sig_atomic_t completed_child_pid;
  67
  68    extern "C"
  69    void child_handler(int)
  70    {
  71      // Clean up the child process.
  72      completed_child_pid = wait(&completed_child_status);
  73    }
  74
  75    (See the signals tutorial at http://tinyurl.com/3h82w.)
  76
  77    It's safe because:
  78    1. wait(2) is guaranteed to be async-safe.
  79    2. child_handler handles only SIGCHLD signals so all subsequent
  80       SIGCHLD signals are blocked from entering the handler until the
  81       existing signal is processed.
  82
  83    This handler performs 'half' of the necessary clean up after a
  84    completed child process. It prevents us leaving a stream of zombies
  85    behind but does not go on to tell the main LyX program to finish the
  86    clean-up by emitting the stored signal. That would most definitely
  87    not be safe.
  88
  89    The only problem with the above is that the global stores
  90    completed_child_status, completed_child_pid may be overwritten before
  91    the clean-up is completed in the main loop.
  92
  93    However, the code in child_handler can be extended to fill an array of
  94    completed processes. Everything remains safe so long as no 'unsafe'
  95    functions are called. (See the list of async-safe functions at
  96    http://tinyurl.com/3h82w.)
  97
  98    struct child_data {
  99      pid_t pid;
 100      int status;
 101    };
 102
 103    // This variable may need to be resized in the main program
 104    // as and when a new process is forked. This resizing must be
 105    // protected with sigprocmask
 106    std::vector<child_data> reaped_children;
 107    sig_atomic_t current_child = -1;
 108
 109    extern "C"
 110    void child_handler(int)
 111    {
 112      child_data & store = reaped_children[++current_child];
 113      // Clean up the child process.
 114      store.pid = wait(&store.status);
 115    }
 116
 117    That is, we build up a list of completed children in anticipation of
 118    the main loop then looping over this list and invoking any associated
 119    callbacks etc. The nice thing is that the main loop needs only to
 120    check the value of 'current_child':
 121
 122    if (current_child != -1)
 123      handleCompletedProcesses();
 124
 125    handleCompletedProcesses now loops over only those child processes
 126    that have completed (ie, those stored in reaped_children). It blocks
 127    any subsequent SIGCHLD signal whilst it does so:
 128
 129    // Used to block SIGCHLD signals.
 130    sigset_t newMask, oldMask;
 131
 132    ForkedcallsController::ForkedcallsController()
 133    {
 134      reaped_children.resize(50);
 135      signal(SIGCHLD, child_handler);
 136
 137      sigemptyset(&oldMask);
 138      sigemptyset(&newMask);
 139      sigaddset(&newMask, SIGCHLD);
 140    }
 141
 142    void ForkedcallsController::handleCompletedProcesses()
 143    {
 144      if (current_child == -1)
 145        return;
 146
 147      // Block the SIGCHLD signal.
 148      sigprocmask(SIG_BLOCK, &newMask, &oldMask);
 149
 150      for (int i = 0; i != 1+current_child; ++i) {
 151        child_data & store = reaped_children[i];
 152        // Go on to handle the child process
 153        ...
 154      }
 155
 156      // Unblock the SIGCHLD signal and restore the old mask.
 157      sigprocmask(SIG_SETMASK, &oldMask, 0);
 158    }
 159
 160    Voilà! An efficient, elegant and *safe* mechanism to handle child processes.
 161 */
 162
 163 namespace {
 164
 165 extern "C"
 166 void child_handler(int)
 167 {
 168         ForkedcallsController & fcc = ForkedcallsController::get();
 169
 170         // Be safe
 171         typedef vector<ForkedcallsController::Data>::size_type size_type;
 172         if (size_type(fcc.current_child + 1) >= fcc.reaped_children.size())
 173                 return;
 174
 175         ForkedcallsController::Data & store =
 176                 fcc.reaped_children[++fcc.current_child];
 177         // Clean up the child process.
 178         store.pid = wait(&store.status);
 179 }
 180
 181 } // namespace anon
 182
 183
 184 // Ensure, that only one controller exists inside process
 185 ForkedcallsController & ForkedcallsController::get()
 186 {
 187         static ForkedcallsController singleton;
 188         return singleton;
 189 }
 190
 191
 192 ForkedcallsController::ForkedcallsController()
 193         : reaped_children(50), current_child(-1)
 194 {
 195         signal(SIGCHLD, child_handler);
 196
 197         sigemptyset(&oldMask);
 198         sigemptyset(&newMask);
 199         sigaddset(&newMask, SIGCHLD);
 200 }
 201
 202
 203 // open question: should we stop childs here?
 204 // Asger says no: I like to have my xdvi open after closing LyX. Maybe
 205 // I want to print or something.
 206 ForkedcallsController::~ForkedcallsController()
 207 {
 208         signal(SIGCHLD, SIG_DFL);
 209 }
 210
 211
 212 void ForkedcallsController::addCall(ForkedProcess const & newcall)
 213 {
 214         forkedCalls.push_back(newcall.clone());
 215
 216         if (forkedCalls.size() > reaped_children.size()) {
 217                 // Block the SIGCHLD signal.
 218                 sigprocmask(SIG_BLOCK, &newMask, &oldMask);
 219
 220                 reaped_children.resize(2*reaped_children.size());
 221
 222                 // Unblock the SIGCHLD signal and restore the old mask.
 223                 sigprocmask(SIG_SETMASK, &oldMask, 0);
 224         }
 225 }
 226
 227
 228 ForkedcallsController::iterator
 229  ForkedcallsController::find_pid(pid_t pid)
 230 {
 231         return find_if(forkedCalls.begin(), forkedCalls.end(),
 232                        bind(equal_to<pid_t>(),
 233                             bind(&Forkedcall::pid, _1),
 234                             pid));
 235 }
 236
 237
 238 // Kill the process prematurely and remove it from the list
 239 // within tolerance secs
 240 void ForkedcallsController::kill(pid_t pid, int tolerance)
 241 {
 242         ListType::iterator it = find_pid(pid);
 243         if (it == forkedCalls.end())
 244                 return;
 245
 246         (*it)->kill(tolerance);
 247         forkedCalls.erase(it);
 248 }
 249
 250
 251 // Check the list of dead children and emit any associated signals.
 252 void ForkedcallsController::handleCompletedProcesses()
 253 {
 254         if (current_child == -1)
 255                 return;
 256
 257         // Block the SIGCHLD signal.
 258         sigprocmask(SIG_BLOCK, &newMask, &oldMask);
 259
 260         for (int i = 0; i != 1 + current_child; ++i) {
 261                 Data & store = reaped_children[i];
 262
 263                 if (store.pid == -1) {
 264                         // Might happen perfectly innocently, eg as a result
 265                         // of the system (3) call.
 266                         if (errno)
 267                                 lyxerr << "LyX: Error waiting for child: "
 268                                        << strerror(errno) << endl;
 269                         continue;
 270                 }
 271
 272                 ListType::iterator it = find_pid(store.pid);
 273                 if (it == forkedCalls.end())
 274                         // Eg, child was run in blocking mode
 275                         continue;
 276
 277                 ListType::value_type child = (*it);
 278                 bool remove_it = false;
 279
 280                 if (WIFEXITED(store.status)) {
 281                         // Ok, the return value goes into retval.
 282                         child->setRetValue(WEXITSTATUS(store.status));
 283                         remove_it = true;
 284
 285                 } else if (WIFSIGNALED(store.status)) {
 286                         // Child died, so pretend it returned 1
 287                         child->setRetValue(1);
 288                         remove_it = true;
 289
 290                 } else if (WIFSTOPPED(store.status)) {
 291                         lyxerr << "LyX: Child (pid: " << store.pid
 292                                << ") stopped on signal "
 293                                << WSTOPSIG(store.status)
 294                                << ". Waiting for child to finish." << endl;
 295
 296                 } else {
 297                         lyxerr << "LyX: Something rotten happened while "
 298                                << "waiting for child " << store.pid << endl;
 299
 300                         // Child died, so pretend it returned 1
 301                         child->setRetValue(1);
 302                         remove_it = true;
 303                 }
 304
 305                 if (remove_it) {
 306                         child->emitSignal();
 307                         forkedCalls.erase(it);
 308                 }
 309         }
 310
 311         // Reset the counter
 312         current_child = -1;
 313
 314         // Unblock the SIGCHLD signal and restore the old mask.
 315         sigprocmask(SIG_SETMASK, &oldMask, 0);
 316 }
 317
 318 } // namespace support
 319 } // namespace lyx