Merge "Consistent spacing after colon in apihelp"

[lhc/web/wiklou.git] / includes / jobqueue / Job.php

diff --git a/includes/jobqueue/Job.php b/includes/jobqueue/Job.php
index 334d374..f7ef8a9 100644 (file)
--- a/includes/jobqueue/Job.php
+++ b/includes/jobqueue/Job.php
@@ -32,7 +32,7 @@ abstract class Job implements IJobSpecification {
        /** @var string */
        public $command;
 
-       /** @var array|bool Array of job parameters or false if none */
+       /** @var array Array of job parameters */
        public $params;
 
        /** @var array Additional queue metadata */
@@ -58,11 +58,11 @@ abstract class Job implements IJobSpecification {
         *
         * @param string $command Job command
         * @param Title $title Associated title
-        * @param array|bool $params Job parameters
+        * @param array $params Job parameters
         * @throws MWException
         * @return Job
         */
-       public static function factory( $command, Title $title, $params = false ) {
+       public static function factory( $command, Title $title, $params = array() ) {
                global $wgJobClasses;
                if ( isset( $wgJobClasses[$command] ) ) {
                        $class = $wgJobClasses[$command];
@@ -80,7 +80,7 @@ abstract class Job implements IJobSpecification {
        public function __construct( $command, $title, $params = false ) {
                $this->command = $command;
                $this->title = $title;
-               $this->params = $params;
+               $this->params = is_array( $params ) ? $params : array(); // sanity
 
                // expensive jobs may set this to true
                $this->removeDuplicates = false;
@@ -134,6 +134,16 @@ abstract class Job implements IJobSpecification {
                        : null;
        }
 
+       /**
+        * @return int|null UNIX timestamp of when the job was queued, or null
+        * @since 1.26
+        */
+       public function getQueuedTimestamp() {
+               return isset( $this->metadata['timestamp'] )
+                       ? wfTimestampOrNull( TS_UNIX, $this->metadata['timestamp'] )
+                       : null;
+       }
+
        /**
         * Whether the queue should reject insertion of this job if a duplicate exists
         *
@@ -188,21 +198,35 @@ abstract class Job implements IJobSpecification {
                        unset( $info['params']['rootJobTimestamp'] );
                        // Likewise for jobs with different delay times
                        unset( $info['params']['jobReleaseTimestamp'] );
+                       // Queues pack and hash this array, so normalize the order
+                       ksort( $info['params'] );
                }
 
                return $info;
        }
 
        /**
+        * Get "root job" parameters for a task
+        *
+        * This is used to no-op redundant jobs, including child jobs of jobs,
+        * as long as the children inherit the root job parameters. When a job
+        * with root job parameters and "rootJobIsSelf" set is pushed, the
+        * deduplicateRootJob() method is automatically called on it. If the
+        * root job is only virtual and not actually pushed (e.g. the sub-jobs
+        * are inserted directly), then call deduplicateRootJob() directly.
+        *
         * @see JobQueue::deduplicateRootJob()
+        *
         * @param string $key A key that identifies the task
         * @return array Map of:
+        *   - rootJobIsSelf    : true
         *   - rootJobSignature : hash (e.g. SHA1) that identifies the task
         *   - rootJobTimestamp : TS_MW timestamp of this instance of the task
         * @since 1.21
         */
        public static function newRootJobParams( $key ) {
                return array(
+                       'rootJobIsSelf'    => true,
                        'rootJobSignature' => sha1( $key ),
                        'rootJobTimestamp' => wfTimestampNow()
                );
@@ -234,6 +258,14 @@ abstract class Job implements IJobSpecification {
                        && isset( $this->params['rootJobTimestamp'] );
        }
 
+       /**
+        * @see JobQueue::deduplicateRootJob()
+        * @return bool Whether this is job is a root job
+        */
+       public function isRootJob() {
+               return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
+       }
+
        /**
         * Insert a single job into the queue.
         * @return bool True on success