History

About 3 min

History

Execution history of the agent's configured CRON schedules.

class History

The history is what lets the agent work out, when it starts, which schedules fell due while it wasn't running. It is kept in a Hazaar\Util\BTree file with one record per schedule, keyed by a hash of the schedule's identity (see key()). BTree writes records in place and locks the file around every operation, so recording an execution is a single small write rather than a rewrite of the whole history.

Each record contains:

tag - The schedule's tag, or null for an untagged schedule.
action - The scheduled action, e.g. App\Models\Reports::daily.
when - The CRON expression the record was made against.
due - The occurrence the last execution represents. This is when it was due, not when it started.
started - When the last execution started, or null if it never ran (a baseline or a skipped catch-up).
finished - When the last execution finished, or null if it has not finished.
status - One of the STATUS_* constants.
exitCode - The exit code of the last execution's process, if known.
catchup - True if the last execution was a catch-up of a missed occurrence.

Nothing in here throws. A failure is logged and reported to the caller, because the history must never stop the agent from starting or from running its tasks.

Constants

STATUS_BASELINE

public const STATUS_BASELINE = 'baseline'

STATUS_SKIPPED

public const STATUS_SKIPPED = 'skipped'

STATUS_RUNNING

public const STATUS_RUNNING = 'running'

STATUS_COMPLETE

public const STATUS_COMPLETE = 'complete'

STATUS_ERROR

public const STATUS_ERROR = 'error'

STATUS_TIMEOUT

public const STATUS_TIMEOUT = 'timeout'

STATUS_CANCELLED

public const STATUS_CANCELLED = 'cancelled'

KEY_SIZE

private const KEY_SIZE = 32

Properties

db

private BTree $db

Type: Hazaar\Util\BTree

log

private Logger $log

Type: Hazaar\Warlock\Logger

file

private string $file

Type: string

Methods

__construct

private __construct(BTree $db, Logger $log, string $file): void

Parameters

Parameter	Type	Description
`$db`	Hazaar\Util\BTree
`$log`	Hazaar\Warlock\Logger
`$file`	string

open

Opens the history file, creating it if it does not exist.

public open(string $file, Logger $log): ?self

Returns: self

A file that can not be read as a BTree, or that fails verification, is moved aside to <file>.corrupt-<timestamp> and a new history is started.

Parameters

Parameter	Type	Description
`$file`	string	path to the history file
`$log`	Hazaar\Warlock\Logger	logger for errors and notices

key

Returns the history key for a schedule identity.

public key(string $identity): string

Returns: string

Keys are hashed so that every key is the same length, however long a schedule's tag is. The identity is built by Entry, which prefixes it so that a tag can never collide with an untagged schedule.

Parameters

Parameter	Type	Description
`$identity`	string

getFile

Returns the path to the history file.

public getFile(): string

Returns: string

get

Returns the record for a schedule, or null if there is none.

public get(string $key): ?array

Returns: array

Parameters

Parameter	Type	Description
`$key`	string

all

Returns every record in the history, keyed by schedule key.

public all(): array

Returns: array

baseline

Records an occurrence as handled without running it.

public baseline(Entry $entry, int $due, string $status = 'self::STATUS_BASELINE'): bool

Returns: bool

Used when a schedule is seen for the first time, when its CRON expression has changed, when the history is in the future, when the schedule has opted out of catch-up, and (with STATUS_SKIPPED) when a catch-up was skipped. The details of the last real execution are kept.

Parameters

Parameter	Type	Description
`$entry`	Hazaar\Warlock\Agent\Schedule\Entry
`$due`	int
`$status`	string

markStarted

Records that an execution of an occurrence has started.

public markStarted(Entry $entry, int $due, bool $catchup): bool

Returns: bool

Parameters

Parameter	Type	Description
`$entry`	Hazaar\Warlock\Agent\Schedule\Entry
`$due`	int	the occurrence the execution represents
`$catchup`	bool	true if the execution is a catch-up of a missed occurrence

markFinished

Records how an execution finished.

public markFinished(Entry $entry, string $status, ?int $exitCode): bool

Returns: bool

Parameters

Parameter	Type	Description
`$entry`	Hazaar\Warlock\Agent\Schedule\Entry
`$status`	string	one of `STATUS_COMPLETE`, `STATUS_ERROR`, `STATUS_TIMEOUT` or `STATUS_CANCELLED`
`$exitCode`	int

prune

Removes the records of schedules that are no longer configured.

public prune(array $keys): int

Returns: int

Parameters

Parameter	Type	Description
`$keys`	array	the keys of every schedule that is still configured

compact

Compacts the history file to reclaim the space left by records that grew and were rewritten elsewhere.

public compact(): bool

Returns: bool

openTree

Opens and verifies the BTree file.

private openTree(string $file): BTree

Returns: Hazaar\Util\BTree

Parameters

Parameter	Type	Description
`$file`	string

set

Writes a record, logging any failure.

private set(string $key, array $record): bool

Returns: bool

Parameters

Parameter	Type	Description
`$key`	string
`$record`	array

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