includes/poolcounter/PoolCounter.php

   1 <?php
   2 /**
   3  * This program is free software; you can redistribute it and/or modify
   4  * it under the terms of the GNU General Public License as published by
   5  * the Free Software Foundation; either version 2 of the License, or
   6  * (at your option) any later version.
   7  *
   8  * This program is distributed in the hope that it will be useful,
   9  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  10  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11  * GNU General Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along
  14  * with this program; if not, write to the Free Software Foundation, Inc.,
  15  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  16  * http://www.gnu.org/copyleft/gpl.html
  17  *
  18  * @file
  19  */
  20
  21 namespace MediaWiki\PoolCounter;
  22
  23 use MediaWiki\Status\Status;
  24 use Psr\Log\LoggerAwareInterface;
  25 use Psr\Log\LoggerInterface;
  26 use Psr\Log\NullLogger;
  27
  28 /**
  29  * Semaphore semantics to restrict how many workers may concurrently perform a task.
  30  *
  31  * When you have many workers (threads/servers) in service, and a
  32  * cached item expensive to produce expires, you may get several workers
  33  * computing the same expensive item at the same time.
  34  *
  35  * Given enough incoming requests and the item expiring quickly (non-cacheable,
  36  * or lots of edits or other invalidation events) that single task can end up
  37  * unfairly using most (or all) of the CPUs of the server cluster.
  38  * This is also known as "Michael Jackson effect", as this scenario happened on
  39  * the English Wikipedia in 2009 on the day Michael Jackson died.
  40  * See also <https://wikitech.wikimedia.org/wiki/Michael_Jackson_effect>.
  41  *
  42  * PoolCounter was created to provide semaphore semantics to restrict the number
  43  * of workers that may be concurrently performing a given task. Only one key
  44  * can be locked by any PoolCounter instance of a process, except for keys
  45  * that start with "nowait:". However, only non-blocking requests (timeout=0)
  46  * may be used with a "nowait:" key.
  47  *
  48  * By default PoolCounterNull is used, which provides no locking.
  49  * Install the poolcounterd service from
  50  * <https://gerrit.wikimedia.org/g/mediawiki/services/poolcounter> to
  51  * enable this feature.
  52  *
  53  * @since 1.16
  54  * @stable to extend
  55  */
  56 abstract class PoolCounter implements LoggerAwareInterface {
  57         /* Return codes */
  58         public const LOCKED = 1; /* Lock acquired */
  59         public const RELEASED = 2; /* Lock released */
  60         public const DONE = 3; /* Another worker did the work for you */
  61
  62         public const ERROR = -1; /* Indeterminate error */
  63         public const NOT_LOCKED = -2; /* Called release() with no lock held */
  64         public const QUEUE_FULL = -3; /* There are already maxqueue workers on this lock */
  65         public const TIMEOUT = -4; /* Timeout exceeded */
  66         public const LOCK_HELD = -5; /* Cannot acquire another lock while you have one lock held */
  67
  68         /** @var string All workers with the same key share the lock */
  69         protected $key;
  70         /** @var int Maximum number of workers working on tasks with the same key simultaneously */
  71         protected $workers;
  72         /**
  73          * Maximum number of workers working on this task type, regardless of key.
  74          * 0 means unlimited. Max allowed value is 65536.
  75          * The way the slot limit is enforced is overzealous - this option should be used with caution.
  76          * @var int
  77          */
  78         protected $slots = 0;
  79         /** @var int If this number of workers are already working/waiting, fail instead of wait */
  80         protected $maxqueue;
  81         /** @var int Maximum time in seconds to wait for the lock */
  82         protected $timeout;
  83         protected LoggerInterface $logger;
  84
  85         /**
  86          * @var bool Whether the key is a "might wait" key
  87          */
  88         private $isMightWaitKey;
  89         /**
  90          * @var int Whether this process holds a "might wait" lock key
  91          */
  92         private static $acquiredMightWaitKey = 0;
  93
  94         /**
  95          * @var bool Enable fast stale mode (T250248). This may be overridden by the work class.
  96          */
  97         private $fastStale;
  98
  99         /**
 100          * @param array $conf
 101          * @param string $type The class of actions to limit concurrency for (task type)
 102          * @param string $key
 103          */
 104         public function __construct( array $conf, string $type, string $key ) {
 105                 $this->workers = $conf['workers'];
 106                 $this->maxqueue = $conf['maxqueue'];
 107                 $this->timeout = $conf['timeout'];
 108                 if ( isset( $conf['slots'] ) ) {
 109                         $this->slots = $conf['slots'];
 110                 }
 111                 $this->fastStale = $conf['fastStale'] ?? false;
 112                 $this->logger = new NullLogger();
 113
 114                 if ( $this->slots ) {
 115                         $key = $this->hashKeyIntoSlots( $type, $key, $this->slots );
 116                 }
 117
 118                 $this->key = $key;
 119                 $this->isMightWaitKey = !preg_match( '/^nowait:/', $this->key );
 120         }
 121
 122         /**
 123          * @return string
 124          */
 125         public function getKey() {
 126                 return $this->key;
 127         }
 128
 129         /**
 130          * I want to do this task and I need to do it myself.
 131          *
 132          * @param int|null $timeout Wait timeout, or null to use value passed to
 133          *   the constructor
 134          * @return Status Value is one of Locked/Error
 135          */
 136         abstract public function acquireForMe( $timeout = null );
 137
 138         /**
 139          * I want to do this task, but if anyone else does it
 140          * instead, it's also fine for me. I will read its cached data.
 141          *
 142          * @param int|null $timeout Wait timeout, or null to use value passed to
 143          *   the constructor
 144          * @return Status Value is one of Locked/Done/Error
 145          */
 146         abstract public function acquireForAnyone( $timeout = null );
 147
 148         /**
 149          * I have successfully finished my task.
 150          * Lets another one grab the lock, and returns the workers
 151          * waiting on acquireForAnyone()
 152          *
 153          * @return Status Value is one of Released/NotLocked/Error
 154          */
 155         abstract public function release();
 156
 157         /**
 158          * Checks that the lock request is sensible.
 159          * @return Status good for sensible requests, fatal for the not so sensible
 160          * @since 1.25
 161          */
 162         final protected function precheckAcquire() {
 163                 if ( $this->isMightWaitKey ) {
 164                         if ( self::$acquiredMightWaitKey ) {
 165                                 /*
 166                                  * The poolcounter itself is quite happy to allow you to wait
 167                                  * on another lock while you have a lock you waited on already
 168                                  * but we think that it is unlikely to be a good idea.  So we
 169                                  * made it an error.  If you are _really_ _really_ sure it is a
 170                                  * good idea then feel free to implement an unsafe flag or
 171                                  * something.
 172                                  */
 173                                 return Status::newFatal(
 174                                         'poolcounter-usage-error',
 175                                         'You may only aquire a single non-nowait lock.'
 176                                 );
 177                         }
 178                 } elseif ( $this->timeout !== 0 ) {
 179                         return Status::newFatal(
 180                                 'poolcounter-usage-error',
 181                                 'Locks starting in nowait: must have 0 timeout.'
 182                         );
 183                 }
 184                 return Status::newGood();
 185         }
 186
 187         /**
 188          * Update any lock tracking information when the lock is acquired
 189          * @since 1.25
 190          */
 191         final protected function onAcquire() {
 192                 self::$acquiredMightWaitKey |= $this->isMightWaitKey;
 193         }
 194
 195         /**
 196          * Update any lock tracking information when the lock is released
 197          * @since 1.25
 198          */
 199         final protected function onRelease() {
 200                 self::$acquiredMightWaitKey &= !$this->isMightWaitKey;
 201         }
 202
 203         /**
 204          * Given a key (any string) and the number of lots, returns a slot key (a prefix with a suffix
 205          * integer from the [0..($slots-1)] range). This is used for a global limit on the number of
 206          * instances of a given type that can acquire a lock. The hashing is deterministic so that
 207          * PoolCounter::$workers is always an upper limit of how many instances with the same key
 208          * can acquire a lock.
 209          *
 210          * @param string $type The class of actions to limit concurrency for (task type)
 211          * @param string $key PoolCounter instance key (any string)
 212          * @param int $slots The number of slots (max allowed value is 65536)
 213          * @return string Slot key with the type and slot number
 214          */
 215         protected function hashKeyIntoSlots( $type, $key, $slots ) {
 216                 return $type . ':' . ( hexdec( substr( sha1( $key ), 0, 4 ) ) % $slots );
 217         }
 218
 219         /**
 220          * Is fast stale mode (T250248) enabled? This may be overridden by the
 221          * PoolCounterWork subclass.
 222          *
 223          * @return bool
 224          */
 225         public function isFastStaleEnabled() {
 226                 return $this->fastStale;
 227         }
 228
 229         /**
 230          * @since 1.42
 231          * @param LoggerInterface $logger
 232          * @return void
 233          */
 234         public function setLogger( LoggerInterface $logger ) {
 235                 $this->logger = $logger;
 236         }
 237
 238         /**
 239          * @internal For use in PoolCounterWork only
 240          * @return LoggerInterface
 241          */
 242         public function getLogger(): LoggerInterface {
 243                 return $this->logger;
 244         }
 245 }
 246
 247 /** @deprecated class alias since 1.42 */
 248 class_alias( PoolCounter::class, 'PoolCounter' );