3 * Job queue code for federated queues.
5 * This program is free software; you can redistribute it and/or modify
6 * it under the terms of the GNU General Public License as published by
7 * the Free Software Foundation; either version 2 of the License, or
8 * (at your option) any later version.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License along
16 * with this program; if not, write to the Free Software Foundation, Inc.,
17 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
18 * http://www.gnu.org/copyleft/gpl.html
24 * Class to handle enqueueing and running of background jobs for federated queues
26 * This class allows for queues to be partitioned into smaller queues.
27 * A partition is defined by the configuration for a JobQueue instance.
28 * For example, one can set $wgJobTypeConf['refreshLinks'] to point to a
29 * JobQueueFederated instance, which itself would consist of three JobQueueRedis
30 * instances, each using their own redis server. This would allow for the jobs
31 * to be split (evenly or based on weights) across multiple servers if a single
32 * server becomes impractical or expensive. Different JobQueue classes can be mixed.
34 * The basic queue configuration (e.g. "order", "claimTTL") of a federated queue
35 * is inherited by the partition queues. Additional configuration defines what
36 * section each wiki is in, what partition queues each section uses (and their weight),
37 * and the JobQueue configuration for each partition. Some sections might only need a
38 * single queue partition, like the sections for groups of small wikis.
40 * If used for performance, then $wgMainCacheType should be set to memcached/redis.
41 * Note that "fifo" cannot be used for the ordering, since the data is distributed.
42 * One can still use "timestamp" instead, as in "roughly timestamp ordered". Also,
43 * queue classes used by this should ignore down servers (with TTL) to avoid slowness.
48 class JobQueueFederated
extends JobQueue
{
50 protected $partitionRing;
51 /** @var JobQueue[] (partition name => JobQueue) reverse sorted by weight */
52 protected $partitionQueues = [];
54 /** @var int Maximum number of partitions to try */
55 protected $maxPartitionsTry;
58 * @param array $params Possible keys:
59 * - sectionsByWiki : A map of wiki IDs to section names.
60 * Wikis will default to using the section "default".
61 * - partitionsBySection : Map of section names to maps of (partition name => weight).
62 * A section called 'default' must be defined if not all wikis
63 * have explicitly defined sections.
64 * - configByPartition : Map of queue partition names to configuration arrays.
65 * These configuration arrays are passed to JobQueue::factory().
66 * The options set here are overridden by those passed to this
67 * the federated queue itself (e.g. 'order' and 'claimTTL').
68 * - maxPartitionsTry : Maximum number of times to attempt job insertion using
69 * different partition queues. This improves availability
70 * during failure, at the cost of added latency and somewhat
71 * less reliable job de-duplication mechanisms.
74 protected function __construct( array $params ) {
75 parent
::__construct( $params );
76 $section = isset( $params['sectionsByWiki'][$this->wiki
] )
77 ?
$params['sectionsByWiki'][$this->wiki
]
79 if ( !isset( $params['partitionsBySection'][$section] ) ) {
80 throw new MWException( "No configuration for section '$section'." );
82 $this->maxPartitionsTry
= isset( $params['maxPartitionsTry'] )
83 ?
$params['maxPartitionsTry']
85 // Get the full partition map
86 $partitionMap = $params['partitionsBySection'][$section];
87 arsort( $partitionMap, SORT_NUMERIC
);
88 // Get the config to pass to merge into each partition queue config
89 $baseConfig = $params;
90 foreach ( [ 'class', 'sectionsByWiki', 'maxPartitionsTry',
91 'partitionsBySection', 'configByPartition', ] as $o
93 unset( $baseConfig[$o] ); // partition queue doesn't care about this
95 // The class handles all aggregator calls already
96 unset( $baseConfig['aggregator'] );
97 // Get the partition queue objects
98 foreach ( $partitionMap as $partition => $w ) {
99 if ( !isset( $params['configByPartition'][$partition] ) ) {
100 throw new MWException( "No configuration for partition '$partition'." );
102 $this->partitionQueues
[$partition] = JobQueue
::factory(
103 $baseConfig +
$params['configByPartition'][$partition] );
105 // Ring of all partitions
106 $this->partitionRing
= new HashRing( $partitionMap );
109 protected function supportedOrders() {
110 // No FIFO due to partitioning, though "rough timestamp order" is supported
111 return [ 'undefined', 'random', 'timestamp' ];
114 protected function optimalOrder() {
115 return 'undefined'; // defer to the partitions
118 protected function supportsDelayedJobs() {
119 foreach ( $this->partitionQueues
as $queue ) {
120 if ( !$queue->supportsDelayedJobs() ) {
128 protected function doIsEmpty() {
131 foreach ( $this->partitionQueues
as $queue ) {
133 $empty = $empty && $queue->doIsEmpty();
134 } catch ( JobQueueError
$e ) {
136 $this->logException( $e );
139 $this->throwErrorIfAllPartitionsDown( $failed );
144 protected function doGetSize() {
145 return $this->getCrossPartitionSum( 'size', 'doGetSize' );
148 protected function doGetAcquiredCount() {
149 return $this->getCrossPartitionSum( 'acquiredcount', 'doGetAcquiredCount' );
152 protected function doGetDelayedCount() {
153 return $this->getCrossPartitionSum( 'delayedcount', 'doGetDelayedCount' );
156 protected function doGetAbandonedCount() {
157 return $this->getCrossPartitionSum( 'abandonedcount', 'doGetAbandonedCount' );
161 * @param string $type
162 * @param string $method
165 protected function getCrossPartitionSum( $type, $method ) {
168 foreach ( $this->partitionQueues
as $queue ) {
170 $count +
= $queue->$method();
171 } catch ( JobQueueError
$e ) {
173 $this->logException( $e );
176 $this->throwErrorIfAllPartitionsDown( $failed );
181 protected function doBatchPush( array $jobs, $flags ) {
182 // Local ring variable that may be changed to point to a new ring on failure
183 $partitionRing = $this->partitionRing
;
184 // Try to insert the jobs and update $partitionsTry on any failures.
185 // Retry to insert any remaning jobs again, ignoring the bad partitions.
187 // phpcs:ignore Generic.CodeAnalysis.ForLoopWithTestFunctionCall
188 for ( $i = $this->maxPartitionsTry
; $i > 0 && count( $jobsLeft ); --$i ) {
190 $partitionRing->getLiveLocationWeights();
191 } catch ( UnexpectedValueException
$e ) {
192 break; // all servers down; nothing to insert to
194 $jobsLeft = $this->tryJobInsertions( $jobsLeft, $partitionRing, $flags );
196 if ( count( $jobsLeft ) ) {
197 throw new JobQueueError(
198 "Could not insert job(s), {$this->maxPartitionsTry} partitions tried." );
204 * @param HashRing &$partitionRing
206 * @throws JobQueueError
207 * @return array List of Job object that could not be inserted
209 protected function tryJobInsertions( array $jobs, HashRing
&$partitionRing, $flags ) {
212 // Because jobs are spread across partitions, per-job de-duplication needs
213 // to use a consistent hash to avoid allowing duplicate jobs per partition.
214 // When inserting a batch of de-duplicated jobs, QOS_ATOMIC is disregarded.
215 $uJobsByPartition = []; // (partition name => job list)
217 foreach ( $jobs as $key => $job ) {
218 if ( $job->ignoreDuplicates() ) {
219 $sha1 = sha1( serialize( $job->getDeduplicationInfo() ) );
220 $uJobsByPartition[$partitionRing->getLiveLocation( $sha1 )][] = $job;
221 unset( $jobs[$key] );
224 // Get the batches of jobs that are not de-duplicated
225 if ( $flags & self
::QOS_ATOMIC
) {
226 $nuJobBatches = [ $jobs ]; // all or nothing
228 // Split the jobs into batches and spread them out over servers if there
229 // are many jobs. This helps keep the partitions even. Otherwise, send all
230 // the jobs to a single partition queue to avoids the extra connections.
231 $nuJobBatches = array_chunk( $jobs, 300 );
234 // Insert the de-duplicated jobs into the queues...
235 foreach ( $uJobsByPartition as $partition => $jobBatch ) {
236 /** @var JobQueue $queue */
237 $queue = $this->partitionQueues
[$partition];
240 $queue->doBatchPush( $jobBatch, $flags | self
::QOS_ATOMIC
);
241 } catch ( JobQueueError
$e ) {
243 $this->logException( $e );
246 if ( !$partitionRing->ejectFromLiveRing( $partition, 5 ) ) { // blacklist
247 throw new JobQueueError( "Could not insert job(s), no partitions available." );
249 $jobsLeft = array_merge( $jobsLeft, $jobBatch ); // not inserted
253 // Insert the jobs that are not de-duplicated into the queues...
254 foreach ( $nuJobBatches as $jobBatch ) {
255 $partition = ArrayUtils
::pickRandom( $partitionRing->getLiveLocationWeights() );
256 $queue = $this->partitionQueues
[$partition];
259 $queue->doBatchPush( $jobBatch, $flags | self
::QOS_ATOMIC
);
260 } catch ( JobQueueError
$e ) {
262 $this->logException( $e );
265 if ( !$partitionRing->ejectFromLiveRing( $partition, 5 ) ) { // blacklist
266 throw new JobQueueError( "Could not insert job(s), no partitions available." );
268 $jobsLeft = array_merge( $jobsLeft, $jobBatch ); // not inserted
275 protected function doPop() {
276 $partitionsTry = $this->partitionRing
->getLiveLocationWeights(); // (partition => weight)
279 while ( count( $partitionsTry ) ) {
280 $partition = ArrayUtils
::pickRandom( $partitionsTry );
281 if ( $partition === false ) {
282 break; // all partitions at 0 weight
285 /** @var JobQueue $queue */
286 $queue = $this->partitionQueues
[$partition];
288 $job = $queue->pop();
289 } catch ( JobQueueError
$e ) {
291 $this->logException( $e );
295 $job->metadata
['QueuePartition'] = $partition;
299 unset( $partitionsTry[$partition] ); // blacklist partition
302 $this->throwErrorIfAllPartitionsDown( $failed );
307 protected function doAck( Job
$job ) {
308 if ( !isset( $job->metadata
['QueuePartition'] ) ) {
309 throw new MWException( "The given job has no defined partition name." );
312 $this->partitionQueues
[$job->metadata
['QueuePartition']]->ack( $job );
315 protected function doIsRootJobOldDuplicate( Job
$job ) {
316 $signature = $job->getRootJobParams()['rootJobSignature'];
317 $partition = $this->partitionRing
->getLiveLocation( $signature );
319 return $this->partitionQueues
[$partition]->doIsRootJobOldDuplicate( $job );
320 } catch ( JobQueueError
$e ) {
321 if ( $this->partitionRing
->ejectFromLiveRing( $partition, 5 ) ) {
322 $partition = $this->partitionRing
->getLiveLocation( $signature );
323 return $this->partitionQueues
[$partition]->doIsRootJobOldDuplicate( $job );
330 protected function doDeduplicateRootJob( IJobSpecification
$job ) {
331 $signature = $job->getRootJobParams()['rootJobSignature'];
332 $partition = $this->partitionRing
->getLiveLocation( $signature );
334 return $this->partitionQueues
[$partition]->doDeduplicateRootJob( $job );
335 } catch ( JobQueueError
$e ) {
336 if ( $this->partitionRing
->ejectFromLiveRing( $partition, 5 ) ) {
337 $partition = $this->partitionRing
->getLiveLocation( $signature );
338 return $this->partitionQueues
[$partition]->doDeduplicateRootJob( $job );
345 protected function doDelete() {
347 /** @var JobQueue $queue */
348 foreach ( $this->partitionQueues
as $queue ) {
351 } catch ( JobQueueError
$e ) {
353 $this->logException( $e );
356 $this->throwErrorIfAllPartitionsDown( $failed );
360 protected function doWaitForBackups() {
362 /** @var JobQueue $queue */
363 foreach ( $this->partitionQueues
as $queue ) {
365 $queue->waitForBackups();
366 } catch ( JobQueueError
$e ) {
368 $this->logException( $e );
371 $this->throwErrorIfAllPartitionsDown( $failed );
374 protected function doFlushCaches() {
375 /** @var JobQueue $queue */
376 foreach ( $this->partitionQueues
as $queue ) {
377 $queue->doFlushCaches();
381 public function getAllQueuedJobs() {
382 $iterator = new AppendIterator();
384 /** @var JobQueue $queue */
385 foreach ( $this->partitionQueues
as $queue ) {
386 $iterator->append( $queue->getAllQueuedJobs() );
392 public function getAllDelayedJobs() {
393 $iterator = new AppendIterator();
395 /** @var JobQueue $queue */
396 foreach ( $this->partitionQueues
as $queue ) {
397 $iterator->append( $queue->getAllDelayedJobs() );
403 public function getAllAcquiredJobs() {
404 $iterator = new AppendIterator();
406 /** @var JobQueue $queue */
407 foreach ( $this->partitionQueues
as $queue ) {
408 $iterator->append( $queue->getAllAcquiredJobs() );
414 public function getAllAbandonedJobs() {
415 $iterator = new AppendIterator();
417 /** @var JobQueue $queue */
418 foreach ( $this->partitionQueues
as $queue ) {
419 $iterator->append( $queue->getAllAbandonedJobs() );
425 public function getCoalesceLocationInternal() {
426 return "JobQueueFederated:wiki:{$this->wiki}" .
427 sha1( serialize( array_keys( $this->partitionQueues
) ) );
430 protected function doGetSiblingQueuesWithJobs( array $types ) {
434 /** @var JobQueue $queue */
435 foreach ( $this->partitionQueues
as $queue ) {
437 $nonEmpty = $queue->doGetSiblingQueuesWithJobs( $types );
438 if ( is_array( $nonEmpty ) ) {
439 $result = array_unique( array_merge( $result, $nonEmpty ) );
441 return null; // not supported on all partitions; bail
443 if ( count( $result ) == count( $types ) ) {
444 break; // short-circuit
446 } catch ( JobQueueError
$e ) {
448 $this->logException( $e );
451 $this->throwErrorIfAllPartitionsDown( $failed );
453 return array_values( $result );
456 protected function doGetSiblingQueueSizes( array $types ) {
459 /** @var JobQueue $queue */
460 foreach ( $this->partitionQueues
as $queue ) {
462 $sizes = $queue->doGetSiblingQueueSizes( $types );
463 if ( is_array( $sizes ) ) {
464 foreach ( $sizes as $type => $size ) {
465 $result[$type] = isset( $result[$type] ) ?
$result[$type] +
$size : $size;
468 return null; // not supported on all partitions; bail
470 } catch ( JobQueueError
$e ) {
472 $this->logException( $e );
475 $this->throwErrorIfAllPartitionsDown( $failed );
480 protected function logException( Exception
$e ) {
481 wfDebugLog( 'JobQueueFederated', $e->getMessage() . "\n" . $e->getTraceAsString() );
485 * Throw an error if no partitions available
487 * @param int $down The number of up partitions down
489 * @throws JobQueueError
491 protected function throwErrorIfAllPartitionsDown( $down ) {
492 if ( $down >= count( $this->partitionQueues
) ) {
493 throw new JobQueueError( 'No queue partitions available.' );