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