Merge "Add method parameter type documentation"

[lhc/web/wiklou.git] / includes / job / JobQueue.php

diff --git a/includes/job/JobQueue.php b/includes/job/JobQueue.php
index 3295c24..81e7b73 100644 (file)
--- a/includes/job/JobQueue.php
+++ b/includes/job/JobQueue.php
@@ -168,7 +168,7 @@ abstract class JobQueue {
         * not distinguishable from the race condition between isEmpty() and pop().
         *
         * @return bool
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function isEmpty() {
                wfProfileIn( __METHOD__ );
@@ -190,7 +190,7 @@ abstract class JobQueue {
         * If caching is used, this number might be out of date for a minute.
         *
         * @return integer
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function getSize() {
                wfProfileIn( __METHOD__ );
@@ -212,7 +212,7 @@ abstract class JobQueue {
         * If caching is used, this number might be out of date for a minute.
         *
         * @return integer
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function getAcquiredCount() {
                wfProfileIn( __METHOD__ );
@@ -234,7 +234,7 @@ abstract class JobQueue {
         * If caching is used, this number might be out of date for a minute.
         *
         * @return integer
-        * @throws MWException
+        * @throws JobQueueError
         * @since 1.22
         */
        final public function getDelayedCount() {
@@ -259,7 +259,7 @@ abstract class JobQueue {
         * If caching is used, this number might be out of date for a minute.
         *
         * @return integer
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function getAbandonedCount() {
                wfProfileIn( __METHOD__ );
@@ -284,7 +284,7 @@ abstract class JobQueue {
         * @param $jobs Job|Array
         * @param $flags integer Bitfield (supports JobQueue::QOS_ATOMIC)
         * @return bool Returns false on failure
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function push( $jobs, $flags = 0 ) {
                return $this->batchPush( is_array( $jobs ) ? $jobs : array( $jobs ), $flags );
@@ -298,7 +298,7 @@ abstract class JobQueue {
         * @param array $jobs List of Jobs
         * @param $flags integer Bitfield (supports JobQueue::QOS_ATOMIC)
         * @return bool Returns false on failure
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function batchPush( array $jobs, $flags = 0 ) {
                if ( !count( $jobs ) ) {
@@ -333,7 +333,7 @@ abstract class JobQueue {
         * Outside callers should use JobQueueGroup::pop() instead of this function.
         *
         * @return Job|bool Returns false if there are no jobs
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function pop() {
                global $wgJobClasses;
@@ -374,7 +374,7 @@ abstract class JobQueue {
         *
         * @param $job Job
         * @return bool
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function ack( Job $job ) {
                if ( $job->getType() !== $this->type ) {
@@ -421,7 +421,7 @@ abstract class JobQueue {
         *
         * @param $job Job
         * @return bool
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function deduplicateRootJob( Job $job ) {
                if ( $job->getType() !== $this->type ) {
@@ -466,7 +466,7 @@ abstract class JobQueue {
         *
         * @param $job Job
         * @return bool
-        * @throws MWException
+        * @throws JobQueueError
         */
        final protected function isRootJobOldDuplicate( Job $job ) {
                if ( $job->getType() !== $this->type ) {
@@ -511,7 +511,7 @@ abstract class JobQueue {
         * Deleted all unclaimed and delayed jobs from the queue
         *
         * @return bool Success
-        * @throws MWException
+        * @throws JobQueueError
         * @since 1.22
         */
        final public function delete() {
@@ -535,7 +535,7 @@ abstract class JobQueue {
         * This does nothing for certain queue classes.
         *
         * @return void
-        * @throws MWException
+        * @throws JobQueueError
         */
        final public function waitForBackups() {
                wfProfileIn( __METHOD__ );
@@ -597,25 +597,82 @@ abstract class JobQueue {
        /**
         * Get an iterator to traverse over all available jobs in this queue.
         * This does not include jobs that are currently acquired or delayed.
-        * This should only be called on a queue that is no longer being popped.
+        * Note: results may be stale if the queue is concurrently modified.
         *
         * @return Iterator
-        * @throws MWException
+        * @throws JobQueueError
         */
        abstract public function getAllQueuedJobs();
 
        /**
         * Get an iterator to traverse over all delayed jobs in this queue.
-        * This should only be called on a queue that is no longer being popped.
+        * Note: results may be stale if the queue is concurrently modified.
         *
         * @return Iterator
-        * @throws MWException
+        * @throws JobQueueError
         * @since 1.22
         */
        public function getAllDelayedJobs() {
                return new ArrayIterator( array() ); // not implemented
        }
 
+       /**
+        * Do not use this function outside of JobQueue/JobQueueGroup
+        *
+        * @return string
+        * @since 1.22
+        */
+       public function getCoalesceLocationInternal() {
+               return null;
+       }
+
+       /**
+        * Check whether each of the given queues are empty.
+        * This is used for batching checks for queues stored at the same place.
+        *
+        * @param array $types List of queues types
+        * @return array|null (list of non-empty queue types) or null if unsupported
+        * @throws MWException
+        * @since 1.22
+        */
+       final public function getSiblingQueuesWithJobs( array $types ) {
+               $section = new ProfileSection( __METHOD__ );
+               return $this->doGetSiblingQueuesWithJobs( $types );
+       }
+
+       /**
+        * @see JobQueue::getSiblingQueuesWithJobs()
+        * @param array $types List of queues types
+        * @return array|null (list of queue types) or null if unsupported
+        */
+       protected function doGetSiblingQueuesWithJobs( array $types ) {
+               return null; // not supported
+       }
+
+       /**
+        * Check the size of each of the given queues.
+        * For queues not served by the same store as this one, 0 is returned.
+        * This is used for batching checks for queues stored at the same place.
+        *
+        * @param array $types List of queues types
+        * @return array|null (job type => whether queue is empty) or null if unsupported
+        * @throws MWException
+        * @since 1.22
+        */
+       final public function getSiblingQueueSizes( array $types ) {
+               $section = new ProfileSection( __METHOD__ );
+               return $this->doGetSiblingQueueSizes( $types );
+       }
+
+       /**
+        * @see JobQueue::getSiblingQueuesSize()
+        * @param array $types List of queues types
+        * @return array|null (list of queue types) or null if unsupported
+        */
+       protected function doGetSiblingQueueSizes( array $types ) {
+               return null; // not supported
+       }
+
        /**
         * Call wfIncrStats() for the queue overall and for the queue type
         *
@@ -640,3 +697,10 @@ abstract class JobQueue {
                throw new MWException( "Queue namespacing not supported for this queue type." );
        }
 }
+
+/**
+ * @ingroup JobQueue
+ * @since 1.22
+ */
+class JobQueueError extends MWException {}
+class JobQueueConnectionError extends JobQueueError {}