Merge "Make sure images that don't have an explicit alignment get aligned right"
[mediawiki.git] / includes / poolcounter / PoolCounterWork.php
blob523e9e019474db07501a6adbea3ae1402c2d7b69
1 <?php
2 /**
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
21 * @file
24 /**
25 * Class for dealing with PoolCounters using class members
27 abstract class PoolCounterWork {
28 /** @var string */
29 protected $type = 'generic';
30 /** @var bool */
31 protected $cacheable = false; // does this override getCachedWork() ?
33 /**
34 * @param string $type The type of PoolCounter to use
35 * @param string $key Key that identifies the queue this work is placed on
37 public function __construct( $type, $key ) {
38 $this->type = $type;
39 $this->poolCounter = PoolCounter::factory( $type, $key );
42 /**
43 * Actually perform the work, caching it if needed
44 * @return mixed Work result or false
46 abstract public function doWork();
48 /**
49 * Retrieve the work from cache
50 * @return mixed Work result or false
52 public function getCachedWork() {
53 return false;
56 /**
57 * A work not so good (eg. expired one) but better than an error
58 * message.
59 * @return mixed Work result or false
61 public function fallback() {
62 return false;
65 /**
66 * Do something with the error, like showing it to the user.
67 * @return bool
69 public function error( $status ) {
70 return false;
73 /**
74 * Log an error
76 * @param Status $status
77 * @return void
79 public function logError( $status ) {
80 $key = $this->poolCounter->getKey();
82 wfDebugLog( 'poolcounter', "Pool key '$key' ({$this->type}): "
83 . $status->getMessage()->inLanguage( 'en' )->useDatabase( false )->text() );
86 /**
87 * Get the result of the work (whatever it is), or the result of the error() function.
88 * This returns the result of the first applicable method that returns a non-false value,
89 * where the methods are checked in the following order:
90 * - a) doWork() : Applies if the work is exclusive or no another process
91 * is doing it, and on the condition that either this process
92 * successfully entered the pool or the pool counter is down.
93 * - b) doCachedWork() : Applies if the work is cacheable and this blocked on another
94 * process which finished the work.
95 * - c) fallback() : Applies for all remaining cases.
96 * If these all fall through (by returning false), then the result of error() is returned.
98 * @param bool $skipcache
99 * @return mixed
101 public function execute( $skipcache = false ) {
102 if ( $this->cacheable && !$skipcache ) {
103 $status = $this->poolCounter->acquireForAnyone();
104 } else {
105 $status = $this->poolCounter->acquireForMe();
108 if ( !$status->isOK() ) {
109 // Respond gracefully to complete server breakage: just log it and do the work
110 $this->logError( $status );
111 return $this->doWork();
114 switch ( $status->value ) {
115 case PoolCounter::LOCKED:
116 $result = $this->doWork();
117 $this->poolCounter->release();
118 return $result;
120 case PoolCounter::DONE:
121 $result = $this->getCachedWork();
122 if ( $result === false ) {
123 /* That someone else work didn't serve us.
124 * Acquire the lock for me
126 return $this->execute( true );
128 return $result;
130 case PoolCounter::QUEUE_FULL:
131 case PoolCounter::TIMEOUT:
132 $result = $this->fallback();
134 if ( $result !== false ) {
135 return $result;
137 /* no break */
139 /* These two cases should never be hit... */
140 case PoolCounter::ERROR:
141 default:
142 $errors = array(
143 PoolCounter::QUEUE_FULL => 'pool-queuefull',
144 PoolCounter::TIMEOUT => 'pool-timeout' );
146 $status = Status::newFatal( isset( $errors[$status->value] )
147 ? $errors[$status->value]
148 : 'pool-errorunknown' );
149 $this->logError( $status );
150 return $this->error( $status );
156 * Convenience class for dealing with PoolCounters using callbacks
157 * @since 1.22
159 class PoolCounterWorkViaCallback extends PoolCounterWork {
160 /** @var callable */
161 protected $doWork;
162 /** @var callable|null */
163 protected $doCachedWork;
164 /** @var callable|null */
165 protected $fallback;
166 /** @var callable|null */
167 protected $error;
170 * Build a PoolCounterWork class from a type, key, and callback map.
172 * The callback map must at least have a callback for the 'doWork' method.
173 * Additionally, callbacks can be provided for the 'doCachedWork', 'fallback',
174 * and 'error' methods. Methods without callbacks will be no-ops that return false.
175 * If a 'doCachedWork' callback is provided, then execute() may wait for any prior
176 * process in the pool to finish and reuse its cached result.
178 * @param string $type
179 * @param string $key
180 * @param array $callbacks Map of callbacks
181 * @throws MWException
183 public function __construct( $type, $key, array $callbacks ) {
184 parent::__construct( $type, $key );
185 foreach ( array( 'doWork', 'doCachedWork', 'fallback', 'error' ) as $name ) {
186 if ( isset( $callbacks[$name] ) ) {
187 if ( !is_callable( $callbacks[$name] ) ) {
188 throw new MWException( "Invalid callback provided for '$name' function." );
190 $this->$name = $callbacks[$name];
193 if ( !isset( $this->doWork ) ) {
194 throw new MWException( "No callback provided for 'doWork' function." );
196 $this->cacheable = isset( $this->doCachedWork );
199 public function doWork() {
200 return call_user_func_array( $this->doWork, array() );
203 public function getCachedWork() {
204 if ( $this->doCachedWork ) {
205 return call_user_func_array( $this->doCachedWork, array() );
207 return false;
210 public function fallback() {
211 if ( $this->fallback ) {
212 return call_user_func_array( $this->fallback, array() );
214 return false;
217 public function error( $status ) {
218 if ( $this->error ) {
219 return call_user_func_array( $this->error, array( $status ) );
221 return false;