Code Coverage
 
Lines
Functions and Methods
Classes and Traits
Total
38.71% covered (danger)
38.71%
12 / 31
22.22% covered (danger)
22.22%
2 / 9
 CRAP
0.00% covered (danger)
0.00%
0 / 1
PoolCounter
40.00% covered (danger)
40.00%
12 / 30
22.22% covered (danger)
22.22%
2 / 9
 56.34
0.00% covered (danger)
0.00%
0 / 1
 __construct
100.00% covered (success)
100.00%
11 / 11
100.00% covered (success)
100.00%
1 / 1
 3
 getKey
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 acquireForMe
n/a
0 / 0
n/a
0 / 0
 0
 acquireForAnyone
n/a
0 / 0
n/a
0 / 0
 0
 release
n/a
0 / 0
n/a
0 / 0
 0
 precheckAcquire
0.00% covered (danger)
0.00%
0 / 12
0.00% covered (danger)
0.00%
0 / 1
 20
 onAcquire
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 onRelease
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 hashKeyIntoSlots
100.00% covered (success)
100.00%
1 / 1
100.00% covered (success)
100.00%
1 / 1
 1
 isFastStaleEnabled
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 setLogger
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
 getLogger
0.00% covered (danger)
0.00%
0 / 1
0.00% covered (danger)
0.00%
0 / 1
 2
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
21namespace MediaWiki\PoolCounter;
22
23use MediaWiki\Status\Status;
24use Psr\Log\LoggerAwareInterface;
25use Psr\Log\LoggerInterface;
26use 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 */
56abstract 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 */
248class_alias( PoolCounter::class, 'PoolCounter' );