[Summary view] [Print] [Text view]

   1  <?php
   2  /**
   3   * Job queue task 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   * @defgroup JobQueue JobQueue
  22   */
  23  
  24  /**
  25   * Class to both describe a background job and handle jobs.
  26   * The queue aspects of this class are now deprecated.
  27   * Using the class to push jobs onto queues is deprecated (use JobSpecification).
  28   *
  29   * @ingroup JobQueue
  30   */
  31  abstract class Job implements IJobSpecification {
  32      /** @var string */
  33      public $command;
  34  
  35      /** @var array|bool Array of job parameters or false if none */
  36      public $params;
  37  
  38      /** @var array Additional queue metadata */
  39      public $metadata = array();
  40  
  41      /** @var Title */
  42      protected $title;
  43  
  44      /** @var bool Expensive jobs may set this to true */
  45      protected $removeDuplicates;
  46  
  47      /** @var string Text for error that occurred last */
  48      protected $error;
  49  
  50      /*-------------------------------------------------------------------------
  51       * Abstract functions
  52       *------------------------------------------------------------------------*/
  53  
  54      /**
  55       * Run the job
  56       * @return bool Success
  57       */
  58      abstract public function run();
  59  
  60      /*-------------------------------------------------------------------------
  61       * Static functions
  62       *------------------------------------------------------------------------*/
  63  
  64      /**
  65       * Create the appropriate object to handle a specific job
  66       *
  67       * @param string $command Job command
  68       * @param Title $title Associated title
  69       * @param array|bool $params Job parameters
  70       * @throws MWException
  71       * @return Job
  72       */
  73  	public static function factory( $command, Title $title, $params = false ) {
  74          global $wgJobClasses;
  75          if ( isset( $wgJobClasses[$command] ) ) {
  76              $class = $wgJobClasses[$command];
  77  
  78              return new $class( $title, $params );
  79          }
  80          throw new MWException( "Invalid job command `{$command}`" );
  81      }
  82  
  83      /**
  84       * Batch-insert a group of jobs into the queue.
  85       * This will be wrapped in a transaction with a forced commit.
  86       *
  87       * This may add duplicate at insert time, but they will be
  88       * removed later on, when the first one is popped.
  89       *
  90       * @param array $jobs Array of Job objects
  91       * @return bool
  92       * @deprecated since 1.21
  93       */
  94  	public static function batchInsert( $jobs ) {
  95          JobQueueGroup::singleton()->push( $jobs );
  96          return true;
  97      }
  98  
  99      /**
 100       * Insert a group of jobs into the queue.
 101       *
 102       * Same as batchInsert() but does not commit and can thus
 103       * be rolled-back as part of a larger transaction. However,
 104       * large batches of jobs can cause slave lag.
 105       *
 106       * @param array $jobs Array of Job objects
 107       * @return bool
 108       * @deprecated since 1.21
 109       */
 110  	public static function safeBatchInsert( $jobs ) {
 111          JobQueueGroup::singleton()->push( $jobs, JobQueue::QOS_ATOMIC );
 112          return true;
 113      }
 114  
 115      /**
 116       * Pop a job of a certain type.  This tries less hard than pop() to
 117       * actually find a job; it may be adversely affected by concurrent job
 118       * runners.
 119       *
 120       * @param string $type
 121       * @return Job|bool Returns false if there are no jobs
 122       * @deprecated since 1.21
 123       */
 124  	public static function pop_type( $type ) {
 125          return JobQueueGroup::singleton()->get( $type )->pop();
 126      }
 127  
 128      /**
 129       * Pop a job off the front of the queue.
 130       * This is subject to $wgJobTypesExcludedFromDefaultQueue.
 131       *
 132       * @return Job|bool False if there are no jobs
 133       * @deprecated since 1.21
 134       */
 135  	public static function pop() {
 136          return JobQueueGroup::singleton()->pop();
 137      }
 138  
 139      /*-------------------------------------------------------------------------
 140       * Non-static functions
 141       *------------------------------------------------------------------------*/
 142  
 143      /**
 144       * @param string $command
 145       * @param Title $title
 146       * @param array|bool $params
 147       */
 148  	public function __construct( $command, $title, $params = false ) {
 149          $this->command = $command;
 150          $this->title = $title;
 151          $this->params = $params;
 152  
 153          // expensive jobs may set this to true
 154          $this->removeDuplicates = false;
 155      }
 156  
 157      /**
 158       * @return string
 159       */
 160  	public function getType() {
 161          return $this->command;
 162      }
 163  
 164      /**
 165       * @return Title
 166       */
 167  	public function getTitle() {
 168          return $this->title;
 169      }
 170  
 171      /**
 172       * @return array
 173       */
 174  	public function getParams() {
 175          return $this->params;
 176      }
 177  
 178      /**
 179       * @return int|null UNIX timestamp to delay running this job until, otherwise null
 180       * @since 1.22
 181       */
 182  	public function getReleaseTimestamp() {
 183          return isset( $this->params['jobReleaseTimestamp'] )
 184              ? wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] )
 185              : null;
 186      }
 187  
 188      /**
 189       * @return bool Whether only one of each identical set of jobs should be run
 190       */
 191  	public function ignoreDuplicates() {
 192          return $this->removeDuplicates;
 193      }
 194  
 195      /**
 196       * @return bool Whether this job can be retried on failure by job runners
 197       * @since 1.21
 198       */
 199  	public function allowRetries() {
 200          return true;
 201      }
 202  
 203      /**
 204       * @return int Number of actually "work items" handled in this job
 205       * @see $wgJobBackoffThrottling
 206       * @since 1.23
 207       */
 208  	public function workItemCount() {
 209          return 1;
 210      }
 211  
 212      /**
 213       * Subclasses may need to override this to make duplication detection work.
 214       * The resulting map conveys everything that makes the job unique. This is
 215       * only checked if ignoreDuplicates() returns true, meaning that duplicate
 216       * jobs are supposed to be ignored.
 217       *
 218       * @return array Map of key/values
 219       * @since 1.21
 220       */
 221  	public function getDeduplicationInfo() {
 222          $info = array(
 223              'type' => $this->getType(),
 224              'namespace' => $this->getTitle()->getNamespace(),
 225              'title' => $this->getTitle()->getDBkey(),
 226              'params' => $this->getParams()
 227          );
 228          if ( is_array( $info['params'] ) ) {
 229              // Identical jobs with different "root" jobs should count as duplicates
 230              unset( $info['params']['rootJobSignature'] );
 231              unset( $info['params']['rootJobTimestamp'] );
 232              // Likewise for jobs with different delay times
 233              unset( $info['params']['jobReleaseTimestamp'] );
 234          }
 235  
 236          return $info;
 237      }
 238  
 239      /**
 240       * @see JobQueue::deduplicateRootJob()
 241       * @param string $key A key that identifies the task
 242       * @return array Map of:
 243       *   - rootJobSignature : hash (e.g. SHA1) that identifies the task
 244       *   - rootJobTimestamp : TS_MW timestamp of this instance of the task
 245       * @since 1.21
 246       */
 247  	public static function newRootJobParams( $key ) {
 248          return array(
 249              'rootJobSignature' => sha1( $key ),
 250              'rootJobTimestamp' => wfTimestampNow()
 251          );
 252      }
 253  
 254      /**
 255       * @see JobQueue::deduplicateRootJob()
 256       * @return array
 257       * @since 1.21
 258       */
 259  	public function getRootJobParams() {
 260          return array(
 261              'rootJobSignature' => isset( $this->params['rootJobSignature'] )
 262                  ? $this->params['rootJobSignature']
 263                  : null,
 264              'rootJobTimestamp' => isset( $this->params['rootJobTimestamp'] )
 265                  ? $this->params['rootJobTimestamp']
 266                  : null
 267          );
 268      }
 269  
 270      /**
 271       * @see JobQueue::deduplicateRootJob()
 272       * @return bool
 273       * @since 1.22
 274       */
 275  	public function hasRootJobParams() {
 276          return isset( $this->params['rootJobSignature'] )
 277              && isset( $this->params['rootJobTimestamp'] );
 278      }
 279  
 280      /**
 281       * Insert a single job into the queue.
 282       * @return bool True on success
 283       * @deprecated since 1.21
 284       */
 285  	public function insert() {
 286          JobQueueGroup::singleton()->push( $this );
 287          return true;
 288      }
 289  
 290      /**
 291       * @return string
 292       */
 293  	public function toString() {
 294          $truncFunc = function ( $value ) {
 295              $value = (string)$value;
 296              if ( mb_strlen( $value ) > 1024 ) {
 297                  $value = "string(" . mb_strlen( $value ) . ")";
 298              }
 299              return $value;
 300          };
 301  
 302          $paramString = '';
 303          if ( $this->params ) {
 304              foreach ( $this->params as $key => $value ) {
 305                  if ( $paramString != '' ) {
 306                      $paramString .= ' ';
 307                  }
 308                  if ( is_array( $value ) ) {
 309                      $filteredValue = array();
 310                      foreach ( $value as $k => $v ) {
 311                          if ( is_scalar( $v ) ) {
 312                              $filteredValue[$k] = $truncFunc( $v );
 313                          } else {
 314                              $filteredValue = null;
 315                              break;
 316                          }
 317                      }
 318                      if ( $filteredValue ) {
 319                          $value = FormatJson::encode( $filteredValue );
 320                      } else {
 321                          $value = "array(" . count( $value ) . ")";
 322                      }
 323                  } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
 324                      $value = "object(" . get_class( $value ) . ")";
 325                  }
 326  
 327                  $paramString .= "$key={$truncFunc( $value )}";
 328              }
 329          }
 330  
 331          if ( is_object( $this->title ) ) {
 332              $s = "{$this->command} " . $this->title->getPrefixedDBkey();
 333              if ( $paramString !== '' ) {
 334                  $s .= ' ' . $paramString;
 335              }
 336  
 337              return $s;
 338          } else {
 339              return "{$this->command} $paramString";
 340          }
 341      }
 342  
 343  	protected function setLastError( $error ) {
 344          $this->error = $error;
 345      }
 346  
 347  	public function getLastError() {
 348          return $this->error;
 349      }
 350  }