[Summary view] [Print] [Text view]

   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  }