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  */
  22
  23 /**
  24  * Job queue task description interface
  25  *
  26  * @ingroup JobQueue
  27  * @since 1.23
  28  */
  29 interface IJobSpecification {
  30         /**
  31          * @return string Job type
  32          */
  33         public function getType();
  34
  35         /**
  36          * @return array
  37          */
  38         public function getParams();
  39
  40         /**
  41          * @return int|null UNIX timestamp to delay running this job until, otherwise null
  42          */
  43         public function getReleaseTimestamp();
  44
  45         /**
  46          * @return bool Whether only one of each identical set of jobs should be run
  47          */
  48         public function ignoreDuplicates();
  49
  50         /**
  51          * Subclasses may need to override this to make duplication detection work.
  52          * The resulting map conveys everything that makes the job unique. This is
  53          * only checked if ignoreDuplicates() returns true, meaning that duplicate
  54          * jobs are supposed to be ignored.
  55          *
  56          * @return array Map of key/values
  57          */
  58         public function getDeduplicationInfo();
  59
  60         /**
  61          * @see JobQueue::deduplicateRootJob()
  62          * @return array
  63          * @since 1.26
  64          */
  65         public function getRootJobParams();
  66
  67         /**
  68          * @see JobQueue::deduplicateRootJob()
  69          * @return bool
  70          * @since 1.22
  71          */
  72         public function hasRootJobParams();
  73
  74         /**
  75          * @see JobQueue::deduplicateRootJob()
  76          * @return bool Whether this is job is a root job
  77          */
  78         public function isRootJob();
  79
  80         /**
  81          * @return Title Descriptive title (this can simply be informative)
  82          */
  83         public function getTitle();
  84 }
  85
  86 /**
  87  * Job queue task description base code
  88  *
  89  * Example usage:
  90  * @code
  91  * $job = new JobSpecification(
  92  *              'null',
  93  *              array( 'lives' => 1, 'usleep' => 100, 'pi' => 3.141569 ),
  94  *              array( 'removeDuplicates' => 1 ),
  95  *              Title::makeTitle( NS_SPECIAL, 'nullity' )
  96  * );
  97  * JobQueueGroup::singleton()->push( $job )
  98  * @endcode
  99  *
 100  * @ingroup JobQueue
 101  * @since 1.23
 102  */
 103 class JobSpecification implements IJobSpecification {
 104         /** @var string */
 105         protected $type;
 106
 107         /** @var array Array of job parameters or false if none */
 108         protected $params;
 109
 110         /** @var Title */
 111         protected $title;
 112
 113         /** @var array */
 114         protected $opts;
 115
 116         /**
 117          * @param string $type
 118          * @param array $params Map of key/values
 119          * @param array $opts Map of key/values; includes 'removeDuplicates'
 120          * @param Title|null $title Optional descriptive title
 121          */
 122         public function __construct(
 123                 $type, array $params, array $opts = [], Title $title = null
 124         ) {
 125                 $this->validateParams( $params );
 126                 $this->validateParams( $opts );
 127
 128                 $this->type = $type;
 129                 $this->params = $params;
 130                 $this->title = $title ?: Title::makeTitle( NS_SPECIAL, 'Badtitle/' . static::class );
 131                 $this->opts = $opts;
 132         }
 133
 134         /**
 135          * @param array $params
 136          */
 137         protected function validateParams( array $params ) {
 138                 foreach ( $params as $p => $v ) {
 139                         if ( is_array( $v ) ) {
 140                                 $this->validateParams( $v );
 141                         } elseif ( !is_scalar( $v ) && $v !== null ) {
 142                                 throw new UnexpectedValueException( "Job parameter $p is not JSON serializable." );
 143                         }
 144                 }
 145         }
 146
 147         public function getType() {
 148                 return $this->type;
 149         }
 150
 151         public function getTitle() {
 152                 return $this->title;
 153         }
 154
 155         public function getParams() {
 156                 return $this->params;
 157         }
 158
 159         public function getReleaseTimestamp() {
 160                 return isset( $this->params['jobReleaseTimestamp'] )
 161                         ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
 162                         : null;
 163         }
 164
 165         public function ignoreDuplicates() {
 166                 return !empty( $this->opts['removeDuplicates'] );
 167         }
 168
 169         public function getDeduplicationInfo() {
 170                 $info = [
 171                         'type' => $this->getType(),
 172                         'namespace' => $this->getTitle()->getNamespace(),
 173                         'title' => $this->getTitle()->getDBkey(),
 174                         'params' => $this->getParams()
 175                 ];
 176                 if ( is_array( $info['params'] ) ) {
 177                         // Identical jobs with different "root" jobs should count as duplicates
 178                         unset( $info['params']['rootJobSignature'] );
 179                         unset( $info['params']['rootJobTimestamp'] );
 180                         // Likewise for jobs with different delay times
 181                         unset( $info['params']['jobReleaseTimestamp'] );
 182                 }
 183
 184                 return $info;
 185         }
 186
 187         public function getRootJobParams() {
 188                 return [
 189                         'rootJobSignature' => $this->params['rootJobSignature'] ?? null,
 190                         'rootJobTimestamp' => $this->params['rootJobTimestamp'] ?? null
 191                 ];
 192         }
 193
 194         public function hasRootJobParams() {
 195                 return isset( $this->params['rootJobSignature'] )
 196                         && isset( $this->params['rootJobTimestamp'] );
 197         }
 198
 199         public function isRootJob() {
 200                 return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
 201         }
 202
 203         /**
 204          * @return array Field/value map that can immediately be serialized
 205          * @since 1.25
 206          */
 207         public function toSerializableArray() {
 208                 return [
 209                         'type'   => $this->type,
 210                         'params' => $this->params,
 211                         'opts'   => $this->opts,
 212                         'title'  => [
 213                                 'ns'  => $this->title->getNamespace(),
 214                                 'key' => $this->title->getDBkey()
 215                         ]
 216                 ];
 217         }
 218
 219         /**
 220          * @param array $map Field/value map
 221          * @return JobSpecification
 222          * @since 1.25
 223          */
 224         public static function newFromArray( array $map ) {
 225                 $title = Title::makeTitle( $map['title']['ns'], $map['title']['key'] );
 226
 227                 return new self( $map['type'], $map['params'], $map['opts'], $title );
 228         }
 229 }