Jump to content

Manual:runJobs.php

From mediawiki.org
Since MediaWiki 1.40, maintenance scripts should be invoked directly through maintenance/run.php instead. Invoking maintenance scripts directly will trigger a warning.

Details

[edit]

runJobs.php file is a maintenance script to manually force the job queue to run. Under normal circumstances jobs in the queue are run as a function of user interaction with the wiki (ordinary apache requests). The default rate jobs are run is 1 to 1 and can be changed by adjusting $wgJobRunRate in the LocalSettings.php file. Note that the default memory limit for a job is 150 MB so that a bad job does not consume all the server's memory.

You may wish to use this script because your wiki's traffic is too slow to clear the queue, or there may be an exceptionally large number of jobs to clear. Be advised though that for many server configurations this can cause your wiki to become sluggish or even unresponsive until the script completes. You are advised to first try 50 or 100 to get a feel for the script's speed before running it for several hundred jobs or with no parameters.

Note also that if you accidentally ran a script that loaded the job queue with a large number of undesired or unneeded jobs it is also possible to completely clear the job queue by clearing the job table in your wiki database. Be certain there are no jobs in the queue you need as all jobs will be irretrievably deleted.

Usage

[edit]
Before MW 1.40
php maintenance/runJobs.php
MW 1.40+
php maintenance/run.php runJobs

Advanced Usage

[edit]
Before MW 1.40
php maintenance/runJobs.php [--conf|--dbpass|--dbuser|--globals|--help|--maxjobs|--maxtime|--memory-limit|--nothrottle|--procs|--quiet|--server|--type|--wait|--wiki]
MW 1.40+
php maintenance/run.php runJobs [--conf|--dbpass|--dbuser|--globals|--help|--maxjobs|--maxtime|--memory-limit|--nothrottle|--procs|--quiet|--server|--type|--wait|--wiki]

Generic maintenance parameters

[edit]
Option/Parameter Description
no parameters Will run all jobs currently in the queue
--help (-h) Display this help message
--quiet (-q) Whether to suppress non-error output
--conf Location of "LocalSettings.php", if not default
--wiki For specifying the wiki ID
--globals Output globals at the end of processing for debugging
--memory-limit Set a specific memory limit for the script, "max" for no limit or "default" to avoid changing it
--server The protocol and server name to use in URLs, e.g. https://en.wikipedia.org. This is sometimes necessary because server name detection may fail in command line scripts.

Script dependent parameters

[edit]
Option/Parameter Description
--dbuser The DB user to use for this script
--dbpass The password to use for this script

Script specific parameters

[edit]
Option/Parameter Description
--maxjobs Maximum number of jobs to run
--maxtime Maximum amount of wall-clock time (in seconds)
--procs Number of processes to use
--type Type of job to run. See $wgJobClasses for available job types.
--wait Wait for new jobs instead of exiting
--nothrottle Ignore the job throttling configuration
--result Set to "json" to print only a JSON response

Use limits

[edit]
It is not recommended to have "runJobs.php" run indefinitely without any limits. Using --maxjobs on its own is insufficient, so it is best paired with --maxtime and/or --memory-limit. Typical usage involves periodic runs with at least one of the restrictions set to prevent it from running too long in one go.

Example

[edit]
Before MW 1.40
php maintenance/runJobs.php --maxjobs 5  --memory-limit 150M --type refreshLinks
MW 1.40+
php maintenance/run.php runJobs --maxjobs 5  --memory-limit 150M --type refreshLinks
Before MW 1.40
/home/flowerwiki/public_html/w/maintenance$ php runJobs.php --maxjobs 5 --memory-limit 150M --type refreshLinks
MW 1.40+
/home/flowerwiki/public_html/w/maintenance$ php run.php runJobs --maxjobs 5 --memory-limit 150M --type refreshLinks

When the script is run, you may see an output like this, here including jobs from the refreshLinks queue:

2010-10-29 13:50:38 refreshLinks Daisies STARTING
2010-10-29 13:50:38 refreshLinks Daisies t=501 good
2010-10-29 13:50:38 refreshLinks Magnolias STARTING
2010-10-29 13:50:38 refreshLinks Magnolias t=501 good
2010-10-29 13:50:39 refreshLinks Heirloom_Roses STARTING
2010-10-29 13:50:39 refreshLinks Heirloom_Roses t=500 good
2010-10-29 13:50:39 refreshLinks Carnations STARTING
2010-10-29 13:50:39 refreshLinks Carnations t=501 good
2010-10-29 13:50:40 refreshLinks Tulips STARTING
2010-10-29 13:50:40 refreshLinks Tulips t=563 good


Possible issues

[edit]

The job queue appears to be stuck

[edit]

Under certain circumstances, "runJobs.php" may hang indefinitely. Some jobs may fail to get completed, clogging up the queue.

As noted above, it is best to prevent this from happening by providing the necessary flags, but if you do find yourself in this situation, ideally you should find the cause of the problem. Possible causes include

  • A missing PHP extension in the php.ini of the PHP being run from the command line.
  • A buggy extension.

No standard tools or methods are currently available to let you diagnose the issue.

Object caching

[edit]

"runJobs.php" may hang if you have object caching enabled. If this happens, there is something you could try, with the caveat below in mind.

  1. Create another "LocalSettings.php" file with object caching disabled:
    $wgMainCacheType = CACHE_NONE;
    
  2. Then run runJobs.php, or run.php runJobs, with the --conf parameter to specify the location of the new LocalSettings.php file with caching disabled.

This approach is not recommended, since some jobs will purge objects from the object cache, which won't get purged because caching is disabled. This will result in some updates not being reflected on the wiki.

Terminate a running process

[edit]

Sometimes, if you cannot find the problem and the job queue is creating overhead, you may have no other choice than to terminate it, possibly at the expense of deleting jobs you might need. If this is the case and you accept the risk, you can try to clear the job that you think is causing trouble, or clear the entire jobs table.

Note that on some control panels that use cronjob automation, clearing jobs may have no visible effect. The process initiated may still appear to hang even if there are no jobs left to execute.

Using a database administration tool
  • Go to your database administration tool (e.g. phpMyAdmin) and locate the job table.
  • If you're lucky, it may just be an active job that is causing trouble and that needs to be cleared. You can locate it by finding the row that has a hash value in the job_token column.
  • Repeat if necessary. If all else fails, clear the entire jobs table.
Using manageJobs.php

The maintenance script manageJobs.php does not lend you insights but it does let you delete jobs by group.

See also

[edit]