Task API - Revision history

Devdocsbot: Protected "Task API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

2022-07-20T12:46:13Z

Protected "Task API": Developer Docs Migration ([Edit=Allow only administrators] (indefinite))

← Older revision	Revision as of 12:46, 20 July 2022
(No difference)

Devdocsbot: Update migration status and path

2022-07-20T12:44:34Z

Update migration status and path

← Older revision		Revision as of 12:44, 20 July 2022
Line 1:		Line 1:
			{{Template:Migrated\|newDocId=/docs/apis/subsystems/task/}}
	{{Infobox Project		{{Infobox Project
	\|name = Task		\|name = Task

Brendanheywood: Reordered to match cron spec order

2022-03-20T22:45:15Z

Reordered to match cron spec order

@@ Line 82: / Line 82: @@
 ==== Cron syntax examples ====
-* day - Day of month field for task schedule.
+* '''minute''' - Minute 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
-* dayofweek - Day of week field for task schedule.
+* '''month''' - Month field for task schedule.
 ** "*" - Every day
 ** "0" - Every Sunday
@@ Line 93: / Line 110: @@
 ** "1,5" - Every Monday and Friday
 ** "1-5" - Every weekday
 === Adhoc task usage ===
 This is even easier than scheduled tasks.

Brendanheywood: Added weekday example

2022-03-20T22:41:35Z

Added weekday example

Show changes

Mudrd8mz: Text replacement - "" to ""

2021-07-14T20:27:47Z

Text replacement - "</code>" to "</syntaxhighlight>"

← Older revision		Revision as of 20:27, 14 July 2021
Line 67:		Line 67:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>
	2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task):		2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task):
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
Line 81:		Line 81:
	],		],
	];		];
	</~~code~~>		</syntaxhighlight>

	The fields required in the db/tasks.php file are:		The fields required in the db/tasks.php file are:
Line 143:		Line 143:
	}		}
	}		}
	</~~code~~>		</syntaxhighlight>

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

	// profit		// profit
	</~~code~~>		</syntaxhighlight>

	3. There is no 3.		3. There is no 3.
Line 169:		Line 169:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	$task->set_userid($user->id);		$task->set_userid($user->id);
	</~~code~~>		</syntaxhighlight>

	==== Set a task to run at a future time ====		==== Set a task to run at a future time ====
Line 177:		Line 177:
	$task->set_next_run_time($futuretime);		$task->set_next_run_time($futuretime);
	\core\task\manager::queue_adhoc_task($task);		\core\task\manager::queue_adhoc_task($task);
	</~~code~~>		</syntaxhighlight>

	==== Ignore duplicate adhoc tasks ====		==== Ignore duplicate adhoc tasks ====
Line 187:		Line 187:
	<syntaxhighlight lang="php">		<syntaxhighlight lang="php">
	\core\task\manager::queue_adhoc_task($task, true);		\core\task\manager::queue_adhoc_task($task, true);
	</~~code~~>		</syntaxhighlight>

	==== Rescheduling an adhoc task ====		==== Rescheduling an adhoc task ====
Line 199:		Line 199:
	$task->set_next_run_time(time() + 5 * MINSECS);		$task->set_next_run_time(time() + 5 * MINSECS);
	\core\task\manager::reschedule_or_queue_adhoc_task($task);		\core\task\manager::reschedule_or_queue_adhoc_task($task);
	</~~code~~>		</syntaxhighlight>

	=== Failures ===		=== Failures ===
Line 236:		Line 236:

	}		}
	</~~code~~>		</syntaxhighlight>

	== For Admins ==		== For Admins ==

Mudrd8mz: Text replacement - "`" to ""`


2021-07-14T13:35:58Z
Text replacement - "<code php>" to "<syntaxhighlight lang="php">"

				
				
				
				
				
				← Older revision
				Revision as of 13:35, 14 July 2021
				
Line 41:
Line 41:
1. Create a subclass of \core\task\scheduled_task that contains your code to run in a schedule (within "<pluginroot>/classes/task/cut_my_toe_nails.php" for the autoloading mechanism to pick up). 1. Create a subclass of \core\task\scheduled_task that contains your code to run in a schedule (within "<pluginroot>/classes/task/cut_my_toe_nails.php" for the autoloading mechanism to pick up).



<code php> <syntaxhighlight lang="php">
namespace mod_hygene\task; namespace mod_hygene\task;



Line 69:
Line 69:
</code> </code>
2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task): 2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task):
<code php> <syntaxhighlight lang="php">
$tasks = [ $tasks = [
     [      [
Line 132:
Line 132:
1. Create a subclass of \core\task\adhoc_task that contains your code to run in the background. 1. Create a subclass of \core\task\adhoc_task that contains your code to run in the background.



<code php> <syntaxhighlight lang="php">
class take_over_the_world extends \core\task\adhoc_task { class take_over_the_world extends \core\task\adhoc_task {
     public function execute() {      public function execute() {
Line 147:
Line 147:
2. Create an instance of the task and queue it (adding custom data if required). 2. Create an instance of the task and queue it (adding custom data if required).



<code php> <syntaxhighlight lang="php">
// create the instance // create the instance
$domination = new take_over_the_world(); $domination = new take_over_the_world();
Line 167:
Line 167:
By default, your task will run as admin. If you would like it to run as a specific user, call: By default, your task will run as admin. If you would like it to run as a specific user, call:



<code php> <syntaxhighlight lang="php">
$task->set_userid($user->id); $task->set_userid($user->id);
</code> </code>
Line 173:
Line 173:
==== Set a task to run at a future time ==== ==== Set a task to run at a future time ====



<code php> <syntaxhighlight lang="php">
$task = new my_future_task(); $task = new my_future_task();
$task->set_next_run_time($futuretime); $task->set_next_run_time($futuretime);
Line 185:
Line 185:
If you pass true as the second argument $checkforexisting and a task with the same classname, component and customdata is already scheduled then it will not schedule a new task. If you pass true as the second argument $checkforexisting and a task with the same classname, component and customdata is already scheduled then it will not schedule a new task.



<code php> <syntaxhighlight lang="php">
\core\task\manager::queue_adhoc_task($task, true); \core\task\manager::queue_adhoc_task($task, true);
</code> </code>
Line 195:
Line 195:
A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. You can use this to implement "debounce" and its a good pattern do some expensive processing after some action, but the action maybe repeated several times and it keeps pushing back the task processing until there is lull in activity. A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. You can use this to implement "debounce" and its a good pattern do some expensive processing after some action, but the action maybe repeated several times and it keeps pushing back the task processing until there is lull in activity.



<code php> <syntaxhighlight lang="php">
$task = new heavy_debounced_task(); $task = new heavy_debounced_task();
$task->set_next_run_time(time() + 5 * MINSECS); $task->set_next_run_time(time() + 5 * MINSECS);
Line 224:
Line 224:
In order to improve debugging information, it is good practice to call ''mtrace'' to log what's going on within a task execution: In order to improve debugging information, it is good practice to call ''mtrace'' to log what's going on within a task execution:



<code php> <syntaxhighlight lang="php">
class my_task extends \core\task\scheduled_task { class my_task extends \core\task\scheduled_task {



Noeldemartin: Add suggestion to use mtrace for logs
2020-05-25T17:03:07Z
Add suggestion to use mtrace for logs

				
				
				
				
				
				← Older revision
				Revision as of 17:03, 25 May 2020
				
Line 220:
Line 220:
=== Generating output === === Generating output ===
Since Moodle 3.5 it is safe to use the [[Output_API]] in cron tasks. Prior to this there may be cases where the Output API has not been initialised. Since Moodle 3.5 it is safe to use the [[Output_API]] in cron tasks. Prior to this there may be cases where the Output API has not been initialised.
These issues were addressed in MDL-61800 and were also backported to Moodle 3.4.3 ,and Moodle 3.3.3. These issues were addressed in MDL-61800 and were also backported to Moodle 3.4.3, and Moodle 3.3.3.
 
In order to improve debugging information, it is good practice to call ''mtrace'' to log what's going on within a task execution:
 
<code php>
class my_task extends \core\task\scheduled_task {
 
    public function execute() {
         mtrace("My task started");
 
         // do some work...
 
         mtrace("My task finished");
    }
 
}
</code>



== For Admins == == For Admins ==



Brendanheywood: /* Rescheduling an adhoc task */
2020-05-22T14:54:46Z
Rescheduling an adhoc task

				
				
				
				
				
				← Older revision
				Revision as of 14:54, 22 May 2020
				
Line 193:
Line 193:
{{Moodle 3.7}} {{Moodle 3.7}}



A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. You can use this to implement "debounce" and its a good pattern do some expensive processing after some action, but the action maybe repeated several times and it keeps pushing back the task processing until there is lull in activity.



<code php> <code php>
$task->set_next_run_time($futuretime); $task = new heavy_debounced_task();
$task->set_next_run_time(time() + 5 * MINSECS);
\core\task\manager::reschedule_or_queue_adhoc_task($task); \core\task\manager::reschedule_or_queue_adhoc_task($task);
</code> </code>



Brendanheywood: /* Ignore duplicate adhoc tasks */
2020-05-22T14:49:11Z
Ignore duplicate adhoc tasks

				
				
				
				
				
				← Older revision
				Revision as of 14:49, 22 May 2020
				
Line 169:
Line 169:
<code php> <code php>
$task->set_userid($user->id); $task->set_userid($user->id);
</code>

==== Set a task to run at a future time ====

<code php>
$task = new my_future_task();
$task->set_next_run_time($futuretime);
\core\task\manager::queue_adhoc_task($task);
</code> </code>






Brendanheywood: /* Adhoc tasks */
2019-10-20T11:02:03Z
Adhoc tasks

				
				
				
				
				
				← Older revision
				Revision as of 11:02, 20 October 2019
				
Line 30:
Line 30:



=== Adhoc tasks === === Adhoc tasks ===
Adhoc tasks are for when you need to queue something to run in the background immediately, they would be executed as soon as possible. Adhoc tasks can contain custom data, specific to this specific instance of the task.  
Adhoc tasks are for when you need to queue something to run in the background either immediately where they would be executed as soon as possible, or as a once off task at some future point in time. Adhoc tasks can contain custom data, specific to this specific instance of the task.



== Usage == == Usage ==

← Older revision		Revision as of 13:35, 14 July 2021
Line 41:		Line 41:
	1. Create a subclass of \core\task\scheduled_task that contains your code to run in a schedule (within "<pluginroot>/classes/task/cut_my_toe_nails.php" for the autoloading mechanism to pick up).		1. Create a subclass of \core\task\scheduled_task that contains your code to run in a schedule (within "<pluginroot>/classes/task/cut_my_toe_nails.php" for the autoloading mechanism to pick up).

	<~~code~~ php>		<syntaxhighlight lang="php">
	namespace mod_hygene\task;		namespace mod_hygene\task;

Line 69:		Line 69:
	</code>		</code>
	2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task):		2. Create entry in db/tasks.php for your plugin (then a version bump to your plugin will install the task):
	<~~code~~ php>		<syntaxhighlight lang="php">
	$tasks = [		$tasks = [
	[		[
Line 132:		Line 132:
	1. Create a subclass of \core\task\adhoc_task that contains your code to run in the background.		1. Create a subclass of \core\task\adhoc_task that contains your code to run in the background.

	<~~code~~ php>		<syntaxhighlight lang="php">
	class take_over_the_world extends \core\task\adhoc_task {		class take_over_the_world extends \core\task\adhoc_task {
	public function execute() {		public function execute() {
Line 147:		Line 147:
	2. Create an instance of the task and queue it (adding custom data if required).		2. Create an instance of the task and queue it (adding custom data if required).

	<~~code~~ php>		<syntaxhighlight lang="php">
	// create the instance		// create the instance
	$domination = new take_over_the_world();		$domination = new take_over_the_world();
Line 167:		Line 167:
	By default, your task will run as admin. If you would like it to run as a specific user, call:		By default, your task will run as admin. If you would like it to run as a specific user, call:

	<~~code~~ php>		<syntaxhighlight lang="php">
	$task->set_userid($user->id);		$task->set_userid($user->id);
	</code>		</code>
Line 173:		Line 173:
	==== Set a task to run at a future time ====		==== Set a task to run at a future time ====

	<~~code~~ php>		<syntaxhighlight lang="php">
	$task = new my_future_task();		$task = new my_future_task();
	$task->set_next_run_time($futuretime);		$task->set_next_run_time($futuretime);
Line 185:		Line 185:
	If you pass true as the second argument $checkforexisting and a task with the same classname, component and customdata is already scheduled then it will not schedule a new task.		If you pass true as the second argument $checkforexisting and a task with the same classname, component and customdata is already scheduled then it will not schedule a new task.

	<~~code~~ php>		<syntaxhighlight lang="php">
	\core\task\manager::queue_adhoc_task($task, true);		\core\task\manager::queue_adhoc_task($task, true);
	</code>		</code>
Line 195:		Line 195:
	A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. You can use this to implement "debounce" and its a good pattern do some expensive processing after some action, but the action maybe repeated several times and it keeps pushing back the task processing until there is lull in activity.		A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. You can use this to implement "debounce" and its a good pattern do some expensive processing after some action, but the action maybe repeated several times and it keeps pushing back the task processing until there is lull in activity.

	<~~code~~ php>		<syntaxhighlight lang="php">
	$task = new heavy_debounced_task();		$task = new heavy_debounced_task();
	$task->set_next_run_time(time() + 5 * MINSECS);		$task->set_next_run_time(time() + 5 * MINSECS);
Line 224:		Line 224:
	In order to improve debugging information, it is good practice to call ''mtrace'' to log what's going on within a task execution:		In order to improve debugging information, it is good practice to call ''mtrace'' to log what's going on within a task execution:

	<~~code~~ php>		<syntaxhighlight lang="php">
	class my_task extends \core\task\scheduled_task {		class my_task extends \core\task\scheduled_task {

← Older revision		Revision as of 14:54, 22 May 2020
Line 193:		Line 193:
	{{Moodle 3.7}}		{{Moodle 3.7}}

	A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required.		A method to allow queuing or rescheduling of an existing scheduled task was added. This allows an existing task to be updated or queued as required. You can use this to implement "debounce" and its a good pattern do some expensive processing after some action, but the action maybe repeated several times and it keeps pushing back the task processing until there is lull in activity.

	<code php>		<code php>
	$task->set_next_run_time(~~$futuretime~~);		$task = new heavy_debounced_task();
			$task->set_next_run_time(time() + 5 * MINSECS);
	\core\task\manager::reschedule_or_queue_adhoc_task($task);		\core\task\manager::reschedule_or_queue_adhoc_task($task);
	</code>		</code>

← Older revision		Revision as of 14:49, 22 May 2020
Line 169:		Line 169:
	<code php>		<code php>
	$task->set_userid($user->id);		$task->set_userid($user->id);
			</code>

			==== Set a task to run at a future time ====

			<code php>
			$task = new my_future_task();
			$task->set_next_run_time($futuretime);
			\core\task\manager::queue_adhoc_task($task);
	</code>		</code>

← Older revision		Revision as of 11:02, 20 October 2019
Line 30:		Line 30:

	=== Adhoc tasks ===		=== Adhoc tasks ===
	Adhoc tasks are for when you need to queue something to run in the background immediately, they would be executed as soon as possible. Adhoc tasks can contain custom data, specific to this specific instance of the task.
			Adhoc tasks are for when you need to queue something to run in the background either immediately where they would be executed as soon as possible, or as a once off task at some future point in time. Adhoc tasks can contain custom data, specific to this specific instance of the task.

	== Usage ==		== Usage ==