Skip to content

Commit ac532cb

Browse files
committed
Add new Task APIs documentation
1 parent d96a390 commit ac532cb

File tree

2 files changed

+42
-0
lines changed

2 files changed

+42
-0
lines changed

docs/apis/subsystems/task/adhoc.md

+25
Original file line numberDiff line numberDiff line change
@@ -156,3 +156,28 @@ The `reschedule_or_queue_adhoc_task()` function will locate any existing task ma
156156
```php
157157
\core\task\manager::reschedule_or_queue_adhoc_task($task);
158158
```
159+
160+
#### Retrying failing tasks
161+
162+
<Since version="4.4" issueNumber="MDL-79128" />
163+
164+
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.
165+
166+
```php
167+
$task->set_attempts_available(2);
168+
\core\task\manager::queue_adhoc_task($task);
169+
```
170+
171+
You can get the remaining available attempts of a task by calling the `get_attempts_available()` function.
172+
173+
```php
174+
$task->get_attempts_available();
175+
```
176+
177+
Tasks are retried by default, but this behaviour can be modified by overriding the `retry_until_success()` method in your task class, for example:
178+
179+
```php
180+
public function retry_until_success(): bool {
181+
return false;
182+
}
183+
```

docs/devupdate.md

+17
Original file line numberDiff line numberDiff line change
@@ -326,6 +326,23 @@ If you are using this functionality in older versions of Moodle you are advised
326326

327327
:::
328328

329+
<Since version="4.4" issueNumber="MDL-79128" />
330+
331+
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.
332+
333+
The default value for the maximum retry limit on an Ad-hoc task is **12**.
334+
335+
Retries can be entirely disabled by passing a value of `0`, for example:
336+
337+
```php
338+
$task = new example_task();
339+
// This task wil not be retried at all.
340+
$task->set_attempts_available(0);
341+
\core\task\manager::queue_task($task);
342+
```
343+
344+
See the [detailed documentation](./apis/subsystems/task/adhoc#retrying-failing-tasks) on how to use these new APIs.
345+
329346
## Parameters
330347

331348
### API Change

0 commit comments

Comments
 (0)