MediaWiki  master
PoolCounter.php
Go to the documentation of this file.
1 <?php
23 use Wikimedia\ObjectFactory\ObjectFactory;
24 
50 abstract class PoolCounter {
51  /* Return codes */
52  public const LOCKED = 1; /* Lock acquired */
53  public const RELEASED = 2; /* Lock released */
54  public const DONE = 3; /* Another worker did the work for you */
55 
56  public const ERROR = -1; /* Indeterminate error */
57  public const NOT_LOCKED = -2; /* Called release() with no lock held */
58  public const QUEUE_FULL = -3; /* There are already maxqueue workers on this lock */
59  public const TIMEOUT = -4; /* Timeout exceeded */
60  public const LOCK_HELD = -5; /* Cannot acquire another lock while you have one lock held */
61 
63  protected $key;
65  protected $workers;
72  protected $slots = 0;
74  protected $maxqueue;
76  protected $timeout;
77 
81  private $isMightWaitKey;
85  private static $acquiredMightWaitKey = 0;
86 
90  private $fastStale;
91 
97  protected function __construct( array $conf, string $type, string $key ) {
98  $this->workers = $conf['workers'];
99  $this->maxqueue = $conf['maxqueue'];
100  $this->timeout = $conf['timeout'];
101  if ( isset( $conf['slots'] ) ) {
102  $this->slots = $conf['slots'];
103  }
104  $this->fastStale = $conf['fastStale'] ?? false;
105 
106  if ( $this->slots ) {
107  $key = $this->hashKeyIntoSlots( $type, $key, $this->slots );
108  }
109 
110  $this->key = $key;
111  $this->isMightWaitKey = !preg_match( '/^nowait:/', $this->key );
112  }
113 
122  public static function factory( string $type, string $key ) {
123  $poolCounterConf = MediaWikiServices::getInstance()->getMainConfig()
124  ->get( MainConfigNames::PoolCounterConf );
125  if ( !isset( $poolCounterConf[$type] ) ) {
126  return new PoolCounterNull;
127  }
128  $conf = $poolCounterConf[$type];
129 
131  $poolCounter = ObjectFactory::getObjectFromSpec(
132  $conf,
133  [
134  'extraArgs' => [ $conf, $type, $key ],
135  'assertClass' => self::class
136  ]
137  );
138 
139  return $poolCounter;
140  }
141 
145  public function getKey() {
146  return $this->key;
147  }
148 
156  abstract public function acquireForMe( $timeout = null );
157 
166  abstract public function acquireForAnyone( $timeout = null );
167 
175  abstract public function release();
176 
182  final protected function precheckAcquire() {
183  if ( $this->isMightWaitKey ) {
184  if ( self::$acquiredMightWaitKey ) {
185  /*
186  * The poolcounter itself is quite happy to allow you to wait
187  * on another lock while you have a lock you waited on already
188  * but we think that it is unlikely to be a good idea. So we
189  * made it an error. If you are _really_ _really_ sure it is a
190  * good idea then feel free to implement an unsafe flag or
191  * something.
192  */
193  return Status::newFatal( 'poolcounter-usage-error',
194  'You may only aquire a single non-nowait lock.' );
195  }
196  } elseif ( $this->timeout !== 0 ) {
197  return Status::newFatal( 'poolcounter-usage-error',
198  'Locks starting in nowait: must have 0 timeout.' );
199  }
200  return Status::newGood();
201  }
202 
207  final protected function onAcquire() {
208  self::$acquiredMightWaitKey |= $this->isMightWaitKey;
209  }
210 
215  final protected function onRelease() {
216  self::$acquiredMightWaitKey &= !$this->isMightWaitKey;
217  }
218 
231  protected function hashKeyIntoSlots( $type, $key, $slots ) {
232  return $type . ':' . ( hexdec( substr( sha1( $key ), 0, 4 ) ) % $slots );
233  }
234 
241  public function isFastStaleEnabled() {
242  return $this->fastStale;
243  }
244 }
A class containing constants representing the names of configuration variables.
Service locator for MediaWiki core services.
A default PoolCounter, which provides no locking.
Semaphore semantics to restrict how many workers may concurrently perform a task.
Definition: PoolCounter.php:50
const QUEUE_FULL
Definition: PoolCounter.php:58
int $workers
Maximum number of workers working on tasks with the same key simultaneously.
Definition: PoolCounter.php:65
acquireForAnyone( $timeout=null)
I want to do this task, but if anyone else does it instead, it's also fine for me.
const LOCKED
Definition: PoolCounter.php:52
onAcquire()
Update any lock tracking information when the lock is acquired.
const TIMEOUT
Definition: PoolCounter.php:59
__construct(array $conf, string $type, string $key)
Definition: PoolCounter.php:97
int $maxqueue
If this number of workers are already working/waiting, fail instead of wait.
Definition: PoolCounter.php:74
isFastStaleEnabled()
Is fast stale mode (T250248) enabled? This may be overridden by the PoolCounterWork subclass.
string $key
All workers with the same key share the lock.
Definition: PoolCounter.php:63
const RELEASED
Definition: PoolCounter.php:53
int $slots
Maximum number of workers working on this task type, regardless of key.
Definition: PoolCounter.php:72
hashKeyIntoSlots( $type, $key, $slots)
Given a key (any string) and the number of lots, returns a slot key (a prefix with a suffix integer f...
release()
I have successfully finished my task.
precheckAcquire()
Checks that the lock request is sensible.
static factory(string $type, string $key)
Create a Pool counter.
acquireForMe( $timeout=null)
I want to do this task and I need to do it myself.
const NOT_LOCKED
Definition: PoolCounter.php:57
int $timeout
Maximum time in seconds to wait for the lock.
Definition: PoolCounter.php:76
const LOCK_HELD
Definition: PoolCounter.php:60
onRelease()
Update any lock tracking information when the lock is released.
static newFatal( $message,... $parameters)
Factory function for fatal errors.
Definition: StatusValue.php:73
static newGood( $value=null)
Factory function for good results.
Definition: StatusValue.php:85