MediaWiki  master
Job.php
Go to the documentation of this file.
1 <?php
28 
40 abstract class Job implements RunnableJob {
42  public $command;
43 
45  public $params;
46 
48  public $metadata = [];
49 
51  protected $title;
52 
54  protected $removeDuplicates = false;
55 
57  protected $error;
58 
60  protected $teardownCallbacks = [];
61 
63  protected $executionFlags = 0;
64 
75  public static function factory( $command, $params = [] ) {
76  $factory = MediaWikiServices::getInstance()->getJobFactory();
77 
78  // FIXME: fix handling for legacy signature!
79  // @phan-suppress-next-line PhanParamTooFewUnpack one argument is known to be present.
80  return $factory->newJob( ...func_get_args() );
81  }
82 
89  public function __construct( $command, $params = null ) {
90  if ( $params instanceof PageReference ) {
91  // Backwards compatibility for old signature ($command, $title, $params)
92  $page = $params;
93  $params = func_num_args() >= 3 ? func_get_arg( 2 ) : [];
94  } else {
95  // Newer jobs may choose to not have a top-level title (e.g. GenericParameterJob)
96  $page = null;
97  }
98 
99  if ( !is_array( $params ) ) {
100  throw new InvalidArgumentException( '$params must be an array' );
101  }
102 
103  if (
104  $page &&
105  !isset( $params['namespace'] ) &&
106  !isset( $params['title'] )
107  ) {
108  // When constructing this class for submitting to the queue,
109  // normalise the $page arg of old job classes as part of $params.
110  $params['namespace'] = $page->getNamespace();
111  $params['title'] = $page->getDBkey();
112  }
113 
114  $this->command = $command;
115  $this->params = $params + [ 'requestId' => WebRequest::getRequestId() ];
116 
117  if ( $this->title === null ) {
118  // Set this field for access via getTitle().
119  $this->title = ( isset( $params['namespace'] ) && isset( $params['title'] ) )
120  ? Title::makeTitle( $params['namespace'], $params['title'] )
121  // GenericParameterJob classes without namespace/title params
122  // should not use getTitle(). Set an invalid title as placeholder.
123  : Title::makeTitle( NS_SPECIAL, '' );
124  }
125  }
126 
131  public function hasExecutionFlag( $flag ) {
132  return ( $this->executionFlags & $flag ) === $flag;
133  }
134 
139  public function getType() {
140  return $this->command;
141  }
142 
146  final public function getTitle() {
147  return $this->title;
148  }
149 
154  public function getParams() {
155  return $this->params;
156  }
157 
164  public function getMetadata( $field = null ) {
165  if ( $field === null ) {
166  return $this->metadata;
167  }
168 
169  return $this->metadata[$field] ?? null;
170  }
171 
179  public function setMetadata( $field, $value ) {
180  $old = $this->getMetadata( $field );
181  if ( $value === null ) {
182  unset( $this->metadata[$field] );
183  } else {
184  $this->metadata[$field] = $value;
185  }
186 
187  return $old;
188  }
189 
195  public function getReleaseTimestamp() {
196  $time = wfTimestampOrNull( TS_UNIX, $this->params['jobReleaseTimestamp'] ?? null );
197  return $time ? (int)$time : null;
198  }
199 
204  public function getQueuedTimestamp() {
205  $time = wfTimestampOrNull( TS_UNIX, $this->metadata['timestamp'] ?? null );
206  return $time ? (int)$time : null;
207  }
208 
213  public function getRequestId() {
214  return $this->params['requestId'] ?? null;
215  }
216 
221  public function getReadyTimestamp() {
222  return $this->getReleaseTimestamp() ?: $this->getQueuedTimestamp();
223  }
224 
238  public function ignoreDuplicates() {
240  }
241 
246  public function allowRetries() {
247  return true;
248  }
249 
254  public function workItemCount() {
255  return 1;
256  }
257 
268  public function getDeduplicationInfo() {
269  $info = [
270  'type' => $this->getType(),
271  'params' => $this->getParams()
272  ];
273  if ( is_array( $info['params'] ) ) {
274  // Identical jobs with different "root" jobs should count as duplicates
275  unset( $info['params']['rootJobSignature'] );
276  unset( $info['params']['rootJobTimestamp'] );
277  // Likewise for jobs with different delay times
278  unset( $info['params']['jobReleaseTimestamp'] );
279  // Identical jobs from different requests should count as duplicates
280  unset( $info['params']['requestId'] );
281  // Queues pack and hash this array, so normalize the order
282  ksort( $info['params'] );
283  }
284 
285  return $info;
286  }
287 
307  public static function newRootJobParams( $key ) {
308  return [
309  'rootJobIsSelf' => true,
310  'rootJobSignature' => sha1( $key ),
311  'rootJobTimestamp' => wfTimestampNow()
312  ];
313  }
314 
321  public function getRootJobParams() {
322  return [
323  'rootJobSignature' => $this->params['rootJobSignature'] ?? null,
324  'rootJobTimestamp' => $this->params['rootJobTimestamp'] ?? null
325  ];
326  }
327 
334  public function hasRootJobParams() {
335  return isset( $this->params['rootJobSignature'] )
336  && isset( $this->params['rootJobTimestamp'] );
337  }
338 
344  public function isRootJob() {
345  return $this->hasRootJobParams() && !empty( $this->params['rootJobIsSelf'] );
346  }
347 
354  protected function addTeardownCallback( $callback ) {
355  $this->teardownCallbacks[] = $callback;
356  }
357 
362  public function teardown( $status ) {
363  foreach ( $this->teardownCallbacks as $callback ) {
364  call_user_func( $callback, $status );
365  }
366  }
367 
372  public function toString() {
373  $paramString = '';
374  if ( $this->params ) {
375  foreach ( $this->params as $key => $value ) {
376  if ( $paramString != '' ) {
377  $paramString .= ' ';
378  }
379  if ( is_array( $value ) ) {
380  $filteredValue = [];
381  foreach ( $value as $k => $v ) {
382  $json = FormatJson::encode( $v );
383  if ( $json === false || mb_strlen( $json ) > 512 ) {
384  $filteredValue[$k] = gettype( $v ) . '(...)';
385  } else {
386  $filteredValue[$k] = $v;
387  }
388  }
389  if ( count( $filteredValue ) <= 10 ) {
390  $value = FormatJson::encode( $filteredValue );
391  } else {
392  $value = "array(" . count( $value ) . ")";
393  }
394  } elseif ( is_object( $value ) && !method_exists( $value, '__toString' ) ) {
395  $value = "object(" . get_class( $value ) . ")";
396  }
397 
398  $flatValue = (string)$value;
399  if ( mb_strlen( $flatValue ) > 1024 ) {
400  $flatValue = "string(" . mb_strlen( $value ) . ")";
401  }
402 
403  // Remove newline characters from the value, since
404  // newlines indicate new job lines in log files
405  $flatValue = preg_replace( '/\s+/', ' ', $flatValue );
406 
407  $paramString .= "$key={$flatValue}";
408  }
409  }
410 
411  $metaString = '';
412  foreach ( $this->metadata as $key => $value ) {
413  if ( is_scalar( $value ) && mb_strlen( $value ) < 1024 ) {
414  $metaString .= ( $metaString ? ",$key=$value" : "$key=$value" );
415  }
416  }
417 
418  $s = $this->command;
419  if ( is_object( $this->title ) ) {
420  $s .= ' ' . $this->title->getPrefixedDBkey();
421  }
422  if ( $paramString != '' ) {
423  $s .= " $paramString";
424  }
425  if ( $metaString != '' ) {
426  $s .= " ($metaString)";
427  }
428 
429  return $s;
430  }
431 
432  protected function setLastError( $error ) {
433  $this->error = $error;
434  }
435 
440  public function getLastError() {
441  return $this->error;
442  }
443 }
const NS_SPECIAL
Definition: Defines.php:53
wfTimestampOrNull( $outputtype=TS_UNIX, $ts=null)
Return a formatted timestamp, or null if input is null.
wfTimestampNow()
Convenience function; returns MediaWiki timestamp for the present time.
static encode( $value, $pretty=false, $escaping=0)
Returns the JSON representation of a value.
Definition: FormatJson.php:98
Class to both describe a background job and handle jobs.
Definition: Job.php:40
hasRootJobParams()
Definition: Job.php:334
string $command
Definition: Job.php:42
setMetadata( $field, $value)
Definition: Job.php:179
getParams()
array Parameters that specify sources, targets, and options for execution
Definition: Job.php:154
getReadyTimestamp()
int|null UNIX timestamp of when the job was runnable, or null 1.26
Definition: Job.php:221
toString()
string Debugging string describing the job
Definition: Job.php:372
getType()
string Job type that defines what sort of changes this job makes
Definition: Job.php:139
Title $title
Definition: Job.php:51
getRootJobParams()
Definition: Job.php:321
hasExecutionFlag( $flag)
JOB_* class constant bool 1.31
Definition: Job.php:131
callable[] $teardownCallbacks
Definition: Job.php:60
getQueuedTimestamp()
Definition: Job.php:204
bool $removeDuplicates
Expensive jobs may set this to true.
Definition: Job.php:54
setLastError( $error)
Definition: Job.php:432
getMetadata( $field=null)
Definition: Job.php:164
teardown( $status)
Definition: Job.php:362
isRootJob()
Definition: Job.php:344
addTeardownCallback( $callback)
Definition: Job.php:354
array $params
Array of job parameters.
Definition: Job.php:45
getTitle()
Definition: Job.php:146
array $metadata
Additional queue metadata.
Definition: Job.php:48
static factory( $command, $params=[])
Create the appropriate object to handle a specific job.
Definition: Job.php:75
int $executionFlags
Bitfield of JOB_* class constants.
Definition: Job.php:63
workItemCount()
Definition: Job.php:254
getRequestId()
string|null Id of the request that created this job. Follows jobs recursively, allowing to track the ...
Definition: Job.php:213
static newRootJobParams( $key)
Get "root job" parameters for a task.
Definition: Job.php:307
getDeduplicationInfo()
Subclasses may need to override this to make duplication detection work.
Definition: Job.php:268
getReleaseTimestamp()
Definition: Job.php:195
ignoreDuplicates()
Whether the queue should reject insertion of this job if a duplicate exists.
Definition: Job.php:238
getLastError()
string
Definition: Job.php:440
string $error
Text for error that occurred last.
Definition: Job.php:57
allowRetries()
bool Whether this job can be retried on failure by job runners 1.21
Definition: Job.php:246
__construct( $command, $params=null)
Definition: Job.php:89
Service locator for MediaWiki core services.
The WebRequest class encapsulates getting at data passed in the URL or via a POSTed form stripping il...
Definition: WebRequest.php:50
Represents a title within MediaWiki.
Definition: Title.php:76
Interface for objects (potentially) representing a page that can be viewable and linked to on a wiki.
Job that has a run() method and metadata accessors for JobQueue::pop() and JobQueue::ack()
Definition: RunnableJob.php:37