Fix comment on JobQueue::push
[lhc/web/wiklou.git] / includes / job / JobQueue.php
index 6556ee8..52978b8 100644 (file)
  * @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
         */
@@ -106,6 +118,7 @@ abstract class JobQueue {
                if ( !( $obj instanceof self ) ) {
                        throw new MWException( "Class '$class' is not a " . __CLASS__ . " class." );
                }
+
                return $obj;
        }
 
@@ -141,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();
 
@@ -155,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
@@ -177,6 +190,7 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $res = $this->doIsEmpty();
                wfProfileOut( __METHOD__ );
+
                return $res;
        }
 
@@ -192,19 +206,20 @@ 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() {
                wfProfileIn( __METHOD__ );
                $res = $this->doGetSize();
                wfProfileOut( __METHOD__ );
+
                return $res;
        }
 
        /**
         * @see JobQueue::getSize()
-        * @return integer
+        * @return int
         */
        abstract protected function doGetSize();
 
@@ -214,19 +229,20 @@ 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() {
                wfProfileIn( __METHOD__ );
                $res = $this->doGetAcquiredCount();
                wfProfileOut( __METHOD__ );
+
                return $res;
        }
 
        /**
         * @see JobQueue::getAcquiredCount()
-        * @return integer
+        * @return int
         */
        abstract protected function doGetAcquiredCount();
 
@@ -236,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
         */
@@ -244,12 +260,13 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $res = $this->doGetDelayedCount();
                wfProfileOut( __METHOD__ );
+
                return $res;
        }
 
        /**
         * @see JobQueue::getDelayedCount()
-        * @return integer
+        * @return int
         */
        protected function doGetDelayedCount() {
                return 0; // not implemented
@@ -261,31 +278,32 @@ 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() {
                wfProfileIn( __METHOD__ );
                $res = $this->doGetAbandonedCount();
                wfProfileOut( __METHOD__ );
+
                return $res;
        }
 
        /**
         * @see JobQueue::getAbandonedCount()
-        * @return integer
+        * @return int
         */
        protected function doGetAbandonedCount() {
                return 0; // not implemented
        }
 
        /**
-        * Push a single jobs into the queue.
+        * Push one or more jobs into the queue.
         * 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
         */
@@ -299,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 ) ) {
@@ -321,11 +339,14 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $ok = $this->doBatchPush( $jobs, $flags );
                wfProfileOut( __METHOD__ );
+
                return $ok;
        }
 
        /**
         * @see JobQueue::batchPush()
+        * @param array $jobs
+        * @param $flags
         * @return bool
         */
        abstract protected function doBatchPush( array $jobs, $flags );
@@ -335,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;
@@ -358,7 +379,9 @@ abstract class JobQueue {
                                JobQueue::incrStats( 'job-pop-duplicate', $this->type );
                                $job = DuplicateJob::newFromJob( $job ); // convert to a no-op
                        }
-               } catch ( MWException $e ) {} // don't lose jobs over this
+               } catch ( MWException $e ) {
+                       // don't lose jobs over this
+               }
 
                return $job;
        }
@@ -375,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 ) {
@@ -386,11 +409,13 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $ok = $this->doAck( $job );
                wfProfileOut( __METHOD__ );
+
                return $ok;
        }
 
        /**
         * @see JobQueue::ack()
+        * @param Job $job
         * @return bool
         */
        abstract protected function doAck( Job $job );
@@ -422,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 ) {
@@ -433,12 +458,14 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $ok = $this->doDeduplicateRootJob( $job );
                wfProfileOut( __METHOD__ );
+
                return $ok;
        }
 
        /**
         * @see JobQueue::deduplicateRootJob()
-        * @param $job Job
+        * @param Job $job
+        * @throws MWException
         * @return bool
         */
        protected function doDeduplicateRootJob( Job $job ) {
@@ -465,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 ) {
@@ -476,6 +503,7 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $isDuplicate = $this->doIsRootJobOldDuplicate( $job );
                wfProfileOut( __METHOD__ );
+
                return $isDuplicate;
        }
 
@@ -504,6 +532,7 @@ abstract class JobQueue {
         */
        protected function getRootJobCacheKey( $signature ) {
                list( $db, $prefix ) = wfSplitWikiID( $this->wiki );
+
                return wfForeignMemcKey( $db, $prefix, 'jobqueue', $this->type, 'rootjob', $signature );
        }
 
@@ -518,11 +547,13 @@ abstract class JobQueue {
                wfProfileIn( __METHOD__ );
                $res = $this->doDelete();
                wfProfileOut( __METHOD__ );
+
                return $res;
        }
 
        /**
         * @see JobQueue::delete()
+        * @throws MWException
         * @return bool Success
         */
        protected function doDelete() {
@@ -547,7 +578,8 @@ abstract class JobQueue {
         * @see JobQueue::waitForBackups()
         * @return void
         */
-       protected function doWaitForBackups() {}
+       protected function doWaitForBackups() {
+       }
 
        /**
         * Return a map of task names to task definition maps.
@@ -559,19 +591,20 @@ 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();
                foreach ( $tasks as $name => &$def ) {
                        $def['name'] = $name;
                }
+
                return $tasks;
        }
 
        /**
         * @see JobQueue::getPeriodicTasks()
-        * @return Array
+        * @return array
         */
        protected function doGetPeriodicTasks() {
                return array();
@@ -592,7 +625,8 @@ abstract class JobQueue {
         * @see JobQueue::flushCaches()
         * @return void
         */
-       protected function doFlushCaches() {}
+       protected function doFlushCaches() {
+       }
 
        /**
         * Get an iterator to traverse over all available jobs in this queue.
@@ -637,6 +671,7 @@ abstract class JobQueue {
         */
        final public function getSiblingQueuesWithJobs( array $types ) {
                $section = new ProfileSection( __METHOD__ );
+
                return $this->doGetSiblingQueuesWithJobs( $types );
        }
 
@@ -661,6 +696,7 @@ abstract class JobQueue {
         */
        final public function getSiblingQueueSizes( array $types ) {
                $section = new ProfileSection( __METHOD__ );
+
                return $this->doGetSiblingQueueSizes( $types );
        }
 
@@ -678,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 ) {
@@ -689,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
         */
@@ -702,5 +738,8 @@ abstract class JobQueue {
  * @ingroup JobQueue
  * @since 1.22
  */
-class JobQueueError extends MWException {}
-class JobQueueConnectionError extends JobQueueError {}
+class JobQueueError extends MWException {
+}
+
+class JobQueueConnectionError extends JobQueueError {
+}