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 = $params['sectionsByWiki'][$this->wiki
] ??
'default';
77 if ( !isset( $params['partitionsBySection'][$section] ) ) {
78 throw new MWException( "No configuration for section '$section'." );
80 $this->maxPartitionsTry
= $params['maxPartitionsTry'] ??
2;
81 // Get the full partition map
82 $partitionMap = $params['partitionsBySection'][$section];
83 arsort( $partitionMap, SORT_NUMERIC
);
84 // Get the config to pass to merge into each partition queue config
85 $baseConfig = $params;
86 foreach ( [ 'class', 'sectionsByWiki', 'maxPartitionsTry',
87 'partitionsBySection', 'configByPartition', ] as $o
89 unset( $baseConfig[$o] ); // partition queue doesn't care about this
91 // The class handles all aggregator calls already
92 unset( $baseConfig['aggregator'] );
93 // Get the partition queue objects
94 foreach ( $partitionMap as $partition => $w ) {
95 if ( !isset( $params['configByPartition'][$partition] ) ) {
96 throw new MWException( "No configuration for partition '$partition'." );
98 $this->partitionQueues
[$partition] = JobQueue
::factory(
99 $baseConfig +
$params['configByPartition'][$partition] );
101 // Ring of all partitions
102 $this->partitionRing
= new HashRing( $partitionMap );
105 protected function supportedOrders() {
106 // No FIFO due to partitioning, though "rough timestamp order" is supported
107 return [ 'undefined', 'random', 'timestamp' ];
110 protected function optimalOrder() {
111 return 'undefined'; // defer to the partitions
114 protected function supportsDelayedJobs() {
115 foreach ( $this->partitionQueues
as $queue ) {
116 if ( !$queue->supportsDelayedJobs() ) {
124 protected function doIsEmpty() {
127 foreach ( $this->partitionQueues
as $queue ) {
129 $empty = $empty && $queue->doIsEmpty();
130 } catch ( JobQueueError
$e ) {
132 $this->logException( $e );
135 $this->throwErrorIfAllPartitionsDown( $failed );
140 protected function doGetSize() {
141 return $this->getCrossPartitionSum( 'size', 'doGetSize' );
144 protected function doGetAcquiredCount() {
145 return $this->getCrossPartitionSum( 'acquiredcount', 'doGetAcquiredCount' );
148 protected function doGetDelayedCount() {
149 return $this->getCrossPartitionSum( 'delayedcount', 'doGetDelayedCount' );
152 protected function doGetAbandonedCount() {
153 return $this->getCrossPartitionSum( 'abandonedcount', 'doGetAbandonedCount' );
157 * @param string $type
158 * @param string $method
161 protected function getCrossPartitionSum( $type, $method ) {
164 foreach ( $this->partitionQueues
as $queue ) {
166 $count +
= $queue->$method();
167 } catch ( JobQueueError
$e ) {
169 $this->logException( $e );
172 $this->throwErrorIfAllPartitionsDown( $failed );
177 protected function doBatchPush( array $jobs, $flags ) {
178 // Local ring variable that may be changed to point to a new ring on failure
179 $partitionRing = $this->partitionRing
;
180 // Try to insert the jobs and update $partitionsTry on any failures.
181 // Retry to insert any remaning jobs again, ignoring the bad partitions.
183 // phpcs:ignore Generic.CodeAnalysis.ForLoopWithTestFunctionCall
184 for ( $i = $this->maxPartitionsTry
; $i > 0 && count( $jobsLeft ); --$i ) {
186 $partitionRing->getLiveLocationWeights();
187 } catch ( UnexpectedValueException
$e ) {
188 break; // all servers down; nothing to insert to
190 $jobsLeft = $this->tryJobInsertions( $jobsLeft, $partitionRing, $flags );
192 if ( count( $jobsLeft ) ) {
193 throw new JobQueueError(
194 "Could not insert job(s), {$this->maxPartitionsTry} partitions tried." );
200 * @param HashRing &$partitionRing
202 * @throws JobQueueError
203 * @return array List of Job object that could not be inserted
205 protected function tryJobInsertions( array $jobs, HashRing
&$partitionRing, $flags ) {
208 // Because jobs are spread across partitions, per-job de-duplication needs
209 // to use a consistent hash to avoid allowing duplicate jobs per partition.
210 // When inserting a batch of de-duplicated jobs, QOS_ATOMIC is disregarded.
211 $uJobsByPartition = []; // (partition name => job list)
213 foreach ( $jobs as $key => $job ) {
214 if ( $job->ignoreDuplicates() ) {
215 $sha1 = sha1( serialize( $job->getDeduplicationInfo() ) );
216 $uJobsByPartition[$partitionRing->getLiveLocation( $sha1 )][] = $job;
217 unset( $jobs[$key] );
220 // Get the batches of jobs that are not de-duplicated
221 if ( $flags & self
::QOS_ATOMIC
) {
222 $nuJobBatches = [ $jobs ]; // all or nothing
224 // Split the jobs into batches and spread them out over servers if there
225 // are many jobs. This helps keep the partitions even. Otherwise, send all
226 // the jobs to a single partition queue to avoids the extra connections.
227 $nuJobBatches = array_chunk( $jobs, 300 );
230 // Insert the de-duplicated jobs into the queues...
231 foreach ( $uJobsByPartition as $partition => $jobBatch ) {
232 /** @var JobQueue $queue */
233 $queue = $this->partitionQueues
[$partition];
236 $queue->doBatchPush( $jobBatch, $flags | self
::QOS_ATOMIC
);
237 } catch ( JobQueueError
$e ) {
239 $this->logException( $e );
242 if ( !$partitionRing->ejectFromLiveRing( $partition, 5 ) ) { // blacklist
243 throw new JobQueueError( "Could not insert job(s), no partitions available." );
245 $jobsLeft = array_merge( $jobsLeft, $jobBatch ); // not inserted
249 // Insert the jobs that are not de-duplicated into the queues...
250 foreach ( $nuJobBatches as $jobBatch ) {
251 $partition = ArrayUtils
::pickRandom( $partitionRing->getLiveLocationWeights() );
252 $queue = $this->partitionQueues
[$partition];
255 $queue->doBatchPush( $jobBatch, $flags | self
::QOS_ATOMIC
);
256 } catch ( JobQueueError
$e ) {
258 $this->logException( $e );
261 if ( !$partitionRing->ejectFromLiveRing( $partition, 5 ) ) { // blacklist
262 throw new JobQueueError( "Could not insert job(s), no partitions available." );
264 $jobsLeft = array_merge( $jobsLeft, $jobBatch ); // not inserted
271 protected function doPop() {
272 $partitionsTry = $this->partitionRing
->getLiveLocationWeights(); // (partition => weight)
275 while ( count( $partitionsTry ) ) {
276 $partition = ArrayUtils
::pickRandom( $partitionsTry );
277 if ( $partition === false ) {
278 break; // all partitions at 0 weight
281 /** @var JobQueue $queue */
282 $queue = $this->partitionQueues
[$partition];
284 $job = $queue->pop();
285 } catch ( JobQueueError
$e ) {
287 $this->logException( $e );
291 $job->metadata
['QueuePartition'] = $partition;
295 unset( $partitionsTry[$partition] ); // blacklist partition
298 $this->throwErrorIfAllPartitionsDown( $failed );
303 protected function doAck( Job
$job ) {
304 if ( !isset( $job->metadata
['QueuePartition'] ) ) {
305 throw new MWException( "The given job has no defined partition name." );
308 $this->partitionQueues
[$job->metadata
['QueuePartition']]->ack( $job );
311 protected function doIsRootJobOldDuplicate( Job
$job ) {
312 $signature = $job->getRootJobParams()['rootJobSignature'];
313 $partition = $this->partitionRing
->getLiveLocation( $signature );
315 return $this->partitionQueues
[$partition]->doIsRootJobOldDuplicate( $job );
316 } catch ( JobQueueError
$e ) {
317 if ( $this->partitionRing
->ejectFromLiveRing( $partition, 5 ) ) {
318 $partition = $this->partitionRing
->getLiveLocation( $signature );
319 return $this->partitionQueues
[$partition]->doIsRootJobOldDuplicate( $job );
326 protected function doDeduplicateRootJob( IJobSpecification
$job ) {
327 $signature = $job->getRootJobParams()['rootJobSignature'];
328 $partition = $this->partitionRing
->getLiveLocation( $signature );
330 return $this->partitionQueues
[$partition]->doDeduplicateRootJob( $job );
331 } catch ( JobQueueError
$e ) {
332 if ( $this->partitionRing
->ejectFromLiveRing( $partition, 5 ) ) {
333 $partition = $this->partitionRing
->getLiveLocation( $signature );
334 return $this->partitionQueues
[$partition]->doDeduplicateRootJob( $job );
341 protected function doDelete() {
343 /** @var JobQueue $queue */
344 foreach ( $this->partitionQueues
as $queue ) {
347 } catch ( JobQueueError
$e ) {
349 $this->logException( $e );
352 $this->throwErrorIfAllPartitionsDown( $failed );
356 protected function doWaitForBackups() {
358 /** @var JobQueue $queue */
359 foreach ( $this->partitionQueues
as $queue ) {
361 $queue->waitForBackups();
362 } catch ( JobQueueError
$e ) {
364 $this->logException( $e );
367 $this->throwErrorIfAllPartitionsDown( $failed );
370 protected function doFlushCaches() {
371 /** @var JobQueue $queue */
372 foreach ( $this->partitionQueues
as $queue ) {
373 $queue->doFlushCaches();
377 public function getAllQueuedJobs() {
378 $iterator = new AppendIterator();
380 /** @var JobQueue $queue */
381 foreach ( $this->partitionQueues
as $queue ) {
382 $iterator->append( $queue->getAllQueuedJobs() );
388 public function getAllDelayedJobs() {
389 $iterator = new AppendIterator();
391 /** @var JobQueue $queue */
392 foreach ( $this->partitionQueues
as $queue ) {
393 $iterator->append( $queue->getAllDelayedJobs() );
399 public function getAllAcquiredJobs() {
400 $iterator = new AppendIterator();
402 /** @var JobQueue $queue */
403 foreach ( $this->partitionQueues
as $queue ) {
404 $iterator->append( $queue->getAllAcquiredJobs() );
410 public function getAllAbandonedJobs() {
411 $iterator = new AppendIterator();
413 /** @var JobQueue $queue */
414 foreach ( $this->partitionQueues
as $queue ) {
415 $iterator->append( $queue->getAllAbandonedJobs() );
421 public function getCoalesceLocationInternal() {
422 return "JobQueueFederated:wiki:{$this->wiki}" .
423 sha1( serialize( array_keys( $this->partitionQueues
) ) );
426 protected function doGetSiblingQueuesWithJobs( array $types ) {
430 /** @var JobQueue $queue */
431 foreach ( $this->partitionQueues
as $queue ) {
433 $nonEmpty = $queue->doGetSiblingQueuesWithJobs( $types );
434 if ( is_array( $nonEmpty ) ) {
435 $result = array_unique( array_merge( $result, $nonEmpty ) );
437 return null; // not supported on all partitions; bail
439 if ( count( $result ) == count( $types ) ) {
440 break; // short-circuit
442 } catch ( JobQueueError
$e ) {
444 $this->logException( $e );
447 $this->throwErrorIfAllPartitionsDown( $failed );
449 return array_values( $result );
452 protected function doGetSiblingQueueSizes( array $types ) {
455 /** @var JobQueue $queue */
456 foreach ( $this->partitionQueues
as $queue ) {
458 $sizes = $queue->doGetSiblingQueueSizes( $types );
459 if ( is_array( $sizes ) ) {
460 foreach ( $sizes as $type => $size ) {
461 $result[$type] = isset( $result[$type] ) ?
$result[$type] +
$size : $size;
464 return null; // not supported on all partitions; bail
466 } catch ( JobQueueError
$e ) {
468 $this->logException( $e );
471 $this->throwErrorIfAllPartitionsDown( $failed );
476 protected function logException( Exception
$e ) {
477 wfDebugLog( 'JobQueueFederated', $e->getMessage() . "\n" . $e->getTraceAsString() );
481 * Throw an error if no partitions available
483 * @param int $down The number of up partitions down
485 * @throws JobQueueError
487 protected function throwErrorIfAllPartitionsDown( $down ) {
488 if ( $down >= count( $this->partitionQueues
) ) {
489 throw new JobQueueError( 'No queue partitions available.' );