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 $command String: Job command
63 * @param $title Title: Associated title
64 * @param $params Array|bool: Job parameters
65 * @param $id Int: 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 $jobs array 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 $jobs array 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
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 bool Whether only one of each identical set of jobs should be run
182 public function ignoreDuplicates() {
183 return $this->removeDuplicates
;
187 * @return bool Whether this job can be retried on failure by job runners
189 public function allowRetries() {
194 * Subclasses may need to override this to make duplication detection work
196 * @return Array Map of key/values
198 public function getDeduplicationInfo() {
200 'type' => $this->getType(),
201 'namespace' => $this->getTitle()->getNamespace(),
202 'title' => $this->getTitle()->getDBkey(),
203 'params' => $this->getParams()
205 // Identical jobs with different "root" jobs should count as duplicates
206 if ( is_array( $info['params'] ) ) {
207 unset( $info['params']['rootJobSignature'] );
208 unset( $info['params']['rootJobTimestamp'] );
214 * @param $key string A key that identifies the task
217 public static function newRootJobParams( $key ) {
219 'rootJobSignature' => sha1( $key ),
220 'rootJobTimestamp' => wfTimestampNow()
227 public function getRootJobParams() {
229 'rootJobSignature' => isset( $this->params
['rootJobSignature'] )
230 ?
$this->params
['rootJobSignature']
232 'rootJobTimestamp' => isset( $this->params
['rootJobTimestamp'] )
233 ?
$this->params
['rootJobTimestamp']
239 * Insert a single job into the queue.
240 * @return bool true on success
243 public function insert() {
244 return JobQueueGroup
::singleton()->push( $this );
250 public function toString() {
252 if ( $this->params
) {
253 foreach ( $this->params
as $key => $value ) {
254 if ( $paramString != '' ) {
257 if ( is_array( $value ) ) {
258 $value = "array(" . count( $value ) . ")";
259 } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
260 $value = "object(" . get_class( $value ) . ")";
262 $value = (string)$value;
263 if ( mb_strlen( $value ) > 1024 ) {
264 $value = "string(" . mb_strlen( $value ) . ")";
267 $paramString .= "$key=$value";
271 if ( is_object( $this->title
) ) {
272 $s = "{$this->command} " . $this->title
->getPrefixedDBkey();
273 if ( $paramString !== '' ) {
274 $s .= ' ' . $paramString;
278 return "{$this->command} $paramString";
282 protected function setLastError( $error ) {
283 $this->error
= $error;
286 public function getLastError() {