Main

Main Warlock agent process responsible for task orchestration.

class Main extends \Hazaar\Warlock\Process

Extends: Hazaar\Warlock\Process

Properties

tasks

Main task queue.

public array $tasks

Type: array

tags

Tags for scheduled tasks.

public array $tags

Type: array

reconnect

Reconnect automatically when control channel is interrupted.

protected bool $reconnect = true

Type: bool

taskSubscriptions

Event subscriptions requested by running tasks (e.g. Services), keyed by event ID and then task ID.

private array $taskSubscriptions

Type: array

The agent holds a single upstream subscription per event on behalf of all its tasks and forwards matching events down to each subscribed task.

config

Agent configuration loaded from environment and config files.

private Config $config

Type: Hazaar\Config

app

Application metadata used by spawned task processes.

private Application $app

Type: Hazaar\Warlock\Agent\Struct\Application

scheduleHistory

public History $scheduleHistory

Type: Hazaar\Warlock\Agent\Schedule\History

Methods

__construct

public __construct(?string $configFile, string $env = 'development'): void

Parameters

Parameter	Type	Description
$configFile	string	agent config filename
$env	string	runtime environment name

getConfig

Returns the agent configuration.

public getConfig(): Config

Returns: Hazaar\Config

setSilent

Enables or disables agent log output.

public setSilent(bool $silent = true): void

Returns: void

Parameters

Parameter	Type	Description
$silent	bool

createConnection

Creates the agent control-channel socket connection.

public createConnection(Protocol $protocol, ?string $guid): Connection

Returns: Hazaar\Warlock\Interface\Connection

Parameters

Parameter	Type	Description
$protocol	Hazaar\Warlock\Protocol
$guid	string

bootstrap

Performs one-time agent setup before entering the run loop.

public bootstrap(): self

Returns: self

registerServices

Loads and registers service tasks from a services config file.

public registerServices(string $configFile = 'services'): void

Returns: void

Parameters

Parameter	Type	Description
$configFile	string

registerScheduledTasks

Registers scheduled tasks based on the provided configuration array.

public registerScheduledTasks(array $scheduleConfig): void

Returns: void

Iterates through each task in the schedule configuration, validates the presence of the 'action' attribute, creates an Endpoint for the action, sets parameters if provided, and schedules the task to run at the specified time. Handles special scheduling keyword '@reboot' by calculating the appropriate start time with an optional boot delay. Logs notices and errors for missing or invalid configuration attributes.

Parameters

Parameter	Type	Description
$scheduleConfig	array

scheduleStarted

Records in the schedule history that a tracked schedule's execution has started.

public scheduleStarted(Task\Runner $task): void

Returns: void

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task\Runner

scheduleFinished

Records in the schedule history how a tracked schedule's execution finished.

public scheduleFinished(Task\Runner $task, string $status): void

Returns: void

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task\Runner
$status	string	one of the History::STATUS_* constants for a finished execution

registerEventHandlers

Registers event handlers based on the provided configuration array.

public registerEventHandlers(array $eventConfig): void

Returns: void

Iterates through each event in the event configuration, creates an Endpoint for the handler, and subscribes to the event with the corresponding handler. Logs notices and errors for invalid configuration attributes.

Parameters

Parameter	Type	Description
$eventConfig	array	array of event configurations where the key is the event name and the value is the handler (callable)

shutdown

public shutdown(): void

Returns: void

init

public init(): bool

Returns: bool

announce

public announce(): void

Returns: void

trigger

Triggers an event.

public trigger(string $event, mixed $data, bool $echoSelf, ?Task $origin): bool

Returns: bool

The event is delivered locally to this agent's own handlers and to any subscribed tasks, then sent upstream without echo so the server doesn't send it straight back to us.

Parameters

Parameter	Type	Description
$event	string
$data	mixed
$echoSelf	bool
$origin	Hazaar\Warlock\Agent\Task	the task that triggered the event, if any. It will not receive its own event unless $echoSelf is true.

taskSubscribe

Subscribes a task to an event on its behalf.

public taskSubscribe(Task $task, string $eventID, ?array $filter): bool

Returns: bool

The agent subscribes upstream once per event, the first time anything on this agent is interested in it.

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task
$eventID	string
$filter	array

taskUnsubscribe

Unsubscribes a task from an event, dropping the upstream subscription once nothing else needs it.

public taskUnsubscribe(Task $task, string $eventID): bool

Returns: bool

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task
$eventID	string

taskUnsubscribeAll

Removes every subscription held by a task, e.g. when its process exits.

public taskUnsubscribeAll(Task $task): void

Returns: void

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task

handleTaskError

Handles a task reporting an unhandled exception from its child process.

public handleTaskError(Task $task, mixed $error): bool

Returns: bool

If a task.error_handler callable is configured, schedules it as a new task, passing it the error and information about the task that failed. Without a task.error_handler configured, the error is only logged, which is what happened previously.

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task
$error	mixed

run

protected run(): void

Returns: void

processCommand

protected processCommand(PacketType $command, ?\stdClass $payload): bool

Returns: bool

Parameters

Parameter	Type	Description
$command	Hazaar\Warlock\Enum\PacketType
$payload	stdClass

hasSubscribers

private hasSubscribers(string $eventID): bool

Returns: bool

Parameters

Parameter	Type	Description
$eventID	string

forwardEvent

Forwards an event to every task subscribed to it whose filter matches.

private forwardEvent(string $eventID, \stdClass $payload, ?Task $exclude): void

Returns: void

Parameters

Parameter	Type	Description
$eventID	string
$payload	stdClass
$exclude	Hazaar\Warlock\Agent\Task

processEvent

private processEvent(string $event, mixed $payload): void

Returns: void

Parameters

Parameter	Type	Description
$event	string
$payload	mixed

queueRemoteRunner

Queues a runner task sent by a client (DELAY or SCHEDULE) and acknowledges it.

private queueRemoteRunner(\stdClass $payload, int $when, ?int $interval): bool

Returns: bool

The server assigns the task ID (id), so the ID it gave the client is the one cancelTask() can use.

Parameters

Parameter	Type	Description
$payload	stdClass
$when	int
$interval	int

scheduleRunner

private scheduleRunner(int|string $when, Endpoint $endpoint, array $params, ?string $tag, bool $overwrite, ?int $timeout, ?string $id, ?int $interval): false|string

Returns: false|string

Parameters

Parameter	Type	Description
$when	int	string
$endpoint	Hazaar\Warlock\Agent\Struct\Endpoint
$params	array	the endpoint's arguments
$tag	string
$overwrite	bool
$timeout	int
$id	string
$interval	int

scheduleErrorHandler

Schedules an error handler task, replacing any non-running task already queued for the

private scheduleErrorHandler(Endpoint $endpoint, mixed $error, array $taskInfo, string $tag, int $when): ?string

Returns: string

same tag. Skips scheduling if the tagged handler is currently running.

Parameters

Parameter	Type	Description
$endpoint	Hazaar\Warlock\Agent\Struct\Endpoint
$error	mixed
$taskInfo	array
$tag	string
$when	int

scheduleCatchups

Opens the schedule history and catches up any CRON schedules missed while the agent was not running.

private scheduleCatchups(array $scheduled): void

Returns: void

Only CRON schedules are tracked. @reboot and timestamp schedules aren't, and nor are tasks that application code schedules with delay(), schedule() or interval(). If the history can't be opened, catch-up is disabled and the agent carries on without it.

Parameters

Parameter	Type	Description
$scheduled	array	the config of each scheduled task, keyed by task ID

getRuntimePath

Returns the application's runtime directory, as set by app.runtimePath in the application config.

private getRuntimePath(): string

Returns: string

taskQueueAdd

private taskQueueAdd(Task $task): void

Returns: void

Parameters

Parameter	Type	Description
$task	Hazaar\Warlock\Agent\Task

taskCancel

private taskCancel(string $taskID): bool

Returns: bool

Parameters

Parameter	Type	Description
$taskID	string

---

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