Catchup

Works out which configured CRON schedules were missed while the agent was not running.

class Catchup

This works like anacron. Each schedule's most recent due occurrence is compared with its record in the schedule history. If that occurrence never ran, the schedule is caught up: it runs once, however many occurrences were missed, shortly after the agent starts, and then continues on its normal schedule.

For each schedule, in this order:

1. A schedule with the same identity as one already checked is not tracked.
2. No history: the occurrence is recorded as a baseline and not run. Turning catch-up on never runs anything.
3. The CRON expression has changed: a new baseline is recorded and nothing runs.
4. The history is in the future (the clock went backwards): a new baseline is recorded and nothing runs.
5. The schedule has opted out (catchup: false): its history is moved on and nothing runs.
6. The occurrence was already handled: nothing runs, unless its execution was interrupted (running or cancelled) and rerun_interrupted is set, in which case that occurrence runs again.
7. The missed occurrence is older than max_age: skipped.
8. The next regular run is due before the catch-up would start: skipped.
9. The next regular run is due within buffer seconds of the catch-up: skipped.
10. Otherwise a catch-up is scheduled at now + boot_delay + n * stagger, where n counts the catch-ups already scheduled.

Skipped catch-ups are logged and recorded in the history with the status skipped. Records of schedules that are no longer configured are removed, and the history file is then compacted.

Properties

history

the schedule history

private History $history

Type: Hazaar\Warlock\Agent\Schedule\History

log

logger for decisions

private Logger $log

Type: Hazaar\Warlock\Logger

options

the task.catchup config: max_age, buffer, stagger and rerun_interrupted

private array $options

Type: array

bootDelay

seconds after startup before the first catch-up runs (task.boot_delay)

private int $bootDelay

Type: int

Methods

__construct

public __construct(History $history, Logger $log, array $options, int $bootDelay): void

Parameters

Parameter	Type	Description
$history	Hazaar\Warlock\Agent\Schedule\History	the schedule history
$log	Hazaar\Warlock\Logger	logger for decisions
$options	array	the task.catchup config: max_age, buffer, stagger and rerun_interrupted
$bootDelay	int	seconds after startup before the first catch-up runs (task.boot_delay)

apply

Checks each schedule against the history and schedules any catch-ups.

public apply(array $entries, ?int $now): int

Returns: int

For each schedule that is caught up, Entry::$catchup is set to true, Entry::$start to when the catch-up should run and Entry::$occurrence to the occurrence it represents. Entry::$tracked is set to false for a schedule that can't be tracked.

Parameters

Parameter	Type	Description
$entries	array	the configured CRON schedules
$now	int	the current time, which tests can set

check

Checks one schedule and schedules a catch-up if it missed an occurrence.

private check(Entry $entry, int $now, int $delay): bool

Returns: bool

Parameters

Parameter	Type	Description
$entry	Hazaar\Warlock\Agent\Schedule\Entry
$now	int
$delay	int	seconds from now until the catch-up would start

option

Returns a catch-up option for a schedule: its own catchup_<name> override, or the task.catchup setting.

private option(Entry $entry, string $name): mixed

Returns: mixed

Parameters

Parameter	Type	Description
$entry	Hazaar\Warlock\Agent\Schedule\Entry
$name	string

date

private date(int $time): string

Returns: string

Parameters

Parameter	Type	Description
$time	int

---

Generated by Hazaar API Doc Generator on Thu, 22 Oct 2026 05:05:31 +0000