JobQueueGroup.php

Go to the documentation of this file.

<?php
use MediaWiki\Deferred\DeferredUpdates;
use MediaWiki\Deferred\JobQueueEnqueueUpdate;
use MediaWiki\MediaWikiServices;
use Wikimedia\ObjectCache\WANObjectCache;
use Wikimedia\Rdbms\ReadOnlyMode;
use Wikimedia\Stats\IBufferingStatsdDataFactory;
use Wikimedia\UUID\GlobalIdGenerator;
 
class JobQueueGroup {
    protected $cache;
 
    protected $domain;
    protected $readOnlyMode;
    private $localJobClasses;
    private $jobTypeConfiguration;
    private $jobTypesExcludedFromDefaultQueue;
    private $statsdDataFactory;
    private $wanCache;
    private $globalIdGenerator;
 
    protected $coalescedQueues;
 
    public const TYPE_DEFAULT = 1; // integer; jobs popped by default
    private const TYPE_ANY = 2; // integer; any job
 
    public const USE_CACHE = 1; // integer; use process or persistent cache
 
    private const PROC_CACHE_TTL = 15; // integer; seconds
 
    public function __construct(
        $domain,
        ReadOnlyMode $readOnlyMode,
        ?array $localJobClasses,
        array $jobTypeConfiguration,
        array $jobTypesExcludedFromDefaultQueue,
        IBufferingStatsdDataFactory $statsdDataFactory,
        WANObjectCache $wanCache,
        GlobalIdGenerator $globalIdGenerator
    ) {
        $this->domain = $domain;
        $this->readOnlyMode = $readOnlyMode;
        $this->cache = new MapCacheLRU( 10 );
        $this->localJobClasses = $localJobClasses;
        $this->jobTypeConfiguration = $jobTypeConfiguration;
        $this->jobTypesExcludedFromDefaultQueue = $jobTypesExcludedFromDefaultQueue;
        $this->statsdDataFactory = $statsdDataFactory;
        $this->wanCache = $wanCache;
        $this->globalIdGenerator = $globalIdGenerator;
    }
 
    public function get( $type ) {
        $conf = [ 'domain' => $this->domain, 'type' => $type ];
        $conf += $this->jobTypeConfiguration[$type] ?? $this->jobTypeConfiguration['default'];
        if ( !isset( $conf['readOnlyReason'] ) ) {
            $conf['readOnlyReason'] = $this->readOnlyMode->getConfiguredReason();
        }
 
        $conf['stats'] = $this->statsdDataFactory;
        $conf['wanCache'] = $this->wanCache;
        $conf['idGenerator'] = $this->globalIdGenerator;
 
        return JobQueue::factory( $conf );
    }
 
    public function push( $jobs ) {
        $jobs = is_array( $jobs ) ? $jobs : [ $jobs ];
        if ( $jobs === [] ) {
            return;
        }
 
        $this->assertValidJobs( $jobs );
 
        $jobsByType = []; // (job type => list of jobs)
        foreach ( $jobs as $job ) {
            $type = $job->getType();
            if ( isset( $this->jobTypeConfiguration[$type] ) ) {
                $jobsByType[$type][] = $job;
            } else {
                if (
                    isset( $this->jobTypeConfiguration['default']['typeAgnostic'] ) &&
                    $this->jobTypeConfiguration['default']['typeAgnostic']
                ) {
                    $jobsByType['default'][] = $job;
                } else {
                    $jobsByType[$type][] = $job;
                }
            }
        }
 
        foreach ( $jobsByType as $type => $jobs ) {
            $this->get( $type )->push( $jobs );
        }
 
        if ( $this->cache->hasField( 'queues-ready', 'list' ) ) {
            $list = $this->cache->getField( 'queues-ready', 'list' );
            if ( count( array_diff( array_keys( $jobsByType ), $list ) ) ) {
                $this->cache->clear( 'queues-ready' );
            }
        }
 
        $cache = MediaWikiServices::getInstance()->getObjectCacheFactory()->getLocalClusterInstance();
        $cache->set(
            $cache->makeGlobalKey( 'jobqueue', $this->domain, 'hasjobs', self::TYPE_ANY ),
            'true',
            15
        );
        if ( array_diff( array_keys( $jobsByType ), $this->jobTypesExcludedFromDefaultQueue ) ) {
            $cache->set(
                $cache->makeGlobalKey( 'jobqueue', $this->domain, 'hasjobs', self::TYPE_DEFAULT ),
                'true',
                15
            );
        }
    }
 
    public function lazyPush( $jobs ) {
        if ( PHP_SAPI === 'cli' || PHP_SAPI === 'phpdbg' ) {
            $this->push( $jobs );
            return;
        }
 
        $jobs = is_array( $jobs ) ? $jobs : [ $jobs ];
 
        // Throw errors now instead of on push(), when other jobs may be buffered
        $this->assertValidJobs( $jobs );
 
        DeferredUpdates::addUpdate( new JobQueueEnqueueUpdate( $this->domain, $jobs ) );
    }
 
    public function pop( $qtype = self::TYPE_DEFAULT, $flags = 0, array $ignored = [] ) {
        $job = false;
 
        if ( !$this->localJobClasses ) {
            throw new JobQueueError(
                "Cannot pop '{$qtype}' job off foreign '{$this->domain}' wiki queue." );
        }
        if ( is_string( $qtype ) && !isset( $this->localJobClasses[$qtype] ) ) {
            // Do not pop jobs if there is no class for the queue type
            throw new JobQueueError( "Unrecognized job type '$qtype'." );
        }
 
        if ( is_string( $qtype ) ) { // specific job type
            if ( !in_array( $qtype, $ignored ) ) {
                $job = $this->get( $qtype )->pop();
            }
        } else { // any job in the "default" jobs types
            if ( $flags & self::USE_CACHE ) {
                if ( !$this->cache->hasField( 'queues-ready', 'list', self::PROC_CACHE_TTL ) ) {
                    $this->cache->setField( 'queues-ready', 'list', $this->getQueuesWithJobs() );
                }
                $types = $this->cache->getField( 'queues-ready', 'list' );
            } else {
                $types = $this->getQueuesWithJobs();
            }
 
            if ( $qtype == self::TYPE_DEFAULT ) {
                $types = array_intersect( $types, $this->getDefaultQueueTypes() );
            }
 
            $types = array_diff( $types, $ignored ); // avoid selected types
            shuffle( $types ); // avoid starvation
 
            foreach ( $types as $type ) { // for each queue...
                $job = $this->get( $type )->pop();
                if ( $job ) { // found
                    break;
                } else { // not found
                    $this->cache->clear( 'queues-ready' );
                }
            }
        }
 
        return $job;
    }
 
    public function ack( RunnableJob $job ) {
        $this->get( $job->getType() )->ack( $job );
    }
 
    public function deduplicateRootJob( RunnableJob $job ) {
        wfDeprecated( __METHOD__, '1.40' );
        return true;
    }
 
    public function waitForBackups() {
        wfDeprecated( __METHOD__, '1.41' );
        // Try to avoid doing this more than once per queue storage medium
        foreach ( $this->jobTypeConfiguration as $type => $conf ) {
            $this->get( $type )->waitForBackups();
        }
    }
 
    public function getQueueTypes() {
        if ( !$this->localJobClasses ) {
            throw new JobQueueError( 'Cannot inspect job queue from foreign wiki' );
        }
        return array_keys( $this->localJobClasses );
    }
 
    public function getDefaultQueueTypes() {
        return array_diff( $this->getQueueTypes(), $this->jobTypesExcludedFromDefaultQueue );
    }
 
    public function queuesHaveJobs( $type = self::TYPE_ANY ) {
        $cache = MediaWikiServices::getInstance()->getObjectCacheFactory()->getLocalClusterInstance();
        $key = $cache->makeGlobalKey( 'jobqueue', $this->domain, 'hasjobs', $type );
 
        $value = $cache->get( $key );
        if ( $value === false ) {
            $queues = $this->getQueuesWithJobs();
            if ( $type == self::TYPE_DEFAULT ) {
                $queues = array_intersect( $queues, $this->getDefaultQueueTypes() );
            }
            $value = count( $queues ) ? 'true' : 'false';
            $cache->add( $key, $value, 15 );
        }
 
        return ( $value === 'true' );
    }
 
    public function getQueuesWithJobs() {
        $types = [];
        foreach ( $this->getCoalescedQueues() as $info ) {
            $queue = $info['queue'];
            $nonEmpty = $queue->getSiblingQueuesWithJobs( $this->getQueueTypes() );
            if ( is_array( $nonEmpty ) ) { // batching features supported
                $types = array_merge( $types, $nonEmpty );
            } else { // we have to go through the queues in the bucket one-by-one
                foreach ( $info['types'] as $type ) {
                    if ( !$this->get( $type )->isEmpty() ) {
                        $types[] = $type;
                    }
                }
            }
        }
 
        return $types;
    }
 
    public function getQueueSizes() {
        $sizeMap = [];
        foreach ( $this->getCoalescedQueues() as $info ) {
            $queue = $info['queue'];
            $sizes = $queue->getSiblingQueueSizes( $this->getQueueTypes() );
            if ( is_array( $sizes ) ) { // batching features supported
                $sizeMap += $sizes;
            } else { // we have to go through the queues in the bucket one-by-one
                foreach ( $info['types'] as $type ) {
                    $sizeMap[$type] = $this->get( $type )->getSize();
                }
            }
        }
 
        return $sizeMap;
    }
 
    protected function getCoalescedQueues() {
        if ( $this->coalescedQueues === null ) {
            $this->coalescedQueues = [];
            foreach ( $this->jobTypeConfiguration as $type => $conf ) {
                $conf['domain'] = $this->domain;
                $conf['type'] = 'null';
                $conf['stats'] = $this->statsdDataFactory;
                $conf['wanCache'] = $this->wanCache;
                $conf['idGenerator'] = $this->globalIdGenerator;
 
                $queue = JobQueue::factory( $conf );
                $loc = $queue->getCoalesceLocationInternal();
                if ( !isset( $this->coalescedQueues[$loc] ) ) {
                    $this->coalescedQueues[$loc]['queue'] = $queue;
                    $this->coalescedQueues[$loc]['types'] = [];
                }
                if ( $type === 'default' ) {
                    $this->coalescedQueues[$loc]['types'] = array_merge(
                        $this->coalescedQueues[$loc]['types'],
                        array_diff( $this->getQueueTypes(), array_keys( $this->jobTypeConfiguration ) )
                    );
                } else {
                    $this->coalescedQueues[$loc]['types'][] = $type;
                }
            }
        }
 
        return $this->coalescedQueues;
    }
 
    private function assertValidJobs( array $jobs ) {
        foreach ( $jobs as $job ) {
            if ( !( $job instanceof IJobSpecification ) ) {
                $type = get_debug_type( $job );
                throw new InvalidArgumentException( "Expected IJobSpecification objects, got " . $type );
            }
        }
    }
}