Collection of task related methods. More...

Static Public Member Functions
static	adhoc_task_complete (adhoc_task $task)
	This function indicates that an adhoc task was completed successfully.

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

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

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

static	clean_failed_adhoc_tasks ()
	Clean up failed adhoc tasks.

static	cleanup_metadata ()
	Cleanup stale task metadata.

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

static	clear_static_caches ()
	This function is used to indicate that any long running cron processes should exit at the next opportunity and restart.

static	configure_scheduled_task (scheduled_task $task)
	Change the default configuration for a scheduled task.

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

static	fail_running_task ()
	This function will fail the currently running task, if there is one.

static	get_adhoc_task (int $taskid)
	This function will get an adhoc task by id.

static	get_adhoc_tasks (string $classname, bool $failedonly=false, bool $skiprunning=false)
	This function load the adhoc tasks for a given classname.

static	get_adhoc_tasks_summary ()
	This function returns adhoc tasks summary per component classname.

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

static	get_candidate_adhoc_tasks (int $timestart, int $limit, ?int $runmax, array $pertasklimits=[])
	Return a list of candidate adhoc tasks to run.

static	get_canonical_class_name ($taskorstring)
	Gets class name for use in database table.

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

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

static	get_next_adhoc_task (int $timestart, ?bool $checklimits=true, ?string $classname=null)
	This function will dispatch the next adhoc task in the queue.

static	get_next_scheduled_task ($timestart)
	This function will dispatch the next scheduled task in the queue.

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

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

static	is_runnable ()
	Returns if Moodle have access to PHP CLI binary or not.

static	load_default_scheduled_tasks_for_component ($componentname, $expandr=true)
	Given a component name, will load the list of tasks in the db/tasks.php file for that component.

static	load_scheduled_tasks_for_component ($componentname)
	Given a component name, will load the list of tasks from the scheduled_tasks table for that component.

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

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

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

static	record_from_scheduled_task ($task)
	Utility method to create a DB record from a scheduled task.

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

static	reset_scheduled_tasks_for_component ($componentname)
	Update the database to contain a list of scheduled task for a component.

static	reset_state ()
	Reset the state of the task manager.

static	run_adhoc_from_cli (int $taskid)
	Executes an ad hoc task from web invocation using PHP CLI.

static	run_all_adhoc_from_cli (?bool $failedonly=false, ?string $classname=null)
	Executes ad hoc tasks from web invocation using PHP CLI.

static	run_from_cli (scheduled_task $task)
	Executes a cron from web invocation using PHP CLI.

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

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

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

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

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

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

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

Public Attributes
int const	ADHOC_TASK_FAILED_RETENTION = 4 * WEEKSECS
	Used to set the retention period for adhoc tasks that have failed and to be cleaned up.

int const	ADHOC_TASK_QUEUE_MODE_DISTRIBUTING = 0
	Used to tell the adhoc task queue to fairly distribute tasks.

int const	ADHOC_TASK_QUEUE_MODE_FILLING = 1
	Used to tell the adhoc task queue to try and fill unused capacity.

Static Public Attributes
static bool bool	$registeredshutdownhandler = false
	Used to tell if the manager's shutdown callback has been registered.

static task_base task_base	$runningtask = null
	$runningtask Used to tell what is the current running task in this process.

Static Protected Member Functions
static	find_php_cli_path ()
	Find the path of PHP CLI binary.

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

static	get_queued_adhoc_task_record ($task)
	Checks if the task with the same classname, component and customdata is already scheduled.

static	get_record_with_config_overrides (\stdClass $record)
	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.

static	task_is_scheduled ($task)
	Checks if the task with the same classname, component and customdata is already scheduled.

Static Protected Attributes
static array array	$miniqueue = []
	A cached queue of adhoc tasks.

static null int int	$mode = null
	Used to determine if the adhoc task queue is distributing or filling capacity.

static int int	$numtasks = 0
	The last recorded number of unique adhoc tasks.

Detailed Description

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.

Copyright: 2013 Damyon Wiese

License: http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later

Member Function Documentation

◆ adhoc_task_complete()

static core\task\manager::adhoc_task_complete ( adhoc_task $task )

static

This function indicates that an adhoc task was completed successfully.

Parameters

core\task\adhoc_task $task

◆ adhoc_task_failed()

static core\task\manager::adhoc_task_failed ( adhoc_task $task )

static

This function indicates that an adhoc task was not completed successfully and should be retried.

Parameters

core\task\adhoc_task $task

◆ adhoc_task_from_record()

static core\task\manager::adhoc_task_from_record ( $record )

static

Utility method to create an adhoc task from a DB record.

Parameters

stdClass $record

Return values

core\task\adhoc_task

Exceptions

moodle_exception

◆ adhoc_task_starting()

static core\task\manager::adhoc_task_starting	(	adhoc_task	$task,
		int	$time = 0 )

static

Records that a adhoc task is starting to run.

Parameters

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

Exceptions

dml_exception
coding_exception

◆ clear_fail_delay()

static core\task\manager::clear_fail_delay ( scheduled_task $task )

static

Clears the fail delay for the given task and updates its next run time based on the schedule.

Parameters

scheduled_task $task Task to reset

Exceptions

dml_exception If there is a database error

◆ clear_static_caches()

static core\task\manager::clear_static_caches ( )

static

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.

◆ configure_scheduled_task()

static core\task\manager::configure_scheduled_task ( scheduled_task $task )

static

Change the default configuration for a scheduled task.

The list of scheduled tasks is taken from load_scheduled_tasks_for_component.

Parameters

core\task\scheduled_task $task - The new scheduled task information to store.

Return values

boolean - True if the config was saved.

◆ ensure_adhoc_task_qos()

static core\task\manager::ensure_adhoc_task_qos ( array $records )

static

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.

Parameters

array	$records	array of task records
array	$records	array of same task records shuffled

Deprecated: since Moodle 4.1 MDL-67648 - please do not use this method anymore.

Todo: MDL-74843 This method will be deleted in Moodle 4.5

See also: core\task\manager\get_next_adhoc_task

◆ find_php_cli_path()

static core\task\manager::find_php_cli_path ( )

staticprotected

Find the path of PHP CLI binary.

Return values

string|false The PHP CLI executable PATH

◆ get_adhoc_task()

static core\task\manager::get_adhoc_task ( int $taskid )

static

This function will get an adhoc task by id.

The task will be handed out with an open lock - possibly on the entire cron process. Make sure you call either {

See also: adhoc_task_failed} or {; adhoc_task_complete} to release the lock and reschedule the task.

Parameters

int $taskid

Return values

core\task\adhoc_task|null

Exceptions

moodle_exception

◆ get_adhoc_tasks()

static core\task\manager::get_adhoc_tasks	(	string	$classname,
		bool	$failedonly = false,
		bool	$skiprunning = false )

static

This function load the adhoc tasks for a given classname.

Parameters

string	$classname
bool	$failedonly
bool	$skiprunning	do not return tasks that are in the running state

Return values

array

◆ get_adhoc_tasks_summary()

static core\task\manager::get_adhoc_tasks_summary ( )

static

This function returns adhoc tasks summary per component classname.

Return values

array

◆ get_all_scheduled_tasks()

static core\task\manager::get_all_scheduled_tasks ( )

static

This function will return a list of all the scheduled tasks that exist in the database.

Return values

core\task\scheduled_task[]

◆ get_candidate_adhoc_tasks()

static core\task\manager::get_candidate_adhoc_tasks	(	int	$timestart,
		int	$limit,
		?int	$runmax,
		array	$pertasklimits = [] )

static

Return a list of candidate adhoc tasks to run.

Parameters

int	$timestart	Only return tasks where nextruntime is less than this value
int	$limit	Limit the list to this many results
int \| null	$runmax	Only return tasks that have less than this value currently running
array	$pertasklimits	An array of classname => limit specifying how many instance of a task may be returned

Return values

array Array of candidate tasks

◆ get_canonical_class_name()

static core\task\manager::get_canonical_class_name ( $taskorstring )

static

Gets class name for use in database table.

Always begins with a .

Parameters

string | task_base $taskorstring Task object or a string

◆ get_concurrent_task_lock()

static core\task\manager::get_concurrent_task_lock ( adhoc_task $task )

staticprotected

Gets the concurrent lock required to run an adhoc task.

Parameters

adhoc_task $task The task to obtain the lock for

Return values

core\lock\lock The lock if one was obtained successfully

Exceptions

coding_exception

◆ get_default_scheduled_task()

static core\task\manager::get_default_scheduled_task	(		$classname,
			$expandr = true )

static

This function load the default scheduled task details for a given classname.

Parameters

string	$classname
bool	$expandr	- if true (default) an 'R' value in a time is expanded to an appropriate int. If false, they are left as 'R'

Return values

core\task\scheduled_task|false

◆ get_failed_adhoc_tasks()

static core\task\manager::get_failed_adhoc_tasks ( int $delay = 0 )

static

This function will return a list of all adhoc tasks that have a faildelay.

Parameters

int $delay filter how long the task has been delayed

Return values

core\task\adhoc_task[]

◆ get_next_adhoc_task()

static core\task\manager::get_next_adhoc_task	(	int	$timestart,
		?bool	$checklimits = true,
		?string	$classname = null )

static

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 adhoc_task_failed or adhoc_task_complete to release the lock and reschedule the task.

Parameters

int	$timestart
bool	$checklimits	Should we check limits?
string \| null	$classname	Return only task of this class

Return values

core\task\adhoc_task|null

Exceptions

moodle_exception

◆ get_next_scheduled_task()

static core\task\manager::get_next_scheduled_task ( $timestart )

static

This function will dispatch the next scheduled 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 scheduled_task_failed or scheduled_task_complete to release the lock and reschedule the task.

Parameters

int $timestart - The start of the cron process - do not repeat any tasks that have been run more recently than this.

Return values

core\task\scheduled_task or null

Exceptions

moodle_exception

◆ get_queued_adhoc_task_record()

static core\task\manager::get_queued_adhoc_task_record ( $task )

staticprotected

Checks if the task with the same classname, component and customdata is already scheduled.

Parameters

adhoc_task $task

Return values

stdClass|false

◆ get_record_with_config_overrides()

static core\task\manager::get_record_with_config_overrides ( \stdClass $record )

staticprotected

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'.

Parameters

stdClass $record scheduled task record

Return values

stdClass scheduled task with any configured overrides

◆ get_running_tasks()

static core\task\manager::get_running_tasks ( $sort = '' )

static

Gets a list of currently-running tasks.

Parameters

string $sort Sorting method

Return values

array Array of scheduled and adhoc tasks

Exceptions

dml_exception

◆ get_scheduled_task()

static core\task\manager::get_scheduled_task ( $classname )

static

This function load the scheduled task details for a given classname.

Parameters

string $classname

Return values

core\task\scheduled_task or false

◆ is_runnable()

static core\task\manager::is_runnable ( )

static

Returns if Moodle have access to PHP CLI binary or not.

Return values

bool

◆ load_default_scheduled_tasks_for_component()

static core\task\manager::load_default_scheduled_tasks_for_component	(		$componentname,
			$expandr = true )

static

Given a component name, will load the list of tasks in the db/tasks.php file for that component.

Parameters

string	$componentname	- The name of the component to fetch the tasks for.
bool	$expandr	- if true (default) an 'R' value in a time is expanded to an appropriate int. If false, they are left as 'R'

Return values

core\task\scheduled_task[] - List of scheduled tasks for this component.

◆ load_scheduled_tasks_for_component()

static core\task\manager::load_scheduled_tasks_for_component ( $componentname )

static

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.

Parameters

string $componentname - The name of the component to load the tasks for.

Return values

core\task\scheduled_task[]

◆ passthru_via_mtrace()

static core\task\manager::passthru_via_mtrace ( string $command )

static

This behaves similar to passthru but filters every line via the mtrace function so it can be post processed.

Parameters

string $command to run

Return values

void

◆ queue_adhoc_task()

static core\task\manager::queue_adhoc_task	(	adhoc_task	$task,
			$checkforexisting = false )

static

Queue an adhoc task to run in the background.

Parameters

core\task\adhoc_task	$task	- The new adhoc task information to store.
bool	$checkforexisting	- If set to true and the task with the same user, classname, component and customdata is already scheduled then it will not schedule a new task. Can be used only for ASAP tasks.

Return values

boolean - True if the config was saved.

◆ record_from_adhoc_task()

static core\task\manager::record_from_adhoc_task ( $task )

static

Utility method to create a DB record from an adhoc task.

Parameters

core\task\adhoc_task $task

Return values

stdClass

◆ record_from_scheduled_task()

static core\task\manager::record_from_scheduled_task ( $task )

static

Utility method to create a DB record from a scheduled task.

Parameters

core\task\scheduled_task $task

Return values

stdClass

◆ reschedule_or_queue_adhoc_task()

static core\task\manager::reschedule_or_queue_adhoc_task ( adhoc_task $task )

static

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.

Parameters

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

Since: Moodle 3.7

◆ reset_scheduled_tasks_for_component()

static core\task\manager::reset_scheduled_tasks_for_component ( $componentname )

static

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.

Parameters

string $componentname - The frankenstyle component name.

◆ run_adhoc_from_cli()

static core\task\manager::run_adhoc_from_cli ( int $taskid )

static

Executes an ad hoc task from web invocation using PHP CLI.

Parameters

int $taskid Task to execute via CLI.

Exceptions

moodle_exception

◆ run_all_adhoc_from_cli()

static core\task\manager::run_all_adhoc_from_cli	(	?bool	$failedonly = false,
		?string	$classname = null )

static

Executes ad hoc tasks from web invocation using PHP CLI.

Parameters

bool \| null	$failedonly
string \| null	$classname	Task class to execute via CLI.

Exceptions

moodle_exception

◆ run_from_cli()

static core\task\manager::run_from_cli ( scheduled_task $task )

static

Executes a cron from web invocation using PHP CLI.

Parameters

scheduled_task $task Task that be executed via CLI.

Return values

bool

Exceptions

moodle_exception

◆ scheduled_task_complete()

static core\task\manager::scheduled_task_complete ( scheduled_task $task )

static

This function indicates that a scheduled task was completed successfully and should be rescheduled.

Parameters

core\task\scheduled_task $task

◆ scheduled_task_failed()

static core\task\manager::scheduled_task_failed ( scheduled_task $task )

static

This function indicates that a scheduled task was not completed successfully and should be retried.

Parameters

core\task\scheduled_task $task

◆ scheduled_task_from_record()

static core\task\manager::scheduled_task_from_record	(	$record,
		$expandr = true,
		$override = true )

static

Utility method to create a task from a DB record.

Parameters

stdClass	$record
bool	$expandr	- if true (default) an 'R' value in a time is expanded to an appropriate int. If false, they are left as 'R'
bool	$override	- if true loads overridden settings from config.

Return values

core\task\scheduled_task|false

◆ scheduled_task_get_override_key()

static core\task\manager::scheduled_task_get_override_key ( string $classname )

static

Get the key within the scheduled tasks config object that for a classname.

Parameters

string $classname the scheduled task classname to find

Return values

string the key if found, otherwise null

◆ scheduled_task_has_override()

static core\task\manager::scheduled_task_has_override ( string $classname )

static

This checks whether or not there is a value set in config for a scheduled task.

Parameters

string $classname Scheduled task's classname

Return values

bool	true if there is an entry in config

◆ scheduled_task_starting()

static core\task\manager::scheduled_task_starting	(	scheduled_task	$task,
		int	$time = 0 )

static

Records that a scheduled task is starting to run.

Parameters

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

Exceptions

dml_exception If the task doesn't exist

◆ static_caches_cleared_since()

static core\task\manager::static_caches_cleared_since ( $starttime )

static

Return true if the static caches have been cleared since $starttime.

Parameters

int $starttime The time this process started.

Return values

boolean True if static caches need resetting.

◆ task_is_scheduled()

static core\task\manager::task_is_scheduled ( $task )

staticprotected

Checks if the task with the same classname, component and customdata is already scheduled.

Parameters

adhoc_task $task

Return values

bool

Member Data Documentation

◆ ADHOC_TASK_FAILED_RETENTION

int const core\task\manager::ADHOC_TASK_FAILED_RETENTION = 4 * WEEKSECS

Used to set the retention period for adhoc tasks that have failed and to be cleaned up.

The number is in week unit. The default value is 4 weeks.

The documentation for this class was generated from the following file:

lib/classes/task/manager.php

Static Public Member Functions

Public Attributes

Static Public Attributes

Static Protected Member Functions

Static Protected Attributes

Detailed Description

Member Function Documentation

◆ adhoc_task_complete()

◆ adhoc_task_failed()

◆ adhoc_task_from_record()

◆ adhoc_task_starting()

◆ clear_fail_delay()

◆ clear_static_caches()

◆ configure_scheduled_task()

◆ ensure_adhoc_task_qos()

◆ find_php_cli_path()

◆ get_adhoc_task()

◆ get_adhoc_tasks()

◆ get_adhoc_tasks_summary()

◆ get_all_scheduled_tasks()

◆ get_candidate_adhoc_tasks()

◆ get_canonical_class_name()

◆ get_concurrent_task_lock()

◆ get_default_scheduled_task()

◆ get_failed_adhoc_tasks()

◆ get_next_adhoc_task()

◆ get_next_scheduled_task()

◆ get_queued_adhoc_task_record()

◆ get_record_with_config_overrides()

◆ get_running_tasks()

◆ get_scheduled_task()

◆ is_runnable()

◆ load_default_scheduled_tasks_for_component()

◆ load_scheduled_tasks_for_component()

◆ passthru_via_mtrace()

◆ queue_adhoc_task()

◆ record_from_adhoc_task()

◆ record_from_scheduled_task()

◆ reschedule_or_queue_adhoc_task()

◆ reset_scheduled_tasks_for_component()

◆ run_adhoc_from_cli()

◆ run_all_adhoc_from_cli()

◆ run_from_cli()

◆ scheduled_task_complete()

◆ scheduled_task_failed()

◆ scheduled_task_from_record()

◆ scheduled_task_get_override_key()

◆ scheduled_task_has_override()

◆ scheduled_task_starting()

◆ static_caches_cleared_since()

◆ task_is_scheduled()

Member Data Documentation

◆ ADHOC_TASK_FAILED_RETENTION