Merge pull request #973 from HuongNV13/adhocTaskRetry

Add new Task APIs documentation

Author: andrewnicols

docs/apis/subsystems/task/adhoc.md

@@ -156,3 +156,28 @@ The `reschedule_or_queue_adhoc_task()` function will locate any existing task ma
 ```php
 \core\task\manager::reschedule_or_queue_adhoc_task($task);
 ```
+
+#### Retrying failing tasks
+
+<Since version="4.4" issueNumber="MDL-79128" />
+
+The number of retries for a failing task can be controlled using the `set_attempts_available()` method on the task before it is queued. If not specified a task will be allowed **12** retries.
+
+```php
+$task->set_attempts_available(2);
+\core\task\manager::queue_adhoc_task($task);
+```
+
+You can get the remaining available attempts of a task by calling the `get_attempts_available()` function.
+
+```php
+$task->get_attempts_available();
+```
+
+Tasks are retried by default, but this behaviour can be modified by overriding the `retry_until_success()` method in your task class, for example:
+
+```php
+public function retry_until_success(): bool {
+    return false;
+}
+```

docs/devupdate.md

@@ -326,6 +326,23 @@ If you are using this functionality in older versions of Moodle you are advised
 
 :::
 
+<Since version="4.4" issueNumber="MDL-79128" />
+
+The behaviour of the task runner has been changed to limit the number of retries allowed before a failing _adhoc_ task is removed. Scheduled tasks are not affected.
+
+The default value for the maximum retry limit on an Ad-hoc task is **12**.
+
+Retries can be entirely disabled by passing a value of `0`, for example:
+
+```php
+$task = new example_task();
+// This task wil not be retried at all.
+$task->set_attempts_available(0);
+\core\task\manager::queue_task($task);
+```
+
+See the [detailed documentation](./apis/subsystems/task/adhoc#retrying-failing-tasks) on how to use these new APIs.
+
 ## Parameters
 
 ### API Change