Thijs/wiki.techinc.nl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge "Update documentation for job related classes"

Browse source
This commit is contained in:
jenkins-bot 2013-11-26 16:33:04 +00:00 committed by Gerrit Code Review
commit e620e80e06
15 changed files with 196 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

19
includes/job/Job.php
View file

@ -55,7 +55,7 @@ abstract class Job {
/**
* Run the job
* @return boolean success
* @return bool Success
*/
abstract public function run();
@ -67,7 +67,7 @@ abstract class Job {
* Create the appropriate object to handle a specific job
*
* @param string $command Job command
* @param $title Title: Associated title
* @param Title $title Associated title
* @param array|bool $params Job parameters
* @param int $id Job identifier
* @throws MWException
@ -130,7 +130,7 @@ abstract class Job {
* Pop a job off the front of the queue.
* This is subject to $wgJobTypesExcludedFromDefaultQueue.
*
* @return Job or false if there's no jobs
* @return Job|bool False if there are no jobs
* @deprecated since 1.21
*/
public static function pop() {
@ -153,11 +153,12 @@ abstract class Job {
$this->params = $params;
$this->id = $id;
$this->removeDuplicates = false; // expensive jobs may set this to true
// expensive jobs may set this to true
$this->removeDuplicates = false;
}
/**
* @return integer May be 0 for jobs stored outside the DB
* @return int May be 0 for jobs stored outside the DB
* @deprecated since 1.22
*/
public function getId() {
@ -186,7 +187,7 @@ abstract class Job {
}
/**
* @return integer|null UNIX timestamp to delay running this job until, otherwise null
* @return int|null UNIX timestamp to delay running this job until, otherwise null
* @since 1.22
*/
public function getReleaseTimestamp() {
@ -216,7 +217,7 @@ abstract class Job {
* only checked if ignoreDuplicates() returns true, meaning that duplicate
* jobs are supposed to be ignored.
*
* @return Array Map of key/values
* @return array Map of key/values
* @since 1.21
*/
public function getDeduplicationInfo() {
@ -240,7 +241,7 @@ abstract class Job {
/**
* @see JobQueue::deduplicateRootJob()
* @param string $key A key that identifies the task
* @return Array
* @return array
* @since 1.21
*/
public static function newRootJobParams( $key ) {
@ -252,7 +253,7 @@ abstract class Job {
/**
* @see JobQueue::deduplicateRootJob()
* @return Array
* @return array
* @since 1.21
*/
public function getRootJobParams() {

85
includes/job/JobQueue.php
View file

@ -29,12 +29,23 @@
* @since 1.21
*/
abstract class JobQueue {
protected $wiki; // string; wiki ID
protected $type; // string; job type
protected $order; // string; job priority for pop()
protected $claimTTL; // integer; seconds
protected $maxTries; // integer; maximum number of times to try a job
protected $checkDelay; // boolean; allow delayed jobs
/** @var string Wiki ID */
protected $wiki;
/** @var string Job type */
protected $type;
/** @var string Job priority for pop() */
protected $order;
/** @var int Time to live in seconds */
protected $claimTTL;
/** @var int Maximum number of times to try a job */
protected $maxTries;
/** @var bool Allow delayed jobs */
protected $checkDelay;
/** @var BagOStuff */
protected $dupCache;
@ -44,7 +55,8 @@ abstract class JobQueue {
const ROOTJOB_TTL = 2419200; // integer; seconds to remember root jobs (28 days)
/**
* @param $params array
* @param array $params
* @throws MWException
*/
protected function __construct( array $params ) {
$this->wiki = $params['wiki'];
@ -93,7 +105,7 @@ abstract class JobQueue {
*
* Queue classes should throw an exception if they do not support the options given.
*
* @param $params array
* @param array $params
* @return JobQueue
* @throws MWException
*/
@ -142,7 +154,7 @@ abstract class JobQueue {
/**
* Get the allowed queue orders for configuration validation
*
* @return Array Subset of (random, timestamp, fifo, undefined)
* @return array Subset of (random, timestamp, fifo, undefined)
*/
abstract protected function supportedOrders();
@ -156,7 +168,7 @@ abstract class JobQueue {
/**
* Find out if delayed jobs are supported for configuration validation
*
* @return boolean Whether delayed jobs are supported
* @return bool Whether delayed jobs are supported
*/
protected function supportsDelayedJobs() {
return false; // not implemented
@ -194,7 +206,7 @@ abstract class JobQueue {
*
* If caching is used, this number might be out of date for a minute.
*
* @return integer
* @return int
* @throws JobQueueError
*/
final public function getSize() {
@ -207,7 +219,7 @@ abstract class JobQueue {
/**
* @see JobQueue::getSize()
* @return integer
* @return int
*/
abstract protected function doGetSize();
@ -217,7 +229,7 @@ abstract class JobQueue {
*
* If caching is used, this number might be out of date for a minute.
*
* @return integer
* @return int
* @throws JobQueueError
*/
final public function getAcquiredCount() {
@ -230,7 +242,7 @@ abstract class JobQueue {
/**
* @see JobQueue::getAcquiredCount()
* @return integer
* @return int
*/
abstract protected function doGetAcquiredCount();
@ -240,7 +252,7 @@ abstract class JobQueue {
*
* If caching is used, this number might be out of date for a minute.
*
* @return integer
* @return int
* @throws JobQueueError
* @since 1.22
*/
@ -254,7 +266,7 @@ abstract class JobQueue {
/**
* @see JobQueue::getDelayedCount()
* @return integer
* @return int
*/
protected function doGetDelayedCount() {
return 0; // not implemented
@ -266,7 +278,7 @@ abstract class JobQueue {
*
* If caching is used, this number might be out of date for a minute.
*
* @return integer
* @return int
* @throws JobQueueError
*/
final public function getAbandonedCount() {
@ -279,7 +291,7 @@ abstract class JobQueue {
/**
* @see JobQueue::getAbandonedCount()
* @return integer
* @return int
*/
protected function doGetAbandonedCount() {
return 0; // not implemented
@ -290,8 +302,8 @@ abstract class JobQueue {
* This does not require $wgJobClasses to be set for the given job type.
* Outside callers should use JobQueueGroup::push() instead of this function.
*
* @param $jobs Job|Array
* @param $flags integer Bitfield (supports JobQueue::QOS_ATOMIC)
* @param Job|array $jobs A single job or an array of Jobs
* @param int $flags Bitfield (supports JobQueue::QOS_ATOMIC)
* @return bool Returns false on failure
* @throws JobQueueError
*/
@ -305,9 +317,9 @@ abstract class JobQueue {
* Outside callers should use JobQueueGroup::push() instead of this function.
*
* @param array $jobs List of Jobs
* @param $flags integer Bitfield (supports JobQueue::QOS_ATOMIC)
* @param int $flags Bitfield (supports JobQueue::QOS_ATOMIC)
* @throws MWException
* @return bool Returns false on failure
* @throws JobQueueError
*/
final public function batchPush( array $jobs, $flags = 0 ) {
if ( !count( $jobs ) ) {
@ -333,6 +345,8 @@ abstract class JobQueue {
/**
* @see JobQueue::batchPush()
* @param array $jobs
* @param $flags
* @return bool
*/
abstract protected function doBatchPush( array $jobs, $flags );
@ -342,8 +356,8 @@ abstract class JobQueue {
* This requires $wgJobClasses to be set for the given job type.
* Outside callers should use JobQueueGroup::pop() instead of this function.
*
* @throws MWException
* @return Job|bool Returns false if there are no jobs
* @throws JobQueueError
*/
final public function pop() {
global $wgJobClasses;
@ -384,9 +398,9 @@ abstract class JobQueue {
* This does nothing for certain queue classes or if "claimTTL" is not set.
* Outside callers should use JobQueueGroup::ack() instead of this function.
*
* @param $job Job
* @param Job $job
* @throws MWException
* @return bool
* @throws JobQueueError
*/
final public function ack( Job $job ) {
if ( $job->getType() !== $this->type ) {
@ -401,6 +415,7 @@ abstract class JobQueue {
/**
* @see JobQueue::ack()
* @param Job $job
* @return bool
*/
abstract protected function doAck( Job $job );
@ -432,9 +447,9 @@ abstract class JobQueue {
*
* This does nothing for certain queue classes.
*
* @param $job Job
* @param Job $job
* @throws MWException
* @return bool
* @throws JobQueueError
*/
final public function deduplicateRootJob( Job $job ) {
if ( $job->getType() !== $this->type ) {
@ -449,7 +464,8 @@ abstract class JobQueue {
/**
* @see JobQueue::deduplicateRootJob()
* @param $job Job
* @param Job $job
* @throws MWException
* @return bool
*/
protected function doDeduplicateRootJob( Job $job ) {
@ -476,9 +492,9 @@ abstract class JobQueue {
/**
* Check if the "root" job of a given job has been superseded by a newer one
*
* @param $job Job
* @param Job $job
* @throws MWException
* @return bool
* @throws JobQueueError
*/
final protected function isRootJobOldDuplicate( Job $job ) {
if ( $job->getType() !== $this->type ) {
@ -537,6 +553,7 @@ abstract class JobQueue {
/**
* @see JobQueue::delete()
* @throws MWException
* @return bool Success
*/
protected function doDelete() {
@ -574,7 +591,7 @@ abstract class JobQueue {
* - callback : a PHP callable that performs the task
* - period : the period in seconds corresponding to the task frequency
*
* @return Array
* @return array
*/
final public function getPeriodicTasks() {
$tasks = $this->doGetPeriodicTasks();
@ -587,7 +604,7 @@ abstract class JobQueue {
/**
* @see JobQueue::getPeriodicTasks()
* @return Array
* @return array
*/
protected function doGetPeriodicTasks() {
return array();
@ -697,7 +714,7 @@ abstract class JobQueue {
*
* @param string $key Event type
* @param string $type Job type
* @param integer $delta
* @param int $delta
* @since 1.22
*/
public static function incrStats( $key, $type, $delta = 1 ) {
@ -708,7 +725,7 @@ abstract class JobQueue {
/**
* Namespace the queue with a key to isolate it for testing
*
* @param $key string
* @param string $key
* @return void
* @throws MWException
*/

38
includes/job/JobQueueDB.php
View file

@ -37,7 +37,8 @@ class JobQueueDB extends JobQueue {
/** @var BagOStuff */
protected $cache;
protected $cluster = false; // string; name of an external DB cluster
/** @var bool|string Name of an external DB cluster. False if not set */
protected $cluster = false;
/**
* Additional parameters include:
@ -45,7 +46,7 @@ class JobQueueDB extends JobQueue {
* If not specified, the primary DB cluster for the wiki will be used.
* This can be overridden with a custom cluster so that DB handles will
* be retrieved via LBFactory::getExternalLB() and getConnection().
* @param $params array
* @param array $params
*/
protected function __construct( array $params ) {
global $wgMemc;
@ -94,7 +95,7 @@ class JobQueueDB extends JobQueue {
/**
* @see JobQueue::doGetSize()
* @return integer
* @return int
*/
protected function doGetSize() {
$key = $this->getCacheKey( 'size' );
@ -120,7 +121,7 @@ class JobQueueDB extends JobQueue {
/**
* @see JobQueue::doGetAcquiredCount()
* @return integer
* @return int
*/
protected function doGetAcquiredCount() {
if ( $this->claimTTL <= 0 ) {
@ -150,7 +151,7 @@ class JobQueueDB extends JobQueue {
/**
* @see JobQueue::doGetAbandonedCount()
* @return integer
* @return int
* @throws MWException
*/
protected function doGetAbandonedCount() {
@ -209,12 +210,12 @@ class JobQueueDB extends JobQueue {
/**
* This function should *not* be called outside of JobQueueDB
*
* @param DatabaseBase $dbw
* @param IDatabase $dbw
* @param array $jobs
* @param int $flags
* @param string $method
* @return boolean
* @throws type
* @throws DBError
* @return bool
*/
public function doBatchPushInternal( IDatabase $dbw, array $jobs, $flags, $method ) {
if ( !count( $jobs ) ) {
@ -258,8 +259,11 @@ class JobQueueDB extends JobQueue {
$dbw->insert( 'job', $rowBatch, $method );
}
JobQueue::incrStats( 'job-insert', $this->type, count( $rows ) );
JobQueue::incrStats( 'job-insert-duplicate', $this->type,
count( $rowSet ) + count( $rowList ) - count( $rows ) );
JobQueue::incrStats(
'job-insert-duplicate',
$this->type,
count( $rowSet ) + count( $rowList ) - count( $rows )
);
} catch ( DBError $e ) {
if ( $flags & self::QOS_ATOMIC ) {
$dbw->rollback( $method );
@ -336,7 +340,7 @@ class JobQueueDB extends JobQueue {
* @param string $uuid 32 char hex string
* @param $rand integer Random unsigned integer (31 bits)
* @param bool $gte Search for job_random >= $random (otherwise job_random <= $random)
* @return Row|false
* @return stdClass|bool Row|false
*/
protected function claimRandom( $uuid, $rand, $gte ) {
$dbw = $this->getMasterDB();
@ -386,6 +390,7 @@ class JobQueueDB extends JobQueue {
continue; // use job_random
}
}
if ( $row ) { // claim the job
$dbw->update( 'job', // update by PK
array(
@ -412,7 +417,7 @@ class JobQueueDB extends JobQueue {
* Reserve a row with a single UPDATE without holding row locks over RTTs...
*
* @param string $uuid 32 char hex string
* @return Row|false
* @return stdClass|bool Row|false
*/
protected function claimOldest( $uuid ) {
$dbw = $this->getMasterDB();
@ -557,7 +562,7 @@ class JobQueueDB extends JobQueue {
}
/**
* @return Array
* @return array
*/
protected function doGetPeriodicTasks() {
return array(
@ -639,7 +644,7 @@ class JobQueueDB extends JobQueue {
/**
* Recycle or destroy any jobs that have been claimed for too long
*
* @return integer Number of jobs recycled/deleted
* @return int Number of jobs recycled/deleted
*/
public function recycleAndDeleteStaleJobs() {
$now = time();
@ -721,7 +726,7 @@ class JobQueueDB extends JobQueue {
}
/**
* @param $job Job
* @param Job $job
* @return array
*/
protected function insertFields( Job $job ) {
@ -745,6 +750,7 @@ class JobQueueDB extends JobQueue {
}
/**
* @throws JobQueueConnectionError
* @return DBConnRef
*/
protected function getSlaveDB() {
@ -756,6 +762,7 @@ class JobQueueDB extends JobQueue {
}
/**
* @throws JobQueueConnectionError
* @return DBConnRef
*/
protected function getMasterDB() {
@ -779,6 +786,7 @@ class JobQueueDB extends JobQueue {
}
/**
* @param $property
* @return string
*/
private function getCacheKey( $property ) {

33
includes/job/JobQueueFederated.php
View file

@ -47,10 +47,10 @@
* @since 1.22
*/
class JobQueueFederated extends JobQueue {
/** @var Array (partition name => weight) reverse sorted by weight */
/** @var array (partition name => weight) reverse sorted by weight */
protected $partitionMap = array();
/** @var Array (partition name => JobQueue) reverse sorted by weight */
/** @var array (partition name => JobQueue) reverse sorted by weight */
protected $partitionQueues = array();
/** @var HashRing */
@ -59,7 +59,8 @@ class JobQueueFederated extends JobQueue {
/** @var BagOStuff */
protected $cache;
protected $maxPartitionsTry; // integer; maximum number of partitions to try
/** @var int Maximum number of partitions to try */
protected $maxPartitionsTry;
const CACHE_TTL_SHORT = 30; // integer; seconds to cache info without re-validating
const CACHE_TTL_LONG = 300; // integer; seconds to cache info that is kept up to date
@ -82,6 +83,7 @@ class JobQueueFederated extends JobQueue {
* during failure, at the cost of added latency and somewhat
* less reliable job de-duplication mechanisms.
* @param array $params
* @throws MWException
*/
protected function __construct( array $params ) {
parent::__construct( $params );
@ -184,7 +186,7 @@ class JobQueueFederated extends JobQueue {
/**
* @param string $type
* @param string $method
* @return integer
* @return int
*/
protected function getCrossPartitionSum( $type, $method ) {
$key = $this->getCacheKey( $type );
@ -228,7 +230,8 @@ class JobQueueFederated extends JobQueue {
/**
* @param array $jobs
* @param HashRing $partitionRing
* @param integer $flags
* @param int $flags
* @throws JobQueueError
* @return array List of Job object that could not be inserted
*/
protected function tryJobInsertions( array $jobs, HashRing &$partitionRing, $flags ) {
@ -238,6 +241,7 @@ class JobQueueFederated extends JobQueue {
// to use a consistent hash to avoid allowing duplicate jobs per partition.
// When inserting a batch of de-duplicated jobs, QOS_ATOMIC is disregarded.
$uJobsByPartition = array(); // (partition name => job list)
/** @var Job $job */
foreach ( $jobs as $key => $job ) {
if ( $job->ignoreDuplicates() ) {
$sha1 = sha1( serialize( $job->getDeduplicationInfo() ) );
@ -257,6 +261,7 @@ class JobQueueFederated extends JobQueue {
// Insert the de-duplicated jobs into the queues...
foreach ( $uJobsByPartition as $partition => $jobBatch ) {
/** @var JobQueue $queue */
$queue = $this->partitionQueues[$partition];
try {
$ok = $queue->doBatchPush( $jobBatch, $flags | self::QOS_ATOMIC );
@ -316,6 +321,8 @@ class JobQueueFederated extends JobQueue {
if ( $partition === false ) {
break; // all partitions at 0 weight
}
/** @var JobQueue $queue */
$queue = $this->partitionQueues[$partition];
try {
$job = $queue->pop();
@ -374,6 +381,7 @@ class JobQueueFederated extends JobQueue {
}
protected function doDelete() {
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
try {
$queue->doDelete();
@ -384,6 +392,7 @@ class JobQueueFederated extends JobQueue {
}
protected function doWaitForBackups() {
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
try {
$queue->waitForBackups();
@ -395,6 +404,7 @@ class JobQueueFederated extends JobQueue {
protected function doGetPeriodicTasks() {
$tasks = array();
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $partition => $queue ) {
foreach ( $queue->getPeriodicTasks() as $task => $def ) {
$tasks["{$partition}:{$task}"] = $def;
@ -412,9 +422,12 @@ class JobQueueFederated extends JobQueue {
'delayedcount',
'abandonedcount'
);
foreach ( $types as $type ) {
$this->cache->delete( $this->getCacheKey( $type ) );
}
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
$queue->doFlushCaches();
}
@ -422,6 +435,8 @@ class JobQueueFederated extends JobQueue {
public function getAllQueuedJobs() {
$iterator = new AppendIterator();
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
$iterator->append( $queue->getAllQueuedJobs() );
}
@ -431,6 +446,8 @@ class JobQueueFederated extends JobQueue {
public function getAllDelayedJobs() {
$iterator = new AppendIterator();
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
$iterator->append( $queue->getAllDelayedJobs() );
}
@ -445,6 +462,8 @@ class JobQueueFederated extends JobQueue {
protected function doGetSiblingQueuesWithJobs( array $types ) {
$result = array();
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
try {
$nonEmpty = $queue->doGetSiblingQueuesWithJobs( $types );
@ -466,6 +485,8 @@ class JobQueueFederated extends JobQueue {
protected function doGetSiblingQueueSizes( array $types ) {
$result = array();
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
try {
$sizes = $queue->doGetSiblingQueueSizes( $types );
@ -485,12 +506,14 @@ class JobQueueFederated extends JobQueue {
}
public function setTestingPrefix( $key ) {
/** @var JobQueue $queue */
foreach ( $this->partitionQueues as $queue ) {
$queue->setTestingPrefix( $key );
}
}
/**
* @param $property
* @return string
*/
private function getCacheKey( $property ) {

27
includes/job/JobQueueGroup.php
View file

@ -28,13 +28,14 @@
* @since 1.21
*/
class JobQueueGroup {
/** @var Array */
/** @var array */
protected static $instances = array();
/** @var ProcessCacheLRU */
protected $cache;
protected $wiki; // string; wiki ID
/** @var string Wiki ID */
protected $wiki;
/** @var array Map of (bucket => (queue => JobQueue, types => list of types) */
protected $coalescedQueues;
@ -58,7 +59,7 @@ class JobQueueGroup {
}
/**
* @param string $wiki Wiki ID
* @param bool|string $wiki Wiki ID
* @return JobQueueGroup
*/
public static function singleton( $wiki = false ) {
@ -82,7 +83,7 @@ class JobQueueGroup {
/**
* Get the job queue object for a given queue type
*
* @param $type string
* @param string $type
* @return JobQueue
*/
public function get( $type ) {
@ -104,7 +105,7 @@ class JobQueueGroup {
* This inserts the jobs into the queue specified by $wgJobTypeConf
* and updates the aggregate job queue information cache as needed.
*
* @param $jobs Job|array A single Job or a list of Jobs
* @param Job|array $jobs A single Job or a list of Jobs
* @throws MWException
* @return bool
*/
@ -145,8 +146,8 @@ class JobQueueGroup {
* This pops a job off a queue as specified by $wgJobTypeConf and
* updates the aggregate job queue information cache as needed.
*
* @param $qtype integer|string JobQueueGroup::TYPE_DEFAULT or type string
* @param $flags integer Bitfield of JobQueueGroup::USE_* constants
* @param int|string $qtype JobQueueGroup::TYPE_DEFAULT or type string
* @param int $flags Bitfield of JobQueueGroup::USE_* constants
* @return Job|bool Returns false on failure
*/
public function pop( $qtype = self::TYPE_DEFAULT, $flags = 0 ) {
@ -195,7 +196,7 @@ class JobQueueGroup {
/**
* Acknowledge that a job was completed
*
* @param $job Job
* @param Job $job
* @return bool
*/
public function ack( Job $job ) {
@ -206,7 +207,7 @@ class JobQueueGroup {
* Register the "root job" of a given job into the queue for de-duplication.
* This should only be called right *after* all the new jobs have been inserted.
*
* @param $job Job
* @param Job $job
* @return bool
*/
public function deduplicateRootJob( Job $job ) {
@ -255,7 +256,7 @@ class JobQueueGroup {
/**
* Get the list of job types that have non-empty queues
*
* @return Array List of job types that have non-empty queues
* @return array List of job types that have non-empty queues
*/
public function getQueuesWithJobs() {
$types = array();
@ -278,7 +279,7 @@ class JobQueueGroup {
/**
* Get the size of the queus for a list of job types
*
* @return Array Map of (job type => size)
* @return array Map of (job type => size)
*/
public function getQueueSizes() {
$sizeMap = array();
@ -331,7 +332,7 @@ class JobQueueGroup {
* This is only used for performance, such as to avoid spamming
* the queue with many sub-jobs before they actually get run.
*
* @param $type string
* @param string $type
* @return bool
*/
public function isQueueDeprioritized( $type ) {
@ -357,7 +358,7 @@ class JobQueueGroup {
* the defined run period. Concurrent calls to this function will cause tasks
* to be attempted twice, so they may need their own methods of mutual exclusion.
*
* @return integer Number of tasks run
* @return int Number of tasks run
*/
public function executeReadyPeriodicTasks() {
global $wgMemc;

56
includes/job/JobQueueRedis.php
View file

@ -60,12 +60,16 @@ class JobQueueRedis extends JobQueue {
/** @var RedisConnectionPool */
protected $redisPool;
protected $server; // string; server address
protected $compression; // string; compression method to use
/** @var string Server address */
protected $server;
/** @var string Compression method to use */
protected $compression;
const MAX_AGE_PRUNE = 604800; // integer; seconds a job can live once claimed (7 days)
protected $key; // string; key to prefix the queue keys with (used for testing)
/** @var string Key to prefix the queue keys with (used for testing) */
protected $key;
/**
* @params include:
@ -108,7 +112,7 @@ class JobQueueRedis extends JobQueue {
/**
* @see JobQueue::doGetSize()
* @return integer
* @return int
* @throws MWException
*/
protected function doGetSize() {
@ -122,8 +126,8 @@ class JobQueueRedis extends JobQueue {
/**
* @see JobQueue::doGetAcquiredCount()
* @return integer
* @throws MWException
* @return int
* @throws JobQueueError
*/
protected function doGetAcquiredCount() {
if ( $this->claimTTL <= 0 ) {
@ -143,8 +147,8 @@ class JobQueueRedis extends JobQueue {
/**
* @see JobQueue::doGetDelayedCount()
* @return integer
* @throws MWException
* @return int
* @throws JobQueueError
*/
protected function doGetDelayedCount() {
if ( !$this->checkDelay ) {
@ -160,8 +164,8 @@ class JobQueueRedis extends JobQueue {
/**
* @see JobQueue::doGetAbandonedCount()
* @return integer
* @throws MWException
* @return int
* @throws JobQueueError
*/
protected function doGetAbandonedCount() {
if ( $this->claimTTL <= 0 ) {
@ -180,7 +184,7 @@ class JobQueueRedis extends JobQueue {
* @param array $jobs
* @param $flags
* @return bool
* @throws MWException
* @throws JobQueueError
*/
protected function doBatchPush( array $jobs, $flags ) {
// Convert the jobs into field maps (de-duplicated against each other)
@ -234,7 +238,7 @@ class JobQueueRedis extends JobQueue {
/**
* @param RedisConnRef $conn
* @param array $items List of results from JobQueueRedis::getNewJobFields()
* @return integer Number of jobs inserted (duplicates are ignored)
* @return int Number of jobs inserted (duplicates are ignored)
* @throws RedisException
*/
protected function pushBlobs( RedisConnRef $conn, array $items ) {
@ -287,7 +291,7 @@ LUA;
/**
* @see JobQueue::doPop()
* @return Job|bool
* @throws MWException
* @throws JobQueueError
*/
protected function doPop() {
$job = false;
@ -401,7 +405,7 @@ LUA;
* @see JobQueue::doAck()
* @param Job $job
* @return Job|bool
* @throws MWException
* @throws MWException|JobQueueError
*/
protected function doAck( Job $job ) {
if ( !isset( $job->metadata['uuid'] ) ) {
@ -445,7 +449,7 @@ LUA;
* @see JobQueue::doDeduplicateRootJob()
* @param Job $job
* @return bool
* @throws MWException
* @throws MWException|JobQueueError
*/
protected function doDeduplicateRootJob( Job $job ) {
if ( !$job->hasRootJobParams() ) {
@ -473,6 +477,7 @@ LUA;
* @see JobQueue::doIsRootJobOldDuplicate()
* @param Job $job
* @return bool
* @throws JobQueueError
*/
protected function doIsRootJobOldDuplicate( Job $job ) {
if ( !$job->hasRootJobParams() ) {
@ -495,6 +500,7 @@ LUA;
/**
* @see JobQueue::doDelete()
* @return bool
* @throws JobQueueError
*/
protected function doDelete() {
static $props = array( 'l-unclaimed', 'z-claimed', 'z-abandoned',
@ -595,7 +601,7 @@ LUA;
* @param $uid string
* @param $conn RedisConnRef
* @return Job|bool Returns false if the job does not exist
* @throws MWException
* @throws MWException|JobQueueError
*/
public function getJobFromUidInternal( $uid, RedisConnRef $conn ) {
try {
@ -620,8 +626,8 @@ LUA;
/**
* Release any ready delayed jobs into the queue
*
* @return integer Number of jobs released
* @throws MWException
* @return int Number of jobs released
* @throws JobQueueError
*/
public function releaseReadyDelayedJobs() {
$count = 0;
@ -657,8 +663,8 @@ LUA;
/**
* Recycle or destroy any jobs that have been claimed for too long
*
* @return integer Number of jobs recycled/deleted
* @throws MWException
* @return int Number of jobs recycled/deleted
* @throws MWException|JobQueueError
*/
public function recycleAndDeleteStaleJobs() {
if ( $this->claimTTL <= 0 ) { // sanity
@ -732,7 +738,7 @@ LUA;
}
/**
* @return Array
* @return array
*/
protected function doGetPeriodicTasks() {
$tasks = array();
@ -753,7 +759,7 @@ LUA;
}
/**
* @param $job Job
* @param Job $job
* @return array
*/
protected function getNewJobFields( Job $job ) {
@ -829,8 +835,8 @@ LUA;
/**
* Get a connection to the server that handles all sub-queues for this queue
*
* @return Array (server name, Redis instance)
* @throws MWException
* @return RedisConnRef
* @throws JobQueueConnectionError
*/
protected function getConnection() {
$conn = $this->redisPool->getConnection( $this->server );
@ -845,7 +851,7 @@ LUA;
* @param $server string
* @param $conn RedisConnRef
* @param $e RedisException
* @throws MWException
* @throws JobQueueError
*/
protected function throwRedisException( $server, RedisConnRef $conn, $e ) {
$this->redisPool->handleException( $server, $conn, $e );

5
includes/job/aggregator/JobQueueAggregator.php
View file

@ -38,6 +38,7 @@ abstract class JobQueueAggregator {
}
/**
* @throws MWException
* @return JobQueueAggregator
*/
final public static function singleton() {
@ -107,7 +108,7 @@ abstract class JobQueueAggregator {
/**
* Get the list of all of the queues with jobs
*
* @return Array (job type => (list of wiki IDs))
* @return array (job type => (list of wiki IDs))
*/
final public function getAllReadyWikiQueues() {
wfProfileIn( __METHOD__ );
@ -144,7 +145,7 @@ abstract class JobQueueAggregator {
* Get all databases that have a pending job.
* This poll all the queues and is this expensive.
*
* @return Array (job type => (list of wiki IDs))
* @return array (job type => (list of wiki IDs))
*/
protected function findPendingWikiQueues() {
global $wgLocalDatabases;

2
includes/job/aggregator/JobQueueAggregatorRedis.php
View file

@ -32,7 +32,7 @@ class JobQueueAggregatorRedis extends JobQueueAggregator {
/** @var RedisConnectionPool */
protected $redisPool;
/** @var Array List of Redis server addresses */
/** @var array List of Redis server addresses */
protected $servers;
/**

5
includes/job/jobs/DoubleRedirectJob.php
View file

@ -81,6 +81,11 @@ class DoubleRedirectJob extends Job {
JobQueueGroup::singleton()->push( $jobs );
}
/**
* @param Title $title
* @param array|bool $params
* @param int $id
*/
function __construct( $title, $params = false, $id = 0 ) {
parent::__construct( 'fixDoubleRedirect', $title, $params, $id );
$this->reason = $params['reason'];

2
includes/job/jobs/DuplicateJob.php
View file

@ -30,7 +30,7 @@ final class DuplicateJob extends Job {
/**
* Callers should use DuplicateJob::newFromJob() instead
*
* @param $title Title
* @param Title $title
* @param array $params job parameters
* @param $id Integer: job id
*/

2
includes/job/jobs/EnotifNotifyJob.php
View file

@ -38,7 +38,7 @@ class EnotifNotifyJob extends Job {
$editor = User::newFromId( $this->params['editorID'] );
// B/C, only the name might be given.
} else {
# FIXME: newFromName could return false on a badly configured wiki.
# @todo FIXME: newFromName could return false on a badly configured wiki.
$editor = User::newFromName( $this->params['editor'], false );
}
$enotif->actuallyNotifyOnPageChange(

11
includes/job/jobs/HTMLCacheUpdateJob.php
View file

@ -47,7 +47,11 @@ class HTMLCacheUpdateJob extends Job {
/** @var BacklinkCache */
protected $blCache;
protected $rowsPerJob, $rowsPerQuery;
/** @var int Number of rows to update per job, see $wgUpdateRowsPerJob */
protected $rowsPerJob;
/** @var int Number of rows to update per query, see $wgUpdateRowsPerQuery */
protected $rowsPerQuery;
/**
* Construct a job
@ -133,7 +137,7 @@ class HTMLCacheUpdateJob extends Job {
* using a pre-calculated title array which gives the links in that range.
* Queue the resulting jobs.
*
* @param array $titleArray
* @param array|TitleArrayFromResult $titleArray
* @param array $rootJobParams
*/
protected function insertJobsFromTitles( $titleArray, $rootJobParams = array() ) {
@ -145,6 +149,7 @@ class HTMLCacheUpdateJob extends Job {
$jobs = array();
$start = $this->params['start']; # start of the current job
$numTitles = 0;
/** @var Title $title */
foreach ( $titleArray as $title ) {
$id = $title->getArticleID();
# $numTitles is now the number of titles in the current job not
@ -213,7 +218,7 @@ class HTMLCacheUpdateJob extends Job {
/**
* Invalidate an array (or iterator) of Title objects, right now
* @param array $titleArray
* @param array|TitleArrayFromResult $titleArray
*/
protected function invalidateTitles( $titleArray ) {
global $wgUseFileCache, $wgUseSquid;

4
includes/job/jobs/NullJob.php
View file

@ -46,9 +46,9 @@
*/
class NullJob extends Job {
/**
* @param $title Title (can be anything)
* @param Title $title
* @param array $params job parameters (lives, usleep)
* @param $id Integer: job id
* @param int $id Job id
*/
function __construct( $title, $params, $id = 0 ) {
parent::__construct( 'null', $title, $params, $id );

20
includes/job/jobs/RefreshLinksJob.php
View file

@ -34,7 +34,7 @@ class RefreshLinksJob extends Job {
/**
* Run a refreshLinks job
* @return boolean success
* @return bool success
*/
function run() {
$linkCache = LinkCache::singleton();
@ -67,7 +67,7 @@ class RefreshLinksJob extends Job {
}
/**
* @return Array
* @return array
*/
public function getDeduplicationInfo() {
$info = parent::getDeduplicationInfo();
@ -80,9 +80,9 @@ class RefreshLinksJob extends Job {
}
/**
* @param $title Title
* @param $revision Revision
* @param $fname string
* @param Title $title
* @param Revision $revision
* @param string $fname
* @return void
*/
public static function runForTitleInternal( Title $title, Revision $revision, $fname ) {
@ -121,7 +121,7 @@ class RefreshLinksJob2 extends Job {
/**
* Run a refreshLinks2 job
* @return boolean success
* @return bool success
*/
function run() {
global $wgUpdateRowsPerJob;
@ -186,9 +186,9 @@ class RefreshLinksJob2 extends Job {
}
/**
* @param $table string
* @param $masterPos mixed
* @return Array
* @param string $table
* @param mixed $masterPos
* @return array
*/
protected function getSingleTitleJobs( $table, $masterPos ) {
# The "start"/"end" fields are not set for the base jobs
@ -214,7 +214,7 @@ class RefreshLinksJob2 extends Job {
}
/**
* @return Array
* @return array
*/
public function getDeduplicationInfo() {
$info = parent::getDeduplicationInfo();

16
includes/job/jobs/UploadFromUrlJob.php
View file

@ -33,14 +33,10 @@
class UploadFromUrlJob extends Job {
const SESSION_KEYNAME = 'wsUploadFromUrlJobData';
/**
* @var UploadFromUrl
*/
/** @var UploadFromUrl */
public $upload;
/**
* @var User
*/
/** @var User */
protected $user;
public function __construct( $title, $params, $id = 0 ) {
@ -87,6 +83,8 @@ class UploadFromUrlJob extends Job {
# Stash the upload
$key = $this->upload->stashFile();
// @todo FIXME: This has been broken for a while.
// User::leaveUserMessage() does not exist.
if ( $this->params['leaveMessage'] ) {
$this->user->leaveUserMessage(
wfMessage( 'upload-warning-subj' )->text(),
@ -121,17 +119,19 @@ class UploadFromUrlJob extends Job {
* Leave a message on the user talk page or in the session according to
* $params['leaveMessage'].
*
* @param $status Status
* @param Status $status
*/
protected function leaveMessage( $status ) {
if ( $this->params['leaveMessage'] ) {
if ( $status->isGood() ) {
// @todo FIXME: user->leaveUserMessage does not exist.
$this->user->leaveUserMessage( wfMessage( 'upload-success-subj' )->text(),
wfMessage( 'upload-success-msg',
$this->upload->getTitle()->getText(),
$this->params['url']
)->text() );
} else {
// @todo FIXME: user->leaveUserMessage does not exist.
$this->user->leaveUserMessage( wfMessage( 'upload-failure-subj' )->text(),
wfMessage( 'upload-failure-msg',
$status->getWikiText(),
@ -157,7 +157,7 @@ class UploadFromUrlJob extends Job {
*
* @param string $result the result (Success|Warning|Failure)
* @param string $dataKey the key of the extra data
* @param $dataValue Mixed: the extra data itself
* @param mixed $dataValue The extra data itself
*/
protected function storeResultInSession( $result, $dataKey, $dataValue ) {
$session =& self::getSessionData( $this->params['sessionKey'] );