MediaWiki  master
PoolCounter.php
Go to the documentation of this file.
1 <?php
49 abstract class PoolCounter {
50  /* Return codes */
51  public const LOCKED = 1; /* Lock acquired */
52  public const RELEASED = 2; /* Lock released */
53  public const DONE = 3; /* Another worker did the work for you */
54 
55  public const ERROR = -1; /* Indeterminate error */
56  public const NOT_LOCKED = -2; /* Called release() with no lock held */
57  public const QUEUE_FULL = -3; /* There are already maxqueue workers on this lock */
58  public const TIMEOUT = -4; /* Timeout exceeded */
59  public const LOCK_HELD = -5; /* Cannot acquire another lock while you have one lock held */
60 
62  protected $key;
64  protected $workers;
71  protected $slots = 0;
73  protected $maxqueue;
75  protected $timeout;
76 
80  private $isMightWaitKey;
84  private static $acquiredMightWaitKey = 0;
85 
89  private $fastStale;
90 
96  public function __construct( array $conf, string $type, string $key ) {
97  $this->workers = $conf['workers'];
98  $this->maxqueue = $conf['maxqueue'];
99  $this->timeout = $conf['timeout'];
100  if ( isset( $conf['slots'] ) ) {
101  $this->slots = $conf['slots'];
102  }
103  $this->fastStale = $conf['fastStale'] ?? false;
104 
105  if ( $this->slots ) {
106  $key = $this->hashKeyIntoSlots( $type, $key, $this->slots );
107  }
108 
109  $this->key = $key;
110  $this->isMightWaitKey = !preg_match( '/^nowait:/', $this->key );
111  }
112 
116  public function getKey() {
117  return $this->key;
118  }
119 
127  abstract public function acquireForMe( $timeout = null );
128 
137  abstract public function acquireForAnyone( $timeout = null );
138 
146  abstract public function release();
147 
153  final protected function precheckAcquire() {
154  if ( $this->isMightWaitKey ) {
155  if ( self::$acquiredMightWaitKey ) {
156  /*
157  * The poolcounter itself is quite happy to allow you to wait
158  * on another lock while you have a lock you waited on already
159  * but we think that it is unlikely to be a good idea. So we
160  * made it an error. If you are _really_ _really_ sure it is a
161  * good idea then feel free to implement an unsafe flag or
162  * something.
163  */
164  return Status::newFatal( 'poolcounter-usage-error',
165  'You may only aquire a single non-nowait lock.' );
166  }
167  } elseif ( $this->timeout !== 0 ) {
168  return Status::newFatal( 'poolcounter-usage-error',
169  'Locks starting in nowait: must have 0 timeout.' );
170  }
171  return Status::newGood();
172  }
173 
178  final protected function onAcquire() {
179  self::$acquiredMightWaitKey |= $this->isMightWaitKey;
180  }
181 
186  final protected function onRelease() {
187  self::$acquiredMightWaitKey &= !$this->isMightWaitKey;
188  }
189 
202  protected function hashKeyIntoSlots( $type, $key, $slots ) {
203  return $type . ':' . ( hexdec( substr( sha1( $key ), 0, 4 ) ) % $slots );
204  }
205 
212  public function isFastStaleEnabled() {
213  return $this->fastStale;
214  }
215 }
Semaphore semantics to restrict how many workers may concurrently perform a task.
Definition: PoolCounter.php:49
const QUEUE_FULL
Definition: PoolCounter.php:57
int $workers
Maximum number of workers working on tasks with the same key simultaneously.
Definition: PoolCounter.php:64
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:51
onAcquire()
Update any lock tracking information when the lock is acquired.
const TIMEOUT
Definition: PoolCounter.php:58
__construct(array $conf, string $type, string $key)
Definition: PoolCounter.php:96
int $maxqueue
If this number of workers are already working/waiting, fail instead of wait.
Definition: PoolCounter.php:73
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:62
const RELEASED
Definition: PoolCounter.php:52
int $slots
Maximum number of workers working on this task type, regardless of key.
Definition: PoolCounter.php:71
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.
acquireForMe( $timeout=null)
I want to do this task and I need to do it myself.
const NOT_LOCKED
Definition: PoolCounter.php:56
int $timeout
Maximum time in seconds to wait for the lock.
Definition: PoolCounter.php:75
const LOCK_HELD
Definition: PoolCounter.php:59
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