includes/PoolCounter.php

   1 <?php
   2 /**
   3  * Provides of semaphore semantics for restricting the number
   4  * of workers that may be concurrently performing the same task.
   5  *
   6  * This program is free software; you can redistribute it and/or modify
   7  * it under the terms of the GNU General Public License as published by
   8  * the Free Software Foundation; either version 2 of the License, or
   9  * (at your option) any later version.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  14  * GNU General Public License for more details.
  15  *
  16  * You should have received a copy of the GNU General Public License along
  17  * with this program; if not, write to the Free Software Foundation, Inc.,
  18  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  19  * http://www.gnu.org/copyleft/gpl.html
  20  *
  21  * @file
  22  */
  23
  24 /**
  25  *  When you have many workers (threads/servers) giving service, and a
  26  * cached item expensive to produce expires, you may get several workers
  27  * doing the job at the same time.
  28  *
  29  *  Given enough requests and the item expiring fast (non-cacheable,
  30  * lots of edits...) that single work can end up unfairly using most (all)
  31  * of the cpu of the pool. This is also known as 'Michael Jackson effect'
  32  * since this effect triggered on the english wikipedia on the day Michael
  33  * Jackson died, the biographical article got hit with several edits per
  34  * minutes and hundreds of read hits.
  35  *
  36  *  The PoolCounter provides semaphore semantics for restricting the number
  37  * of workers that may be concurrently performing such single task.
  38  *
  39  *  By default PoolCounter_Stub is used, which provides no locking. You
  40  * can get a useful one in the PoolCounter extension.
  41  */
  42 abstract class PoolCounter {
  43
  44         /* Return codes */
  45         const LOCKED   = 1; /* Lock acquired */
  46         const RELEASED = 2; /* Lock released */
  47         const DONE     = 3; /* Another worker did the work for you */
  48
  49         const ERROR      = -1; /* Indeterminate error */
  50         const NOT_LOCKED = -2; /* Called release() with no lock held */
  51         const QUEUE_FULL = -3; /* There are already maxqueue workers on this lock */
  52         const TIMEOUT    = -4; /* Timeout exceeded */
  53         const LOCK_HELD  = -5; /* Cannot acquire another lock while you have one lock held */
  54
  55         /**
  56          * I want to do this task and I need to do it myself.
  57          *
  58          * @return Locked/Error
  59          */
  60         abstract function acquireForMe();
  61
  62         /**
  63          * I want to do this task, but if anyone else does it
  64          * instead, it's also fine for me. I will read its cached data.
  65          *
  66          * @return Locked/Done/Error
  67          */
  68         abstract function acquireForAnyone();
  69
  70         /**
  71          * I have successfully finished my task.
  72          * Lets another one grab the lock, and returns the workers
  73          * waiting on acquireForAnyone()
  74          *
  75          * @return Released/NotLocked/Error
  76          */
  77         abstract function release();
  78
  79         /**
  80          *  $key: All workers with the same key share the lock.
  81          *  $workers: It wouldn't be a good idea to have more than this number of
  82          * workers doing the task simultaneously.
  83          *  $maxqueue: If this number of workers are already working/waiting,
  84          * fail instead of wait.
  85          *  $timeout: Maximum time in seconds to wait for the lock.
  86          */
  87         protected $key, $workers, $maxqueue, $timeout;
  88
  89         /**
  90          * Create a Pool counter. This should only be called from the PoolWorks.
  91          *
  92          * @param $type
  93          * @param $key
  94          *
  95          * @return PoolCounter
  96          */
  97         public static function factory( $type, $key ) {
  98                 global $wgPoolCounterConf;
  99                 if ( !isset( $wgPoolCounterConf[$type] ) ) {
 100                         return new PoolCounter_Stub;
 101                 }
 102                 $conf = $wgPoolCounterConf[$type];
 103                 $class = $conf['class'];
 104
 105                 return new $class( $conf, $type, $key );
 106         }
 107
 108         protected function __construct( $conf, $type, $key ) {
 109                 $this->key = $key;
 110                 $this->workers  = $conf['workers'];
 111                 $this->maxqueue = $conf['maxqueue'];
 112                 $this->timeout  = $conf['timeout'];
 113         }
 114 }
 115
 116 class PoolCounter_Stub extends PoolCounter {
 117
 118         /**
 119          * @return Status
 120          */
 121         function acquireForMe() {
 122                 return Status::newGood( PoolCounter::LOCKED );
 123         }
 124
 125         /**
 126          * @return Status
 127          */
 128         function acquireForAnyone() {
 129                 return Status::newGood( PoolCounter::LOCKED );
 130         }
 131
 132         /**
 133          * @return Status
 134          */
 135         function release() {
 136                 return Status::newGood( PoolCounter::RELEASED );
 137         }
 138
 139         public function __construct() {
 140                 /* No parameters needed */
 141         }
 142 }
 143
 144 /**
 145  * Handy class for dealing with PoolCounters using class members instead of callbacks.
 146  */
 147 abstract class PoolCounterWork {
 148         protected $cacheable = false; //Does this override getCachedWork() ?
 149
 150         /**
 151          * Actually perform the work, caching it if needed.
 152          */
 153         abstract function doWork();
 154
 155         /**
 156          * Retrieve the work from cache
 157          * @return mixed work result or false
 158          */
 159         function getCachedWork() {
 160                 return false;
 161         }
 162
 163         /**
 164          * A work not so good (eg. expired one) but better than an error
 165          * message.
 166          * @return mixed work result or false
 167          */
 168         function fallback() {
 169                 return false;
 170         }
 171
 172         /**
 173          * Do something with the error, like showing it to the user.
 174          * @return bool
 175          */
 176         function error( $status ) {
 177                 return false;
 178         }
 179
 180         /**
 181          * Log an error
 182          *
 183          * @param $status Status
 184          */
 185         function logError( $status ) {
 186                 wfDebugLog( 'poolcounter', $status->getWikiText() );
 187         }
 188
 189         /**
 190          * Get the result of the work (whatever it is), or false.
 191          * @param $skipcache bool
 192          * @return bool|mixed
 193          */
 194         function execute( $skipcache = false ) {
 195                 if ( $this->cacheable && !$skipcache ) {
 196                         $status = $this->poolCounter->acquireForAnyone();
 197                 } else {
 198                         $status = $this->poolCounter->acquireForMe();
 199                 }
 200
 201                 if ( !$status->isOK() ) {
 202                         // Respond gracefully to complete server breakage: just log it and do the work
 203                         $this->logError( $status );
 204                         return $this->doWork();
 205                 }
 206
 207                 switch ( $status->value ) {
 208                         case PoolCounter::LOCKED:
 209                                 $result = $this->doWork();
 210                                 $this->poolCounter->release();
 211                                 return $result;
 212
 213                         case PoolCounter::DONE:
 214                                 $result = $this->getCachedWork();
 215                                 if ( $result === false ) {
 216                                         /* That someone else work didn't serve us.
 217                                          * Acquire the lock for me
 218                                          */
 219                                         return $this->execute( true );
 220                                 }
 221                                 return $result;
 222
 223                         case PoolCounter::QUEUE_FULL:
 224                         case PoolCounter::TIMEOUT:
 225                                 $result = $this->fallback();
 226
 227                                 if ( $result !== false ) {
 228                                         return $result;
 229                                 }
 230                                 /* no break */
 231
 232                         /* These two cases should never be hit... */
 233                         case PoolCounter::ERROR:
 234                         default:
 235                                 $errors = array( PoolCounter::QUEUE_FULL => 'pool-queuefull', PoolCounter::TIMEOUT => 'pool-timeout' );
 236
 237                                 $status = Status::newFatal( isset( $errors[$status->value] ) ? $errors[$status->value] : 'pool-errorunknown' );
 238                                 $this->logError( $status );
 239                                 return $this->error( $status );
 240                 }
 241         }
 242
 243         function __construct( $type, $key ) {
 244                 $this->poolCounter = PoolCounter::factory( $type, $key );
 245         }
 246 }