includes/jobqueue/JobSpecification.php

   1 <?php
   2 /**
   3  * Job queue task description base code.
   4  *
   5  * This program is free software; you can redistribute it and/or modify
   6  * it under the terms of the GNU General Public License as published by
   7  * the Free Software Foundation; either version 2 of the License, or
   8  * (at your option) any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; if not, write to the Free Software Foundation, Inc.,
  17  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  * http://www.gnu.org/copyleft/gpl.html
  19  *
  20  * @file
  21  * @ingroup JobQueue
  22  */
  23
  24 /**
  25  * Job queue task description interface
  26  *
  27  * @ingroup JobQueue
  28  * @since 1.23
  29  */
  30 interface IJobSpecification {
  31         /**
  32          * @return string Job type
  33          */
  34         public function getType();
  35
  36         /**
  37          * @return array
  38          */
  39         public function getParams();
  40
  41         /**
  42          * @return int|null UNIX timestamp to delay running this job until, otherwise null
  43          */
  44         public function getReleaseTimestamp();
  45
  46         /**
  47          * @return bool Whether only one of each identical set of jobs should be run
  48          */
  49         public function ignoreDuplicates();
  50
  51         /**
  52          * Subclasses may need to override this to make duplication detection work.
  53          * The resulting map conveys everything that makes the job unique. This is
  54          * only checked if ignoreDuplicates() returns true, meaning that duplicate
  55          * jobs are supposed to be ignored.
  56          *
  57          * @return array Map of key/values
  58          */
  59         public function getDeduplicationInfo();
  60
  61         /**
  62          * @return Title Descriptive title (this can simply be informative)
  63          */
  64         public function getTitle();
  65 }
  66
  67 /**
  68  * Job queue task description base code
  69  *
  70  * Example usage:
  71  * <code>
  72  * $job = new JobSpecification(
  73  *              'null',
  74  *              array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
  75  *              array( 'removeDuplicates' => 1 ),
  76  *              Title::makeTitle( NS_SPECIAL, 'nullity' )
  77  * );
  78  * JobQueueGroup::singleton()->push( $job )
  79  * </code>
  80  *
  81  * @ingroup JobQueue
  82  * @since 1.23
  83  */
  84 class JobSpecification implements IJobSpecification {
  85         /** @var string */
  86         protected $type;
  87
  88         /** @var array Array of job parameters or false if none */
  89         protected $params;
  90
  91         /** @var Title */
  92         protected $title;
  93
  94         /** @var bool Expensive jobs may set this to true */
  95         protected $ignoreDuplicates;
  96
  97         /**
  98          * @param string $type
  99          * @param array $params Map of key/values
 100          * @param array $opts Map of key/values
 101          * @param Title $title Optional descriptive title
 102          */
 103         public function __construct(
 104                 $type, array $params, array $opts = array(), Title $title = null
 105         ) {
 106                 $this->validateParams( $params );
 107
 108                 $this->type = $type;
 109                 $this->params = $params;
 110                 $this->title = $title ?: Title::newMainPage();
 111                 $this->ignoreDuplicates = !empty( $opts['removeDuplicates'] );
 112         }
 113
 114         /**
 115          * @param array $params
 116          */
 117         protected function validateParams( array $params ) {
 118                 foreach ( $params as $p => $v ) {
 119                         if ( is_array( $v ) ) {
 120                                 $this->validateParams( $v );
 121                         } elseif ( !is_scalar( $v ) && $v !== null ) {
 122                                 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
 123                         }
 124                 }
 125         }
 126
 127         /**
 128          * @return string
 129          */
 130         public function getType() {
 131                 return $this->type;
 132         }
 133
 134         /**
 135          * @return Title
 136          */
 137         public function getTitle() {
 138                 return $this->title;
 139         }
 140
 141         /**
 142          * @return array
 143          */
 144         public function getParams() {
 145                 return $this->params;
 146         }
 147
 148         /**
 149          * @return int|null UNIX timestamp to delay running this job until, otherwise null
 150          */
 151         public function getReleaseTimestamp() {
 152                 return isset( $this->params['jobReleaseTimestamp'] )
 153                         ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
 154                         : null;
 155         }
 156
 157         /**
 158          * @return bool Whether only one of each identical set of jobs should be run
 159          */
 160         public function ignoreDuplicates() {
 161                 return $this->ignoreDuplicates;
 162         }
 163
 164         /**
 165          * Subclasses may need to override this to make duplication detection work.
 166          * The resulting map conveys everything that makes the job unique. This is
 167          * only checked if ignoreDuplicates() returns true, meaning that duplicate
 168          * jobs are supposed to be ignored.
 169          *
 170          * @return array Map of key/values
 171          */
 172         public function getDeduplicationInfo() {
 173                 $info = array(
 174                         'type' => $this->getType(),
 175                         'namespace' => $this->getTitle()->getNamespace(),
 176                         'title' => $this->getTitle()->getDBkey(),
 177                         'params' => $this->getParams()
 178                 );
 179                 if ( is_array( $info['params'] ) ) {
 180                         // Identical jobs with different "root" jobs should count as duplicates
 181                         unset( $info['params']['rootJobSignature'] );
 182                         unset( $info['params']['rootJobTimestamp'] );
 183                         // Likewise for jobs with different delay times
 184                         unset( $info['params']['jobReleaseTimestamp'] );
 185                 }
 186
 187                 return $info;
 188         }
 189 }