Task API

Moodle 2.7

Task
Project state	Waiting for Integration Review
Tracker issue	MDL-25505
Discussion	https://moodle.org/mod/forum/discuss.php?d=229139
Assignee	Damyon

Tasks

A task is a unit of work that needs to be done later. Good uses for tasks:

• Run a slow operation in the background
• Run a maintenance task on a regular schedule

In general any operation that takes more than a few seconds should be a candidate for a task.

Benefits

• Better user experience (give them feedback immediately, that their task has been queued)
• Prevent browser timeouts
• Better performance for clusters (tasks can be run on separate, non-webserving cluster node)
• Failed tasks will be retried
• A better user interface will prevent users queuing multiple tasks, because they thought it had "got stuck".

Types of task

Scheduled tasks

Scheduled tasks are tasks that will run on a regular schedule. A default schedule can be set, but admins have the ability to change the default schedule if required.

Adhoc tasks

Adhoc tasks are for when you need to queue something to run in the background immediately. Adhoc tasks can contain custom data, specific to this specific instance of the task.

Usage

Scheduled task usage

Scheduled tasks are created by subclassing \core\task\scheduled_task. They also require an entry in "db/tasks.php" for your plugin.

1. Create a subclass of \core\task\scheduled_task that contains your code to run in a schedule.

class cut_my_toe_nails extends \core\task\scheduled_task {                                                                           
    public function execute() {       
        // apply fungus cream
        // apply chainsaw
        // apply olive oil
    }                                                                                                                               
} 

2. Create entry in db/tasks.php for your plugin:

$tasks = array(                                                                                                                     
    array(                                                                                                                          
        'classname' => 'mod_hygene\task\cut_my_toe_nails',                                                                            
        'blocking' => 0,                                                                                                            
        'minute' => '*',                                                                                                            
        'hour' => '*',                                                                                                              
        'day' => '*',                                                                                                               
        'dayofweek' => '*',                                                                                                         
        'month' => '1,6'                                                                                                              
    )
);

The field required in the db/tasks file are:

• classname - the fully namespaced classname of your task. This needs to comply with the autoloading rules.
• blocking - if this is set to 1, no other scheduled task will run at the same time as this task. Do not set this to 1 unless you really need it as it will impact the performance of the task queue.
• minute, hour, day, dayofweek, month - This is the default schedule for running the task. The syntax matches the syntax of unix cron.

Cron syntax examples

• day - Day of month field for task schedule.
  • "*" - Every day
  • "*/2" - Every 2nd day
  • "1" - The first of every month
  • "1,15" - The first and fifteenth of every month

Adhoc task usage

This is even easier than scheduled tasks.

1. Create a subclass of \core\task\adhoc_task that contains your code to run in the background.

class take_over_the_world extends \core\task\adhoc_task {                                                                           
    public function execute() {       
        // gain 100,000,000 friends on facebook.
        // crash the stock market.
        // run for president.
    }                                                                                                                               
} 
                                      

2. Create an instance of the task and queue it (adding custom data if required).

   // create the instance
   $domination = new take_over_the_world();
   // add custom data
   $domination->set_custom_data(array(
                                 'deadline' => '1/3/2014'
   ));

   // queue it
   \core\task\manager::queue_adhoc_task($domination);

   // profit

3. There is no 3.

Legacy cron

The older syntax of cron.php or modname_cron() is still supported - but is not as good as this new API. This is because:

• the legacy cron functions run serially - a long running cron in one plugin will hold up the other plugins crons
• the legacy cron functions are fragile - a failure in one cron in one plugin will prevent the cron in other functions from running at all
• the scheduling cannot be changed by admins