Search moodle.org's
Developer Documentation

See Release Notes
Long Term Support Release

  • Bug fixes for general core bugs in 4.1.x will end 13 November 2023 (12 months).
  • Bug fixes for security issues in 4.1.x will end 10 November 2025 (36 months).
  • PHP version: minimum PHP 7.4.0 Note: minimum PHP version has increased since Moodle 4.0. PHP 8.0.x is supported too.

Differences Between: [Versions 310 and 401] [Versions 311 and 401] [Versions 39 and 401] [Versions 400 and 401] [Versions 401 and 402] [Versions 401 and 403]

Scheduled and adhoc task management.

Copyright: 2013 Damyon Wiese
License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
File Size: 1516 lines (57 kb)
Included or required:0 times
Referenced: 0 times
Includes or requires: 0 files

Defines 2 classes


Class: manager  - X-Ref

Collection of task related methods.

Some locking rules for this class:
All changes to scheduled tasks must be protected with both - the global cron lock and the lock
for the specific scheduled task (in that order). Locks must be released in the reverse order.
load_default_scheduled_tasks_for_component($componentname, $expandr = true)   X-Ref
Given a component name, will load the list of tasks in the db/tasks.php file for that component.

param: string $componentname - The name of the component to fetch the tasks for.
param: bool $expandr - if true (default) an 'R' value in a time is expanded to an appropriate int.
return: \core\task\scheduled_task[] - List of scheduled tasks for this component.

reset_scheduled_tasks_for_component($componentname)   X-Ref
Update the database to contain a list of scheduled task for a component.
The list of scheduled tasks is taken from @load_scheduled_tasks_for_component.
Will throw exceptions for any errors.

param: string $componentname - The frankenstyle component name.

task_is_scheduled($task)   X-Ref
Checks if the task with the same classname, component and customdata is already scheduled

param: adhoc_task $task
return: bool

get_queued_adhoc_task_record($task)   X-Ref
Checks if the task with the same classname, component and customdata is already scheduled

param: adhoc_task $task
return: bool

reschedule_or_queue_adhoc_task(adhoc_task $task)   X-Ref
Schedule a new task, or reschedule an existing adhoc task which has matching data.

Only a task matching the same user, classname, component, and customdata will be rescheduled.
If these values do not match exactly then a new task is scheduled.

param: \core\task\adhoc_task $task - The new adhoc task information to store.

queue_adhoc_task(adhoc_task $task, $checkforexisting = false)   X-Ref
Queue an adhoc task to run in the background.

param: \core\task\adhoc_task $task - The new adhoc task information to store.
param: bool $checkforexisting - If set to true and the task with the same user, classname, component and customdata
return: boolean - True if the config was saved.

configure_scheduled_task(scheduled_task $task)   X-Ref
Change the default configuration for a scheduled task.
The list of scheduled tasks is taken from {@link load_scheduled_tasks_for_component}.

param: \core\task\scheduled_task $task - The new scheduled task information to store.
return: boolean - True if the config was saved.

record_from_scheduled_task($task)   X-Ref
Utility method to create a DB record from a scheduled task.

param: \core\task\scheduled_task $task
return: \stdClass

record_from_adhoc_task($task)   X-Ref
Utility method to create a DB record from an adhoc task.

param: \core\task\adhoc_task $task
return: \stdClass

adhoc_task_from_record($record)   X-Ref
Utility method to create an adhoc task from a DB record.

param: \stdClass $record
return: \core\task\adhoc_task

scheduled_task_from_record($record, $expandr = true, $override = true)   X-Ref
Utility method to create a task from a DB record.

param: \stdClass $record
param: bool $expandr - if true (default) an 'R' value in a time is expanded to an appropriate int.
param: bool $override - if true loads overridden settings from config.
return: \core\task\scheduled_task|false

load_scheduled_tasks_for_component($componentname)   X-Ref
Given a component name, will load the list of tasks from the scheduled_tasks table for that component.
Do not execute tasks loaded from this function - they have not been locked.

param: string $componentname - The name of the component to load the tasks for.
return: \core\task\scheduled_task[]

get_scheduled_task($classname)   X-Ref
This function load the scheduled task details for a given classname.

param: string $classname
return: \core\task\scheduled_task or false

get_adhoc_tasks($classname)   X-Ref
This function load the adhoc tasks for a given classname.

param: string $classname
return: \core\task\adhoc_task[]

get_default_scheduled_task($classname, $expandr = true)   X-Ref
This function load the default scheduled task details for a given classname.

param: string $classname
param: bool $expandr - if true (default) an 'R' value in a time is expanded to an appropriate int.
return: \core\task\scheduled_task|false

get_all_scheduled_tasks()   X-Ref
This function will return a list of all the scheduled tasks that exist in the database.

return: \core\task\scheduled_task[]

get_failed_adhoc_tasks(int $delay = 0)   X-Ref
This function will return a list of all adhoc tasks that have a faildelay

param: int $delay filter how long the task has been delayed
return: \core\task\adhoc_task[]

ensure_adhoc_task_qos(array $records)   X-Ref
Ensure quality of service for the ad hoc task queue.

This reshuffles the adhoc tasks queue to balance by type to ensure a
level of quality of service per type, while still maintaining the
relative order of tasks queued by timestamp.

param: array $records array of task records
param: array $records array of same task records shuffled

get_next_adhoc_task($timestart, $checklimits = true)   X-Ref
This function will dispatch the next adhoc task in the queue. The task will be handed out
with an open lock - possibly on the entire cron process. Make sure you call either
{@link adhoc_task_failed} or {@link adhoc_task_complete} to release the lock and reschedule the task.

param: int $timestart
param: bool $checklimits Should we check limits?
return: \core\task\adhoc_task or null if not found

Class: as  - X-Ref

get_candidate_adhoc_tasks(int $timestart,int $limit,?int $runmax,array $pertasklimits = [])   X-Ref
No description

get_next_scheduled_task($timestart)   X-Ref
No description

adhoc_task_failed(adhoc_task $task)   X-Ref
This function indicates that an adhoc task was not completed successfully and should be retried.

param: \core\task\adhoc_task $task

adhoc_task_starting(adhoc_task $task, int $time = 0)   X-Ref
Records that a adhoc task is starting to run.

param: adhoc_task $task Task that is starting
param: int $time Start time (leave blank for now)

adhoc_task_complete(adhoc_task $task)   X-Ref
This function indicates that an adhoc task was completed successfully.

param: \core\task\adhoc_task $task

scheduled_task_failed(scheduled_task $task)   X-Ref
This function indicates that a scheduled task was not completed successfully and should be retried.

param: \core\task\scheduled_task $task

clear_fail_delay(scheduled_task $task)   X-Ref
Clears the fail delay for the given task and updates its next run time based on the schedule.

param: scheduled_task $task Task to reset

scheduled_task_starting(scheduled_task $task, int $time = 0)   X-Ref
Records that a scheduled task is starting to run.

param: scheduled_task $task Task that is starting
param: int $time Start time (0 = current)

scheduled_task_complete(scheduled_task $task)   X-Ref
This function indicates that a scheduled task was completed successfully and should be rescheduled.

param: \core\task\scheduled_task $task

get_running_tasks($sort = '')   X-Ref
Gets a list of currently-running tasks.

param: string $sort Sorting method
return: array Array of scheduled and adhoc tasks

cleanup_metadata()   X-Ref
Cleanup stale task metadata.


clear_static_caches()   X-Ref
This function is used to indicate that any long running cron processes should exit at the
next opportunity and restart. This is because something (e.g. DB changes) has changed and
the static caches may be stale.


static_caches_cleared_since($starttime)   X-Ref
Return true if the static caches have been cleared since $starttime.

param: int $starttime The time this process started.
return: boolean True if static caches need resetting.

get_canonical_class_name($taskorstring)   X-Ref
Gets class name for use in database table. Always begins with a \.

param: string|task_base $taskorstring Task object or a string

get_concurrent_task_lock(adhoc_task $task)   X-Ref
Gets the concurrent lock required to run an adhoc task.

param: adhoc_task $task The task to obtain the lock for
return: \core\lock\lock The lock if one was obtained successfully

find_php_cli_path()   X-Ref
Find the path of PHP CLI binary.

return: string|false The PHP CLI executable PATH

is_runnable()   X-Ref
Returns if Moodle have access to PHP CLI binary or not.

return: bool

run_from_cli(\core\task\task_base $task)   X-Ref
Executes a cron from web invocation using PHP CLI.

param: \core\task\task_base $task Task that be executed via CLI.
return: bool

passthru_via_mtrace(string $command)   X-Ref
This behaves similar to passthru but filters every line via
the mtrace function so it can be post processed.

param: string $command to run
return: void

get_record_with_config_overrides(\stdClass $record)   X-Ref
For a given scheduled task record, this method will check to see if any overrides have
been applied in config and return a copy of the record with any overridden values.

The format of the config value is:
$CFG->scheduled_tasks = array(
'$classname' => array(
'schedule' => '* * * * *',
'disabled' => 1,
),
);

Where $classname is the value of the task's classname, i.e. '\core\task\grade_cron_task'.

param: \stdClass $record scheduled task record
return: \stdClass scheduled task with any configured overrides

scheduled_task_has_override(string $classname)   X-Ref
This checks whether or not there is a value set in config
for a scheduled task.

param: string $classname Scheduled task's classname
return: bool true if there is an entry in config

scheduled_task_get_override_key(string $classname)   X-Ref
Get the key within the scheduled tasks config object that
for a classname.

param: string $classname the scheduled task classname to find
return: string the key if found, otherwise null