includes/ForkController.php

   1 <?php
   2
   3 /**
   4  * Class for managing forking command line scripts.
   5  * Currently just does forking and process control, but it could easily be extended
   6  * to provide IPC and job dispatch.
   7  *
   8  * This class requires the posix and pcntl extensions.
   9  *
  10  * @ingroup Maintenance
  11  */
  12 class ForkController {
  13         var $children = array();
  14         var $termReceived = false;
  15         var $flags = 0, $procsToStart = 0;
  16
  17         static $restartableSignals = array(
  18                 SIGFPE,
  19                 SIGILL,
  20                 SIGSEGV,
  21                 SIGBUS,
  22                 SIGABRT,
  23                 SIGSYS,
  24                 SIGPIPE,
  25                 SIGXCPU,
  26                 SIGXFSZ,
  27         );
  28
  29         /**
  30          * Pass this flag to __construct() to cause the class to automatically restart
  31          * workers that exit with non-zero exit status or a signal such as SIGSEGV.
  32          */
  33         const RESTART_ON_ERROR = 1;
  34
  35         public function __construct( $numProcs, $flags = 0 ) {
  36                 if ( php_sapi_name() != 'cli' ) {
  37                         throw new MWException( "ForkController cannot be used from the web." );
  38                 }
  39                 $this->procsToStart = $numProcs;
  40                 $this->flags = $flags;
  41         }
  42
  43         /**
  44          * Start the child processes.
  45          *
  46          * This should only be called from the command line. It should be called
  47          * as early as possible during execution.
  48          *
  49          * This will return 'child' in the child processes. In the parent process,
  50          * it will run until all the child processes exit or a TERM signal is
  51          * received. It will then return 'done'.
  52          * @return string
  53          */
  54         public function start() {
  55                 // Trap SIGTERM
  56                 pcntl_signal( SIGTERM, array( $this, 'handleTermSignal' ), false );
  57
  58                 do {
  59                         // Start child processes
  60                         if ( $this->procsToStart ) {
  61                                 if ( $this->forkWorkers( $this->procsToStart ) == 'child' ) {
  62                                         return 'child';
  63                                 }
  64                                 $this->procsToStart = 0;
  65                         }
  66
  67                         // Check child status
  68                         $status = false;
  69                         $deadPid = pcntl_wait( $status );
  70
  71                         if ( $deadPid > 0 ) {
  72                                 // Respond to child process termination
  73                                 unset( $this->children[$deadPid] );
  74                                 if ( $this->flags & self::RESTART_ON_ERROR ) {
  75                                         if ( pcntl_wifsignaled( $status ) ) {
  76                                                 // Restart if the signal was abnormal termination
  77                                                 // Don't restart if it was deliberately killed
  78                                                 $signal = pcntl_wtermsig( $status );
  79                                                 if ( in_array( $signal, self::$restartableSignals ) ) {
  80                                                         echo "Worker exited with signal $signal, restarting\n";
  81                                                         $this->procsToStart++;
  82                                                 }
  83                                         } elseif ( pcntl_wifexited( $status ) ) {
  84                                                 // Restart on non-zero exit status
  85                                                 $exitStatus = pcntl_wexitstatus( $status );
  86                                                 if ( $exitStatus != 0 ) {
  87                                                         echo "Worker exited with status $exitStatus, restarting\n";
  88                                                         $this->procsToStart++;
  89                                                 } else {
  90                                                         echo "Worker exited normally\n";
  91                                                 }
  92                                         }
  93                                 }
  94                                 // Throttle restarts
  95                                 if ( $this->procsToStart ) {
  96                                         usleep( 500000 );
  97                                 }
  98                         }
  99
 100                         // Run signal handlers
 101                         if ( function_exists( 'pcntl_signal_dispatch' ) ) {
 102                                 pcntl_signal_dispatch();
 103                         } else {
 104                                 declare (ticks=1) { $status = $status; }
 105                         }
 106                         // Respond to TERM signal
 107                         if ( $this->termReceived ) {
 108                                 foreach ( $this->children as $childPid => $unused ) {
 109                                         posix_kill( $childPid, SIGTERM );
 110                                 }
 111                                 $this->termReceived = false;
 112                         }
 113                 } while ( count( $this->children ) );
 114                 pcntl_signal( SIGTERM, SIG_DFL );
 115                 return 'done';
 116         }
 117
 118         protected function prepareEnvironment() {
 119                 global $wgMemc;
 120                 // Don't share DB, storage, or memcached connections
 121                 wfGetLBFactory()->destroyInstance();
 122                 FileBackendGroup::destroySingleton();
 123                 ObjectCache::clear();
 124                 $wgMemc = null;
 125         }
 126
 127         /**
 128          * Fork a number of worker processes.
 129          *
 130          * @return string
 131          */
 132         protected function forkWorkers( $numProcs ) {
 133                 $this->prepareEnvironment();
 134
 135                 // Create the child processes
 136                 for ( $i = 0; $i < $numProcs; $i++ ) {
 137                         // Do the fork
 138                         $pid = pcntl_fork();
 139                         if ( $pid === -1 || $pid === false ) {
 140                                 echo "Error creating child processes\n";
 141                                 exit( 1 );
 142                         }
 143
 144                         if ( !$pid ) {
 145                                 $this->initChild();
 146                                 return 'child';
 147                         } else {
 148                                 // This is the parent process
 149                                 $this->children[$pid] = true;
 150                         }
 151                 }
 152
 153                 return 'parent';
 154         }
 155
 156         protected function initChild() {
 157                 global $wgMemc, $wgMainCacheType;
 158                 $wgMemc = wfGetCache( $wgMainCacheType );
 159                 $this->children = null;
 160                 pcntl_signal( SIGTERM, SIG_DFL );
 161         }
 162
 163         protected function handleTermSignal( $signal ) {
 164                 $this->termReceived = true;
 165         }
 166 }