Manual:Job queue/For developers

From MediaWiki.org
Jump to: navigation, search

To use the job queue to do your deferred updates, you need to do these things:

Create a Job subclass[edit | edit source]

You need to create a class, that, given parameters and a Title, will perform your deferred updates

<?php
class SynchroniseThreadArticleDataJob extends Job {
	public function __construct( $title, $params ) {
		// Replace synchroniseThreadArticleData with an identifier for your job.
		parent::__construct( 'synchroniseThreadArticleData', $title, $params );
	}
 
	/**
	 * Execute the job
	 *
	 * @return bool
	 */
	public function run() {
		// Load data from $this->params and $this->title
		$article = new Article( $this->title, 0 );
		$limit = $this->params['limit'];
		$cascade = $this->params['cascade'];
 
		// Perform your updates
		if ( $article ) {
			Threads::synchroniseArticleData( $article, $limit, $cascade );
		}
 
		return true;
	}
}

Add your Job class to the global list[edit | edit source]

// The key is your job identifier (from the Job constructor), the value is your class name
$wgJobClasses['synchroniseThreadArticleData'] = 'SynchroniseThreadArticleDataJob';

How to invoke a deferred update[edit | edit source]

/**
 * 1. Set any job parameters you want to have available when your job runs
 *
 *    this can also be an empty array()
 *    these values will be available to your job via $this->params['param_name']
 */
$jobParams = array( 'limit' => $limit, 'cascade' => true );
 
 
/**
 * 2. Get the article title that the job will use when running
 *
 *    if you will not use the title to create/modify a new/existing page, you can use :
 *    
 *    a vague, dumby title
 *    Title::newMainPage();
 *
 *    a more specific title
 *    Title::newFromText( 'User:UserName/SynchroniseThreadArticleData' )
 *
 *    a very specific title that includes a unique identifier. this can be useful
 *    when you create several batch jobs with the same base title
 *    Title::newFromText(
 *        User->getName() . '/' .
 *        'MyExtension/' .
 *        'My Batch Job/' .
 *        uniqid(),
 *        NS_USER
 *    ),
 *    
 *    the idea is for the db to have a title reference that will be used by your
 *    job to create/update a title or for troubleshooting by having a title
 *    reference that is not vague
 */
$title = $article->getTitle();
 
 
/**
 * 3. Instantiate a Job object
 */
$job = new SynchroniseThreadArticleDataJob( $title, $jobParams );
 
 
/**
 * 4. Insert the job into the database
 *    note the differences in the mediawiki versions
 *
 *    for performance reasons, if you plan on inserting several jobs into the queue,
 *    it’s best to add them to a single array and then push them all at once into the queue
 *
 *    for example, earlier in your code you have built up an array of $jobs with different 
 *    titles and jobParams
 *
 *    $jobs[] = new SynchroniseThreadArticleDataJob( $title, $jobParams );
 *    JobQueueGroup::singleton()->push( $jobs );
 */
$job->insert();                           // mediawiki < 1.21
JobQueueGroup::singleton()->push( $job ); // mediawiki >= 1.21

Job queue size[edit | edit source]

It’s good practice to check the overall job queue size for a specific job type before adding additional jobs of that type to the job queue; e.g., when the job queue size for your job queue type > 100. One way to handle this would be to:

  1. Check the job queue size of the job type you want to add.
  2. If the job queue size for that job type > your configured threshold:
    • create a new job that:
    1. contains all of the relevant information as its parameters.
    2. will check an attempt parameter to see how many times it has attempted to create the original job.
      • if it exceeds that configured attempt threshold it will stop attempting to create the original job.
    3. will check the job queue size for the original job type when it runs.
    4. if the job queue size < your configured threshold.
      • will create the original job.

Job queue type[edit | edit source]

A job queue type is the command name you give to the parent::__construct() method of your job class; e.g., using the example above, that would be synchroniseThreadArticleData.

getQueueSizes()[edit | edit source]

JobQueueGroup::singleton()->getQueueSizes() will return an array of all job queue types and their sizes.

Array
(
    [refreshLinks] => 10
    [refreshLinks2] => 30
    [synchroniseThreadArticleData] => 100
)

getSize()[edit | edit source]

While getQueueSizes() is handy for analysing the entire job queue, for performance reasons, it’s best to use JobQueueGroup::singleton()->get( <job type> )->getSize() when analysing a specific job type, which will only return the job queue size of that specific job type.

Array
(
    [synchroniseThreadArticleData] => 100
)