Moodle PHP Documentation 4.4
Moodle 4.4.1 (Build: 20240610) (db07c09afc5)
core\task\manager Class Reference

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.

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$taskTask that is starting
int$timeStart 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$taskTask to reset
Exceptions
dml_exceptionIf 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$recordsarray of task records
array$recordsarray 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|falseThe 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$skiprunningdo 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$timestartOnly return tasks where nextruntime is less than this value
int$limitLimit the list to this many results
int | null$runmaxOnly return tasks that have less than this value currently running
array$pertasklimitsAn array of classname => limit specifying how many instance of a task may be returned
Return values
arrayArray 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$taskorstringTask 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$taskThe task to obtain the lock for
Return values
core\lock\lockThe 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$delayfilter 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$checklimitsShould we check limits?
string | null$classnameReturn 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_taskor 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$recordscheduled task record
Return values
stdClassscheduled 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$sortSorting method
Return values
arrayArray 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_taskor 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$commandto 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$taskidTask 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$classnameTask 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$taskTask 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$classnamethe scheduled task classname to find
Return values
stringthe 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$classnameScheduled task's classname
Return values
booltrue 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$taskTask that is starting
int$timeStart time (0 = current)
Exceptions
dml_exceptionIf 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$starttimeThe time this process started.
Return values
booleanTrue 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: