3 * Provides of semaphore semantics for restricting the number
4 * of workers that may be concurrently performing the same task.
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 * http://www.gnu.org/copyleft/gpl.html
25 * Class for dealing with PoolCounters using class members
27 abstract class PoolCounterWork
{
29 protected $type = 'generic';
31 protected $cacheable = false; // does this override getCachedWork() ?
32 /** @var PoolCounter */
36 * @param string $type The class of actions to limit concurrency for (task type)
37 * @param string $key Key that identifies the queue this work is placed on
39 public function __construct( $type, $key ) {
41 $this->poolCounter
= PoolCounter
::factory( $type, $key );
45 * Actually perform the work, caching it if needed
46 * @return mixed Work result or false
48 abstract public function doWork();
51 * Retrieve the work from cache
52 * @return mixed Work result or false
54 public function getCachedWork() {
59 * A work not so good (eg. expired one) but better than an error
61 * @return mixed Work result or false
63 public function fallback() {
68 * Do something with the error, like showing it to the user.
70 * @param Status $status
74 public function error( $status ) {
81 * @param Status $status
84 public function logError( $status ) {
85 $key = $this->poolCounter
->getKey();
87 wfDebugLog( 'poolcounter', "Pool key '$key' ({$this->type}): "
88 . $status->getMessage()->inLanguage( 'en' )->useDatabase( false )->text() );
92 * Get the result of the work (whatever it is), or the result of the error() function.
93 * This returns the result of the first applicable method that returns a non-false value,
94 * where the methods are checked in the following order:
95 * - a) doWork() : Applies if the work is exclusive or no another process
96 * is doing it, and on the condition that either this process
97 * successfully entered the pool or the pool counter is down.
98 * - b) doCachedWork() : Applies if the work is cacheable and this blocked on another
99 * process which finished the work.
100 * - c) fallback() : Applies for all remaining cases.
101 * If these all fall through (by returning false), then the result of error() is returned.
103 * @param bool $skipcache
106 public function execute( $skipcache = false ) {
107 if ( $this->cacheable
&& !$skipcache ) {
108 $status = $this->poolCounter
->acquireForAnyone();
110 $status = $this->poolCounter
->acquireForMe();
113 if ( !$status->isOK() ) {
114 // Respond gracefully to complete server breakage: just log it and do the work
115 $this->logError( $status );
116 return $this->doWork();
119 switch ( $status->value
) {
120 case PoolCounter
::LOCK_HELD
:
121 // Better to ignore nesting pool counter limits than to fail.
122 // Assume that the outer pool limiting is reasonable enough.
124 case PoolCounter
::LOCKED
:
125 $result = $this->doWork();
126 $this->poolCounter
->release();
129 case PoolCounter
::DONE
:
130 $result = $this->getCachedWork();
131 if ( $result === false ) {
132 /* That someone else work didn't serve us.
133 * Acquire the lock for me
135 return $this->execute( true );
139 case PoolCounter
::QUEUE_FULL
:
140 case PoolCounter
::TIMEOUT
:
141 $result = $this->fallback();
143 if ( $result !== false ) {
148 /* These two cases should never be hit... */
149 case PoolCounter
::ERROR
:
152 PoolCounter
::QUEUE_FULL
=> 'pool-queuefull',
153 PoolCounter
::TIMEOUT
=> 'pool-timeout' ];
155 $status = Status
::newFatal( $errors[$status->value
] ??
'pool-errorunknown' );
156 $this->logError( $status );
157 return $this->error( $status );