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.
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.
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
21 * @defgroup JobQueue JobQueue
25 * Class to both describe a background job and handle jobs.
26 * The queue aspects of this class are now deprecated.
42 /** @var Array Additional queue metadata */
43 public $metadata = array();
45 /*-------------------------------------------------------------------------
47 *------------------------------------------------------------------------*/
51 * @return boolean success
53 abstract public function run();
55 /*-------------------------------------------------------------------------
57 *------------------------------------------------------------------------*/
60 * Create the appropriate object to handle a specific job
62 * @param string $command Job command
63 * @param $title Title: Associated title
64 * @param array|bool $params Job parameters
65 * @param int $id Job identifier
69 public static function factory( $command, Title
$title, $params = false, $id = 0 ) {
71 if( isset( $wgJobClasses[$command] ) ) {
72 $class = $wgJobClasses[$command];
73 return new $class( $title, $params, $id );
75 throw new MWException( "Invalid job command `{$command}`" );
79 * Batch-insert a group of jobs into the queue.
80 * This will be wrapped in a transaction with a forced commit.
82 * This may add duplicate at insert time, but they will be
83 * removed later on, when the first one is popped.
85 * @param array $jobs of Job objects
89 public static function batchInsert( $jobs ) {
90 return JobQueueGroup
::singleton()->push( $jobs );
94 * Insert a group of jobs into the queue.
96 * Same as batchInsert() but does not commit and can thus
97 * be rolled-back as part of a larger transaction. However,
98 * large batches of jobs can cause slave lag.
100 * @param array $jobs of Job objects
104 public static function safeBatchInsert( $jobs ) {
105 return JobQueueGroup
::singleton()->push( $jobs, JobQueue
::QoS_Atomic
);
109 * Pop a job of a certain type. This tries less hard than pop() to
110 * actually find a job; it may be adversely affected by concurrent job
113 * @param $type string
114 * @return Job|bool Returns false if there are no jobs
117 public static function pop_type( $type ) {
118 return JobQueueGroup
::singleton()->get( $type )->pop();
122 * Pop a job off the front of the queue.
123 * This is subject to $wgJobTypesExcludedFromDefaultQueue.
125 * @return Job or false if there's no jobs
128 public static function pop() {
129 return JobQueueGroup
::singleton()->pop();
132 /*-------------------------------------------------------------------------
133 * Non-static functions
134 *------------------------------------------------------------------------*/
139 * @param $params array|bool
142 public function __construct( $command, $title, $params = false, $id = 0 ) {
143 $this->command
= $command;
144 $this->title
= $title;
145 $this->params
= $params;
148 $this->removeDuplicates
= false; // expensive jobs may set this to true
152 * @return integer May be 0 for jobs stored outside the DB
154 public function getId() {
161 public function getType() {
162 return $this->command
;
168 public function getTitle() {
175 public function getParams() {
176 return $this->params
;
180 * @return integer|null UNIX timestamp to delay running this job until, otherwise null
183 public function getReleaseTimestamp() {
184 return isset( $this->params
['jobReleaseTimestamp'] )
185 ?
wfTimestampOrNull( TS_UNIX
, $this->params
['jobReleaseTimestamp'] )
190 * @return bool Whether only one of each identical set of jobs should be run
192 public function ignoreDuplicates() {
193 return $this->removeDuplicates
;
197 * @return bool Whether this job can be retried on failure by job runners
199 public function allowRetries() {
204 * Subclasses may need to override this to make duplication detection work
206 * @return Array Map of key/values
208 public function getDeduplicationInfo() {
210 'type' => $this->getType(),
211 'namespace' => $this->getTitle()->getNamespace(),
212 'title' => $this->getTitle()->getDBkey(),
213 'params' => $this->getParams()
215 if ( is_array( $info['params'] ) ) {
216 // Identical jobs with different "root" jobs should count as duplicates
217 unset( $info['params']['rootJobSignature'] );
218 unset( $info['params']['rootJobTimestamp'] );
219 // Likewise for jobs with different delay times
220 unset( $info['params']['jobReleaseTimestamp'] );
226 * @param string $key A key that identifies the task
229 public static function newRootJobParams( $key ) {
231 'rootJobSignature' => sha1( $key ),
232 'rootJobTimestamp' => wfTimestampNow()
239 public function getRootJobParams() {
241 'rootJobSignature' => isset( $this->params
['rootJobSignature'] )
242 ?
$this->params
['rootJobSignature']
244 'rootJobTimestamp' => isset( $this->params
['rootJobTimestamp'] )
245 ?
$this->params
['rootJobTimestamp']
251 * Insert a single job into the queue.
252 * @return bool true on success
255 public function insert() {
256 return JobQueueGroup
::singleton()->push( $this );
262 public function toString() {
264 if ( $this->params
) {
265 foreach ( $this->params
as $key => $value ) {
266 if ( $paramString != '' ) {
269 if ( is_array( $value ) ) {
270 $value = "array(" . count( $value ) . ")";
271 } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
272 $value = "object(" . get_class( $value ) . ")";
274 $value = (string)$value;
275 if ( mb_strlen( $value ) > 1024 ) {
276 $value = "string(" . mb_strlen( $value ) . ")";
279 $paramString .= "$key=$value";
283 if ( is_object( $this->title
) ) {
284 $s = "{$this->command} " . $this->title
->getPrefixedDBkey();
285 if ( $paramString !== '' ) {
286 $s .= ' ' . $paramString;
290 return "{$this->command} $paramString";
294 protected function setLastError( $error ) {
295 $this->error
= $error;
298 public function getLastError() {