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

Other[edit | edit source]

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
)